Authorization Code grant

Adoption Guide

This document is part of the adoption guide for OIDC-conformant authentication. If you haven't already, we strongly suggest reading the introduction before reading this document.

The Authorization Code grant is used by server-side clients that are capable of securely storing secrets, or by native clients through PKCE. This document describes the differences of this flow between the legacy and OIDC-conformant authentication pipelines.

Authentication request

GET /authorize?
    response_type=code
    &scope=openid email favorite_color offline_access
    &client_id=123
    &state=af0ifjsldkj
    &redirect_uri=https://app.example.com/callback
    &device=my-device-name
GET /authorize?
    response_type=code
    &scope=openid email offline_access
    &client_id=123
    &state=af0ifjsldkj
    &redirect_uri=https://app.example.com/callback
    &audience=https://api.example.com 
  • favorite_color is no longer a valid scope value.
  • The device parameter is removed.
  • The audience parameter is optional.

Authentication response

The response from Auth0 is identical in both pipelines:

HTTP/1.1 302 Found
Location: https://app.example.com/callback?
    code=SplxlOBeZQQYbYS6WxSbIA
    &state=af0ifjsldkj

Code exchange request

An authorization code can be exchanged in the same way in both pipelines:

POST /oauth/token HTTP/1.1
Content-Type: application/json
{
    "grant_type": "authorization_code",
    "client_id": "123",
    "client_secret": "...",
    "code": "SplxlOBeZQQYbYS6WxSbIA",
    "redirect_uri": "https://app.example.com/callback"
}

Code exchange response

HTTP/1.1 200 OK
Content-Type: application/json
Cache-Control: no-store
Pragma: no-cache
{
    "access_token": "SlAV32hkKG",
    "token_type": "Bearer",
    "refresh_token": "8xLOxBtZp8",
    "expires_in": 3600,
    "id_token": "eyJ..."
}
  • The returned access token is only valid for calling the /userinfo endpoint.
  • A refresh token will be returned only if a device parameter was passed and the offline_access scope was requested.
HTTP/1.1 200 OK
Content-Type: application/json
Cache-Control: no-store
Pragma: no-cache
{
    "access_token": "eyJ...",
    "token_type": "Bearer",
    "refresh_token": "8xLOxBtZp8",
    "expires_in": 3600,
    "id_token": "eyJ..."
}
  • The returned access token is valid for optionally calling the API specified in the audience parameter and the /userinfo endpoint (provided that the API uses RS256 as the signing algorithm and openid is used as a scope parameter). If you are not implementing your own Resource Server (API), then you can use https://{$account.namespace}/userinfo as the audience parameter, which will return an opaque access token.
  • A refresh token will be returned only if the offline_access scope was granted.

ID token structure

{
    "sub": "auth0|alice",
    "iss": "https://YOUR_AUTH0_DOMAIN/",
    "aud": "123",
    "exp": 1482809609,
    "iat": 1482773609,
    "email": "alice@example.com",
    "email_verified": true,
    "favorite_color": "blue"
}
{
    "sub": "auth0|alice",
    "iss": "https://YOUR_AUTH0_DOMAIN/",
    "aud": "123",
    "exp": 1482809609,
    "iat": 1482773609,
    "email": "alice@example.com",
    "email_verified": true,
    "https://app.example.com/favorite_color": "blue"
}
  • The favorite_color claim must be namespaced and added through a rule.

Access token structure (optional)

SlAV32hkKG
{
    "sub": "auth0|alice",
    "iss": "https://YOUR_AUTH0_DOMAIN/",
    "aud": [
        "https://api.example.com",
        "https://YOUR_AUTH0_DOMAIN/userinfo"
    ],
    "azp": "123",
    "exp": 1482816809,
    "iat": 1482809609,
    "scope": "openid email"
}
  • The returned access token is valid for optionally calling the API specified in the audience parameter and the /userinfo endpoint (provided that the API uses RS256 as the signing algorithm and openid is used as a scope parameter). If you are not implementing your own Resource Server (API), then you can use https://{$account.namespace}/userinfo as the audience parameter, which will return an opaque access token.

Further reading