Skip to main content
Version: 5.39

Entrust Identity as a Service Authentication API

This document describes how to control access to your application using Identity as a Service Authentication API calls.

Prerequisites

Confirm the following before configuring your application to use the API calls included in this guide:

  1. An Authentication API application has been created within Identity as a Service.
  2. A resource rule has been created for your Authentication API application.
  3. Each user who will access the application has an Identity as a Service account.
  4. Each user who will access the Identity as a Service application has had all their authenticators assigned to them and activated.

Identity as a Service Authentication APIs

Identity as a Service uses three API calls to complete an authentication challenge:

  1. Get User's Authenticators
  2. Select Authenticator
  3. Complete Authentication Challenge

These API calls must be made sequentially to complete Identity as a Service authentication. Information is provided in response to each API call that is required to complete the next call. Completing each of these API calls in order allows users to log in to the application.

List of supported Authenticators

The following authenticators are supported for authentication using Identity as a Service API calls:

  • Passwords
  • Knowledge-based authentication (KBA)
  • Temporary Access Codes
  • One-time passcodes (OTP)
    • OTPs can also be dynamically linked with transaction details when used with Authentication API applications for PSD2 (Payment Service Directive).
  • Grid cards
  • Hardware and software tokens
    • Tokens supporting signatures can also be dynamically linked with transaction detail values when used with Authentication API applications for PSD2.
  • Entrust Soft Token Push authentication
  • Mobile Smart Credential Push authentication
  • Passkey/FIDO2

The next section describes how to authenticate through API calls using some of the authenticators listed above. These examples involve single-factor authentication. See Two-factor Authentication for assistance with using Identity as a Service's Authentication APIs to facilitate two-factor authentication.

Transaction Details​

A transaction detail consists of a detail name, a value, and a list of supported usages. Valid usage values are RBA and TVS. When not defined, the transaction detail is used both for RBA (risk-based authentication) and TVS (transaction verification/signing).

When using a push authenticator, such as Entrust Soft Token Push authentication or Mobile Smart Credential Push authentication, transaction details may be included in the challenge request. Transaction details are passed to the mobile device and displayed to the user when confirming authentication.

When using an OTP authenticator with Authentication API or OIDC applications for PSD2, the OTP is dynamically linked with transaction details. The transaction details are included in the challenge request. Identity as a Service generates a new, specific OTP tied directly to the request and transaction details. The OTP is then sent to the user using Email or SMS messaging. The user reviews the transaction details and uses the associated OTP to complete the authentication challenge.

When using a TOKEN authenticator with Authentication API or OIDC applications for PSD2, the token response is dynamically linked with transaction detail values. The transaction details are included in the challenge request. The user reviews the transaction details and enters the transaction values (consecutively) into the token and obtains the signature. The signature is then used to complete the authentication challenge.

When using a TOKEN authenticator with Authentication API or OIDC applications, the token response can be processed offline. The challenge requests include the transactions details. The transaction details consist of a detail name and a value. The challenge response contains a list of QR codes based on the active tokens and the transaction details. The user scans a QR code in the Entrust Identity application, reviews the transaction details, confirms the transaction, and obtains an OTP. The OTP is then used to complete the authentication challenge.

To use the offline QR code transaction with TOKEN authenticator, the request user challenge body and user authentication body need to have the flag offlineTVS set to be true:

"offlineTVS": true

The following restrictions apply to transaction details:

  • The detail name cannot be duplicated.
  • The length of the detail name and value cannot exceed 255 characters.
  • The number of transaction details cannot exceed 25.

When dynamically linking transaction details with Authentication API or OIDC applications that use an OTP authenticator or TOKEN authenticator for PSD2, the same transaction details must be specified in both the user challenge (Select authenticator) request and the user authenticate (Complete authentication challenge) request. They must match.

When using transaction details with push authentication as part of the user challenge (Select authenticator) request, the use of the same transaction details can be optionally specified in the user authenticate (Complete authentication challenge) request. If specified, they must match.

When using the transaction details, it is recommended that the transaction details are always supplied in both the user challenge (Select authenticator) request and the user authenticate (Complete authentication challenge) request. This is mandatory for PSD2 authentications.

Transaction details can be used with OIDC applications only in the JWT IDaaS workflow. The risk-based authentication (RBA) transaction details passed in the user authenticate challenge and authenticate complete requests can be included in the OAuth2 JWT access token using the transaction_details claim. For details, see OIDC/OAuth JWT IDaaS Workflow.

To use transaction details with a push authenticator or an OTP authenticator API or OIDC applications for PSD2, the request user challenge body should contain a JSON object with an array of these details. For example:

{
  "transactionDetails": [
    {
      "detail": "Account",
      "value": "67432",
      "usage": [
        "TVS"
      ]
    },
    {
      "detail": "Amount",
      "value": "$10,001",
      "usage": [
        "TVS"
      ]
    },
    {
      "detail": "Purpose",
      "value": "Transfer",
      "usage": [
        "TVS"
      ]
    }
  ]
}

To use transaction details with a TOKEN authenticator API or OIDC applications for PSD2, the request user challenge body should contain a JSON object with an array of these details. Some tokens may only support numeric transaction values. For example:

