Secure AWS API Gateway Endpoints Using Custom Authorizers


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.

How API Gateway Custom Authorizers Work

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:

The access_token parameter is used for authenticating requests to the provider's API.

We recommend using the field names from the normalized profile.

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.

Before You Begin

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:

Next steps

Log in using the custom connection

You can use any of the Auth0 standard mechanisms (such as direct links, Access TokensAuth0 Lock, auth0.js, and so on.) to login a user with the your 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 href.

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 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 /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 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 blog parameter:

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:

Where [your credentials] is the actual credentials which you need to send to the Identity Provider.

Keep Reading