JSON Web Tokens and the Login API

    Overview

    JSON Web Tokens (or JWT for short - pronounced "jot") is a standard defined as RFC 7519 that provides a portable unit of identity. FusionAuth implements the JWT specification and can provide JWTs as part of the authentication workflows.

    If you are using OAuth grants for authentication, only the JWT signing configuration documentation applies.

    Much of this tutorial is aimed at those using the Login API, not the hosted login pages.

    For more on the OAuth grants and the tokens returned when using them, visit the OAuth documentation.

    After a User is authenticated via the Login API or OAuth, FusionAuth creates a JWT and returns it to the caller. This JWT will be cryptographically signed to allow other applications to verify that it was created by FusionAuth.

    Configuring JWTs in FusionAuth

    FusionAuth provides the ability to configure a couple of aspects of its JWT handling. By navigating to Settings → Tenants in FusionAuth and selecting the JWT tab, you will see the tenant JWT configuration settings.

    The following is an example screenshot of the tenant JWT configuration.

    Tenant Configuration - JWT

    JSON Web Token Settings

    JWT duration Required

    The length of time the issued token (access token and Id token) is valid. JWT tokens are typically short lived.

    Access token signing key Optional

    The key used to sign the access token JWT.

    Id token signing key Optional

    The key used to sign the Id token JWT.

    Refresh Token Settings

    Refresh token duration Required Defaults to 43,200

    The length of time the refresh token is valid. Refresh tokens are typically long lived.

    Refresh token expiration Optional defaults to Fixed

    The Refresh token expiration may be either a fixed or sliding window. By default the expiration of a refresh token is a fixed length of time from when it was originally issued. With a sliding window expiration, the expiration is calculated from the last time the refresh token was used.

    For instance, if a refresh token is issued at 1:00pm and has a duration of 60 minutes, if the expiration is fixed, the token will expire at 2:00pm. If, instead, the expiration is a sliding window, then if the refresh token is used at 1:55pm, it would then expire at 2:55pm. If it were then used at 2:50pm, it would expire at 3:50 pm.

    Refresh token usage Optional Defaults to Reusable

    The Refresh token usage may be reusable or one time use. By default, a token is reusable and the token does not change after it was issued. With a one time use token, the token value will be changed each time the token is used to refresh a JWT. This means the client must store the new value after each use.

    Refresh token revocation Optional

    The event or events that will cause refresh tokens to be revoked.

    Application Specific Configuration

    If you navigate to Applications from the main menu, you can also configure the JWT parameters, including the signing algorithm, on a per application basis. If you don’t select to enable Application specific JWT configuration, the tenant configuration will be used.

    The following is an example screenshot of an Application specific JWT configuration.

    Application Configuration - JWT

    JSON Web Token Settings

    Issuer Read-only

    The issuer used in the iss claim when building the Access Token and Id Token. This is a read-only value in this configuration. It can be modified in the Tenant configuration.

    JWT duration Required

    The duration in seconds for which a JWT will be valid after creation. After this time has passed the JWT will expire and can no longer be used.

    Access token signing key Optional

    The signing key used to sign the Access Token (which is a JWT) when a user authenticates against this Application. When this value is not selected, FusionAuth will generate a new key pair and assign it to this configuration.

    Id token signing key Optional

    The signing key used to sign the Id Token (which is a JWT) when a user authenticates against this Application. When this value is not selected, FusionAuth will generate a new key pair and assign it to this configuration.

    Application Configuration - Refresh Tokens

    Refresh Token Settings

    Refresh token duration Required Defaults to 43,200

    The length of time the refresh token is valid. Refresh tokens are typically long lived.

    Refresh token expiration Optional defaults to Fixed

    The Refresh token expiration may be either a fixed or sliding window. By default the expiration of a refresh token is a fixed length of time from when it was originally issued. With a sliding window expiration, the expiration is calculated from the last time the refresh token was used.

    For instance, if a refresh token is issued at 1:00pm and has a duration of 60 minutes, if the expiration is fixed, the token will expire at 2:00pm. If, instead, the expiration is a sliding window, then if the refresh token is used at 1:55pm, it would then expire at 2:55pm. If it were then used at 2:50pm, it would expire at 3:50 pm.

    Refresh token usage Optional Defaults to Reusable

    The Refresh token usage may be reusable or one time use. By default, a token is reusable and the token does not change after it was issued. With a one time use token, the token value will be changed each time the token is used to refresh a JWT. This means the client must store the new value after each use.

    Refresh token revocation Optional

    The event or events that will cause refresh tokens to be revoked.

    Lambda Settings

    The application specific lambda settings are available even if you choose not to enable additional application specific JWT configuration by leaving the Enable field off.

    Access token populate lambda Optional

    The lambda to be invoked during the generation of an Access Token (JWT) when a user authenticates against this Application.

    Id token populate lambda Optional

    The lambda to be invoked during the generation of an Id Token (JWT) when a user authenticates against this Application.

    Learn more about the JWT Populate Lambda.

    Configuring JWT Signing

    FusionAuth provides three configuration locations for JWT signing:

    • the tenant default values shown above

    • an Application level setting

    • with Entity Management, each entity type can have a unique key

    FusionAuth supports configurations for HMAC, ECDSA (Elliptic Curve) or RSA based signing algorithms.

    Keys are managed in Key Master and can be generated or imported there.

    ECDSA & RSA Signing

    If you are using FusionAuth in a hybrid environment where applications may be untrusted, asymmetric ECDSA or RSA signing is preferred.

    Using this approach allows you to provide applications with a public key to verify the JWT signature while securing the private key in FusionAuth.

    Only the party that holds the private key can produce JWTs. It is easier to know for certain who issued and signed the JWT. It will be FusionAuth.

    HMAC Signing

    If you are in a secure environment and you require better performance, symmetric HMAC signing is best.

    The downside of using HMAC signing is that each application requires access to the HMAC secret and you’ll need to ensure it is distributed safely.

    Anyone with the secret can both produce a JWT with a valid signature and verify the signature which makes it difficult to know for certain who issued and signed the JWT.

    Login and JWTs

    When you complete a request to the Login API, FusionAuth will return a JWT in the JSON response body as well as in an HTTP Only session cookie. The cookie has the benefit of allowing web applications to authenticate directly against FusionAuth and managing JWT identities through the browser. The cookie name that the JWT is returned in is called access_token.

    Here is an example of this Set-Cookie response header that includes a JWT with line breaks and spaces for readability.

    Example HTTP Cookie Header
    
