API Integration Flows

The following sections illustrate the authentication flows with client applications by integrating the various HID Authentication Service API endpoints.

In these flows, the client application calls the APIs via the customer back end with an authenticated client. This client submits a PAR request based on which the HID Authentication Service generates the request_uri for the end user authentication process.

Note: If the client application will call the APIs directly without a back end, it must be allowed in the HID Authentication Service Cross-Origin Resource Sharing (CORS) configuration. For further information, contact HID Global Technical Support.

Enable the Authentication Flow

As an integrator, you can enable the APIs to deploy authentication workflows for a custom front-end application, leveraging the various elements of the HID Authentication Service workflows.

Note: For details of the available parameters, see Create the Authentication Workflow.

Push Authentication Request

The Service Provider (SP) creates the authorization request and sends users to the authentication portal using the par endpoint.

Copy

Create authorization request

POST https://[base-server-url]/tenant/authn/par HTTP/1.1
Content-Type: application/x-www-form-urlencoded
Authorization: Bearer RTp7HwAAAXyStuhFZfZf2g4BQmVj1yf84hUvta3j
scope=openid accounts payments
&response_type=code id_token
&login_hint=5619630280
&nonce=n-0S6_WzA2Mj
&client_id=spl-pisp
&redirect_uri=https://<localhost>
&request=CJleHAiOjE0OTUxOTk1ODd...JjVqsDuushgpwp0E.5leGFtcGxlIiwianRpIjoiM...JleHAiOjE0.olnx_YKAm2J1rbpOP8wGhi1BDNHJjVqsDuushgpwp0E
Copy

PAR Response

HTTP/1.1 200 OK
Cache-Control: no-cache, no-store
Content-Type: application/json
{
    "request_uri": "urn:hid:43d5b009-7b52-4d6f-a8a9-0d8de27968f9",
    "expires_in": 300
}

Authentication Request

The Service Provider (SP) delegates the authentication to the HID Authentication Service using the login endpoint.

HID Authentication Service supports two modes:

  • Using the par endpoint request_uri parameter where the SP must be pre-authenticated to the HID Authentication Service and the parameters are hidden (POST request)

    Copy

    Initiate Authentication by PAR request

    GET https://[base-server-url]/tenant/authn/login?request_uri=urn:hid:43d5b009-7b52-4d6f-a8a9-0d8de27968f9&client_id=spl-pisp
  • Using the login endpoint for 'standard' mode where all the required parameters are sent in the query and visible in the GET query string

    For example, the boostrap URL for standard flow will be:

    Copy
    GET https://[base-server-url]/tenant/authn/login?
    state=VzRP4nD6iKCKPuRi
    &nonce=rgu1VjOl2J0HHItd
    &response_type=code,id_token
    &scope=openid
    &redirect_uri=https://<localhost>
    &client_id=spl-api
    &login_hint=myuserid
    Note: The above URL contains only required parameters for illustration, the other optional parameters are also supported.

The response from HID Authentication Service sends the user to the authentication portal as defined in the URL configured for the OpenID client application, including the theme identifier for the required interface design.

Copy

Sample response to authorization request

HTTP/1.1 302 Found
Location: https://[base-server-url]/authn/portal?theme_id=ID_THEME1&request_uri=urn:hid:43d5b009-7b52-4d6f-a8a9-0d8de27968f9
Set-Cookie: server-csrf-token= urn:hid:256ab6ef-12c4-47e3-b220-0e96c161d283; Domain=<svcaddress>; Path=/; Expires=Sun, 14 Nov 2021 22:23:01 GMT; Secure; SameSite=Strict
Copy

Client gets the portal design (theme)

GET https://<portaladdress>/<tenant>/authn/portal?theme_id=ID_THEME1?request_uri=urn:hid:43d5b009-7b52-4d6f-a8a9-0d8de27968f9

Authentication Workflow

The Flow endpoint retrieves the workflow defined in the client application configuration (workflow_id) to authenticate the user and is called before the interface is displayed to the user.

The workflow configuration defines the authentication factors (first and second) and associated actions.

The interface display is filtered based on access criteria so the user can only select the relevant authentication methods, including conditioning for the first and second factors.

Copy

Sample Request

GET https://[base-server-url]/<tenant>/authn/flow?request_uri=urn:hid:43d5b009-7b52-4d6f-a8a9-0d8de27968f9
server-csrf-token: urn:hid:256ab6ef-12c4-47e3-b220-0e96c161d283
Content-Type: application/x-www-form-urlencoded

