Add a generic OAuth2 Authorization Server to Auth0
The most common identity providers are readily available on Auth0's dashboard. However, you can add any other OAuth2 provider using the Custom Social Connections extension. For details on how to install and configure the extension, refer to Auth0 Extension: Custom Social Connections.
The fetch user profile script
A custom 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:
access_token parameter is used for authenticating requests to the provider's API.
For example, the following code will retrieve the user profile from the GitHub API:
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.
Fetch user profile for OIDC-conformant OAuth2 providers
If the OAuth2 provider is OIDC-conformant, such as another Auth0 tenant, you can extract the user profile from the ID Token. The
ctx object in the fetch user profile script will have the ID Token. You can then decode the token and map its fields to the user object. For example:
Log in using the custom connection
A direct link would look like:
To add a custom connection in Lock, you can add a custom button by following the instructions at Adding custom connections to lock and using this link as the button
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 any static parameters, you can use the
authParams element of the
options when configuring an OAuth 2.0 connection via the Management API.
Let's use WordPress as an example, which allows you to pass an optional
blog parameter to their OAuth 2.0 authorization endpoint (see their OAuth 2.0 documentation for more information). Let's assume that you want to always request a user to grant access to the
myblog.wordpress.com blog when logging in using WordPress.
Using the Management API, you can configure the WordPress connection to always pass this value in the
blog parameter when authorizing a user via WordPress.
Pass dynamic parameters
There are certain circumstances where you may want to pass a dynamic value to 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 of WordPress above, let's assume that you want to pass the
blog parameter to WordPress, but you want to specify the actual value of the parameter when calling the Auth0
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
blog parameter being passed to WordPress:
Now when calling the
/authorize endpoint you can pass the name of the blog in the
access_type parameter, and that value will in turn be passed along to the WordPress authorization endpoint in the
Pass Extra Headers
In some instances you will need to pass extra headers to the Authorization 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:
Let us 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:
[your credentials] is the actual credentials which you need to send to the Identity Provider.