Code Endpoint

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

When the user is successfully authenticated, HID Authentication Service checks the consent:

  • If the consent is already signed and valid, it will generate an authorization code and redirect it to corresponding redirect URI.

  • Otherwise, it will return an error indicating that the consent needs to be signed.

    The replaying party (RP) should then use the Consent endpoint to get the consent content and prompt the user for their signature.

    Once it is signed, the process returns to the Code endpoint to continue the generation of the authorization code.

The differences with the Token endpoint are:

  • The return value is an authorization code, optionally linked to an id_token - with PKCE support

  • If a redirect uri is specified (and matches that specified in the client configuration), Code returns 302 instead of 200 (the code and id_token are appended in the query parameters of the redirection URI)

  • The status of the user consent for shared data is verified (signed, expired, not signed)

Copy

The endpoint is exposed at the following URL (and can be obtained from the server discovery endpoint):

https://[base-server-url]/{tenant}/authn/code [POST]
Method Details
POST for FIDO
POST for Password
POST for Code
POST for Card

Sample Two-Step Authentication Flow with 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

LDAP Authentication

Note: For federated LDAP authentication:

  • The users must already be registered in HID Authentication Service

  • The registered users must not have an existing authenticator (device/credentials) as the LDAP authenticator will be automatically created

  • The workflow must be configured with LDAP as the first factor and OOB as the second factor

  • LDAP Fallback is implicitly allowed if the workflow includes an LDAP authentication factor

Copy

Sample request - authentication with LDAP as the first factor

POST https://[base-server-url]/{tenant}/authn/code
Content-Type: application/x-www-form-urlencoded 
request_uri=urn:hid:43d5b009-7b52-4d6f-a8a9-0d8de27968f9
&grant_type=password
&authType=AT_LDAP
&username=myuser@company.com
&password=<myuserpassword>
Copy

Sample response - authentication successful

HTTP/1.1 200 OK
server-csrf-token: urn:hid:256ab6ef-12c4-47e3-b220-0e96c161d283
{
    "server-csrf-token": "urn:hid:256ab6ef-12c4-47e3-b220-0e96c161d283",
    "expires_in": 5184000
}
Copy

Sample response - authentication failed

HTTP/1.1 400 Bad Request
{
    "error_description": "Invalid grant: Resource owner username or password is invalid",
    "error": "invalid_grant"
}
Copy

Sample response - authentication successful and no-step-up required but consent required

HTTP/1.1 400 Bad Request
{
    "error": "consent_required",
    "error_description" : "User consent is missing or expired, User approval is required",
    "server-csrf-token": "urn:hid:256ab6ef-12c4-47e3-b220-0e96c161d283"
}

OOB Authentication

  • The OOB authentication flow can be triggered by user action:

    Copy

    Sample request - user triggers OTP delivery via email with their Activation code (factor type CODE)

    POST https://[base-server-url]/{tenant}/authn/code
    Content-Type: application/x-www-form-urlencoded
    request_uri=urn:hid:43d5b009-7b52-4d6f-a8a9-0d8de27968f9
    &grant_type=accode
    &authType=AT_OOB
    &usrname=5619630280
    &password=1234
    &method=email
    &locale=en-US
    Copy

    Sample request - user triggers OTP delivery via SMS with their Activation code

    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=accode
    &authType=AT_OOB
    &username=5619630280
    &password=1234
    &method=sms
    &locale=en-US

  • The OOB authentication flow can be triggered by the server:

    Copy

    Sample request - server triggers OTP delivery where the user selects the delivery channel (email or SMS) (factor type OOB)

    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=oob
    &authType=AT_OOB
    &username=5619630280
    &method=email (or sms)
    &locale=en-US
    Copy

    Sample request - server triggers OTP delivery where the channel is automatically selected on the back end (factor type OOB)

    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=oob
    &authType=AT_OOB
    &username=5619630280
    &locale=en-US

  • The OOB flow can be triggered by the user or server:

    Copy

    Sample request - OTP is received in a standard call with grant_type=password (but with same policy from factor type OOB)

    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_OOB
    &username=5619630280
    &password=54917067

FIDO Authentication

The FIDO authentication flow starts after the user has enrolled their passkey using the Enrollment endpoint.

Copy

Sample request to retrieve FIDO challenge from the back end

POST https://[base-server-url]/{tenant}/authn/code
Content-Type: application/json
{
    "request_uri": "urn:hid:43d5b009-7b52-4d6f-a8a9-0d8de27968f9" ,
    "grant_type": "fido_challenge",
    "username" : "testfido", 
    "authType": "AT_FIDO"
}