HID Authentication Service validates the access criteria based user context (authenticators, devices, ...).

Copy

Sample Response

HTTP/1.1 200 OK
Content-Type: application/json
Cache-Control: no-cache, no-store
{
    "actions": [
        {
            "actionId": "action.change_password",
            "accessCriteriaId": "access_criteria.common_to_all",
            "type": "CHANGE_PWD",
            "retry": 3
        },
        {
            "actionId": "action.forgot_password",
            "accessCriteriaId": "access_criteria.common_to_all",
            "type": "FORGOT_PWD",
            "validityPeriod" : 900,
            "retry": 3,
            "resetPasswordMethods": [ "email", "sms" ]
        }
    ],
    "firstFactors": [
        {
            "factorId": "factor.user_password",
            "accessCriteriaId": "access_criteria.common_to_all",
            "code": "AT_CUSTPWD",
            "type": "LOGIN",
            "retry": 3,
            "expirationWarningThreshold" : 259200,
            "constraints": {
                "minLength": 1,
                "maxLength": 50
                ...other constraints...
            },
            "actions": [
                "action.change_password",
                "action.forgot_password"
            ]
        },
        {
            "factorId": "factor.pki",
            "accessCriteriaId": "access_criteria.common_to_all",
            "code": "AT_EMPPKI",
            "type": "PKI"
        }
    ],
    "secondFactors": [
        {
            "factorId": "factor.push_authentication",
            "accessCriteriaId": "access_criteria.common_to_all",
            "code": "AT_PASA-2FA",
            "type": "PUSH",
            "retry": 3,
            "pollTimeout": 30,
            "pollInterval": 2,
            "okStatus": "approved",
            "upon": [ "factor.customer_password_with_reset" ],
            "devices": [
                {
                    "deviceId": 15168,
                    "deviceFriendlyName": "my phone"
                },
                {
                    "deviceId": 15169,
                    "deviceFriendlyName": "my laptop"
                },
                {
                    "deviceId": 15170,
                    "deviceFriendlyName": "my tablet"
                }
            ]
        }
    ],
    "enrollActions": []
}

If the user does not meet the access criteria requirements for the requested resource (for example, they do not have a required authenticator factor), a workflow template cannot be applied and HID Authentication Service will return an error and maintain the error in the PAR context.

Copy

Sample Error Response

HTTP/1.1 400 Bad Request
{
    "error": "no_template_found_for_criteria",
    "error_description" : "User does not meet the access criteria, no authentication template applies"
}

Authentication Portal Design

The Theme endpoint retrieves the design for the portal interface defined in the client application configuration (theme_id) and the returned value is the content from the payload.

Copy

Sample request to retrieve the theme

GET https://[base-server-url]/{tenant}/authn/theme?&theme_id=ID_THEME1&request_uri=urn:hid:43d5b009-7b52-4d6f-a8a9-0d8de27968f9
server-csrf-token: urn:hid:256ab6ef-12c4-47e3-b220-0e96c161d283
Copy

Sample response

HTTP/1.1 200 OK
ontent-Type: application/json
{
    "ui": {
        "hid_portal": {
            "gradient-start": "red",
            "gradient-end": "orange",
            "logo": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAVWZqWNWH.....<shortened>...LVjB1zBZk1nJTi/LYLKyb3YxefWSOu1b1t9HnOP+eHXbHZnV95bz0evVCtToyzZqNaY6q1UK9dy/UNmzYsGHDhg1C8D/J9batc1Yi+wAAAABJRU5ErkJggg=="
        },
        "extensions": {
            "mycustomelement1": {
                "color": "red"
            },
            "mycustomelement2": {
                "color": "orange"
            },
            "mycustomelement3": {
                "mycustomlogo1": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAVWZqWNWH.....<shortened>...LVjB1zBZk1nJTi/LYLKyb3YxefWSOu1b1t9HnOP+eHXbHZnV95bz0evVCtToyzZqNaY6q1UK9dy/UNmzYsGHDhg1C8D/J9batc1Yi+wAAAABJRU5ErkJggg=="
            }
        }
    },
    "localization": {
        "hid_portal": {
            "fr": {
                "service_name": "Mon service d'authentification HID",
                "service_tagline": "Construisez et délivrez rapidement vos solutions d'identité de confiance",
                "company_name": "Mon HID Global",
                "application_title": "Mon service d'authentification"
            },
            "en": {
                "service_name": "My HID Authentication Service",
                "service_tagline": "Rapidly build and deliver your trusted identity solutions",
                "company_name": "My HID Global",
                "application_title": "My Authentication Service"
            }
        },
        "extensions": {}
    }
}