Set-Cookie: access_token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.
                         eyJleHAiOjE0ODUxNDA5ODQsImlhdCI6MTQ4NTEzNzM4NCwiaXNzIjoiYWNtZS5jb20iLCJzdWIiOiIyOWFjMGMxOC0wYjRhLTQyY2YtODJmYy0wM2Q1NzAzMThhMWQiLCJhcHBsaWNhdGlvbklkIjoiNzkxMDM3MzQtOTdhYi00ZDFhLWFmMzctZTAwNmQwNWQyOTUyIiwicm9sZXMiOltdfQ.
                         Mp0Pcwsz5VECK11Kf2ZZNF_SMKu5CgBeLN9ZOP04kZo;
                         Secure; HttpOnly

    The JSON response body will also contain the JWT in an attribute called token like this:

    Example JSON Response Body with JWT
    
{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJleHAiOjE0ODUxNDA5ODQsImlhdCI6MTQ4NTEzNzM4NCwiaXNzIjoiYWNtZS5jb20iLCJzdWIiOiIyOWFjMGMxOC0wYjRhLTQyY2YtODJmYy0wM2Q1NzAzMThhMWQiLCJhcHBsaWNhdGlvbklkIjoiNzkxMDM3MzQtOTdhYi00ZDFhLWFmMzctZTAwNmQwNWQyOTUyIiwicm9sZXMiOltdfQ.Mp0Pcwsz5VECK11Kf2ZZNF_SMKu5CgBeLN9ZOP04kZo",
  "user": {
    "active": true,
    "email": "example@fusionauth.io",
    "expiry": 1571786483322,
    "id": "00000000-0000-0001-0000-000000000000",
    "lastLoginInstant": 1471786483322,
    "passwordChangeRequired": false,
    "passwordLastUpdateInstant": 1471786483322,
    "verified": true
  }
}

    Skipping JWT Creation

    There are some circumstances where you don’t need a JWT returned as part of the Login API response and therefore you can instruct FusionAuth to omit the JWT from the response. This will reduce the latency of calling the Login API because FusionAuth can skip the creation and signing of the JWT. To disable JWTs during authentication, supply the noJWT parameter in the JSON request body on the Login API.

    JWT Payload

    FusionAuth provides a few custom claims in addition to some registered claims as defined by RFC 7519 Section 4.1. The following claims will be found in a JWT issued by FusionAuth.

    Claims

    applicationId [UUID]

    The unique Id of the Application for which the User has been authenticated. A JWT can only represent authorization to a single Application.

    This claim is only present if the User has a registration to the Application.

    To obtain a JWT for another Application you must either authenticate again with a different applicationId using the Authentication API or utilize the Issue a JWT API to exchange a valid JWT for another.

    aud [String]

    The audience the JWT is intended for. This registered claim is defined by RFC 7519 Section 4.1.3.

    This claim will be equal to the client_id.

    authenticationType [String]

    The method used to authenticate the User which resulted in this JWT being generated. The possible values are:

    • APPLE - The User was authenticated using Apple. Available since 1.17.0

    • APPLICATION_TOKEN - The User was authenticated using an Application Authentication Token.

    • EpicGames -The User was authenticated using Epic Games.   Available since 1.28.0

    • FACEBOOK - The User was authenticated using Facebook.   Available since 1.1.0

    • FEDERATED_JWT - The User was authenticated using a JWT from an external Identity Provider.

    • GENERIC_CONNECTOR - The user was authenticated using a generic connector.   Available since 1.18.0

    • GOOGLE - The User was authenticated using Google. Available since 1.1.0

    • HYPR - The User was authenticated using the HYPR provider. Available since 1.12.0

    • JWT_SSO - A valid JWT authorized to one Application was exchanged for another JWT authorized to a different Application.

    • LDAP_CONNECTOR - The user was authenticated using an LDAP connector.   Available since 1.18.0

    • LINKEDIN - The user was authenticated using LinkedIn.   Available since 1.23.0

    • Nintendo - The User was authenticated using Nintendo.   Available since 1.36.0

    • ONE_TIME_PASSWORD The User was authenticated using a one time password.   Available since 1.5.0

    • OPENID_CONNECT - The User was authenticated using an external OpenID Connect provider. Available since 1.1.0

    • PASSWORD - The User was authenticated using a loginId and password combination.

    • PASSWORDLESS - The user was authenticated using a passwordless login link.   Available since 1.5.0

    • PING - The user was authenticated using a PUT request on the Login API. This is used to record a login event without prompting for credentials.

    • REFRESH_TOKEN - The User requested a new JWT using a Refresh Token.

    • REGISTRATION - The user was created using the Registration API.   Available since 1.16.0

    • SAMLv2 - The User was authenticated using an external SAMLv2 provider. Available since 1.6.0

    • SAMLv2IdpInitiated - The User was authenticated using an external SAMLv2 provider using an IdP Initiated login. Available since 1.28.0

    • SonyPSN - The User was authenticated using Sony Available since 1.28.0

    • Steam - The User was authenticated using Steam Available since 1.28.0

    • TWITTER - The User was authenticated using Twitter. Available since 1.1.0

    • Twitch - The User was authenticated using Twitch Available since 1.28.0

    • USER_CREATE - The user was created using the User API.   Available since 1.16.0

    • Xbox - The User was authenticated using Xbox Available since 1.28.0

    auth_time [Long] Available since 1.36.0

    The time of the initial authentication request, expressed as UNIX time which is the number of seconds since Epoch. This claim will remain the same even when the token has been re-issued through the use of a Refresh Token.

    email [String]

    The email address of the User whose claims are represented by this JWT.

    email_verified [Boolean]

    The OpenId Connect claim indicating if the User’s email has been verified.

    exp [Long]

    The expiration instant of the JWT, expressed as UNIX time which is the number of seconds since Epoch. This registered claim is defined by RFC 7519 Section 4.1.4.

    iat [Long]

    The instant that the JWT was issued, expressed as UNIX time which is the number of seconds since Epoch. This registered claim is defined by RFC 7519 Section 4.1.6.

    jti [String] Available since 1.18.0

    The unique identifier for this JWT. This registered claim is defined by RFC 7519 Section 4.1.7.

    iss [String]

    The issuer of the JWT. For FusionAuth, this is always the value defined in the tenant JWT configuration. This registered claim is defined by RFC 7519 Section 4.1.1.

    preferred_username [String] Available since 1.5.0

    The username of the User whose claims are represented by this JWT.

    roles [Array<String>]

    The roles assigned to the User in the authenticated Application. This claim is only present if the User has a registration to the Application.

    sid [String] Available since 1.37.0

    The unique Id of the refresh token returned along with this access token when the offline_access scope was requested. This unique Id is the persistent identifier for this refresh token, and will not change even when using one-time use refresh tokens. This value may optionally be used to revoke the token using the Refresh Token API.

    sub [UUID]

    The subject of the access token. This value is equal to the User’s unique Id in FusionAuth. This registered claim is defined by RFC 7519 Section 4.1.2.

    tid [UUID] Available since 1.36.0

    The FusionAuth Tenant unique Id.

    Example JWT

    Here is an example JWT that might be returned from FusionAuth:

    Example JWT
    