The response includes the challenge and allowCredentials array containing the credential identifier(s) of the user's FIDO passkey(s) that correspond to the device type specified in workflow configuration.

Copy

Sample response for a FIDO passkey

HTTP/1.1 200 OK
server-csrf-token: urn:hid:256ab6ef-12c4-47e3-b220-0e96c161d283
{
    "challenge": "NtxjwWK3VZzlNI2ckMkf1tu0lc2cTZhU",
    "allowCredentials": [ {
        "id": "TZwMoswIbOR2w6IEQvkWu0bDepIXQ7ov_k2EPIc4y8Tje6yhP-f63r6c8_BkdNgdzwf_LoS9EeHofCQSNqKclg",
        "type": "public-key" }
    ] 
}
Copy

Sample response for a FIDO passkey where the transports parameter indicates the communication method

HTTP/1.1 200 OK
server-csrf-token: urn:hid:256ab6ef-12c4-47e3-b220-0e96c161d283
{
    "userVerification": "required",
    "challenge": "AGnGpm_iy-ElSV2sQlJja3QznINBX7SU",
    "rpId": "localhost",
    "allowCredentials": [
        {
            "transports": [
                "hybrid",
                "internal"
            ],
            "id": "ARKRHvCb6KmOunzLaSBTyOvD9CNH9VAAWcDkOn8vFk1AsHFAhfW9iWvK8Ly6ukHqkTGynWBT6hely9jS7FMdE8Y=",
            "type": "public-key"
        }
    ]
}
Note: For the IdP, if discoverCredentialsInDevice is set to false, allowCredentials returns the list of all the credentials (discoverable or non-discoverable) available for the user. If set to true, the user will only be able to choose from a list of discoverable keys.

The client application calls the WebAuthn to retrieve the signed assertion (a JSON formatted with inner arraybuffer objects encoded in base64url).

The Code endpoint is then called to validate the FIDO assertion (signature and counter).

Copy

API to verify the FIDO assertion

POST https://[base-server-url]/{tenant}/authn/code
server-csrf-token: urn:hid:256ab6ef-12c4-47e3-b220-0e96c161d283
{
    "request_uri": "urn:hid:43d5b009-7b52-4d6f-a8a9-0d8de27968f9",
    "grant_type": "password",
    "username": "testfido",
    "authType": "AT_FIDO",
    "password": {
        "id": "WK_ON6Tolgfcjm9AQ_axEA",
        "response": {
            "authenticatorData": "zHUM-fXe8fPTc7IQdAU8xhonRmZeDznRqJqecdVRcUMFYfOzqg",
            "signature": "MEUCIHxzf1KZNJTb831gqw0oit-6ms8DoSXLaM8zyZ4Q6iyjAiEAwbguOZU2iJae_I8-Q7qlFwR45isZ-XYVMDgU2SkABU8",
            "userHandle": "Kosv9fPtkDoh4Oz7Yq_pVgWHS8HhdlCto5cR0aBoVMw",
            "clientDataJSON": "eyJ0eXBlIjoid2ViYXV0aG4uZ2V0IiwiY2hhbGxlb...G53b3Jrcy5naXRodWIuaW8iLCJjcm9zc09yaWdpbiI6ZmFsc2V9"
        }
    }
}
Note:  

  • The password field is a JSON constructed from the response field in the WebAuthn result that contains the FIDO assertion with the result from the device

  • The id parameter (that is, the credential ID) can be added to the request to allow the back end find and verify the specific credential, instead of trying all the detected FIDO credentials. This will make the authentication flow more efficient and increment the credential authentication counter

If validated, the user is authenticated.

Copy

Sample response

HTTP/1.1 200 OK
server-csrf-token: urn:hid:60419bb3-2ab3-47ac-a767-334eb0aeacb5
{
    "expires_in": 5184000
}

A final call is made to terminate the process (by removing the object associated to request_uri) and returns the result of the process that can include an authorization code or an id_token for the user depending on the response_type in the par request.

Copy

Sample request to get the result of the process

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

Sample response

HTTP/1.1 200 OK
server-csrf-token: urn:hid:256ab6ef-12c4-47e3-b220-0e96c161d283
{
    "code": "SplxlOBeZQQYbYS6WxSbIA",
    "id_token": "eyJ0 ... NiJ9.eyJ1c ... I6IjIifX0.DeWt4Qu ... ZXso"
}

See also User Authentication with a FIDO Passkey.

Card Authentication

The Card authentication flow starts after the user has enrolled their card using the Enrollment endpoint.

Copy

Sample Request

