<commit_before>---
connection: OAuth2 Provider (Generic)
image: /media/connections/oauth2.png
seo_alias: oauth2
toc: true
index: 15
description: You can add any OAuth2 provider using the Auth0 Custom Social Connections extension.
topics:
  - connections
  - social
  - oauth2
contentType: how-to
useCase:
    - customize-connections
    - add-idp
---
# Connect Apps to Generic OAuth2 Authorization Servers

The most common [identity providers](/identityproviders) are available on Auth0's Dashboard and in the [Auth0 Marketplace](https://marketplace.auth0.com/features/social-connections). However, you can add any other <dfn data-key="oauth2">OAuth2</dfn> provider using a **Custom Social Connection**.

To create a new Custom Social Connection, either [click this link](${manage_url}/select-tenant?path=/connections/social/create/custom) and select your tenant or go to **Connections > Social** in the Auth0 Dashboard, scroll to the bottom, and click **Create Custom**.

The form that appears contains several fields which are used to configure the custom connection:

- **Connection Name** - The logical identifier for the Connection being created. This name cannot be changed, must start and end with an alphanumeric character, and can only contain alphanumeric characters and dashes.
- **Authorization URL** - The URL where users are redirected to login.
- **Token URL** - The URL used to exchange the authorization code received for access and, if requested, ID tokens.
- **Scope** - The `scope` parameters to send with the authroization request. Separate multiple scopes with spaces.
- **Client ID** - The Client ID for Auth0 as an application used to request authorization and exchange the authorization code. You will need to register with the identity provider in order to get a Client ID.
- **Client Secret** - The Client Secret for Auth0 as an application used to exchange the authorization code. You will need to register with the identity provider in order to get a Client Secret.
- **Fetch User Profile Script** - A Node.js script to call a userinfo URL with the provided access token. Please see the section below for details on this script.

Once the custom connection is created, the **Applications** tab will be active where you can select when the Connection will appear.

## 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:

```js
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. See the [User Profile Root Attributes reference](/users/updating-user-profile-root-attributes) for more information on  what attributes can be returned.

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](/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 login a user with the your custom connection. A direct link would look like:

```text
https://${account.namespace}/authorize
  ?response_type=code
  &client_id=${account.clientId}
  &redirect_uri=${account.callback}
  &scope=openid%20profile%20email
  &connection=THE_NAME_OF_THE_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](/api/management/v2#!/Connections/patch_connections_by_id).

```har
{
  "method": "PATCH",
  "url": "https://${account.namespace}/api/v2/connections/CONNECTION-ID",
  "headers": [
    { "name": "Content-Type", "value": "application/json" }
  ],
  "postData": {
    "mimeType": "application/json",
    "text": "{ \"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\""
  }
}
```

![Custom OAuth2 Connection with a custom icon and name](/media/articles/connections/social/oauth2/custom-connection-icon.png)

## Pass provider-specific parameters

You can pass provider-specific parameters to the Authorization endpoint of an 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](/api/management/v2#!/Connections/patch_connections_by_id). The call below will set a static parameter of `custom_param` set to `custom.param.value` on all authorization requests:

```har
{
  "method": "PATCH",<commit_msg>Add note about icon and display name<commit_after>---
connection: OAuth2 Provider (Generic)
image: /media/connections/oauth2.png
seo_alias: oauth2
toc: true
index: 15
description: You can add any OAuth2 provider using the Auth0 Custom Social Connections extension.
topics:
  - connections
  - social
  - oauth2
contentType: how-to
useCase:
    - customize-connections
    - add-idp
---
# Connect Apps to Generic OAuth2 Authorization Servers

The most common [identity providers](/identityproviders) are available on Auth0's Dashboard and in the [Auth0 Marketplace](https://marketplace.auth0.com/features/social-connections). However, you can add any other <dfn data-key="oauth2">OAuth2</dfn> provider using a **Custom Social Connection**.

To create a new Custom Social Connection, either [click this link](${manage_url}/select-tenant?path=/connections/social/create/custom) and select your tenant or go to **Connections > Social** in the Auth0 Dashboard, scroll to the bottom, and click **Create Custom**.

The form that appears contains several fields which are used to configure the custom connection:

- **Connection Name** - The logical identifier for the Connection being created. This name cannot be changed, must start and end with an alphanumeric character, and can only contain alphanumeric characters and dashes.
- **Authorization URL** - The URL where users are redirected to login.
- **Token URL** - The URL used to exchange the authorization code received for access and, if requested, ID tokens.
- **Scope** - The `scope` parameters to send with the authroization request. Separate multiple scopes with spaces.
- **Client ID** - The Client ID for Auth0 as an application used to request authorization and exchange the authorization code. You will need to register with the identity provider in order to get a Client ID.
- **Client Secret** - The Client Secret for Auth0 as an application used to exchange the authorization code. You will need to register with the identity provider in order to get a Client Secret.
- **Fetch User Profile Script** - A Node.js script to call a userinfo URL with the provided access token. Please see the section below for details on this script.

Once the custom connection is created, the **Applications** tab will be active where you can select when the Connection will appear.

## 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:

```js
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. See the [User Profile Root Attributes reference](/users/updating-user-profile-root-attributes) for more information on  what attributes can be returned.

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](/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 login a user with the your custom connection. A direct link would look like:

```text
https://${account.namespace}/authorize
  ?response_type=code
  &client_id=${account.clientId}
  &redirect_uri=${account.callback}
  &scope=openid%20profile%20email
  &connection=THE_NAME_OF_THE_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](/api/management/v2#!/Connections/patch_connections_by_id).

:::note
These fields will only affect how the Connection is displayed in the [New Universal Login Experience](https://auth0.com/docs/universal-login/new-experience).
:::

```har
{
  "method": "PATCH",
  "url": "https://${account.namespace}/api/v2/connections/CONNECTION-ID",
  "headers": [
    { "name": "Content-Type", "value": "application/json" }
  ],
  "postData": {
    "mimeType": "application/json",
    "text": "{ \"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\""
  }
}
```

![Custom OAuth2 Connection with a custom icon and name](/media/articles/connections/social/oauth2/custom-connection-icon.png)

## Pass provider-specific parameters

You can pass provider-specific parameters to the Authorization endpoint of an 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](/api/management/v2#!/Connections/patch_connections_by_id). The call below will set a static parameter of `custom_param` set to `custom.param.value` on all authorization requests:

```har
{
  "method": "PATCH",
{'fraction_non_alphanumeric': 0.10582796764074624, 'fraction_numerical': 0.006521380221231633, 'mean_word_length': 3.991759373712402, 'pattern_counts': {'":': 40, '<': 7, '<?xml version=': 0, '>': 11, 'https://': 15, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '4212342', 'n_tokens_mistral': 3285, 'n_tokens_neox': 3186, 'n_words': 1370}