{
  "transactionDetails": [
    {
      "detail": "Account",
      "value": "67432",
      "usage": [
        "TVS"
      ]
    },
    {
      "detail": "Amount",
      "value": "10001",
      "usage": [
        "TVS"
      ]
    }
  ]
}

Mobile SDK Push Messages​

When using a customized push message for TOKENPUSH notification, you need to configure a Soft Token SDK.

When a Soft Token SDK is created, a Push Message is generated with a default flag set to true. Users can add, modify, and delete push message configurations. To delete a row with a default flag set to true, users must first add a new push message and set it as the default message before deleting the default message.

If you want to send customized messages to the device, you need to set the pushMessageIdentifier parameter in the request to match the identifier column of the customized push message. For example, if you create a customized push message with the Identifier column in the push message table in the SDK settings set to Hello, you must set pushMessageIdentifier to Hello.

If a match is not found, it throws an error. If you have a Soft Token SDK, and you do not set pushMessageIdentifier, the default push message will be used.

The parameter pushMessageIdentifier is case-insensitive. And it is optional.

Examples

OTP​

Get User's Authenticators​

The first step is to submit a POST request to get all the 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 ID of the application being accessed. For example:

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

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​

The next step is to select which authenticator to use from those listed in the previous API response. The authenticator is selected by entering a POST request. That request must be sent to the correct URL with the name of authenticator at the end. The URL is different for each authenticator that you want to select using the API call. For example:

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

The body of this request should contain a JSON object with User ID (containing the user id or a user alias value) and the ID of the application being accessed. For example:

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

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

{
  "status": null,
  "firstName": null,
  "lastName": null,
  "authenticationCompleted": false,
  "machineAuthenticator": null,
  "userMachineSettings": {
    "machineAuthenticatorEnabled": false,
    "deviceFingerprintRequired": false,
    "attributeExclusions": [],
    "userMachineAuthenticators": []
  },
  "kbaChallenge": null,
  "token": "GCFi6gQPNM7eMZ3AQ7vboW8d5vL6x7vtO8tn4yAYNOpV5UYI2Xo5MZg0zYE7m/R1U1cCFm83ocC1KZ3PJbeD9zqZvPQSvxxt1KIbtD9DERd21oAVEbnqqj9/8DYUBQQoxBRfwVINlCpVt8X0ZaDMSka53ZIO9VifLwS2gjy7KNRCD9DLcDznasaYoGB2YSvj+w4bE3Z9j0bgtYmhy9swn8wmd6QMSP4eb9mH2KcqgXzCUPxTxeTZu0EkIToXD1LN8v9BCyScdCLNJ/DjOGwfmpnT4hveKX5qe/dHjgsCME5kjmHtWKlmS0SPMMMgRyNII0nCcKMZI1Khd60ubnnVoFcAUpFWG1vGJwhN6ipiuwie+EW4wAXSE1HicHhY1Q/jUQev3PvVBi+GzSKowDIorhVzApd1WP0a4686yQEMGWRdqDRltXHw7udKU8UqN5tCqUK6bZsX7x2NxabqJmmxUFBbNncuzPMPJrPNMVQtw0z8BlWCyRqYl64BZAIMTpf8F/uFPLrOHgpaV1yEiMuQBea2Hf9LyXX5Dv2L44LvABIyPZ7Jy7paeffJ7ozfLwS2VpSnjTD/1ir+p6lMYjlcfJ7l5gEoW/dS8w==",
  "otpdeliveryType": "SMS",
  "expires": 1520966778923,
  "time": 1520965879202
}

Once an authentication type is selected through the API call, Identity as a Service also provides the information necessary to complete the authentication challenge. For example, if OTP is selected, Identity as a Service generates an OTP and sends it to the user, so they can complete the authentication challenge. If kbaChallenge is selected, Identity as a Service generates the questions that must be answered to authenticate.

Complete authentication challenge​

The last 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. For example:

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

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
}

Identity as a Service receives the request once it is entered and validates it.

In the example above, authenticationCompleted is marked as true because the response sent in the post request was valid.

The response from the call would indicate a failure if an invalid value is passed in the body of the response. For example:

{
  "errorCode": "invalid_user_response",
  "errorMessage": "",
  "parameters": null
}

TOKENPUSH​

Get users authenticators​

The first step is to submit a POST request to get all the authenticators that can be used to log in to your 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 ID of the application being accessed. For example:

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

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

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

TOKENPUSH is listed as one of the user's available authenticators (authenticationTypes) in the example above.

Select Authenticator​

The next step is to send a POST request to use token push authentication. Send the request to a URL with TOKENPUSH at the end. For example:

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

The body of this request should contain a JSON object with User ID (containing the user id or a user alias value) and the ID of the application being accessed. The body of this request may also include transaction details, as described above. For example:

{
  "userId": "jsmith",
  "applicationId": "1111111-111111-111111-11111111",
  "transactionDetails": [
    {
      "detail": "Amount",
      "value": "$10,001"
    },
    {
      "detail": "Purpose",
      "value": "Transfer"
    }
  ]
}

To use specific message notifications with a Soft Token SDK, configure the message table and then set the pushMessageIdentifier as a parameter in the JSON object.

{
  "userId": "jsmith",
  "applicationId": "1111111-111111-111111-11111111",
  "pushMessageIdentifier": "hello"
}

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

