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.

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.

If you are using OAuth grants for authentication, with the exception of the JWT signing configuration, most of this tutorial is aimed at those using the Login API directly.

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.

Global JWT Configuration

Form Fields

Refresh token duration Required defaults to 43200 or 30 days

The length of time in minutes a Refresh Toke is considered valid. See Refresh Tokens below for additional information.

JWT duration Required defaults to 60 or 1 minute

The length of time in seconds before a JWT expires.

Access token signing key defaults to HMAC using SHA-256

The selected key will be used to sign the access token JWT, see Key Master settings to add or manage keys.

  • ECDSA using SHA-256 Available since 1.4.0

  • ECDSA using SHA-384 Available since 1.4.0

  • ECDSA using SHA-512 Available since 1.4.0

  • HMAC using SHA-256

  • HMAC using SHA-384

  • HMAC using SHA-512

  • RSA using SHA-256

  • RSA using SHA-384

  • RSA using SHA-512

Id token signing key defaults to HMAC using SHA-256

The selected key will be used to sign the Id token JWT, see Key Master settings to add or manage keys.

  • ECDSA using SHA-256 Available since 1.4.0

  • ECDSA using SHA-384 Available since 1.4.0

  • ECDSA using SHA-512 Available since 1.4.0

  • HMAC using SHA-256

  • HMAC using SHA-384

  • HMAC using SHA-512

  • RSA using SHA-256

  • RSA using SHA-384

  • RSA using SHA-512

Configuring JWT Signing

FusionAuth provides two levels of configuration for JWT signing, the global default values shown above, and then each Application has the option to override these default values and define their own.

From the global JWT configuration page, you can configure the global JWT signing algorithm and keys. FusionAuth supports configurations for HMAC, ECDSA or RSA based signing algorithms.

ECDSA & RSA Signing

If you are using FusionAuth in a hybrid environment where some applications are trusted while others are not, ECDSA or RSA signing is preferred. This allows you to provide those applications with the public key to verify the JWT signature while securing the private key inside FusionAuth.

This means that only one party holds the private key can is able to produce a JWTs, and it is easier to know for certain who issued and signed the JWT.

HMAC Signing

On the other hand, if you are in a secure environment and you require better performance, HMAC is a better solution. The downside of using HMAC signing is that each application that has access to the HMAC secret. 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.

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 global algorithm configuration will be used.

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

Application JWT Configuration

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:

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

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

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

  • ONE_TIME_PASSWORD The User was authenticated using a one time password.   Available since 1.5.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

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

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

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

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

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

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

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

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

iss [String]

The issuer of the JWT. For FusionAuth, this is always the value defined in the global 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 who 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.

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

Example JWT

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

Example JWT
{
  "applicationId": "00000000-0000-0000-0000-000000000000",
  "authenticationType": "PASSWORD",
  "email": "example@fusionauth.io",
  "exp": 1504112919754,
  "iat": 1504103919754,
  "iss": "acme.com",
  "roles": [
    "role 1",
    "role 2"
  ],
  "sub": "00000000-0000-0001-0000-000000000000"
}

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. 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. The refresh token will be returned in the JSON in the response body as well as in a 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.

You will also need to verify that you have enabled Refresh Tokens for the application. Using the FusionAuth UI, navigate to Settings → Applications → Security Tab. Here you will find the Login API settings. Verify this application is configured to generate and use refresh tokens.

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
  }
}

Note: 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.