OIDC/OAuth authentication and authorization flows and resource server API protection

Use this page to understand the OIDC and OAuth endpoints that work with Entrust Identity as a Service Authentication API integrations.

The following defines the various OIDC and OAuth flows and endpoints to acquire access tokens that can be used with resource servers.

Security feature support

The following flows and endpoints support Proof Key for Code Exchange (PKCE), Pushed Authorization Requests (PAR), JWT Secured Authorization Request (JAR), or Demonstrating Proof of Possession (DPoP):

Flow or endpoint	Supported features
Authorization code flow	PKCE, PAR, JAR, DPoP
Authorization JWT grant flow	PKCE, DPoP
Device code flow	DPoP
Token endpoint	PKCE, DPoP
Userinfo endpoint	DPoP
Revocation endpoint	DPoP
PAR endpoint	PKCE, JAR, DPoP

Query and form examples show decoded field values one per line. URL-encode them when constructing a URL or an application/x-www-form-urlencoded request body.

OIDC/OAuth authorization endpoint

The OIDC/OAuth authorization endpoint https://customer.region.trustedauth.com/api/oidc/authorize can be used for both OIDC authentication and OAuth authorization tokens.

• Method: GET or POST
• Path: /api/oidc/authorize

The following examples use query parameters with GET.

OIDC authentication

Use OIDC authentication to obtain ID tokens, access tokens for userinfo data, and refresh tokens.

Example query parameters

response_type=code
client_id=dba4e3c6-f1f3-4d23-9088-fb452064c73f
redirect_uri=https://app.example.com/callback
scope=openid profile offline_access
state=<state>
code_challenge=<pkce-code-challenge>
code_challenge_method=S256

The scope parameter must include openid. Include additional OIDC scope values (for example, profile) to specify which userinfo data to return. Include offline_access to obtain a refresh token.

The optional parameters acr_values and max_age can also be used. The example enables PKCE with code_challenge and code_challenge_method.

The OAuth consent page displays the user ID and the application name associated with the generated tokens.

OAuth2 authorization

Use OAuth2 authorization to obtain an access token for a resource server. Add OIDC scopes when the same request must also authenticate the user.

Example query parameters

response_type=code
client_id=dba4e3c6-f1f3-4d23-9088-fb452064c73f
redirect_uri=https://app.example.com/callback
resource=https://example.com/apis/calendar
scope=view:calendar edit:calendar
state=<state>
code_challenge=<pkce-code-challenge>
code_challenge_method=S256

The resource parameter identifies the resource server API for which an OAuth2 JWT access token is requested. You can also use the audience parameter instead.

Include resource server scope values to specify which scopes are requested, or use all_scopes to request all scopes for the identified resource server. To combine OAuth authorization with OIDC authentication, add openid and any additional OIDC scopes. Add offline_access when a refresh token is required.

The optional parameters acr_values and max_age can also be used. The example enables PKCE with code_challenge and code_challenge_method.

The OAuth consent page displays the user ID, the application name, the resource server API name, and the resource server scope names associated with the generated tokens.

Example response

After successful authentication and consent, IDaaS redirects the user agent to the registered redirect_uri with an authorization code and the original state value:

https://app.example.com/callback?code=<authorization-code>&state=<state>

OIDC/OAuth JWT IDaaS workflow

OIDC/OAuth authorization JWT endpoint

Use the OIDC/OAuth Authorization JWT endpoint https://customer.region.trustedauth.com/api/oidc/authorizejwt to initiate OIDC authentication and OAuth authorization token requests with the JWT IDaaS flow.

• Method: GET or POST
• Path: /api/oidc/authorizejwt
• Content type for POST: application/x-www-form-urlencoded

OIDC authentication

Use OIDC authentication to obtain ID tokens, access tokens for userinfo data, and refresh tokens.

Example request body

client_id=dba4e3c6-f1f3-4d23-9088-fb452064c73f
scope=openid profile offline_access
code_challenge=<pkce-code-challenge>
code_challenge_method=S256

The client_id parameter must be included to identify the client application.

The scope parameter must include openid. Include additional OIDC scope values (for example, profile) to specify which userinfo data to return. Include offline_access to obtain a refresh token.