POST https://[base-server-url]/{tenant}/authn/code
Content-Type: application/json
server-csrf-token: urn:hid:256ab6ef-12c4-47e3-b220-0e96c161d283
{
    "grant_type": "card",
    "request_uri": "urn:hid:aa407830-595b-42dd-90dd-8de5af9c1294",
    "authType": "AT_CARD",
    "password": {
        "OTP": "413620",
        "UID": "EEDxsQAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA",
        "version": 1    
    }
}

Where the body must contain the following mandatory attributes:

  • grant_type - must be card

  • request_uri - created by PAR request at the /par endpoint

  • authType - a card authentication type that must have been created by the Card Auth application at the /application/CardAuth endpoint

  • password - a JSON object containing the TOTP, the card UID and the card data version

Copy

Sample response - authentication successful

HTTP/1.1 200 OK
server-csrf-token: urn:hid:256ab6ef-12c4-47e3-b220-0e96c161d283

PKI Authentication

The Code endpoint redirects the authentication call to the mtls_url defined in the client configuration without any secret.

Copy

Sample request to perform the call on mtls_url

POST https://<mtls_url>/authn/code
Content-Type: application/x-www-form-urlencoded
request_uri=urn:hid:43d5b009-7b52-4d6f-a8a9-0d8de27968f9
&grant_type=mtls
&authType=AT_EMPPKI
&username=myuser@company.com

This call triggers the browser to request a client certificate selection for mTLS to establish the connection.

The certificate is extracted from the TLS connection and passed in the configured header (by default, ClientCertificateHTTPHeader="HID-SSL-CERT").

The IdP back end retrieves the certificate value using header (defined by ClientCertificateHTTPHeader) from the request and performs the PKI authentication.

Note: The OpenID metadata includes the mTLS endpoints:
Copy
"hid_authz_code": "https://[base-server-url]/{tenant}/authn/code",
"mtls_endpoint_aliases":
    {
        "token_endpoint": "https://mtls.[base-server-url]/{tenant}/authn/token",
        "hid_authz_code": "https://mtls.[base-server-url]/{tenant}/authn/code", 
    }

For further information, see OpenID Provider Metadata and Client ID and User Authentication with mTLS.

Push Authentication (as Second Factor)

Push authentication is usually implemented as a second factor, where the corresponding first factor is defined in the upon parameter in the workflow factor definition.

Push authentication is allowed if the state attached to request_uri (PAR request) is STEP_UP_REQUIRED when authentication with the first factor defined in upon is successful.

For further information, see Define the Authentication Factors.

Copy

Push request creation using the CIBA poll mode

POST https://[base-server-url]/{tenant}/authn/code
Content-Type: application/json
server-csrf-token: urn:hid:256ab6ef-12c4-47e3-b220-0e96c161d283
{
    "request_uri" : "urn:hid:43d5b009-7b52-4d6f-a8a9-0d8de27968f9",
    "grant_type": "urn%3Aopenid%3Aparams%3Agrant-type%3Aciba&",
    "login_hint_token": {
        "authType": "AT_PASA",
        "tds": "Logon to portal",
        "usercode": "bankuser01",
        "deviceid": "11058"
    }
}
Copy

Sample response

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8 
server-csrf-token: urn:hid:256ab6ef-12c4-47e3-b220-0e96c161d283
{
    "auth_req_id": "a95c61e0-f604-4905-98b1-26b7b87fe073",
    "interval": 5,
    "expires_in": 120
}
Note: txid that is now part of the standard bcauthorize response endpoint must not be returned.
Copy

Sample request to retrieve authentication result using the CIBA poll mode

POST https://[base-server-url]/{tenant}/authn/code
server-csrf-token: urn:hid:256ab6ef-12c4-47e3-b220-0e96c161d283
request_uri=urn:hid:43d5b009-7b52-4d6f-a8a9-0d8de27968f9
&grant_type=ciba_poll
&auth_req_id=a95c61e0-f604-4905-98b1-26b7b87fe073

HID Authentication Service then checks the clientapprovalstatus of the HID Approve process and consent.

Copy

Sample response when the user has approved or denied the request on HID Approve and consent already been signed

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
server-csrf-token: urn:hid:256ab6ef-12c4-47e3-b220-0e96c161d283
{
    "auth_req_id": "a95c61e0-f604-4905-98b1-26b7b87fe073"
}

The IdP will then request redirection to the SP and the HID Authentication Service will check the state on the server-side. It will redirect to the SP with OK or an error depending on the state.

Copy

Sample response when the user has approved the request on HID Approve but consent has not yet been signed

