> For AI agents: [llms.txt](https://docs.trustedauth.com/llms.txt) provides a Markdown index of this documentation. # 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 ```text response_type=code client_id=dba4e3c6-f1f3-4d23-9088-fb452064c73f redirect_uri=https://app.example.com/callback scope=openid profile offline_access state= 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 ```text 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= 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: ```text https://app.example.com/callback?code=&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 ```text client_id=dba4e3c6-f1f3-4d23-9088-fb452064c73f scope=openid profile offline_access 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 ```text client_id=dba4e3c6-f1f3-4d23-9088-fb452064c73f resource=https://example.com/apis/calendar scope=view:calendar edit:calendar 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. ```json { "authRequestKey": "", "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 ```json { "userId": "jsmith", "authRequestKey": "" } ``` For reauthentication, add the existing IDaaS JWT: ```json { "userId": "jsmith", "authRequestKey": "", "authToken": "" } ``` #### Example response body ```json { "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 ```json { "applicationId": "11111111-1111-1111-1111-111111111111", "userId": "jsmith" } ``` For reauthentication, also include the `token` returned by Get User's Authenticators: ```json { "applicationId": "11111111-1111-1111-1111-111111111111", "userId": "jsmith", "authToken": "" } ``` #### Example response body ```json { "authenticationCompleted": false, "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 ```text Authorization: Bearer ``` This request body should include `applicationId` and the authenticator `response`. #### Example request body ```json { "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: ```json { "applicationId": "11111111-1111-1111-1111-111111111111", "response": "123456", "authRequestKey": "", "transactionDetails": [ { "detail": "Amount", "value": "10001", "usage": ["RBA"] } ] } ``` #### Example response body ```json { "firstName": "John", "lastName": "Smith", "authenticationCompleted": true, "token": "" } ``` 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](#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=` ### 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 ```text 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 ```json { "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 ```text 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: ```text Authorization: Basic ``` ### 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 ```text grant_type=authorization_code code= redirect_uri=https://app.example.com/callback 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 ```text grant_type=urn:ietf:params:oauth:grant-type: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 ```text grant_type=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 ```text 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 ```text grant_type=jwt_idaas jwt= code= ``` 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. ```json { "access_token": "", "token_type": "Bearer", "expires_in": 3600, "refresh_token": "", "id_token": "" } ``` For the client credentials grant, the response contains an access token and does not contain an ID token or refresh token: ```json { "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 ```text Authorization: Bearer ``` For a DPoP-bound access token, send both the DPoP authorization scheme and a proof JWT created for this request: ```text Authorization: DPoP DPoP: ``` #### Example response body ```json { "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: ```text Authorization: Basic ``` Use the revocation endpoint to revoke an access token or refresh token. #### Example request body ```text 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 ```text post_logout_redirect_uri=https://app.example.com/signed-out client_id=dba4e3c6-f1f3-4d23-9088-fb452064c73f id_token_hint= ``` 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: ```text Authorization: Basic ``` 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 ```text 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= code_challenge= code_challenge_method=S256 ``` #### Example response body The endpoint returns HTTP `201` when it accepts the request. ```json { "request_uri": "urn:ietf:params:oauth:request_uri:", "expires_in": 60 } ``` Use the returned `request_uri` in the authorization request: ```text client_id=dba4e3c6-f1f3-4d23-9088-fb452064c73f request_uri=urn:ietf:params:oauth:request_uri: ``` ## 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`: ```text client_id=dba4e3c6-f1f3-4d23-9088-fb452064c73f request= ``` ## 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: ```text dpop_jkt= ``` Send a proof JWT signed with the corresponding private key when exchanging the code or device code: ```text DPoP: ``` The proof JWT header contains the public JWK for the signing key: ```json { "typ": "dpop+jwt", "alg": "ES256", "jwk": { "kty": "EC", "crv": "P-256", "x": "", "y": "" } } ``` Generate the payload values for each request. The following JavaScript example uses a 60-second proof lifetime: ```javascript const now = Math.floor(Date.now() / 1000); const payload = { jti: "", 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.