{
  "status": null,
  "firstName": null,
  "lastName": null,
  "authenticationCompleted": false,
  "machineAuthenticator": null,
  "userMachineSettings": {
    "machineAuthenticatorEnabled": true,
    "deviceFingerprintRequired": false,
    "attributeExclusions": [],
    "userMachineAuthenticators": []
  },
  "kbaChallenge": null,
  "token": "GHldL54iaM9Rn4I4TZ85BzYJVsvxn0sWZxWdUZfFWZxzAawEvJDd4tC9frfvxy6hV7BJDsg2GN3mbxzezsN+AT5tKlX8mPhoWrcUyGYawVxZsbvfmsVesAzNey9RPXyfOvuWqh6BDkpqrL68E1ik+dN50aFK88G4DWxQJ5+oYn0bnarJlLyr4hH62XBCMOmr1T2dTe2SFm+Brj8NI6wKdCnptWAG8QguAlVnXOVntBCzQ/XMFs6ktEnbeCIqXgsUIc2zVd7iXpNMjX5Cl3pgqozCY7UKHFW9WGxFcRz/5+1Y4DuAEGk6VygrdMLV2Hi0UaFN280JQY2jzC1eb6089JOtcm2Rnqi+Zg6OYbzscQfp+o2ARj8IlltQOIgjueiCG5X/AdIbEqc5/nFhbg/d+wNV9M6Fk2bX25iTa6mcIMp2Gvo2mhM8q0ysqzAnXjgveaikymJIx01/q0ctKNCHNN8pgXMF4sNU+GRm2vqdQXcbuTc0krALqtF40QN97JdoBSACUMN4M7gYzFC2SBsArIZwmXAqgCDvzWYq9FhUekgrIr18Bxl7yUFRJLDU",
  "otpdeliveryType": null,
  "expires": 1521484056513,
  "time": 1521483156531
}

Complete Authentication challenge​

The user receives a push notification to the device registered with the Entrust Soft Token mobile application. The last step is to complete the authentication process using the token push authenticator. Note that in the push authentication case, there is no response that must be passed to the last API call. The post request should be sent to this API call:

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

As in the first example, this request will also include an Authorization header field. 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 a JSON object with the ID of the application being accessed. For example:

{
  "applicationId": "1111111-111111-111111-11111111"
}

An API response to the request is received. The response will vary depending on whether the user has completed the push authentication challenge or not. For example, if the user has not yet processed the request, the API response appears as shown:

{
  "status": "NO_RESPONSE",
  "firstName": null,
  "lastName": null,
  "authenticationCompleted": false,
  "machineAuthenticator": null,
  "userMachineSettings": null,
  "kbaChallenge": null,
  "token": null,
  "otpdeliveryType": null,
  "expires": 0,
  "time": 1521485352309
}

If the user selected a Confirm response for the push request, the API response appears as shown:

{
  "status": "CONFIRM",
  "firstName": "John",
  "lastName": "Smith",
  "authenticationCompleted": true,
  "machineAuthenticator": null,
  "userMachineSettings": null,
  "kbaChallenge": null,
  "token": "GFu9JJTpgxlAgudDrdm49fxU/sCVVf41jyxM97GDMdHhrqjSwM23bGZt2JBdCWJ/hgo0cq1DN7DYfM74+Xd/EYpMt+Ijn8iWQY2fOohCQLtC4wTJAWkQ2D5iKNGNli3iazbt65mpkqZ7Z5V5krsS1REKLES54jpDjqO4y6a+d8N9SPD8OfQx71cCGf58iDPHm96My2WH/cqvfg0Nl+8NKgtmzpLiG9HayE7KwGqOPlpsQoxuk9Mt6q8z5GL+uZ4zBV8h07KmhWxmFloaJEdJYIqQQbPHrgIZdXNHceGsJjSctkm/68Ib5ZHrtEW/IzHmMDPjau93xP9KB363TTudpO37LlprDBWvjdu+YgkN2ofUO0wsS9aVW9zu/u5LgLLk8WqpX+sS3pWD7naxqpTF0l8+hV7UknTx9n7GEIWlSZnz+5cTJe/qw9n5MXgZMkYhv6aaScKdx+gPlKFqWW7t+8xrvCBX5jybi7qknYsJxjsDnJ9xbfd5AsdE7jdZLkGIrbuh4LeJekz4S3UkC23++9jx99d+OHw9DZjSDAIYx5bApkhPje8wXRwCfHOGq/YuasmwH0lOdOmKVJs51EUbolHfSqVsIXR3SQZqCkVA82yMdYSiY/3Z65mA5EMeyyd0YNXfMGO8nw==",
  "otpdeliveryType": null,
  "expires": 1521486237824,
  "time": 1521485466748
}

If the user selected a Cancel response for the push request, the API response appears as shown:

{
  "errorCode": "no_transaction",
  "errorMessage": "",
  "parameters": null
}

Two-factor Authentication​

Two-factor authentication supports logging in by completing two-authentication challenges instead of one. This section describes how to use Identity as a Service's Authentication APIs to complete two-factor authentication. The API calls required are similar to those required for single-factor authentication:

  1. Get User's Authenticators
  2. Select Authenticator (First-factor)
  3. Complete Authentication Challenge (First-factor)
  4. Select Authenticator (Second-factor)
  5. Complete Authentication Challenge (Second-factor)

Get User's Authenticators​

The first step is to submit a POST request to get all the authenticators that can be used. 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 ID of the application being accessed. For example:

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

An API response to the request is received. The response would include authenticationTypes marked as * PASSWORD_AND_SECONDFACTOR*. It would also include the section availableSecondFactor, showing all the authenticators that can be used for second-factor authentication. For example:

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

Select Authenticator (First-factor)​

The next step is to send a POST request to use first-factor authentication. It must be sent to a URL with PASSWORD_AND_SECONDFACTOR at the end of it. For example:

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

The body of this request should contain a JSON object with User ID (containing the user id or a user alias value) and the ID of the application being accessed. For example:

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

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

{
  "status": null,
  "firstName": null,
  "lastName": null,
  "authenticationCompleted": false,
  "machineAuthenticator": null,
  "userMachineSettings": {
    "machineAuthenticatorEnabled": false,
    "deviceFingerprintRequired": false,
    "attributeExclusions": [],
    "userMachineAuthenticators": []
  },
  "kbaChallenge": null,
  "token": "GC/qKOp/15eRQ8QnJ8DXA+RCtlXYxuAEyC5mF9WxT4byFl6EQYlPUUIaMMnbEq3+vQ3EGi4Mcp/sX3ttDdRzU6GMdjPHL21i9tNAw22fNE+ZsUtwoPzhCO6b5YRKQcJ9jJBADp+2o05oF/iQFaWeOnP6E1cW6zPAD4DYXwwbXe6pR46/XN6XDrR+C5JiCklwlY2Pf3L5fAG4Bl0QCEmEjeTpLCp7wbWsRv45RNgBE8O2MTLoRigzxMRen6+Hw94E2SD2EHvf4+IetJAsTFgfnx1YMabuHfrw5D0jlN0veaHmxp0yF0iitMkyNWPwoNEh+XltvVKYDas3Q9V16Xk5/rMKWgOYHp/Z/U8pf6heUgA6yeLo5dXIqC+TkSpibRpere/gBkVAskjePYs60BIpMiqiXAisKaIi4t3D50/X/6JXNvoinL60XHu+I97DrCQ20ozhn7aG1jHRNIGYFU+JDR9+qAOhmUQbZVQV9Ngqg7Av4jBDkBWAquA/E6zhZe4vDQo7WV0=",
  "expires": 1521648764763,
  "otpdeliveryType": null,
  "time": 1521647864782
}

Complete authentication challenge (First-factor)​

The next step is to complete the first-factor authentication challenge. For an example, a POST request to complete a Password authentication challenge would be sent to the following URL:

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

As in the first example, this request will also include an Authorization header field. 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 a JSON object with the password response and the ID of the application being accessed. For example:

{
  "applicationId": "1111111-111111-111111-11111111",
  "response": "password"
}

The response received from this request would include a new token and a field authenticationCompleted that would be marked as false. For example:

{
  "status": null,
  "firstName": null,
  "lastName": null,
  "authenticationCompleted": false,
  "machineAuthenticator": null,
  "userMachineSettings": {
    "machineAuthenticatorEnabled": true,
    "deviceFingerprintRequired": false,
    "attributeExclusions": [],
    "userMachineAuthenticators": []
  },
  "kbaChallenge": null,
  "token": "GO7mOyRuLzfTOXLk/IbzsDEuw8cFQspxz8TCWRwcrrhtoBw/o7udXt94eTkbkDFcbMVpfqHZJcJ4vavS4MEN6wp0d7MFhd0n9A9XymY5KHKyMvrqJlqh8+NrIZjkiA0sZvrAhu+6IRGfTYfoe/DwWclJi2JNNxpMX/17b7QHZdrj5ItbJUp3wHhAswUX02uWn/Fxwnt3cxGVHgmtTaVfz42JBkiIeRcOiv81iJqfTuSrd+S29RqO4PCKYGw1pKhymottvV3eVGNxdPvwSrLgXusfuCyfAB8tGl047WJQOKaHZ7k4GbzC1QKjldNWHrMAtiLUMWaxgvpU/vANJUibIPXJ6+1i7X7U6THJJg4fBG+pJo8jPKPI1B+XxE1mNBdLdMEdfUSKwUqv3BGg8g+WsL+ZLkbSzrswuoyBKWioEVXkxUVDtRghDLDjiRFjyQMwD+MhvdoC46a10IMkz1G5kKkQ6xaTTwhkEsh2iGeWtn6WDcC0PILFX4NmiF/g650j41aFWAyOD5ULBKV04a2dYKdadGfaAH0=",
  "expires": 1521648936739,
  "otpdeliveryType": null,
  "time": 1521648060983
}

Select Authenticator (Second-factor)​

The next step is to send a POST request to use a specific second-factor authentication. It must be sent to a URL with PASSWORD_AND_SECONDFACTOR at the end of it. For example:

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

The body of this request should contain a JSON object with the ID of the application being accessed, the token that was received from the last request, and a second-factor authenticator. All the available second-factor authenticator options were received in the first call we made. For example:

{
  "applicationId": "1111111-111111-111111-11111111",
  "secondFactorAuthenticator": "OTP",
  "authToken": "GO7mOyRuLzfTOXLk/IbzsDEuw8cFQspxz8TCWRwcrrhtoBw/o7udXt94eTkbkDFcbMVpfqHZJcJ4vavS4MEN6wp0d7MFhd0n9A9XymY5KHKyMvrqJlqh8+NrIZjkiA0sZvrAhu+6IRGfTYfoe/DwWclJi2JNNxpMX/17b7QHZdrj5ItbJUp3wHhAswUX02uWn/Fxwnt3cxGVHgmtTaVfz42JBkiIeRcOiv81iJqfTuSrd+S29RqO4PCKYGw1pKhymottvV3eVGNxdPvwSrLgXusfuCyfAB8tGl047WJQOKaHZ7k4GbzC1QKjldNWHrMAtiLUMWaxgvpU/vANJUibIPXJ6+1i7X7U6THJJg4fBG+pJo8jPKPI1B+XxE1mNBdLdMEdfUSKwUqv3BGg8g+WsL+ZLkbSzrswuoyBKWioEVXkxUVDtRghDLDjiRFjyQMwD+MhvdoC46a10IMkz1G5kKkQ6xaTTwhkEsh2iGeWtn6WDcC0PILFX4NmiF/g650j41aFWAyOD5ULBKV04a2dYKdadGfaAH0="
}

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

{
  "status": null,
  "firstName": null,
  "lastName": null,
  "authenticationCompleted": false,
  "machineAuthenticator": null,
  "userMachineSettings": {
    "machineAuthenticatorEnabled": true,
    "deviceFingerprintRequired": false,
    "attributeExclusions": [],
    "userMachineAuthenticators": []
  },
  "kbaChallenge": null,
  "token": "GMITwEPkGILJI/jBMVT3p8a09JtGag3AzXqjan1+FBNdWjnCi16JNdpNxrBt/iuFYlozZ2Jrf6V6JEZEuQeFtZtFyETEVKNOxhbbOf+u6SmkBSwLQQm529WKUtFssLnQ9Mliojlb/1W8VXkseazUhWuvpab9t7b4Y9BP9RcXdPNdAOtR++dGwuwtAh0O6Edq9SE4yDGn8aRWJuydc7k8aQymLZfFR76y0EbG4mP/m9kZ2pDOjUrhHa8rToLLx3Jr70aHqJr5bNyCrQ96/c+5YTQeLhFL86Ch8LcIAKHh5RI2Ma6X+PTBZ4CwMrU6jUczCjJ6m94jlwIH37P0vv2GdlMZHPqjjmAuHB2SGKA0UxQywL9SbsIhyM2lxhBLUK30wRH0LHlW4reki0vF9gfc+kZQZFaVyj/bJ0P63lTsIywEmPBbCo8o21A5Mram5m+kNcCLg4ZlIaM2bWrvtBX0SxL5Cpx7vy1cUABQw+4ifRgcrwt6KWgIngmu1y/ItwaLCGgvw2dCFd3kPHd+HoXzsb2aVP+9tqo=",
  "expires": 1521648936739,
  "otpdeliveryType": "SMS",
  "time": 1521648184761
}

The token received in this request would be used to complete the second-factor authentication in the next step.

Complete authentication challenge (Second-factor)​

The last step is to send a POST request to complete the second-factor authentication challenge. It must be sent to a URL with PASSWORD_AND_SECONDFACTOR at the end of it. For example:

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

As in the first example, this request will also include an Authorization header field. 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 a JSON object with the second factor response, the ID of the application being accessed, and the second factor authenticator being used. For example:

{
  "applicationId": "1111111-111111-111111-11111111",
  "response": "123456789",
  "secondFactorAuthenticator": "OTP"
}

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": "GENw36RGssBDAmU8UgULDBFGp2cG6aWDO0dWUQU24QyAIDo2KFzfr62MEymgHxlU17EkLPknUUCwXm/azikw04oG2qniwwZVlXghQBFoME3DvenPMCXobOeqRqyDOeLbfLWIXdlNK2jJFIpPcTQqe3puKlAis3VfwltcOgmnQTK2ZnQA6dOICTKa0Kfr+fvUg0fmdBJ8asvryswSdeNjw2ndO638uZYhYks+2QstKxTuHXsslECPPgxa1CCidWm3EDigpH2SJQ9W1FY06zq/8BQMu3sxivWGOtd1p7xg2LldXb0dnoeztI7OQSye/8NbBuzWOdGOrwTIlOSd6mECcsdMQadstzQLoAtdRCsYW0JDVhvaaNjg2l5l7d3Tte20AXKUAKLA4NTpDZSz8N74A7me1pDV5GUXY5BdhwQGqIKtwpQvzt5uv9W/inomGdr+RO9KZGOV4Nfvilqr2yxoo0HfWkNvcsqtUXrHYN4chauqTYB7vqBBQzvhK/ar7lXg4WAjbqAOUvJXhSpuG92dltNRC9TsttUyFZ4RljhyPAyh2MNevhnEIq/jd34BhYmGyUFyshrYQE/fRTI5UvGrSybUX9IJN8dpKua64GhOspO4",
  "expires": 1521648936739,
  "otpdeliveryType": null,
  "time": 1521648223398
}

This response would indicate authenticationCompleted as true. This indicates that two-factor authentication was successful.

How risk based authentication (RBA) and authentication APIs work together

Risk-based authentication (RBA) identifies the level of risk associated with each authentication request. Once the risk level is identified, RBA defines the level of authentication required to authenticate.

An authentication request consists of three API calls (as described above):

  • Get User's Authenticators
  • Select Authenticator
  • Complete Authentication Challenge

As part of figuring out what authentications are available and required, each application's resource rule uses RBA to determine the request's risk level. The risk levels possible are low, medium, and high. The risk level of the request defines which authenticators can be used. The following factors are considered when determining the request's risk level:

  1. Date and time of request
  2. Location of request
  3. Source IP address of request origin
  4. Machine Authentication (described in the next section)
  5. Location history of authentication requests received
  6. Travel velocity of authentication requests received

Machine Authentication​

Machine authentication is one of the factors used to evaluate each request's risk. Entrust recommends downloading the Identity as a ServiceGuard Device Fingerprint SDKs from TrustedCare for machine authentication. The SDK collects the device fingerprint and includes it as part of the machine authentication.

The risk condition generates a risk score by completing the following steps:

  1. The Identity as a Service user's Web Browser assigned the Machine Authenticator generates a machine secret. It includes these components:

    • Machine nonce: A value generated when the machine authenticator is registered and stored by the client.
    • Sequence nonce: Another value generated in a previous authentication attempt that is stored by the client. Unlike a machine nonce, the sequence nonce is modified every time an authentication API call is made.
    • Device fingerprint – A value collected from the client device.

  2. The machine secret is submitted to Identity as a Service in the query request.

  3. The machine secret is compared to machine secrets from previous authentication requests to determine a risk level.

  4. At the end of a successful authentication, a machine nonce and sequence nonce may be returned to the client. In that case, the client should store these values for future authentication attempts.

Below are example use cases for Machine Authentication:

  • Authentication from a new Web Browser that normally requires two-factor authentication. A resource rule could be configured to allow users to log by only completing a single-factor authentication if a valid Machine Authenticator is detected.
  • Authentication from a previously-used machine that normally only requires password authentication. The application's resource rule would need to be customized to support Machine Authentication. For example, a resource rule would be customized as follows to consider Machine Authentication and only require password authentication:
    • Customize the risk score assigned to users who do not have a Machine Authenticator
    • Customize the risk assigned to users who do have a Machine Authenticator
    • Set low risk authentication to PASSWORD + NONE
    • Medium risk authentication to PASSWORD + OTP

EXTERNAL plus Second-factor authentication​

In this type of authentication, a client has already completed the first factor authentication outside of Identity as a Service and uses Identity as a Service to determine if second-factor authentication is necessary.

This section describes how to use the Identity as a Service's Authentication APIs to complete, if required, second-factor authentication. The API calls required are similar to those required for single-factor authentication:

  1. Get User's Authenticators
  2. Complete EXTERNAL Authentication (the result indicates if second-factor is required)
  3. Select Authenticator (Second-factor)
  4. Complete Authentication Challenge (Second-factor)

Notes:

  • If the Authentication API application is configured such that the client doesn't require to perform second-factor authentication, the client will receive an authenticated JWT in step 2.
  • To use some of the risk conditions, the client IP address must be made available to Identity as a Service in all requests. You define the source of the client IP address when the Authentication API application is created. The examples below assume that you selected Provided in the API.

Get User's Authenticators​

The first step is to submit a POST request to get all the authenticators that can be used. 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 ID of the Authentication API application being accessed. For example:

{
  "userId": "jsmith",
  "applicationId": "1111111-111111-111111-11111111",
  "clientIp": "1.2.3.4"
}

A response with a JSON object to the API request is received. The response includes the authenticationTypes attribute marked as EXTERNAL. It also includes the availableSecondFactor attribute showing all the authenticators that can be used for second-factor authentication. For example:

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

Complete first-factor authentication​

The next step is to complete the first-factor EXTERNAL authentication to determine if second-factor authentication is required. A POST request to complete the EXTERNAL authentication challenge would be sent to the following URL:

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

As in the first example, this request will also include an Authorization header field. 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 a JSON object with the ID of the API application being accessed. For example:

{
  "applicationId": "1111111-111111-111111-11111111",
  "clientIp": "1.2.3.4"
}

The response received from this request would include a new token and the authenticationCompleted attribute that would be marked as false. For example:

{
  "status": null,
  "firstName": null,
  "lastName": null,
  "authenticationCompleted": false,
  "machineAuthenticator": null,
  "userMachineSettings": {
    "machineAuthenticatorEnabled": true,
    "deviceFingerprintRequired": false,
    "attributeExclusions": [],
    "userMachineAuthenticators": []
  },
  "kbaChallenge": null,
  "token": "GO7mOyRuLzfTOXLk/IbzsDEuw8cFQspxz8TCWRwcrrhtoBw/o7udXt94eTkbkDFcbMVpfqHZJcJ4vavS4MEN6wp0d7MFhd0n9A9XymY5KHKyMvrqJlqh8+NrIZjkiA0sZvrAhu+6IRGfTYfoe/DwWclJi2JNNxpMX/17b7QHZdrj5ItbJUp3wHhAswUX02uWn/Fxwnt3cxGVHgmtTaVfz42JBkiIeRcOiv81iJqfTuSrd+S29RqO4PCKYGw1pKhymottvV3eVGNxdPvwSrLgXusfuCyfAB8tGl047WJQOKaHZ7k4GbzC1QKjldNWHrMAtiLUMWaxgvpU/vANJUibIPXJ6+1i7X7U6THJJg4fBG+pJo8jPKPI1B+XxE1mNBdLdMEdfUSKwUqv3BGg8g+WsL+ZLkbSzrswuoyBKWioEVXkxUVDtRghDLDjiRFjyQMwD+MhvdoC46a10IMkz1G5kKkQ6xaTTwhkEsh2iGeWtn6WDcC0PILFX4NmiF/g650j41aFWAyOD5ULBKV04a2dYKdadGfaAH0=",
  "expires": 1521648936739,
  "otpdeliveryType": null,
  "time": 1521648060983
}

If the Authentication API application is configured in a such a way that users with low risk score do not require to perform second-factor authentication, in this step the user would be authenticated and the response would set * authenticationCompleted* as true indicating that EXTERNAL plus second-factor authentication was successful.

Select Authenticator (Second-factor)​

The next step is to send a POST request to use a specific second-factor authentication. All the available second-factor authenticator options were received in the first call we made. For example, with OTP, the request URL would be:

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

The body of this request should contain a JSON object with the ID of the Authentication API application being accessed and the token that was received from the last request. For example:

{
  "applicationId": "1111111-111111-111111-11111111",
  "clientIp": "1.2.3.4",
  "authToken": "GO7mOyRuLzfTOXLk/IbzsDEuw8cFQspxz8TCWRwcrrhtoBw/o7udXt94eTkbkDFcbMVpfqHZJcJ4vavS4MEN6wp0d7MFhd0n9A9XymY5KHKyMvrqJlqh8+NrIZjkiA0sZvrAhu+6IRGfTYfoe/DwWclJi2JNNxpMX/17b7QHZdrj5ItbJUp3wHhAswUX02uWn/Fxwnt3cxGVHgmtTaVfz42JBkiIeRcOiv81iJqfTuSrd+S29RqO4PCKYGw1pKhymottvV3eVGNxdPvwSrLgXusfuCyfAB8tGl047WJQOKaHZ7k4GbzC1QKjldNWHrMAtiLUMWaxgvpU/vANJUibIPXJ6+1i7X7U6THJJg4fBG+pJo8jPKPI1B+XxE1mNBdLdMEdfUSKwUqv3BGg8g+WsL+ZLkbSzrswuoyBKWioEVXkxUVDtRghDLDjiRFjyQMwD+MhvdoC46a10IMkz1G5kKkQ6xaTTwhkEsh2iGeWtn6WDcC0PILFX4NmiF/g650j41aFWAyOD5ULBKV04a2dYKdadGfaAH0="
}

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

{
  "status": null,
  "firstName": null,
  "lastName": null,
  "authenticationCompleted": false,
  "machineAuthenticator": null,
  "userMachineSettings": {
    "machineAuthenticatorEnabled": true,
    "deviceFingerprintRequired": false,
    "attributeExclusions": [],
    "userMachineAuthenticators": []
  },
  "kbaChallenge": null,
  "token": "GMITwEPkGILJI/jBMVT3p8a09JtGag3AzXqjan1+FBNdWjnCi16JNdpNxrBt/iuFYlozZ2Jrf6V6JEZEuQeFtZtFyETEVKNOxhbbOf+u6SmkBSwLQQm529WKUtFssLnQ9Mliojlb/1W8VXkseazUhWuvpab9t7b4Y9BP9RcXdPNdAOtR++dGwuwtAh0O6Edq9SE4yDGn8aRWJuydc7k8aQymLZfFR76y0EbG4mP/m9kZ2pDOjUrhHa8rToLLx3Jr70aHqJr5bNyCrQ96/c+5YTQeLhFL86Ch8LcIAKHh5RI2Ma6X+PTBZ4CwMrU6jUczCjJ6m94jlwIH37P0vv2GdlMZHPqjjmAuHB2SGKA0UxQywL9SbsIhyM2lxhBLUK30wRH0LHlW4reki0vF9gfc+kZQZFaVyj/bJ0P63lTsIywEmPBbCo8o21A5Mram5m+kNcCLg4ZlIaM2bWrvtBX0SxL5Cpx7vy1cUABQw+4ifRgcrwt6KWgIngmu1y/ItwaLCGgvw2dCFd3kPHd+HoXzsb2aVP+9tqo=",
  "expires": 1521648936739,
  "otpdeliveryType": "SMS",
  "time": 1521648184761
}

The token received in this request would be used to complete the second-factor authentication in the next step.

Complete authentication challenge (Second-factor)​

The last step is to send a POST request to complete the second-factor authentication challenge. For example:

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

As in the first example, this request will also include an Authorization header field. 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 a JSON object with the second-factor response, the ID of the application being accessed, and the second-factor authenticator being used. For example:

{
  "applicationId": "1111111-111111-111111-11111111",
  "response": "123456789",
  "clientIp": "1.2.3.4"
}

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

{
  "status": null,
  "firstName": "John",
  "lastName": "Smith",
  "authenticationCompleted": true,
  "machineAuthenticator": null,
  "userMachineSettings": null,
  "kbaChallenge": null,
  "token": "GENw36RGssBDAmU8UgULDBFGp2cG6aWDO0dWUQU24QyAIDo2KFzfr62MEymgHxlU17EkLPknUUCwXm/azikw04oG2qniwwZVlXghQBFoME3DvenPMCXobOeqRqyDOeLbfLWIXdlNK2jJFIpPcTQqe3puKlAis3VfwltcOgmnQTK2ZnQA6dOICTKa0Kfr+fvUg0fmdBJ8asvryswSdeNjw2ndO638uZYhYks+2QstKxTuHXsslECPPgxa1CCidWm3EDigpH2SJQ9W1FY06zq/8BQMu3sxivWGOtd1p7xg2LldXb0dnoeztI7OQSye/8NbBuzWOdGOrwTIlOSd6mECcsdMQadstzQLoAtdRCsYW0JDVhvaaNjg2l5l7d3Tte20AXKUAKLA4NTpDZSz8N74A7me1pDV5GUXY5BdhwQGqIKtwpQvzt5uv9W/inomGdr+RO9KZGOV4Nfvilqr2yxoo0HfWkNvcsqtUXrHYN4chauqTYB7vqBBQzvhK/ar7lXg4WAjbqAOUvJXhSpuG92dltNRC9TsttUyFZ4RljhyPAyh2MNevhnEIq/jd34BhYmGyUFyshrYQE/fRTI5UvGrSybUX9IJN8dpKua64GhOspO4",
  "expires": 1521648936739,
  "otpdeliveryType": null,
  "time": 1521648223398
}

This response would indicate authenticationCompleted as true. This indicates that two-factor authentication was successful.

User logout​

To log the user out, send a POST request which invalidates the user session and logs the user out of Identity as a Service. For example:

https://customer.region.trustedauth.com/api/web/v1/authentication/logout

OIDC/OAuth Authentication/Authorization Flows and Resource Server API Protection

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.

Note: 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:

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

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

OAuth2 Authorization with OIDC Authentication​

OAuth authorization 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:

  • resource = https://example.com/apis/calendar
  • scope = openid profile offline_access view:calendar edit:calendar

or

  • 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 and the others are optional (e.g., profile).

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 for both OIDC authentication and OAuth authorization tokens 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.

OAuth2 Authorization with OIDC Authentication​

OAuth authorization 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:

  • resource = https://example.com/apis/calendar
  • scope = openid profile offline_access view:calendar edit:calendar

or

  • 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 and the others are optional (e.g., profile).

There is no consent page as identity as a service does not control 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 get all the 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. The ID of the application is optional in this case. For example:

{
  "userId": "jsmith",
  "authRequestKey": "QoOuQ3JyccbHqVJxUwHInxSPdn37nSJTgOMn6UE3Yi9c="
}

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​

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.

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 transaction details exist in the request, and the OAuth2 JWT access token needs to contain transaction_details claim, the authRequestKey obtained from authorization jwt endpoint is required. Otherwise, authRequestKey is not needed. 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 request to token endpoint. See Token Endpoint 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 for both OIDC authentication and OAuth authorization tokens 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.

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 with 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:

  • 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 and the others are optional (e.g., profile).

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.

Note: 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.

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 for to logout out 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.

OIDC/OAuth Token Examples​

The following is the resulting token payload data for various types of tokens. These have been parsed and simplified for display purposes. Items, such as signatures, have been removed.

OIDC ID Token​

{
  "sub": "user1",
  "aud": "acd612d3-79e6-4702-ba9d-90575125394f",
  "acr": "urn:oasis:names:tc:SAML:2.0:ac:classes:TimeSyncToken",
  "nbf": 1616425220,
  "auth_time": 1616425012,
  "iss": "https://customer.region.trustedauth.com/api/oidc",
  "exp": 1616425940,
  "iat": 1616425220,
  "nonce": "abcd",
  "jti": "3f4e7ed0-e916-4140-9c3e-93ad7a4aabd2"
}

OIDC Access Token (for Userinfo data)​

U-720039ce-5a55-433a-85a2-3a4ee720d9d6-QJ1N4r3jEFOjPBeNfXQw0wbJHzErgG3uS3MJAZI5bSk=

The corresponding Userinfo data that is obtained based on the access token

{
  "sub": "user1",
  "aud": "acd612d3-79e6-4702-ba9d-90575125394f",
  "name": "User One",
  "iss": "https://customer.region.trustedauth.com/api/oidc",
  "given_name": "User",
  "family_name": "One",
  "email": "user1@example.com",
  "iat": 1616423220
}

OAuth Access Token (used with Resource Server APIs)​

{
  "app": "Sample Client Application",
  "sub": "user1",
  "iss": "https://customer.region.trustedauth.com/api/oidc",
  "given_name": "User",
  "aud": "https://example.com/apis/calendar",
  "nbf": 1616425220,
  "scope": "view:calendar edit:calendar",
  "name": "User One",
  "exp": 1616428820,
  "iat": 1616425220,
  "family_name": "One",
  "jti": "5f474e42-92ef-4ae4-bab7-b5ab2c052161",
  "cid": "acd612d3-79e6-4702-ba9d-90575125394f"
}

Refresh Token​

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

Authentication​

Security Scheme Type:

apiKey

Header parameter name:

Authorization

Contact

Entrust Identity as a Service: support@entrust.com

URL: https://www.entrust.com/

License

By using the Entrust Identity as a Service (IDaaS) Authentication API, you agree to the terms of the license.