Connect Apps to Generic OAuth2 Authorization Servers

The most common identity providers (IdP) are available in Auth0 Dashboard and in the Auth0 Marketplace. You can, however, add any OAuth 2.0 provider as a Custom Social Connection in the Auth0 Dashboard.

1. In the Dashboard, go to Authentication > Social.
2. Select Create Connection, go to the bottom of the list, and then select Create Custom.

The form that appears contains several fields that you must use to configure the custom connection:

• Connection Name: Logical identifier for the Connection you are creating. This name cannot be changed, must start and end with an alphanumeric character, and can only contain alphanumeric characters and dashes.

• Authorization URL: URL to which users are redirected to log in.

  Do not attempt to set the OAuth2 response_mode parameter in the authorization URL. This connection only supports the default response_mode (query).

• Token URL: URL used to exchange the received authorization code for access tokens and, if requested, ID tokens.

• Scope: scope parameters to send with the authorization request. Separate multiple scopes with spaces.

• Separate scopes using a space: Toggle that determines how scopes are delimited if the connection_scope parameter is included when calling the IdP’s API. By default, scopes are delimited by a comma. If the toggle is enabled, scopes are delimited by a space. To learn more, read Add Scopes/Permissions to Call Identity Provider APIs.

• Client ID: Client ID for Auth0 as an application used to request authorization and exchange the authorization code. To get a Client ID, you will need to register with the identity provider.

• Client Secret: Client Secret for Auth0 as an application used to exchange the authorization code. To get a Client Secret, you will need to register with the identity provider.

• Fetch User Profile Script: Node.js script used to call a userinfo URL with the provided access token. To learn more about this script, see Fetch User Profile Script.

When configuring the custom identity provider, use the callback URL https://{yourDomain}/login/callback.

Once you create the custom connection, you will see the Applications view and your connection will be subject to Auth0’s Rate Limit Policy. Here, you can enable and disable applications for which you would like the connection to appear.

Update authentication flow

When you create a connection, the default OAuth 2.0 grant type assigned to the connection is Authorization Code Flow. If you have a public application unable to store a Client Secret, such single-page or native applications, you can use the Management API to update the connection to use Authorization Code Flow + PKCE. To learn more about authorization flows, read Which OAuth 2.0 Flow Should I Use?

1. Make a GET request to the /get-connections-by-id endpoint. The response will be similar to:

   {
     "id": "[connectionID]",
     "options": {
       "email": true,
       "scope": [
         "email",
         "profile"
       ],
       "profile": true
     },
     "strategy": "google-oauth2",
     "name": "google-oauth2",
     "is_domain_connection": false,
     "enabled_clients": [
       "[yourAuth0Domain]"
     ],
     "realms": [
       "google-oauth2"
     ]
   }
   

2. Copy the entire options object.

3. Make a PATCH request with the options object and add "pkce_enabled": true.

If you do not include the entire options object, information will be lost and the connection will break.

Fetch User Profile Script

The fetch user profile script is called after the user has logged in with the OAuth2 provider. Auth0 executes this script to call the OAuth2 provider API and get the user profile:

function fetchUserProfile(accessToken, context, callback) {
  request.get(
    {
      url: 'https://auth.example.com/userinfo',
      headers: {
        'Authorization': 'Bearer ' + accessToken,
      }
    },
    (err, resp, body) => {
      if (err) {
        return callback(err);
      }
      if (resp.statusCode !== 200) {
        return callback(new Error(body));
      }
      let bodyParsed;
      try {
        bodyParsed = JSON.parse(body);
      } catch (jsonError) {
        return callback(new Error(body));
      }
      const profile = {
        user_id: bodyParsed.account.uuid,
        email: bodyParsed.account.email
      };
      callback(null, profile);
    }
  );
}

The user_id property in the returned profile is required, and the email property is optional but highly recommended. To learn more about what attributes can be returned, see User Profile Root Attributes.

You can filter, add, or remove anything from the profile returned from the provider. However, it is recommended that you keep this script as simple as possible. More sophisticated manipulation of user information can be achieved through the use of Rules. One advantage of using Rules is that they apply to any connection.

Log in using the custom connection

