Skip to main content

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.

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.

PKCE support

The authorization code flow now supports PKCE (Proof Key for Code Exchange).

OIDC Authentication​

OIDC authentication is used to initiate the process of obtaining id tokens, access tokens to acquire userinfo data, and refresh tokens by including standard OIDC/OAuth parameters, including these:

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

The scope parameter must include the OIDC scope openid.

The scope parameter should include the OIDC scope values (e.g., profile) to specify which userinfo data to include.

The scope parameter can also include offline_access in order to obtain a refresh token.

Optional standard OIDC parameters, including acr_values, max_age, and code_challenge, can also be used.

The OAuth consent page displayed to the user will include the userid and the application name that will be associated with the generated tokens.

OAuth2 Authorization​

OAuth authorization, optionally with OIDC authentication, is used to initiate the process of obtaining id tokens, access tokens to be used with resource servers, and refresh tokens by including standard OIDC/OAuth parameters, including these:

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

or

  • client_id = dba4e3c6-f1f3-4d23-9088-fb452064c73f
  • resource = https://example.com/apis/calendar
  • scope = openid profile offline_access all_scopes

The resource parameter is used to identify the resource server API for which an OAuth2 JWT access token is being requested by a client application on behalf of a user. This value can be set using the resource parameter or alternatively by using the audience parameter.

The scope parameter should include openid in order to obtain an id token.

The scope parameter should include the resource server scope values to specify which scopes are being requested for the identified resource server API. As opposed to specifying specific resource server scope values, the scope parameter can also include all_scopes in order to specify that all scopes are being requested for the identified resource server API.

The scope parameter can also include offline_access in order to obtain a refresh token.

As with OIDC authentication, the use of the OIDC scope parameter openid is required to obtain an id token and the others are optional (e.g., profile).

Optional standard OIDC parameters, including acr_values, max_age, and code_challenge, can also be used.

The OAuth consent page displayed to the user will include the userid, the application name, the resource server API name, and the resource server scope names that will be associated with the generated tokens.

OIDC/OAuth JWT IDaaS Workflow​

OIDC/OAuth Authorization JWT Endpoint​

The OIDC/OAuth authorization jwt endpoint https://customer.region.trustedauth.com/api/oidc/authorizejwt can be used to initiate both OIDC authentication and OAuth authorization token requests using the JWT IDaaS flow.

OIDC Authentication​

OIDC authentication is used to initiate the process of obtaining id tokens, access tokens to acquire userinfo data, and refresh tokens by including standard OIDC/OAuth parameters, including these:

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

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

The scope parameter must include the OIDC scope openid.

The scope parameter should include the OIDC scope values (e.g., profile) to specify which userinfo data to include.

The scope parameter can also include offline_access in order to obtain a refresh token.

Optional standard OIDC parameters, including acr_values, max_age, and code_challenge, can also be used.

OAuth2 Authorization​

OAuth authorization, optionally with OIDC authentication, is used to initiate the process of obtaining id tokens, access tokens to be used with resource servers, and refresh tokens by including standard OIDC/OAuth parameters, including these:

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

or

  • client_id = dba4e3c6-f1f3-4d23-9088-fb452064c73f
  • resource = https://example.com/apis/calendar
  • scope = openid profile offline_access all_scopes

The resource parameter is used to identify the resource server API for which an OAuth2 JWT access token is being requested by a client application on behalf of a user. This value can be set using the resource parameter or alternatively by using the audience parameter.

As with OIDC authentication, the scope parameter must include openid in order to obtain an id token. The others are optional (e.g., profile).

The scope parameter should include the resource server scope values to specify which scopes are being requested for the identified resource server API for which the user has access to. As opposed to specifying specific resource server scope values, the scope parameter can also include all_scopes in order to specify that all scopes the user has access to are being requested for the identified resource server API, if this option is enabled for the resource server.

The scope parameter can also include offline_access in order to obtain a refresh token.

Optional standard OIDC parameters, including acr_values, max_age, and code_challenge, can also be used.

No consent page

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

An API response is received after submitting an OIDC or OAuth2 authentication request. For example:

{
  "authRequestKey": "QoOuQ3JyccbHqVJxUwHInxSPdn37nSJTgOMn6UE3Yi9c=",
  "applicationId": "1111111-111111-111111-11111111"
}

After getting the response, call Authentication APIs sequentially. The documentation takes OTP authenticator as an example in the following.

Get User's Authenticators​