{
  "applicationId": "469b0ba1-a849-4603-883e-3b05c0d2b7ce",
  "aud": "469b0ba1-a849-4603-883e-3b05c0d2b7ce",
  "authenticationType": "PASSWORD",
  "email": "richard@fusionauth.io",
  "exp": 1504112919754,
  "iat": 1504103919754,
  "iss": "acme.com",
  "roles": [
    "role 1",
    "role 2"
  ],
  "sub": "6558c73f-b345-4917-9aac-0feab21eeeeb"
}

    Refresh Tokens

    Refresh tokens are a method of allowing a User to stay logged into an Application for a long period of time without requiring them to type in their password. This method is often used by Applications that don’t store sensitive data such as games and social networks.

    To receive a refresh token from the Login API, enable Refresh Tokens for the application. Using the FusionAuth UI, navigate to Settings → Applications → Security Tab. Here you will find the Login API settings. Ensure that both Generate Refresh Tokens and Enable JWT refresh fields are enabled.

    FusionAuth provides refresh tokens in the response from the Login API provided that you supply these elements:

    • loginId - the User’s login Id

    • password - the User’s password or Authentication Token

    • applicationId - the identifier for the Application the user is logging into

    If all of these attributes are supplied to the Login API then FusionAuth will produce a refresh token.

    If any of the required elements are missing, no refresh token will be generated.

    The refresh token will be returned in the JSON in the response body as well as in a cookie header. The refresh token will be in a parameter called refreshToken in the JSON response and the HTTP Only persistent cookie will be named refresh_token.

    Here is an example of this Set-Cookie response header for a refresh token.

    Example HTTP Cookie Header
    