HTTP/1.1 400 Bad Request
server-csrf-token: urn:hid:256ab6ef-12c4-47e3-b220-0e96c161d283
{
    "error": "consent_required",
    "error_description" : "User consent is missing or expired, User approval is required",
    "auth_req_id"="a95c61e0-f604-4905-98b1-26b7b87fe073"
}
Note: If user as denies the request, the state is set to 'fail'.
Copy

Sample response when the authentication request is still in progress

HTTP/1.1 400 Bad Request
Content-Type: application/json;charset=UTF-8
server-csrf-token: urn:hid:256ab6ef-12c4-47e3-b220-0e96c161d283
{
    "error_description": "The authorization request is still pending as the end-user hasn't yet been authenticated.",
    "error": "authorization_pending",
    "auth_req_id"="a95c61e0-f604-4905-98b1-26b7b87fe073"
}
Copy

Sample response if their is no user action on HID Approve (the request expires), the IdP will time out and request redirection to the SP with an error

HTTP/1.1 400 Bad Request
Content-Type: application/json;charset=UTF-8
{
    "error_description": "The auth_req_id has expired. The Client will need to make a new Authentication Request.", 
    "error": "expired_token",
    "auth_req_id"="a95c61e0-f604-4905-98b1-26b7b87fe073"
}

If the user cancels the push request during the CIBA polling period and the reties, the IdP can explicitly delete the request before creating a new one:

Copy

Sample request to delete a pending request

POST https://[base-server-url]/{tenant}/authn/code
Content-Type: application/json
server-csrf-token: urn:hid:256ab6ef-12c4-47e3-b220-0e96c161d283
{
    "request_uri" : "urn:hid:43d5b009-7b52-4d6f-a8a9-0d8de27968f9",
    "grant_type": "ciba_delete",
    "auth_req_id": "a95c61e0-f604-4905-98b1-26b7b87fe073"
}
Copy

Sample response

HTTP/1.1 204 NO CONTENT
server-csrf-token: urn:hid:256ab6ef-12c4-47e3-b220-0e96c161d283

UserID-less Authentication

UserID-less authentication is implemented as a first factor authentication method enabling the user to authenticate by scanning a QR code without needing to provide their User ID.

As with the push authentication flow:

  1. The Code endpoint creates a Push request using the CIBA grant type.

  2. The Code endpoint retrieves the authentication result using the CIBA poll mode.

  3. The HID Authentication Service then checks the clientapprovalstatus of the HID Approve process and consent.

  4. The IdP requests redirection to the SP and the HID Authentication Service will check the state on the server-side. It will redirect to the SP with OK or an error depending on the state.

  5. You can then use the Code endpoint to delete the userID-less request using the CIBA delete mode.

Note: For userID-less flow, the push notification is not sent as the username and deviceID are unknown.
Copy

Sample CIBA request where the challenge is generated on the back end without sending a push notification

POST https://[base-server-url]/{tenant}/authn/code 
server-csrf-token: urn:hid:256ab6ef-12c4-47e3-b220-0e96c161d283
Content-Type: application/json 
{ 
    "request_uri" : "urn:hid:43d5b009-7b52-4d6f-a8a9-0d8de27968f9",
    "grant_type": "urn%3Aopenid%3Aparams%3Agrant-type%3Aciba",
    "login_hint_token": {
        "authType": "AT_PASA"
    }
}
Copy

Sample response that can be used to generate the QR code

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
 
{
    "auth_req_id": "a95c61e0-f604-4905-98b1-26b7b87fe073",
    "txid": "eyJ6aXAiOiJERUYiLCJraWQiOiJLRVkxIiwiY3R5IjoidGV4dFwvcGxhaW4iLCJlbmMiOiJBMjU2Q0JDLUhTNTEyIiwiY29udGFpbmVyaWQiOiI2MSIsInZlcnNpb24iOiJ2OCIsImFsZyI6ImRpciIsImNpZCI6MTExOTl9..Vj1nP-C6ZQZvZYmNBN57iQ.lCMO6ibvDO1U-cEQcDyhSo7mx_ky4rlzpYXdrLF4eBwRmu9swgR9Ln7FrabIJVTL0tVRDx2-HbBcsFd6l8OzurV2UWNI6XiH8qTf3WaKBKU.Ye9A3mRIlZyN2JK5hR4O_IRLcBowVX05d--MJy5CAEw",
    "interval": 5,
    "expires_in": 120,
    "server-csrf-token": "urn:hid:256ab6ef-12c4-47e3-b220-0e96c161d283"
}