After getting the successful response, submit a POST request to obtain the user's available authenticators that can be used to log in to the application. For example:

https://customer.region.trustedauth.com/api/web/v2/authentication/users

The body of this request should contain a JSON object with User ID (containing the user id or a user alias value) and the authRequestKey obtained from Authorization JWT endpoint response. The ID of the application is optional in this case. If the authorization jwt endpoint included request parameters such as acr_values or max_age, the body of this request must contain the previously authenticated authToken (IDaaS JWT) in order for a recentness check to be performed on the previously completed authentication. For example:

{
  "userId": "jsmith",
  "authRequestKey": "QoOuQ3JyccbHqVJxUwHInxSPdn37nSJTgOMn6UE3Yi9c=",
  "authToken": "GMZmc7Jg464fx7Vm5EwfEDyHaCYZLosqI8mdaPF8Xi+0gOZbTKMBXuQRRlrf8hWBQDOLmubJvS+t5K6m9Ox5CVPdyRvlgs2/5zGXO1QGltcWOnraibaY3Ryvt+ceaAXACkM3r922RkysRBxYDsfVGuQTRjxV4KQoJ2oFiQqKy9HoZmh77rn8AfZGn5lOxCFIQrrJPa6NOo8hIROHWNlom3eXwGBNSu10yYgvHmcmDwR9RrUr3A703fdwSsp9VWmEE38SGdZXOdwgipgqvsy2NjXQWaN2KNTMlfgPZXR15t51oqqxjkI8s3mEqpQWk//4ZoUB6bHK93uav6OCVXgDUpTsM5kHQYiLG5IbSXOuT7sgyoL5GutZz57+J2riJXvSNNhG8Z7t2R5J6rhxluYpNJw7mbHSB2k/ujCit+0AtRAgErGyQWiTjLFcHclZm76o2Osy073gQnYEBrNOfJl7fQR8mCcIBU1sYW0OMGzdAUDziNiIBbWE/YNFSTfMzP2UMPRumDQ6LRtDqC1smLR8Byv+547nN7+XQUWqe/KwrYI1OaPiAN2LnmP2goP53ZLbdocmBBRRV2KbytiNmm2cNJdRuEmlTAFp6DuLWyrFK5jGKDFbo8JBlF+HhSzYLpvsRXD0HnAY6OqZg6lQxPN1PYKFL7QCm1YlLJyYMz9uH6CT4O6h4KGjKQFSP+gae0afZzdMla/4PdnFBNh3XuAGGmK8gSPHwRF+qxixzlK9+DZP/Nzk8JZTm305Im1OnZycqh9cbYuk0Fc7bcfqbloiakhrfEKW34C5nwxNJf5PNacQhmRjUzfG4fDpSmehv+Fz4hPZ9X7S7k7GRd971h0V9rc7pJMoILHcLxZ3dCgLTqIDRa04bS6J+mEoSn7wDab4Px1OOY0YDH/VrrluWnnbj1/lI+dLgoJu+IisG2avZ9jC+YS5dU2wVGZT4d0lYd+ijLM/H1CZqgsyspc7Ei/AkXJbt+qEgxKcKRHbxDsvejb13lWgpEJ9ydACCm2+6wJQxp3LsfkpAngYQQ6w2sum0hSip1/gJ6Co+3l9AesdhCj2N3lDr5Z3PPI5SmB6f0cqhm/up9F4MAo9faAg5gujhIAinE8fqZ/7ifg5W7YIwLurUjbryyi0ntDR0/6SiMXYPbwqP8pJAvOmuzrXgqNrKXN+nMTfBkEGqiXbTud4fu4kVudt06GKSnOf1FDdhw8Z5ANV42HZtV00Gw=="
}

An API response is received after entering the request. For example:

{
  "availableSecondFactor": null,
  "userMachineSettings": {
    "machineAuthenticatorEnabled": true,
    "deviceFingerprintRequired": false,
    "attributeExclusions": [],
    "userMachineAuthenticators": []
  },
  "machineAuthenticator": null,
  "authenticationTypes": ["OTP", "TOKEN"],
  "time": 1520961989641,
  "otpDeliveryInfo": {
    "otpDefaultDelivery": "SMS",
    "availableOTPDelivery": ["SMS", "EMAIL", "VOICE"]
  }
}

