Configuration

You can customise Social Login’s settings using a PHP configuration file. This is optional: each setting has a default, so you only need to include the values you want to change.

To override a setting, create social-login.php in your Craft project’s /config directory and return an array of setting names and values. For example, the following will disable social login in the control panel:

<?php

return [
    'enableCpLogin' => false,
];

All other settings keep their defaults. Add any further settings you want to change to the same array. The options below explain the available settings and their defaults.

Configuration Options

User Groups

A collection of User Group UIDs should be provided.

'userGroups' => [
    '2a99c0a5-3066-45dc-8168-ec7572041f2e',
],

Redirect URI Override

By default, Social Login will continue to use its legacy callback URI. If you need to use a different callback URI, such as for detached domains or an /actions/... callback, set redirectUri at the plugin level.

'redirectUri' => 'https://craft.example.com/actions/social-login/auth/callback',

Trusted Private Image Hosts

Private profile image servers are blocked by default. If a mapped provider image is intentionally hosted on a private server, add its exact host name in social-login.php:

'trustedRemoteImageHosts' => [
    'profile-images.example.test',
],

Provider Settings

Provider settings can contain authentication credentials, so only Craft administrators can access them. Saving changes also requires Craft’s allowAdminChanges setting to be enabled.

You can set provider settings by adding the handle of a provider, and passing in any setting specific to that provider. Typically, this will be OAuth settings.

return [
    '*' => [
        // ...
        'providers' => [
            'facebook' => [
                'enabled' => true,
                'loginEnabled' => true,
                'cpLoginEnabled' => true,

                // Matching registration fields (provider-side, Craft-side)
                'matchUserSource' => 'email',
                'matchUserDestination' => 'email',

                // Field mapping
                'fieldMapping' => [
                    'username' => 'email',
                    'email' => 'email',
                    'field:myFieldHandle' => 'description',
                    'field:text' => 'response',
                ],

                // OAuth settings
                'clientId' => '••••••••••••••••••••••••••••',
                'clientSecret' => '••••••••••••••••••••••••••••',

                // Add in any additional OAuth scopes
                'scopes' => [
                     'user_birthday',
                 ],

                 // Add in any additional OAuth authorization options, used when redirecting
                 // to the provider to start the OAuth authorization process
                 'authorizationOptions' => [
                    'extra' => 'value',
                 ],

                 // Add in any additional provider-based fields to map from
                 // (depends on the provider API with what's available)
                 'customProfileFields' => [
                     'birthday',
                 ],
            ],
        ],
    ],
];

First-time matching accepts email only when the provider confirms ownership of that address. Use id for providers where you deliberately map the provider's stable account identifier to a Craft user field. Returning users are identified by the stored provider connection.

When enabling automatic administrator registration for Azure or Microsoft Entra, configure a specific tenant rather than common, organizations, or consumers. Salesforce requires its expectedOrganizationId provider setting so an account from another organization cannot create a Craft administrator.