Implicit 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 Implicit grant is used by clients that are incapable of securely storing secrets, such as single-page JavaScript applications. This document describes the differences of this flow between the legacy and OIDC-conformant authentication pipelines.

Authentication request

GET /authorize?
    response_type=token
    &scope=openid email favorite_color offline_access
    &client_id=123
    &state=af0ifjsldkj
    &redirect_uri=https://app.example.com
    &device=my-device-name
GET /authorize?
    response_type=token id_token
    &scope=openid email
    &client_id=123
    &state=af0ifjsldkj
    &nonce=jxdlsjfi0fa
    &redirect_uri=https://app.example.com
    &audience=https://api.example.com 
  • This response_type parameter indicates that we want to receive both an access token and ID token.
  • Refresh tokens are not allowed in the implicit grant. Use prompt=none instead.
  • favorite_color is no longer a valid scope.
  • The audience parameter is optional.
  • The nonce parameter must be a cryptographically secure random string.

Authentication response

HTTP/1.1 302 Found
Location: https://app.example.com/#
    access_token=SlAV32hkKG
    &expires_in=86400
    &state=af0ifjsldk
    &id_token=eyJ...
    &refresh_token=8xLOxBtZp8
    &token_type=Bearer
  • The returned access token is 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 302 Found
Location: https://app.example.com/#
    access_token=eyJ...
    &expires_in=86400
    &state=af0ifjsldk
    &id_token=eyJ...
    &token_type=Bearer
  • The returned access token is valid for calling the /userinfo endpoint (provided that the API specified by the audience param uses RS256 as signing algorithm) and optionally the resource server specified by the audience parameter.
  • If using response_type=id_token, Auth0 will only return an ID token.
  • Refresh tokens are not allowed in the implicit grant. Use prompt=none instead.

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",
    "nonce": "jxdlsjfi0fa"
}

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 a JWT valid for calling the /userinfo endpoint(provided that the API specified by the audience param uses RS256 as signing algorithm) as well as the resource server specified by the audience parameter.
  • Note that an opaque access token could still be returned if /userinfo is the only specified audience.

Further reading