Authentication and Authorization

The Code endpoint provides the session transfer/authorization codes after the user's credentials and consent have been verified.

The following samples illustrate the successful authentication flow (password and OTP) and consent verification.

Copy

Sample request - authentication with password as the first factor

POST https://[base-server-url]/{tenant}/authn/code
Content-Type: application/x-www-form-urlencoded
server-csrf-token: urn:hid:256ab6ef-12c4-47e3-b220-0e96c161d283
 
request_uri=urn:hid:43d5b009-7b52-4d6f-a8a9-0d8de27968f9
&grant_type=password
&authType=AT_CUSTPWD
&username=5619630280
&password=54917067
Copy

Sample response for successful first factor authentication and step-up required (second factor)

HTTP/1.1 400 Bad Request
Content-Type: application/json
server-csrf-token: urn:hid:256ab6ef-12c4-47e3-b220-0e96c161d283

{
    "error_description": "Step up required",
    "error": "step_up_required",
    "secondFactors": [
        {
            "factorId": "factor.cust_pin",
            "acr": "1",
            "code": "AT_EMPPIN"
            "type": "LOGIN",
            "upon": [
                "factor.user_password"
            ],
            "constraints": {
                "atLeastOneUp": false,
                "atLeastOneNum": false,
                "notBlackListed": true,
                "atLeastOneLow": false,
                "minDiffChars": 5,
                "notOldPassword": true,
                "minLength": 8,
                "notUserAttribute": true,
                "characterRange": "onlyNum",
                "maxLength": 100,
                "atLeastOneSpecial": false,
                "notSequence": true
            },
            "accessCriteriaId": "access_criteria.common_to_all",
            "retry": 1
        }
    ]
}

Where:

  • HID Authentication Service generates a random server-csrf-token value attached to the PAR request which must be passed in the subsequent requests and responses by the portal (step-up, consent, redirection etc) to prevent CSRF attacks

  • expires_in is the validity period (in seconds) of the authenticator and a warning will be displayed before expiration based on expirationWarningThreshold

Copy

Sample request - authentication with OTP as the second factor

POST https://[base-server-url]/{tenant}/authn/code
Content-Type: application/x-www-form-urlencoded
server-csrf-token: urn:hid:256ab6ef-12c4-47e3-b220-0e96c161d283
 
request_uri=urn:hid:43d5b009-7b52-4d6f-a8a9-0d8de27968f9
&grant_type=password
&authType=AT_CUSTOTP
&username=5619630280
&password=41096522
Copy

Sample response for successful second factor authentication but the user needs to sign the consent

HTTP/1.1 400 Bad Request
Content-Type: application/json
server-csrf-token: urn:hid:256ab6ef-12c4-47e3-b220-0e96c161d283

{
    "error":"consent_required",
    "error_description":"consent not signed"
}

As the user is required to consent to the sharing of their data, the Consent endpoint is called to retrieve the consent prompt containing details of the information that will be shared:

Copy

Sample request

GET https://[base-server-url]/{tenant}/authn/consent&request_uri=urn:hid:43d5b009-7b52-4d6f-a8a9-0d8de27968f9
server-csrf-token: urn:hid:256ab6ef-12c4-47e3-b220-0e96c161d283
Copy

Sample response


HTTP/1.1 200 OK
Content-Type: application/json
server-csrf-token: urn:hid:256ab6ef-12c4-47e3-b220-0e96c161d283
Cache-Control: no-store
Pragma: no-cache

{
    "consents": [
        {
            "clientid": "spl-idp2",
            "sharing_duration": -1,
            "description": "spl-idp2",
            "sharings": [
                {
                    "scope": "openid",
                    "description": "openid",
                    "status": "accepted"
                },
                {
                    "scope": "profile",
                    "description": "User profile",
                    "status": "unknown"
                }
            ]
        }
    ]
}
Copy

Request to redirect user to SP with authentication successful and consent verified (or error at any step of the flow)

GET https://[base-server-url]/{tenant}/authn/code&request_uri=urn:hid:43d5b009-7b52-4d6f-a8a9-0d8de27968f9
server-csrf-token: urn:hid:256ab6ef-12c4-47e3-b220-0e96c161d283
Copy

Sample Response

HTTP/1.1 302 Found
server-csrf-token: urn:hid:256ab6ef-12c4-47e3-b220-0e96c161d283
Location: https://api.mypisp.com/cb?