The optional parameters acr_values and max_age can also be used. The example enables PKCE with code_challenge and code_challenge_method.

OAuth2 authorization

Use OAuth2 authorization to obtain an access token for a resource server. Add OIDC scopes when the same request must also authenticate the user.

Example request body

client_id=dba4e3c6-f1f3-4d23-9088-fb452064c73f
resource=https://example.com/apis/calendar
scope=view:calendar edit:calendar
code_challenge=<pkce-code-challenge>
code_challenge_method=S256

The resource parameter identifies the resource server API for which an OAuth2 JWT access token is requested by a client application on behalf of a user. You can also use the audience parameter instead.

The scope parameter should include resource server scope values to specify which scopes are requested for the identified resource server API. You can also include all_scopes to request all scopes the user has access to for that resource server API, if this option is enabled for the resource server.

To combine OAuth authorization with OIDC authentication, add openid and any additional OIDC scopes. Add offline_access when a refresh token is required.

The optional parameters acr_values and max_age can also be used. The example enables PKCE with code_challenge and code_challenge_method.

No consent page

There is no consent page because Entrust Identity as a Service does not control the authentication UI in this flow.

Example response body

After submitting an OIDC or OAuth2 request, the endpoint returns the Authentication API application ID and an authRequestKey that connects the Authentication API calls to the OIDC/OAuth request.

{
  "authRequestKey": "<auth-request-key>",
  "applicationId": "11111111-1111-1111-1111-111111111111"
}

After you receive this response, call the Authentication APIs sequentially. The following example uses the OTP authenticator.

Get the user's authenticators

After you receive a successful response, retrieve the user's available authenticators for application sign-in.

• Method: POST
• Path: /api/web/v2/authentication/users
• Content type: application/json

The request body should include a JSON object with userId (the user ID or a user alias value) and the authRequestKey from the Authorization JWT endpoint response. applicationId is optional in this case.

For a new authentication, do not include authToken. To reuse an existing IDaaS session, include its IDaaS JWT as authToken. This is required when max_age must evaluate the age of an existing authentication.

Example request body

{
  "userId": "jsmith",
  "authRequestKey": "<auth-request-key>"
}

For reauthentication, add the existing IDaaS JWT:

{
  "userId": "jsmith",
  "authRequestKey": "<auth-request-key>",
  "authToken": "<previous-idaas-jwt>"
}

Example response body

{
  "authenticationTypes": ["OTP", "TOKEN"],
  "otpDeliveryInfo": {
    "otpDefaultDelivery": "SMS",
    "availableOTPDelivery": ["SMS", "EMAIL", "VOICE"]
  }
}

When an existing session requires reauthentication, the response also contains a new token and its expires value. Pass that token as authToken in the Select Authenticator request.

The authenticator types in this response can be used to complete an authentication challenge and sign in.

authenticationTypes lists the authenticators assigned to the user that can be used for first-factor authentication.

availableSecondFactor lists the authenticators that can be used for second-factor authentication after a successful first-factor challenge.

IDaaS determines both authenticationTypes and availableSecondFactor by cross-referencing authenticators assigned to the user with authenticators allowed by the application's resource rule.

Select authenticator

If authentication is required, select an authenticator from the previous API response. This example requests an OTP challenge.

• Method: POST
• Path: /api/web/v2/authentication/users/authenticate/OTP
• Content type: application/json

Example request body

{
  "applicationId": "11111111-1111-1111-1111-111111111111",
  "userId": "jsmith"
}

For reauthentication, also include the token returned by Get User's Authenticators:

{
  "applicationId": "11111111-1111-1111-1111-111111111111",
  "userId": "jsmith",
  "authToken": "<query-response-token>"
}

Example response body

{
  "authenticationCompleted": false,
  "token": "<authentication-token>",
  "otpdeliveryType": "SMS"
}

Use the returned token to authorize the request that completes the challenge.

Complete authentication challenge

Complete the authentication challenge by submitting the user's response.

• Method: POST
• Path: /api/web/v1/authentication/users/authenticate/OTP/complete
• Content type: application/json

The request must include the end user's authentication response. For example, include the OTP value to complete an OTP challenge. The path must include the selected authenticator (for example, OTP). Add an Authorization header that contains the token value returned in the previous response. The example uses the Bearer type; the endpoint also accepts the token without a type value.

