Terminology

OAuth 2.0 - Common workflow

  1. The client submits an authorization request to the server, which validates that the client is a legitimate client of its service.​
  2. The server redirects the client to the content provider to request access to its resources.​
  3. The content provider validates the user's identity, and often requests their permission to access the resources.​
  4. The content provider redirects the client back to the server, notifying it of success or failure. This request includes an authorization code on success.​
  5. The server makes an out-of-band request to the content provider and exchanges the authorization code for an access token.

Token management

Authorization code

This is a short-lived token representing the user's access grant, created by the authorization server and passed to the client application via the browser. The client application sends the authorization code to the authorization server to obtain an access token and, optionally, a refresh token.​

Access token

This is used by the client to make authenticated requests on behalf of the end-user​. It complies with the JWT profile and contains information about the client and the user (if present). The access token is also used to call the userinfo.idp endpoint to request additional user claims.

Sample access token header:

{
  "alg": "RS256",
  "kid": "Yp4D6PrFwzU5B2WYR7sjNoMkg0c",
  "x5t": "Yp4D6PrFwzU5B2WYR7sjNoMkg0c",
  "typ": "at+jwt"
}

If you're using a version older than 5.17, the typ header will be set to JWT.

To change it back to JWT, you can add a setting called header_typ in the OAuth/OIDC application and set its value to JWT.

oauth-header-typ

The following claims can be included within the access token content:

  • iss: Identifies the principal (https://#identifydomain/runtime/oauth2) that issued the access token.
  • exp: Indicates the expiration time after which the access token must not be accepted.
  • aud: Specifies the recipients that the access token is intended for.
  • sub: Indicates the principal subject of the access token.
  • client_id: Indicates the OAuth 2.0 client that requested the token.
  • iat: Indicates the time at which the access token was issued.
  • jti: Indicates a unique identifier for the access token, which can be used to prevent token replay.

Access tokens used to access the Identify REST API have two required claims:

  • urn:identify:rest-api:role: Specifies the user authorization for calling the Identify REST API.
  • urn:internal:userid: identifies the Identify user ID, which is required by some Identify REST API methods.

Sample access token payload:

{
  "sub": "testuser1",
  "scope": "identify*scim",
  "nameid": "testuser1",
  "unique_name": "testuser1",
  "urn:identify:rest-api:role": "Administrator",
  "urn:internal:userid": "6256637f-f7ad-4579-bbe9-db1af733b81a",
  "token_usage": "access_token",
  "client_id": "oauth2_codeflow_restapi_token_0c6fde2d-53a1-cd26-b8c5-7ea73738dde3",
  "jti": "3fe9bfd1-b537-488b-a745-9c07273f1c36",
  "aud": "https://identify.safewhere.com/runtime/",
  "azp": "oauth2_codeflow_restapi_token_0c6fde2d-53a1-cd26-b8c5-7ea73738dde3",
  "iat": 1718677764,
  "nbf": 1718677764,
  "exp": 1724984964,
  "iss": "https://identify.safewhere.com/runtime/oauth2"
}

Refresh token

This is to obtain a new access token, which has a longer lifetime than the current access token for security reasons.

ID token

The ID token is an assertion of the end user's authentication state that the authentication server makes to the client. That is, an ID token can be considered proof that a specific user is logged in. The client application uses ID Token to log the user in on its side and is not used against any resource servers. It's also worth noting that ID token is used for SLO too.

Sample ID token:

{
  "sub": "testuser1",
  "uiId": "926afe2b-ed9d-4f44-b8a1-a8a11e106f18",
  "token_usage": "identity_token",
  "jti": "2a7088c9-0f0a-4ac0-9e75-57d571ef07c2",
  "aud": [
    "aspnetcore20200220",
    "https://identify.safewhere.com/runtime/"
  ],
  "at_hash": "JcfRYbw_VzftOp_LN03_1Q",
  "azp": "aspnetcore20200220",
  "iat": 1582625106,
  "nbf": 1582625106,
  "exp": 1582628706,
  "iss": "https://identify.safewhere.com/runtime/oauth2"
}

Note: when doing the logout, there's validation on the ID token audience against client_id field.