The authenticator types listed in the response are those that can be used to complete an authentication challenge and log in. authenticationTypes lists all the authenticators that have been assigned to the user and can be used to complete a first-factor authentication challenge. availableSecondFactor lists the authenticators that can be used to complete a second authentication challenge after the user has completed a first-factor challenge. The authenticators listed as authenticationTypes and availableSecondFactor are defined by cross-referencing the authenticators assigned to the user with those the application’s resource rule allows to be used for authentication.

Select Authenticator​

If the previous step indicated authentication is required, the next step is to select which authenticator to use from those listed in the previous API response. This step is the same as Select authenticator.

If the authorization jwt endpoint included request parameters such as acr_values or max_age, the body of this request must contain a JSON object with the authRequestKey obtained from Authorization JWT endpoint response in order for the appropriate authentication to be performed.

{
  "applicationId": "1111111-111111-111111-11111111",
  "userId": "jsmith",
  "authRequestKey": "QoOuQ3JyccbHqVJxUwHInxSPdn37nSJTgOMn6UE3Yi9c="
}

Complete authentication challenge​

The next step is to complete the authentication process. The response for the requested authentication must be included in the last API call. For example, a POST request for OTP would be sent to:

https://customer.region.trustedauth.com/api/web/v1/authentication/users/authenticate/OTP/complete

The request must include the end user’s response to the authentication challenge. For example, the OTP received by the user must be included in the request to complete an OTP challenge. The URL must contain the selected authenticator (for example, OTP). An Authorization header field must be added in the header section of this request. The Authorization header stores the value received as "token" in the last request. The Authorization header can be sent with or without a type value of "Bearer". For example:

Authorization: Bearer <token>

or

Authorization: <token>

The body of this request should contain the Application ID and authenticator response. If the authorization jwt endpoint included request parameters such as acr_values or max_age, the body of this request must contain a JSON object with the authRequestKey obtained from Authorization JWT endpoint response in order for the appropriate authentication to be performed. If transaction details exist in the request, and the OAuth2 JWT access token needs to contain the transaction_details claim, the authRequestKey obtained from the authorization jwt endpoint is required. For example:

{
  "applicationId": "1111111-111111-111111-11111111",
  "response": "123454665",
  "authRequestKey": "QoOuQ3JyccbHqVJxUwHInxSPdn37nSJTgOMn6UE3Yi9c="
}

An API response is received after entering the request. For example:

{
  "status": null,
  "firstName": "John",
  "lastName": "Smith",
  "authenticationCompleted": true,
  "machineAuthenticator": null,
  "userMachineSettings": null,
  "kbaChallenge": null,
  "token": "GNVGALEyZRj9xQnp4+cRoQ3DrMViO+wdXMyeBdG4+63V0O1+B5eBl83HVbOW7daHMf4xPzuJ/TD5j3w5zrIKE6RObuzIfyELpEWlr+JAzuXHCQocmFa1eNz2B2VshyZl3tbes9P3P6pniXZgpG0MdbEALfDm9PydJ4hcqcqDM1XsTcxSBnv+LFWV1HFKzL018Af17iJpnz8VBzOi/x5N8enkZ5g+XO/uXNCiBqDdfMkxkDzkreDXOoiGo7KPEzsuXFQLIigwnYLC2BufWaOnP2KLYGjjH7A2O+tyKsepVREKRTMDcdkcfqJsyJKm3xWl/HW1SCg2Ql2naQ6V4fK6IjrCQqZbPSQV4GL75NB1wqTf3e6ijCJwBJH9JXIov9E8Tw66sKy7dQAlODuLQ9LwhNv6BF+Ndy6HJlCDQjD0Oket4Sp8t0HDe0mTU5FnMc/ch3zuFtVHdGarjPtnt6PIZdUFn1A585q4GeY8nJwyMFu8MpRJyM81sdDe5/nEarDtPPXp3NbY+0kl4fIozogosyHzNstPcZV4rza3XQXB6047lKqs0uUeigwo2TkbKVPHxwleIxcs9d+wpQAZHhfP3IDTwa2Qq7J9PYMEfQsnz3dIFOZdNbDnusYHvp+5LppVWvky4vX5QV5ldAc2B4t+RCvtSvIABVCR+nftzLUcSm02fKU=",
  "otpdeliveryType": null,
  "expires": 1520968457173,
  "time": 1520967582294
}

In the example above, authenticationCompleted is marked as true because the response sent in the post request was valid. The last 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.

OIDC Authentication​