Example request header

Authorization: Bearer <authentication-token>

This request body should include applicationId and the authenticator response.

Example request body

{
  "applicationId": "11111111-1111-1111-1111-111111111111",
  "response": "123456"
}

When transaction details must be added to the access token, include both the original authRequestKey and the transactionDetails to add as claims. The resource server API must also be configured to include transaction claims:

{
  "applicationId": "11111111-1111-1111-1111-111111111111",
  "response": "123456",
  "authRequestKey": "<auth-request-key>",
  "transactionDetails": [
    {
      "detail": "Amount",
      "value": "10001",
      "usage": ["RBA"]
    }
  ]
}

Example response body

{
  "firstName": "John",
  "lastName": "Smith",
  "authenticationCompleted": true,
  "token": "<idaas-jwt>"
}

In the example above, authenticationCompleted is true because the response in the POST request is valid. The final step is to send a request to the token endpoint. See JWT IDaaS Grant Type.

OIDC/OAuth device code endpoint

The OIDC/OAuth device code endpoint https://customer.region.trustedauth.com/api/oidc/devicecode can be used to initiate both OIDC authentication and OAuth authorization tokens requests using the device code flow. The OIDC/OAuth device endpoint https://customer.region.trustedauth.com/api/oidc/device, returned in the device code endpoint response, can then be used to initiate user authentication using the device code flow.

• Method: POST
• Path: /api/oidc/devicecode
• Content type: application/x-www-form-urlencoded

The user-facing verification endpoint uses:

• Method: GET
• Path: /api/oidc/device
• Query parameter: user_code=<user-code>

OIDC authentication

Use OIDC authentication with the device code endpoint to obtain ID tokens, access tokens for userinfo data, and refresh tokens.

Example request body

client_id=dba4e3c6-f1f3-4d23-9088-fb452064c73f
scope=openid profile offline_access

The client_id parameter must be included to identify the client application.

The scope parameter must include openid. Include additional OIDC scope values (for example, profile) to specify which userinfo data to return. Include offline_access to obtain a refresh token.

The optional parameters acr_values and max_age can also be used.

The user must then initiate authentication by using the device endpoint in the device code endpoint response verification_uri together with the user_code.

Example response body

{
  "user_code": "DW-BVVB-LT",
  "device_code": "D8pDxpJtZoiTkJDjdwLAv0UHdS4tBF_OM5ejdn6PmJL4=",
  "interval": 5,
  "verification_uri_complete": "https://customer.region.trustedauth.com/api/oidc/device?user_code=DW-BVVB-LT",
  "verification_uri": "https://customer.region.trustedauth.com/api/oidc/device",
  "expires_in": 300
}

The OAuth consent page displays the user ID and application name associated with the generated tokens. It also displays a configurable, application-specific message that indicates consent is for a device.

OAuth2 authorization

Use OAuth2 authorization with the device code endpoint to obtain an access token for a resource server. Add OIDC scopes when the same request must also authenticate the user.

Example request body

client_id=dba4e3c6-f1f3-4d23-9088-fb452064c73f
resource=https://example.com/apis/calendar
scope=view:calendar edit:calendar

The client_id parameter must be included to identify the client application.

The resource parameter identifies the resource server API for which an OAuth2 JWT access token is requested by a client application on behalf of a user. You can also use the audience parameter instead.

The scope parameter should include resource server scope values to specify which scopes are requested for the identified resource server API. You can also include all_scopes to request all scopes for the identified resource server API.

To combine OAuth authorization with OIDC authentication, add openid and any additional OIDC scopes. Add offline_access when a refresh token is required.

The optional parameters acr_values and max_age can also be used.

The endpoint returns the same response fields as the OIDC authentication example. Direct the user to the returned verification_uri and provide the user_code.

The OAuth consent page displays the user ID, application name, resource server API name, and resource server scope names associated with the generated tokens. It also displays a configurable, application-specific message that indicates consent is for a device.

OIDC/OAuth token endpoint

The OIDC/OAuth token endpoint https://customer.region.trustedauth.com/api/oidc/token can be used for both OIDC authentication and OAuth authorization tokens.