code=SplxlOBeZQQYbYS6WxSbIA
&id_token=eyJ0 ... NiJ9.eyJ1c ... I6IjIifX0.DeWt4Qu ... ZXso
&state=af0ifjsldkj

For further authentication flows and code samples, see Code Endpoint.

Enable FIDO Enrollment and Authentication

As an integrator, you can enable the APIs to deploy FIDO enrollment and authentication workflows for a custom front-end application where the device is then activated and associated with a user in the HID Authentication Service.

The FIDO flow is more complex as it requires managing the communication between the passkey, client application, customer back end and the HID Authentication Service.

The flows below are illustrated using WebAuthn although this is not mandatory for custom flows. The only requirement is that the format of the objects passed to the HID Authentication Service back-end APIs is respected (see the relevant section below).

Framework Guidelines

In this use case, the application framework (front end and back end) requirements are:

  • The client-side is responsible for the communication with the FIDO authenticator

  • An authenticated OpenID client performs the calls to the API endpoints

  • A workflow configuration is defined for the OpenID client (see Create the Authentication Workflow)

  • A component capable of interacting with the FIDO authenticator device leveraging the WebAuthn objects used by the API, for example:

    • Running inside the browser (for example, a JavaScript component on top of WebAuthn)

    • Directly on top of CTAP2 or using specific platform API (such as FIDO platform authenticator)

  • The enrollment process is protected (for example, by pre-authenticating the end user using another authentication factor)

The following sections provide guidelines for the enrollment and authentication flows.

Custom Application FIDO Enrollment Flow

Prerequisites: On the HID Authentication Service back end:
  • Create the user (see the Users endpoint)

  • To implement the devicebinding option, you must also create a pending FIDO authenticator for the user

  • To protect the enrollment process, the user must have an existing authentication method

Note: For details of the available parameters, see Add an Enrollment Workflow.
  1. Authenticate your OpenID client for you customer application by calling the the Token endpoint to get an access_token to be used in the Authorization header for the following requests.

  2. Start the enrollment process on the customer back end using the PAR endpoint.

  3. If EnrollmentProtection is configured, authenticate the user using the Enroll/code endpoint.

  4. Send a request to get the PublicKeyCredentialCreationOptions (the parameters required to create the FIDO authenticator):

    1. On the customer back end, get publicKeyCredentialOptions from the HID Authentication Service back end using "enroll_step": "getcredentialoptions" on the Enroll/fido endpoint.

    2. On the customer back end, send the returned publicKeyCredentialOptions to the customer client.

  5. Create the new credential on the FIDO passkey:

    1. On the customer client, send PublicKeyCredential = navigator.credentials.create(publicKeyCredentialOptions)

    2. On the customer client, send the JSON-formatted PublicKeyCredential.response (authenticatorattestationresponse) to the customer back end.

  6. Register the FIDO credential (credential ID and public key) on the HID Authentication Service back end:

    1. On the customer back end, register the authenticatorattestationresponse on the HID Authentication Service back end using "enroll_step": "registercredential" on the Enroll/fido endpoint.

    2. On the customer back end, send the result (success or failure) to the customer client.

Custom Application FIDO Authentication Flow

Note: For details of the available parameters, see Create the Authentication Workflow.
  1. Authenticate your OpenID client for you customer application by calling the the Token endpoint to get an access_token to be used in the Authorization header for the following requests.

  2. Start the authentication process on the customer back end using the Par endpoint.

  3. Send a request to get the PublicKeyCredentialRequestOptions:

    1. On the customer back end, get publicKeyCredentialOptions from the HID Authentication Service back end using "grant_type": "fido_challenge" on the Code endpoint.

    2. On the customer back end, send publicKeyCredentialOptions to the customer client.

  4. Get the enrolled credential (registered on the server):

    1. On the customer client, send PublicKeyCredential = navigator.credentials.get(publicKeyCredentialOptions)

    2. On the customer client, send the JSON-formatted PublicKeyCredential.response (authenticatorattestationresponse) to the customer back end.

  5. Verify the FIDO attestation certificate and signature on the HID Authentication Service back end:

    1. On the customer back end, validate the authenticatorattestationresponse on the HID Authentication Service back end using "grant_type": "password" on the Code endpoint.

    2. On the customer back end, send the result (success or failure) to the customer client.

    3. On the customer back end, send a request to the Code endpoint to end the process (delete the context and get the result).

      • With GET, an authorization code is redirected to redirect_uri to end the process

      • With POST using grant_type=code_request to get the authorization code in the response