Where:

  • auth_req_id – is a unique ID (that is, correlationID) generated by HID Authentication Service that identifies the userID-less operation in progress

  • txid - is the Signed JWT and is used for the QR code scanned by mobile device to retrieve the challenge/transaction initiated by this call to retrieve the transaction data from server back-end

  • expires_in – the validity (in seconds) of the request on HID Authentication Service

Note: The username is retrieved after successful authentication, stored in the initial request and checked against the login_hint.

Action Use Cases

The following samples illustrate the Actions that can be enabled on the authentication factors in the workflow.

The supported Actions depend on the authentication factor type available to the user. Currently, the Forgot Password and Change Password are supported for the password authentication factor (LOGIN).

Forgot Password

When the user selects the Forgot Password option, a request is sent to reset the password which triggers the generation of temporary password (with constraints corresponding to the authentication type).

This password is then stored in a PAR challenge and sent to the user via an OOB channel (email or SMS).

Copy

Sample request for the temporary password sent via email

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
Accept-Language: en-US,en;q=0.5
request_uri=urn:hid:43d5b009-7b52-4d6f-a8a9-0d8de27968f9
&grant_type=reset_password_request
&authType=AT_EMPPWD
&username=5619630280
&method=email
&user_contact=test@company.com
&locale=en-US
Copy

Sample request for the temporary password sent via sms

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
Accept-Language: en-US,en;q=0.5
request_uri=urn:hid:43d5b009-7b52-4d6f-a8a9-0d8de27968f9
&grant_type=reset_password_request
&authType=AT_CUSTPWD
&username=5619630280
&method=sms
&user_contact=+3360000000000
&locale=en-US

When the user starts the process to reset their password, the temporary password (old_password) is checked with value from on PAR challenge.

If it matches the user's authenticator is updated with the (new_password), and the corresponding authenticator statistics and validity are also updated.

Copy

Sample request to reset password

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=reset_password
&authType=AT_CUSTPWD
&username=5619630280
&old_password=41096522
&new_password=52144455

Change Password

In the Change Password flow, there is no requirement to generate and send a temporary password as the user knows the value of their 'old password'.

Copy

Sample request to change password

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=change_password
&authType=AT_CUSTPWD
&username=5619630280
&old_password=41096522
&new_password=52144455

Error Responses

Code Label Possible Errors

400

BAD REQUEST

  • invalid_grant

  • invalid_request

  • grant_expired

  • consent_required

  • unsupported_grant_type

401

UNAUTHORIZED

invalid_client
Copy

Authentication failed with invalid request_uri

HTTP/1.1 400 Bad Request
server-csrf-token: urn:hid:256ab6ef-12c4-47e3-b220-0e96c161d283
{
    "hid_failure": {
        "reason": -1,
        "authType": "AT_CUSTPW"
        },
    "error_description": "Invalid grant: Resource owner username or password is invalid (null) : Resource owner username or password is invalid",
    "error": "invalid_grant"
}
Copy

First request of authentication (contains password etc.) must be sent via POST

HTTP/1.1 400 Bad Request
server-csrf-token: urn:hid:256ab6ef-12c4-47e3-b220-0e96c161d283
{
    "error_description": "Invalid request:The HTTP request method must be POST",
    "error": "invalid_request"
}
Copy

The request_uri is considered as consumed once the code 302 is returned, and deleted from the database. All subsequent requests with this request_uri return an error response:

HTTP/1.1 400 Bad Request
Content-Type: application/json;charset=UTF-8
server-csrf-token: urn:hid:256ab6ef-12c4-47e3-b220-0e96c161d283
{
    "error_description": "Invalid grant : Cannot find request",
    "error": "invalid_grant"
}
Copy

Authentication successful but the authenticator has expired

HTTP/1.1 400 Bad Request
{
    "error_description": "Authenticator is expired",
    "error": "grant_expired"
    "server-csrf-token": "urn:hid:256ab6ef-12c4-47e3-b220-0e96c161d283"
}
Copy

Authentication successful, step-up not required but consent signature is required

HTTP/1.1 400 Bad Request
{
    "error": "consent_required",
    "error_description" : "User consent is missing or expired, User approval is required",
    "server-csrf-token": "urn:hid:256ab6ef-12c4-47e3-b220-0e96c161d283"
}
Copy

The request is missing a parameter or a parameter is invalid

HTTP/1.1 400 Bad Request
{
    "error_description": "Invalid request : missing request_uri",
    "error": "invalid_request"
}
Copy

Configuration error (for example, the client does not exist)

HTTP/1.1 400 Bad Request
{
    "error_description": "Unsupported grant type: resource owner password grant type is not supported for this client : Client channel not configured for client spl-api",
    "error": "unsupported_grant_type"
}