JWT Authentication Definition

A JWT provider lets an upstream token issuer authenticate a Fudo Enterprise user on the request’s behalf. When a request carries a signed JWT in a configured HTTP header, Fudo Enterprise verifies the token signature against the public keys published by the issuer, checks the standard claims, and maps a claim from the token to an existing user account. The user is not asked for a password and no Fudo Enterprise session is established beforehand — the token is the credential presented with every request.

Warning

The user name carried by the token is mapped directly to a Fudo Enterprise user account, and Fudo Enterprise relies on the issuer to assert that name. Unlike the interactive OpenID Connect login, the account is not bound to the provider that authenticated it. Configure a JWT provider only for an issuer that your organization controls.

Note

The user account has to exist in Fudo Enterprise before the first request that carries a token. The account is not created automatically — it is usually synchronized from an Active Directory or LDAP service. Refer to the Users Synchronization - User Directory section to learn more.


Follow the steps to configure the JWT authentication method:

  1. Select Settings > Authentication.

  2. Open the JWT Providers tab and click Add JWT provider.

  3. Check the Enabled option to activate this provider.

  4. Provide Name.

  5. In the General section, input Issuer — the exact value of the iss claim that tokens from this issuer carry.

  6. Provide Audience — the exact value of the aud claim.

  7. Optionally, provide JWKS URI — the address of the issuer’s JWKS document.

  8. Provide Token header — the name of the HTTP header that carries the token.

  9. In the Authentication domain section, enter the Domain that this provider will authenticate against.

  10. In the Mappings section, provide Username claim — the token claim that carries the user name.

  11. Click Save.

Note

The values required by the configuration come from the token issuer:

  • Issuer and JWKS URI can be read from the issuer’s OpenID configuration document, available at <issuer address>/.well-known/openid-configuration - they correspond to its issuer and jwks_uri fields.

  • Audience is decided on the issuer’s side, when the issuing of tokens for Fudo Enterprise is configured there. It is usually the identifier of the application registered for Fudo Enterprise. The same value has to be entered in this field.

  • Token header follows from the WAF configuration - it is the header into which the WAF injects the token.

  • Username claim depends on which claim the issuer fills with the user name.

../../_images/6-2-jwt-provider.png

Note

  • Issuer must start with https:// and must be unique among providers. Fudo Enterprise uses it to decide which provider a token belongs to, so it has to match the iss claim exactly.

  • Audience is mandatory. A token whose aud claim does not match, or which carries no aud claim at all, is rejected. This prevents a token issued for another service by the same issuer from being accepted.

  • Leave JWKS URI empty to have Fudo Enterprise discover the key set from the issuer’s OpenID configuration, at <issuer>/.well-known/openid-configuration. When set, the address must start with https://.

  • Token header is Authorization by default. Set a custom header, for example X-JWT-Assertion, when the token is injected by a WAF. A token is accepted only from the header configured on an enabled provider, and the Bearer prefix is optional.

  • Domain narrows the search for the user account to the users of that domain. The field is optional.

  • Username claim is sub by default. Provide a different claim when the issuer does not carry the user name there — with Microsoft Entra ID, for example, sub holds an opaque identifier, so use preferred_username or upn instead.

Editing a JWT Provider

To edit a JWT provider definition, proceed as follows.

  1. Select Settings > Authentication.

  2. Open the JWT Providers tab and click the name of the provider you want to edit.

  3. Modify the definition as needed.

  4. Click Save.

Note

Changing Issuer, JWKS URI or Token header, as well as enabling a provider, makes Fudo Enterprise fetch the signing keys of that provider again.

Deleting a JWT Provider

To delete a JWT provider definition, proceed as follows.

  1. Select Settings > Authentication.

  2. Open the JWT Providers tab.

  3. Select the providers you want to delete and click Delete.

Note

Requests carrying a token issued by a deleted provider are no longer accepted.

Signing Keys

Fudo Enterprise fetches the public keys used to verify token signatures on its own, over HTTPS, either from the address given in JWKS URI or through the issuer’s OpenID configuration. Keys are never uploaded to Fudo Enterprise.

The keys are refreshed automatically, once an hour, so a key rotated at the issuer is picked up without any action in the Admin Panel.

The JWT Providers list shows the number of keys currently held for each provider. To fetch them again immediately, click Refresh keys above the list. The keys of every configured provider are fetched, not only of the one selected on the list.

Warning

Every node of a cluster fetches the signing keys on its own, and the fetched keys are not transferred between nodes. The JWKS URI address, or the issuer’s OpenID configuration, has to be reachable from every node of the cluster.

Requirements for the Token Issuer

Fudo Enterprise does not issue the tokens it accepts, so the following has to be set up on the side of the issuer.

Note

  • The signature algorithm must be RS256, RS384, RS512, ES256, ES384, ES512 or EdDSA. Tokens signed with a shared secret (HS256 and similar) and unsigned tokens are rejected, because Fudo Enterprise verifies the signature with a public key that it fetched from the issuer.

  • Encrypted tokens are not supported. Fudo Enterprise accepts a signed token in the compact serialization form, that is header.payload.signature, so when the identity provider issues an encrypted token, the WAF has to pass on its signed form.

  • The exp claim is required, and the claim configured as Username claim has to be present. The nbf claim is optional. A difference of up to 30 seconds between the clock of Fudo Enterprise and the clock of the issuer is tolerated for exp and nbf.

  • When the issuer publishes more than one key, it is worth setting the kid header, as Fudo Enterprise then selects the key by its identifier. This matters while an issuer rotates its keys and publishes the old and the new one at the same time.

  • A token must not exceed 8192 bytes. Adding many claims, for example a long list of groups, can cross that limit.

Logging In

When a request to the Admin Panel or to the Access Gateway carries a valid token, the login screen is skipped and the requested page opens right away.

Note

  • The authentication methods configured on the user account, such as a password, OATH or DUO, are not used on this path. The assurance of the sign-in is entirely the one provided by the issuer, so multi-factor authentication has to be enforced by the issuer and not by Fudo Enterprise.

  • The user name carried by the token is matched against user accounts regardless of letter case.


Related topics: