OAuth2.0 - JWT Bearer Flow

Overview

The JWT bearer grant type (RFC7523) allows a client application to exchange a JSON Web Token (JWT) for an access token. The JWT contains information about the user's identity, such as their name, email address, and other attributes. The client application sends the JWT to the Safewhere Identify, which validates the JWT and returns an access token to the client application.

OpenId Connect Discovery endpoint

The OpenID Connect Discovery endpoint now contains a new supported grant type: urn:ietf:params:oauth:grant-type:jwt-bearer in the grant_types_supported property:

  "grant_types_supported": [
    ...
    "urn:ietf:params:oauth:grant-type:jwt-bearer"
  ],

Configuration

To use the JWT bearer grant type in Safewhere Identify, you need to configure the OAuth connection by following these steps:

  1. Open the existing OAuth/OIDC application.
  2. Go to its Security tab and enable the Allow JWT bearer flow.

allow-jwt-bearer-flow

  1. Validate tokens from trusted issuers

The JWT bearer grant type supports the token signed by RSA or HMAC keys. To validate tokens form trusted issuers, depending on the signing algorithm, you can add trusted issuers as follows:

Bootstrap token trusted issuers

Go to the Connection tab and add a Bootstrap token trusted issuer.

  • Issuer: The iss (issuer) value of the applied JWT assertion.
  • Find Value: The certificate thumbprint to validate the signing of the applied JWT assertion. Note that Bootstrap token trusted issuers do not allow duplicated certificate thumbprints.

jwt-bootstrap-token-trusted-issuer

Issuer symmetric signing keys

Similar to the Bootstrap token trusted issuer, you can add a list of Issuer symmetric signing keys to validate the tokens signed by symmetric keys:

  • Issuer: The iss (issuer) value of the applied JWT assertion.
  • Symmetric signing key: The symmetric key to validate the signing of the applied JWT assertion. Note that Issuer symmetric signing keys do not allow duplicated key.

jwt-issuer-symmetric-signing-key

  1. Assertion validation options

You can also enable additional JWT assertion validation options:

  • Validate target audience: When enabled, the aud (audience) claim of the applied JWT assertion must contain the Safewhere Identify endpoint (https://#identifydomain/runtime/oauth2 or "https://#identifydomain/runtime/oauth2/token.idp).
  • Detect replay attack when doing token exchange: When enabled, the Safewhere Identify performs replay attack detection for every token request.

other-settings

  • Signing certificate revocation check: When the selected value is not None, Safewhere Identify performs a revocation check for the signing certificate used to sign the JWT assertion.

Ask for a token

Perform a POST operation to the token endpoint:

https://#identifydomain/runtime/oauth2/token.idp

With the following parameters:

Parameter Description
client_id Your application's client ID
client_secret Your application's client secret
grant_type This must be "urn:ietf:params:oauth:grant-type:jwt-bearer"
assertion {JWT assertion}

The {JWT assertion} is the JSON Web Token that you received from your JWT identity provider.

Request body example:

Key Value
client_id test_client_id
client_secret test_client_secret
grant_type urn:ietf:params:oauth:grant-type:jwt-bearer
assertion eyJhbGciOiJSUzI1NiIsImtpZCI6IjBOYkZjNmpTRHE5OXJDMC1TTE9WbjIwVUN2RSIsIng1dCI6IjBOYkZjNmpTRHE5OXJDMC1TTE9WbjIwVUN2RSIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJ1c2VyMDAiLCJzY29wZSI6ImlkZW50aWZ5KnNjaW0iLCJ1bmlxdWVfbmFtZSI6InVzZXIwMCIsInVybjppZGVudGlmeTpyZXN0LWFwaTpyb2xlIjoiQWRtaW5pc3RyYXRvciIsInJvbGUiOlsiQ2xhaW1BZG1pbiIsIkdyb3VwQWRtaW4iLCJPcmdhbml6YXRpb25BZG1pbiIsIlVzZXJBZG1pbiJdLCJuYW1lIjoidXNlcjAwIiwidXJuOmludGVybmFsOnVzZXJpZCI6IjliYTdlZjdjLTZjZDItNGU3ZC1hOGFmLTliYmQxZDI1MDNhMyIsInRva2VuX3VzYWdlIjoiYWNjZXNzX3Rva2VuIiwianRpIjoiNmE4OGYyMzYtMGRmMC00ODRlLWFhNDktMmQxMjJhM2M4ZTYzIiwiYXVkIjoiaHR0cHM6Ly9pZGVudGlmeTAxdjUxNGNsaTQtdGVzdC5pZGVudGlmeS5zYWZld2hlcmUuY29tL3J1bnRpbWUvIiwiYXpwIjoib2F1dGgyX2NvZGVmbG93X3Jlc3RhcGlfdG9rZW5fOGE0YjlhMjktNDllMC1kODU4LWIwMzgtOTQ5OTZlNjU4MGIwIiwiaWF0IjoxNjg0NDc5NDIxLCJuYmYiOjE2ODQ0Nzk0MjEsImV4cCI6MTY4NDQ4MzAyMSwiaXNzIjoiaHR0cHM6Ly9pZGVudGlmeTAxdjUxNGNsaTQtdGVzdC5pZGVudGlmeS5zYWZld2hlcmUuY29tL3J1bnRpbWUvb2F1dGgyIn0...

If the request is valid, Safewhere Identify returns an access_token.

{
    "token_type": "Bearer",
    "access_token": "eyJhbGciOiJSUzI1NiIsImtpZCI6ImtvQzdSbEFiZ09weWMzX1VrdHU0ZUI4cTV4QSIsInR5cCI6IkpXVCJ9.eyJ1bmlxdWVfbmFtZSI6InVzZXIwMCIsInN...WwuaWRlbnRpZnkwMXY1MTVmcmUuaWRlbnRpZnkuc2FmZXdoZXJlLmNvbS9ydW50aW1lLyIsImF6cCI6InJmY183NTIzX2F1dGhvcml6YXRpb24ifQ.GcfucBCJi45P7QI9dm6incRvRlcxu2_P...8VH45Vfl4eecdxZjy_KnBkmBxYRnqwAaAkcbCZy2qkg8n856g0kUBo-X9vtbJsI8JASGlop1XwcCV86SxntvbhAtNzpLifqoK5rVVo_DGsWh3wsKucA6R",
    "expires_in": 3600
}

If the request is invalid, you might encounter an error with one of the following event IDs:

  • Event ID 4934: This error occurs when the validation of the input JWT token fails.
  • Event ID 4935: This warning occurs when the Bootstrap token trusted issuers or Issuer symmetric signing keys on the OAuth Connection are improperly configured, leading to issues such as the inability to load the certificate or an invalid symmetric signing key.

For successful validation:

  • Event ID 4936: This information event ID indicates that the token issuer from the JWT token has been successfully validated.