• Method: POST
• Path: /api/oidc/token
• Content type: application/x-www-form-urlencoded

Authenticate the client using the method configured for the OIDC/OAuth application. For example, clients configured for HTTP Basic authentication send:

Authorization: Basic <base64(client_id:client_secret)>

Authorization code grant type

OIDC/OAuth authorization code grant is used to obtain various ID tokens, access tokens, and refresh tokens by including standard OIDC/OAuth parameters.

Example request body

grant_type=authorization_code
code=<authorization-code>
redirect_uri=https://app.example.com/callback
code_verifier=<pkce-code-verifier>

Device code grant type

OIDC/OAuth device code grant is used to obtain various ID tokens, access tokens, and refresh tokens by including standard OIDC/OAuth parameters.

Example request body

grant_type=urn:ietf:params:oauth:grant-type:device_code
device_code=<device-code>
client_id=dba4e3c6-f1f3-4d23-9088-fb452064c73f

Refresh token grant type

OIDC/OAuth refresh token grant is used to obtain new (updated expiry dates) access tokens and refresh tokens by including standard OIDC/OAuth parameters.

Example request body

grant_type=refresh_token
refresh_token=<refresh-token>

Client credentials grant type

OAuth client credentials grant is used to obtain server-based (i.e., non-user-based) access tokens by including standard OIDC/OAuth parameters.

Example request body

grant_type=client_credentials
resource=https://example.com/apis/calendar
scope=view:calendar edit:calendar

The resource parameter is used to identify the resource server API for which an access token is being requested by a client application (no user in this case). This value must be set using the resource parameter.

The scope parameter should include resource server scope values to specify which scopes are requested for the identified resource server API.

JWT IDaaS grant type

OIDC/OAuth JWT IDaaS grant is used to obtain various ID tokens, access tokens, and refresh tokens by including standard OIDC/OAuth parameters.

Example request body

grant_type=jwt_idaas
jwt=<idaas-jwt>
code=<auth-request-key>

The jwt parameter is the token obtained from Complete Authentication Challenge response. The code parameter is the authRequestKey obtained from Authorization JWT endpoint response.

Optionally, the org_id parameter can be used to return the org_id claim with a value set to the uuid of one of the organizations the user is associated with.

Example response body

The fields returned depend on the grant, scopes, and application configuration.

{
  "access_token": "<access-token>",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "<refresh-token>",
  "id_token": "<id-token>"
}

For the client credentials grant, the response contains an access token and does not contain an ID token or refresh token:

{
  "access_token": "<access-token>",
  "token_type": "Bearer",
  "expires_in": 3600
}

OIDC userinfo endpoint

The OIDC userinfo endpoint https://customer.region.trustedauth.com/api/oidc/userinfo can be used to obtain userinfo data with an OIDC access token.

• Method: GET or POST
• Path: /api/oidc/userinfo

Example request header

Authorization: Bearer <oidc-access-token>

For a DPoP-bound access token, send both the DPoP authorization scheme and a proof JWT created for this request:

Authorization: DPoP <oidc-access-token>
DPoP: <dpop-proof-jwt>

Example response body

{
  "sub": "jsmith",
  "name": "John Smith",
  "given_name": "John",
  "family_name": "Smith",
  "email": "jsmith@example.com"
}

OIDC/OAuth revocation endpoint

The OIDC/OAuth revocation endpoint https://customer.region.trustedauth.com/api/oidc/revoke can be used for revoking both OIDC authentication and OAuth authorization access tokens.

• Method: POST
• Path: /api/oidc/revoke
• Content type: application/x-www-form-urlencoded

Authenticate the client using the method configured for the OIDC/OAuth application.

For example, clients configured for HTTP Basic authentication send:

Authorization: Basic <base64(client_id:client_secret)>

Use the revocation endpoint to revoke an access token or refresh token.

Example request body

token=<access-token-or-refresh-token>
token_type_hint=refresh_token

The token parameter must include the access token or refresh token that is being revoked.

A successful revocation returns HTTP 200 with an empty response body.

For a DPoP-bound token, also send a DPoP proof JWT in the DPoP header.

OIDC/OAuth logout endpoint

