Configuring Fusion for JWT

You can configure Fusion Server to use JSON Web Tokens (JWTs) for user authentication and authorization. Fusion can use a shared secret key between the issuer and Fusion to encrypt the JWT payload.

How the JWT realm works

The JWT realm uses an “Authorization” header in the request to authenticate the user and the data inside the JWT token for the authorization.

For JWTs, send a request with an “Authorization” header. This authorization header has a JWT token of the form:

Bearer <jwt-token>

The Fusion app then authenticates this token and emits a response accordingly.

Configure JWT for Fusion

To configure Fusion’s JWT realm, first create a JWT token. Then create a Fusion realm.

Create a JWT token

Using the tool you use to validate users, create a JWT token. The token should have following properties:

  • iss: Issuer value. If the issuer value does not match the one configured in Fusion, then the user will be denied access.

  • sub: Subject. The name/id of the user. The user is logged in by this name.

  • groups: The groups from the group-role mappings that this user belongs to. The groups key should match the one you specify while creating the JWT realm.

Example data inside token:

{
:iss “fusion-enterprise-app”
:iat (java.util.Date.)
:sub “username”
:groups [“group-1” “group-2”]
}

Note that groups is a vector.

Create the Fusion JWT realm

To create a Fusion realm, in the Fusion UI:

  1. Click System > Access Control.

  2. Click the Security Realms tab, then Add Security Realm.

  3. Enter a realm name. Under type, select jwt.

  4. Fill in the fields. Under JWT Realm, note the following:

    • JWT Issuer: This should match the value of iss in the token.

    • Signing key: Key with which the token is signed. The key must be a shared secret key. Leave empty if no signing key is used.

    • Group role mapping:

      1. Click Add new mapping. Two rows appear.

      2. In the first row, add a group. The JWT token contains the groups for a particular user.

      3. In the second row, add the role or roles (separated by spaces) for that group.

        map JWT groups to Fusion roles

  5. Click Save.

Validate the new realm

Now when you send a request to Fusion, you should receive a response. The request to Fusion looks like this:

curl http://127.0.0.1:8764/api/users -H 'authorization: Bearer <token-header>.<token-body>.<token-signing-key>'

Note that Bearer is case sensitive. If no signing key is used, truncate the last part after the dot.