OIDC authentication is initiated by a device using the device code endpoint. This initiates the process of obtaining id tokens, access tokens to acquire userinfo data, and refresh tokens by including the following standard OIDC/OAuth parameters:

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

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

The scope parameter must include the OIDC scope openid.

The scope parameter should include the OIDC scope values (e.g., profile) to specify which userinfo data to include.

The scope parameter can also include offline_access in order to obtain a refresh token.

Optional standard OIDC parameters, including acr_values and max_age, can also be used.

User authentication must then be initiated by the user using the device endpoint specified in the device code endpoint response verification_uri along with the user_code. An example device code endpoint response:

{
  "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 displayed to the user will include the userid and the application name that will be associated with the generated tokens. It will also include a configurable application specific message indicating that the consent is for a device.

OAuth2 Authorization​

OAuth authorization, optionally with OIDC authentication, is initiated by a device using the device code endpoint. This initiates the process of obtaining id tokens, access tokens to acquire userinfo data, and refresh tokens by including the following standard OIDC/OAuth parameters:

  • scope = openid profile offline_access

OAuth authorization with OIDC authentication is initiated by a device using the device code endpoint. This initiates the process of obtaining id tokens, access tokens to be used with resource servers, and refresh tokens by including the following standard OIDC/OAuth parameters:

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

or

  • client_id = dba4e3c6-f1f3-4d23-9088-fb452064c73f
  • resource = https://example.com/apis/calendar
  • scope = openid profile offline_access all_scopes

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

The resource parameter is used to identify the resource server API for which an OAuth2 JWT access token is being requested by a client application on behalf of a user. This value can be set using the resource parameter or alternatively by using the audience parameter.

The scope parameter should include openid in order to obtain an id token.

The scope parameter should include the resource server scope values to specify which scopes are being requested for the identified resource server API. As opposed to specifying specific resource server scope values, the scope parameter can also include all_scopes in order to specify that all scopes are being requested for the identified resource server API.

The scope parameter can also include offline_access in order to obtain a refresh token.

As with OIDC authentication, the use of the OIDC scope parameter openid is required to obtain an id token and the others are optional (e.g., profile).

Optional standard OIDC parameters, including acr_values and max_age, can also be used.

User authentication must then be initiated by the user using the device endpoint specified in the device code endpoint response verification_uri along with the user_code. An example device code endpoint response:

{
  "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 displayed to the user will include the userid, the application name, the resource server API name, and the resource server scope names that will be associated with the generated tokens. It will also include a configurable application specific message indicating that the 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.

PKCE support

The token code flow now supports PKCE (Proof Key for Code Exchange).

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, including these:

  • grant_type = authorization_code
  • code = CWdEdNomrMcCQ9oMjXTMS7XxWiHMsrX9-mXIHwqEXC4U=

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, including these:

  • grant_type = urn:ietf:params:oauth:grant-type:device_code
  • device_code = Dcatvq6_iclfJa_Y7NCcNLkh0NN1IIFV4btgAoXmoKN0=

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, including these:

  • grant_type = refresh_token
  • refresh_token = R-5f474e42-92ef-4ae4-bab7-b5ab2c052161-9arzeOJKHWhtvKQOJw4MXXgLpE99bLEBjTu2q4KsC7s=

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, including these:

  • grant_type = client_credentials
  • resource = http://localhost:3010/stuff/calendar
  • scope = view:calendar add: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 the resource server scope values to specify which scopes are being 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, including these:

  • grant_type = jwt_idaas
  • jwt = GHLITi0s+hZecyZo...MFa6Gzf+kk=
  • code = QoOuQ3JyccbHqVJxUwHInxSPdn37nSJTgOMn6UE3Yi9c=

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.

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 tokens.

A previously obtained OIDC access token is used as the Bearer Authorization header to obtain userinfo data.

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.

OIDC/OAuth revoke token is used to revoke (i.e., delete) existing OIDC access tokens and OAuth access tokens with refresh tokens by including standard OIDC/OAuth parameters, including these:

  • token = R-5f474e42-92ef-4ae4-bab7-b5ab2c052161-9arzeOJKHWhtvKQOJw4MXXgLpE99bLEBjTu2q4KsC7s=

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

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.

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

  • post_logout_redirect_uri = https://www.example.com
  • redirect_uri = https://www.example.com
  • client_id = dba4e3c6-f1f3-4d23-9088-fb452064c73f
  • id_token_hint = eyJ4...weRA

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.