The OIDC/OAuth logout (end session) endpoint https://customer.region.trustedauth.com/api/oidc/endsession can be used to log out of Entrust Identity as a Service sessions.

• Method: GET or POST
• Path: /api/oidc/endsession

The endpoint may be called without any parameters which will result in the user remaining at the Identity as a Service portal. Optionally, include redirect parameters to return the user to the calling client application.

Example query parameters

post_logout_redirect_uri=https://app.example.com/signed-out
client_id=dba4e3c6-f1f3-4d23-9088-fb452064c73f
id_token_hint=<id-token>

The post_logout_redirect_uri parameter (or optionally the redirect_uri parameter) must be included and is used as the redirect uri. This value must be configured as a Logout Redirect URI for the OIDC/OAuth client application. Only one of these parameters is required.

The client_id parameter (or optionally the id_token aud claim value) must be included and is used to identify the client application. Only one of these parameters is required.

Response

IDaaS redirects the user to the configured logout redirect URI. Without redirect parameters, the user remains at the IDaaS portal.

OIDC/OAuth PAR endpoint

The OIDC/OAuth PAR (Pushed Authorization Requests) endpoint https://customer.region.trustedauth.com/api/oidc/par can be used to initiate both OIDC authentication and OAuth authorization token requests using the PAR flow.

• Method: POST
• Path: /api/oidc/par
• Content type: application/x-www-form-urlencoded

The endpoint can be used by any client enabled with the authorization code flow grant type.

Authenticate the client using the method configured for the OIDC/OAuth application.

For example, clients configured for HTTP Basic authentication send:

Authorization: Basic <base64(client_id:client_secret)>

The endpoint should be called with any parameters used with the Authorization Endpoint, including the use of JAR (JWT Secured Authorization Request) if desired, but instead of returning an authorization code, the PAR endpoint returns a request_uri that can be used at the authorization endpoint in place of the standard query parameters.

Example request body

response_type=code
client_id=dba4e3c6-f1f3-4d23-9088-fb452064c73f
redirect_uri=https://app.example.com/callback
resource=https://example.com/apis/calendar
scope=openid profile view:calendar
state=<state>
code_challenge=<pkce-code-challenge>
code_challenge_method=S256

Example response body

The endpoint returns HTTP 201 when it accepts the request.

{
  "request_uri": "urn:ietf:params:oauth:request_uri:<request-key>",
  "expires_in": 60
}

Use the returned request_uri in the authorization request:

client_id=dba4e3c6-f1f3-4d23-9088-fb452064c73f
request_uri=urn:ietf:params:oauth:request_uri:<request-key>

JAR request example

To use a JWT Secured Authorization Request, replace the individual authorization parameters with a signed request object. The signed JWT contains claims such as response_type, client_id, redirect_uri, scope, state, and exp:

client_id=dba4e3c6-f1f3-4d23-9088-fb452064c73f
request=<signed-request-object>

DPoP request example

To bind the authorization code and resulting tokens to a DPoP key, include its JWK SHA-256 thumbprint in the initial authorization, device code, or PAR request:

dpop_jkt=<base64url-jwk-sha256-thumbprint>

Send a proof JWT signed with the corresponding private key when exchanging the code or device code:

DPoP: <dpop-proof-jwt>

The proof JWT header contains the public JWK for the signing key:

{
  "typ": "dpop+jwt",
  "alg": "ES256",
  "jwk": {
    "kty": "EC",
    "crv": "P-256",
    "x": "<public-key-x-coordinate>",
    "y": "<public-key-y-coordinate>"
  }
}

Generate the payload values for each request. The following JavaScript example uses a 60-second proof lifetime:

const now = Math.floor(Date.now() / 1000);

const payload = {
  jti: "<unique-proof-id>",
  htm: "POST",
  htu: "https://customer.region.trustedauth.com/api/oidc/token",
  iat: now,
  exp: now + 60,
};

Use the actual HTTP method and endpoint URI. The proof must contain exp, must be signed with an algorithm allowed by the application's DPoP settings, and must not reuse jti. Generate a new proof for each request.

When the proof accompanies a DPoP-bound access token at a protected endpoint, such as userinfo, include ath with the base64url-encoded SHA-256 hash of that access token. IDaaS verifies that the proof key matches the key bound to the token.