Calling APIs from Server-side Web Apps

Heads up! As part of our efforts to improve security and standards-based interoperability, we have implemented several new features in our authentication flows and made changes to existing ones. For an overview of these changes, and details on how you adopt them, refer to Introducing OIDC Conformant Authentication.

In order to access an API from a regular web app, you need to implement the Authorization Code OAuth 2.0 grant. In this document we will see how this flow works.

If you need a refresher on the OAuth 2.0 protocol, you can go through our OAuth 2.0 article.

Overview of the flow

The Authorization Code Grant (defined in RFC 6749, section 4.1) is a flow where the browser receives an Authorization Code from Auth0 and sends this to the web app. The web app will then interact with Auth0 and exchange the Authorization Code for an access_token, and optionally an id_token and a refresh_token. The web app can now use this access_token to call the API on behalf of the user.

Authorization Code Grant

  1. The web app initiates the flow and redirects the browser to Auth0 (specifically to the /authorize endpoint), so the user can authenticate.

  2. Auth0 authenticates the user (via the browser). The first time the user goes through this flow a consent page will be shown where the permissions are listed that will be given to the Client (for example: post messages, list contacts, and so forth).

  3. Auth0 redirects the user to the web app (specifically to the redirect_uri, as specified in the /authorize request) with an Authorization Code in the querystring (code).

  4. The web app sends the Authorization Code to Auth0 and asks to exchange it with an access_token (and optionally an id_token and a refresh_token). This is done using the /oauth/token endpoint. When making this request, the web app authenticates with Auth0, using the Client Id and Client Secret.

  5. Auth0 authenticates the web app, validates the Authorization Code and responds back with the token.

  6. The web app can use the access_token to call the API on behalf of the user.

In OAuth 2.0 terms, the web app is the Client, the end user the Resource Owner, the API the Resource Server, the browser the User Agent, and Auth0 the Authorization Server.

How to implement the flow

For details on how to implement this using Auth0, refer to Executing an Authorization Code Grant flow.

Rules

Rules will run for the Authorization Code grant. If you wish to execute special logic unique to the Authorization Code grant, you can look at the context.protocol property in your rule. If the value is oidc-basic-profile, then the rule is running during the Authorization Code grant.

For details on how to implement this, refer to Execute an Authorization Code Grant Flow: Customize the Tokens.

Keep reading