You can use any of the Auth0 standard mechanisms to log a user in with your custom connection. A direct link would look like:

https://{yourDomain}/authorize
  ?response_type=code
  &client_id={yourClientId}
  &redirect_uri={https://yourApp/callback}
  &scope=openid%20profile%20email
  &connection=NAME_OF_CONNECTION

Modify the icon and display name

To add an icon to the identity provider’s login button or change the text used on the login button, you can use the icon_url property of the options object and the display_name property, respectively, via the Management API.

• If display_name is not included in your request, the field is overwritten with the Connection name value.
• display_name and icon_url only affect how the Connection displays in the Universal Login experience.

cURL

curl --request PATCH \
  --url 'https://{yourDomain}/api/v2/connections/CONNECTION-ID' \
  --header 'content-type: application/json' \
  --data '{ "options": { "client_id": "...", "client_secret": "...", "icon_url": "https://cdn.example.com/assets/icon.png", "scripts": { "fetchUserProfile": "..." }, "authorizationURL": "https://public-auth.example.com/oauth2/authorize", "tokenURL": "https://auth.example.com/oauth2/token", "scope": "auth" }, "enabled_clients": [ "..." ] }, "display_name": "Connection Name"'

Pass provider-specific parameters

You can pass provider-specific parameters to the Authorization endpoint of OAuth 2.0 providers. These can be either static or dynamic.

Pass static parameters

To pass static parameters (parameters that are sent with every authorization request), you can use the authParams element of the options when configuring an OAuth 2.0 connection via the Management API. The call below will set a static parameter of custom_param set to custom.param.value on all authorization requests:

cURL

curl --request PATCH \
  --url 'https://{yourDomain}/api/v2/connections/CONNECTION-ID' \
  --header 'content-type: application/json' \
  --data '{ "options": { "client_id": "...", "client_secret": "...", "authParams": { "custom_param": "custom.param.value" }, "scripts": { "fetchUserProfile": "..." }, "authorizationURL": "https://public-auth.example.com/oauth2/authorize", "tokenURL": "https://auth.example.com/oauth2/token", "scope": "auth" }, "enabled_clients": [ "..." ] }'

Pass dynamic parameters

In certain circumstances, you may want to pass a dynamic value to an OAuth 2.0 Identity Provider. In this case, you can use the authParamsMap element of the options to specify a mapping between one of the existing additional parameters accepted by the Auth0 /authorize endpoint to the parameter accepted by the Identity Provider.

Using the same example above, let’s assume that you want to pass the custom_param parameter to the authorization endpoint, but you want to specify the actual value of the parameter when calling the Auth0 /authorize endpoint.

In this case, you can use one of the existing addition parameters accepted by the /authorize endpoint, such as access_type, and map that to the custom_param parameter:

cURL

curl --request PATCH \
  --url 'https://{yourDomain}/api/v2/connections/CONNECTION-ID' \
  --header 'content-type: application/json' \
  --data '{ "options": { "client_id": "...", "client_secret": "...", "authParamsMap": { "custom_param": "access_type" }, "scripts": { "fetchUserProfile": "..." }, "authorizationURL": "https://auth.example.com/oauth2/authorize", "tokenURL": "https://auth.example.com/oauth2/token", "scope": "auth" }, "enabled_clients": [ "..." ] }'

Now when calling the /authorize endpoint, you can pass the access type in the access_type parameter, and that value will in turn be passed along to the authorization endpoint in the custom_param parameter.

Pass extra headers

In some instances, you will need to pass extra headers to the Token endpoint of an OAuth 2.0 provider. To configure extra headers, open the Settings for the Connection, and in the Custom Headers field, specify a JSON object with the custom headers as key-value pairs:

{
    "Header1" : "Value",
    "Header2" : "Value"
}

Let’s use an example where an Identity Provider may require you to pass an Authorization header with Basic access authentication credentials. In this scenario, you can specify the following JSON object in the Custom Headers field:

{
  "Authorization": "Basic [your credentials]"
}

Where [your credentials] are the actual credentials to send to the Identity Provider.

Learn more

• Social Identity Providers
• Identity Providers
• Protocols