Auth0 Extension: Custom Social Connections

The Custom Social Connections extension allows you to easily manage multiple social connections.

Set Up a New Social Connection

To install the Custom Social Connection app, click on the Custom Social Connections box on the main Extensions page of the Management Portal. You will be prompted to install the app.

At this point, you will see the app listed under the Installed Extensions tab.

Once you have installed the app, you will need to configure it to work with whichever social providers you require. To do so, click on the Custom Social Connections link listed under Installed Extensions.

You will be asked to authorize the Custom Social Connections app. After you do so, the New Connection window will open.

Click the slider next to the social provider you want to set up. The slider will turn from grey to green, indicating that a connection to that provider exists. For additional information on how each individual provider handles authentication, see that provider's documentation.

Configure the Social Connection Settings

The New Connection window contains two tabs: Settings and Apps:

New Connection: Settings

The Settings page is used to provide the information required to set up the social connection. You will be asked for information in the following fields:

  • Name: The name of the connection. Generally, this will be the name of the social provider, but you are free to name the connection whatever you would like;
  • Client ID: The provider's client ID;
  • Client Secret: The provider's client secret;
  • Authorization URL: The URL where the transaction begins and authorization occurs;
  • Token URL: The URL used to exchange the code generated from the information you provide for an Access Token;
  • Scope: The scope parameters for which you want access rights;
  • Fetch User Profile Script: The JS function that returns the user profile and associated information. It will be auto-generated with the appropriate fields depending on the chosen provider.
  • Custom Headers: An optional JSON object that lets you provide custom headers to be included in the HTTP calls to the provider. Should be in the format of:
    "Header1" : "Value",
    "Header2" : "Value"
    // ...

After you have provided values for the required fields, click Save.

New Connection: Apps

Once you have successfully configured the connection, you will be presented with a list of apps associated with your Auth0 tenant under the Apps tab of the New Connection window.

Using the slider, enable this social connection for the apps that you want to use it with.

Once you have enabled/disabled the appropriate apps, click Save.

Provide your Callback URL to the Identity Provider

The callback URL is the URL that is invoked by the provider after the authentication request has finished.

Use this value for the Callback URL: https://YOUR_DOMAIN/login/callback

Depending on the provider, this field can be referred to by different names. Sometimes called a Redirect URI the callback URL may also be be referred to as: "Valid OAuth redirect URI", "Authorized redirect URI", "Allowed Return URL" or something similar.

Use your new connection

You can use auth0.js or a direct link to log a user in with the new connection.

A direct link would look like this:


For more details, see the documentation for the /authorize authentication API endpoint.

Lock does not currently support displaying buttons for custom social connections.

Optional: Set up Basic Authentication

By default, when invoking the Token URL to exchange the authentication code for an Access Token, Auth0 will provide the client ID and client secret as part of the body of the POST. Some identity providers require HTTP Basic Authentication, which involves providing those same credentials in a HTTP header.

If the identity provider requires Basic Authentication, you can be use the Custom Headers setting with a JSON object like this:

    "Authorization" : "Basic xxxxxxxx"

xxxxxxxx should be the Base64 encoding of the client id, a colon, and the client secret. For example, if the client id is 123456 and the client secret is abcdef you would Base64 encode 123456:abcdef, which results in MTIzNDU2OmFiY2RlZg==. The resulting header would be:

    "Authorization" : "Basic MTIzNDU2OmFiY2RlZg=="

Additional Steps

Depending on which social providers you are you using, there may be additional steps in the provider configuration to enable the connection.