Set-Cookie: refresh_token=eu1SsrjsiDf3h3LryUjxHIKTS0yyrbiPcsKF3HDp; Max-Age=2592000; Expires=Fri, 29-Sep-2017 15:20:24 GMT; Secure; HttpOnly

    Here is an example of the JSON response body that contains the refresh token:

    Example JSON with Refresh Token
    
{
  "refreshToken": "eu1SsrjsiDf3h3LryUjxHIKTS0yyrbiPcsKF3HDp",
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJleHAiOjE1MDQxMDY0ODQsImlhdCI6MTUwNDEwNjQyNCwiaXNzIjoiaW52ZXJzb2Z0LmNvbSIsInN1YiI6ImUzMDIzMmZiLTIxN2EtNDllYi1iN2QxLTI5YzhhNWVmZmM1YiIsImFwcGxpY2F0aW9uSWQiOiIzYzIxOWU1OC1lZDBlLTRiMTgtYWQ0OC1mNGY5Mjc5M2FlMzIiLCJhdXRoZW50aWNhdGlvblR5cGUiOiJQQVNTV09SRCIsInJvbGVzIjpbImFkbWluIl19.eNF4F0iT8qUtyr3kb_-RSM-jibaP0w-419sD94N3Gkk",
  "user": {
    "active": true,
    "email": "example@fusionauth.io",
    "expiry": 1571786483322,
    "id": "00000000-0000-0001-0000-000000000000",
    "lastLoginInstant": 1471786483322,
    "passwordChangeRequired": false,
    "passwordLastUpdateInstant": 1471786483322,
    "verified": true
  }
}

    Refresh Tokens are considered sensitive information. The token must be secured on the User’s device. If a Refresh Token is compromised, the token bearer may perform authenticated requests on behalf of the User.

    Once you have a refresh token on the device, you can call the Refresh a JWT API to get a new JWT from FusionAuth using the refresh token. Using this pattern allows you to perform authenticated actions using the JWT without prompting the User to authenticate as long as the refresh token is active.

    Feedback

    How helpful was this page?

    See a problem?

    File an issue in our docs repo

    Have a question or comment to share?

    Visit the FusionAuth community forum.