Enrollment Endpoint

The Enrollment endpoint allows adding the authenticator enrollment process to the authentication workflow called by the IdP on the Flow and Code endpoints.

For further information about enrollment workflows, see Add an Enrollment Workflow.

The consent can be customized (labels and description) as described in Customizing the Consent Display.

https://[base-server-url]/{tenant}/authn/enroll [POST]

Enrollment Protection

You can protect the enrollment of the FIDO device-bound or synced passkey with an existing authenticator/credential by defining the type of authenticator and/or require that the user must have an associated pending device in enrollActions.protectionFactor.

Before calling the enrollment flow, the portal validates the protectionFactor with a specific authentication flow.

POST https://[base-server-url]/{tenant}/authn/enroll/code
Content-Type: application/x-www-form-urlencoded 
request_uri=urn:hid:43d5b009-7b52-4d6f-a8a9-0d8de27968f9
&grant_type=password
&authType=AT_EMPPWD
&username=testfido &password=54917067

If successfully validated, the portal continues the enrollment flow.

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

If the validation fails, enrollment attempts will be rejected by the server.

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

FIDO Enrollment Flow

1. The IdP calls the Flow endpoint to get the authentication factors.

2. HID Authentication Service computes response for the enrollment factor (for example, factor.fido_uaf).

3. If the factor has enrollActions defined, and the user has a valid authenticator defined by the enrollment factor's upon parameter, the enrollment process is added to the response.

4. When the authentication portal is rendered, the enrollment link/option is available for the user.

5. The user authenticates with their valid authenticator and will trigger the enrollment process.

POST https://[base-server-url]/{tenant}/authn/enroll/fido
Content-Type: application/json
{
    "enroll_step": "getcredentialoptions",
    "username": "myuser",
    "request_uri": "urn:hid:8365b59f-ec71-484f-830e-e5a7ce252a13",
    "authType": "AT_FIDO"
}

HTTP/1.1 200 OK
server-csrf-token: urn:hid:256ab6ef-12c4-47e3-b220-0e96c161d283
{
    "publicKeyCredentialOptions": {
        "attestation": "direct",
        "challenge": "NAb8M_nMQ7eC50gzGOQCljQG_DP5zEO3gudIMxjkApY",
        "authenticatorSelection": {
            "userVerification": "required"
        },
        "user": {
            "displayName": "myuser",
            "name": "myuser",
            "id": "aGppcHVzaA"
        },
        "rp": {
            "name": "auth-service.com"
        }, 
        "pubKeyCredParams": [ 
            { "type": "public-key", "alg": -7 },
            { "type": "public-key", "alg": -35 }, 
            { "type": "public-key", "alg": -36 } 
        ]
    }
}

Where excludeCredentials is a list of credentials that already exist to avoid recreating a new authenticator on same passkey for the same user (see WebAuthn specifications).

WebAuthn then creates the authenticator on the passkey (see WebAuthn specifications), resulting in an iface-pkcredential.

The FIDO credential (credential ID and public key) should then be registered using the JSON-formatted PublicKeyCredential.response (authenticatorattestationresponse).

POST https://[base-server-url]/{tenant}/authn/enroll/fido 
server-csrf-token: urn:hid:256ab6ef-12c4-47e3-b220-0e96c161d283
Content-Type: application/x-www-form-urlencoded
{
    "enroll_step": "registercredential",
    "username": "myuser",
    "request_uri": "urn:hid:8365b59f-ec71-484f-830e-e5a7ce252a13",
    "authType": "AT_FIDO",
    "credential": {
        "id": "l0QFH2q-a4mAkn9cIVapKUooA5XuXRW8-tX3Pf0vG6ZbK8WFM1BHYuX_npGi55d4iyYqiM7JF9AfbWaOJURMkwBEnBPYJZJbqM4SCv08T_E",
        "rawId": "l0QFH2q-a4mAkn9cIVapKUooA5XuXRW8-tX3Pf0vG6ZbK8WFM1BHYuX_npGi55d4iyYqiM7JF9AfbWaOJURMkwBEnBPYJZJbqM4SCv08T_E",
        "response": {
            "clientDataJSON": "eyJjaGFsbGVuZ2UiOiJOLUx3aE1NZ1FRMnBINlh0dHpfQXZEZmk4SVRESUVFTnFSLWw3YmNfd0x3IiwiY2xpZW50RXh0ZW5zaW9ucyI6e30sImhhc2hBbGdvcml0aG0iOiJTSEEtMjU2Iiwib3JpZ2luIjoiaHR0cHM6Ly9hYWFzMS11cy5kZXYuaWFhcy5oaWRjbG91ZC5jb20iLCJ0eXBlIjoid2ViYXV0aG4uY3JlYXRlIn0",
            "attestationObject": "o2NmbXRmcGFja2VkZ2F0dFN0bXSjY2FsZyZjc2lnWEgwRgIhANjJtVM0SE9zQIScB1DoAaeQGsk6bwGtBugDUtXa7eyuAiEApWuZ8NIMXm9NGkz0bvT93Xh6caifFY7xo67CM9L2XWdjeDVjgVkDMjCCAy4wggLUoAMCAQICEEABbNiV8EHC-RIeK56dgEowCgYIKoZIzj0EAwIwZjELMAkGA1UEBhMCVVMxEzARBgNVBAoTCkhJRCBHbG9iYWwxIjAgBgNVBAsTGUF1dGhlbnRpY2F0b3IgQXR0ZXN0YXRpb24xHjAcBgNVBAMTFUZJRE8gQXR0ZXN0YXRpb24gQ0EgMjAeFw0xOTA4MjgxNDE2NDBaFw0zOTA4MjMxNDE2NDBaMGkxCzAJBgNVBAYTAlVTMR8wHQYDVQQKExZISUQgR2xvYmFsIENvcnBvcmF0aW9uMSIwIAYDVQQLExlBdXRoZW50aWNhdG9yIEF0dGVzdGF0aW9uMRUwEwYDVQQDEwxDcmVzY2VuZG9LZXkwWTATBgcqhkjOPQIBBggqhkjOPQMBBwNCAAQBqLiOueMOqmxqJ0k0rTtnBEmE6PBM6_DiYj5DJdNneiuouOMFwildovsPm6Uer4GEGf3CkMTEuLhsraj0TTyHo4IBXzCCAVswDgYDVR0PAQH_BAQDAgeAMIGABggrBgEFBQcBAQR0MHIwLgYIKwYBBQUHMAGGImh0dHA6Ly9oaWQuZmlkby5vY3NwLmlkZW50cnVzdC5jb20wQAYIKwYBBQUHMAKGNGh0dHA6Ly92YWxpZGF0aW9uLmlkZW50cnVzdC5jb20vY2VydHMvaGlkZmlkb2NhMi5wN2MwHwYDVR0jBBgwFoAUDLCbuLslcclrOZIz57Fu0imSMQ8wCQYDVR0TBAIwADBDBgNVHR8EPDA6MDigNqA0hjJodHRwOi8vdmFsaWRhdGlvbi5pZGVudHJ1c3QuY29tL2NybC9oaWRmaWRvY2EyLmNybDATBgsrBgEEAYLlHAIBAQQEAwIEMDAdBgNVHQ4EFgQUfYf5Qlnk4jFIUUtbY99YQV2jrq8wIQYLKwYBBAGC5RwBAQQEEgQQaS21SXrlRNWh5d0gpJO3IzAKBggqhkjOPQQDAgNIADBFAiEA6Q2tWWwHwk5QTIg1LgeVx_IZ4WVBdSQrgpnPkoSOGU8CIGvwKQLnS-UfB8Tjh4JPAAPyaYApDJmA0C1atEBeqMa1aGF1dGhEYXRhWNSj_roMlMceufupsoJrPjy45Lz_H1pglUaCkhLlp2A0pUUAAAB1aS21SXrlRNWh5d0gpJO3IwBQl0QFH2q-a4mAkn9cIVapKUooA5XuXRW8-tX3Pf0vG6ZbK8WFM1BHYuX_npGi55d4iyYqiM7JF9AfbWaOJURMkwBEnBPYJZJbqM4SCv08T_GlAQIDJiABIVgg6UMbzPb0PR--eu87XODbaWC1x2fRkN3qrOtK2y3iaK8iWCA5S--zNan7CGoW01PEgu0QnLHpOz3b_d2-5SrFw_hhCg",
            "transports": ["hybrid", "internal"],
        },
        "type": "public-key"
    }

Where the:

• WebAuthn attestation object is passed in the API 'credential' element

  Format of the WebAuthn enrollment object

  Copy

  Commented WebAuthn attestation object

  publicKeyCredential // the WebAuthn credential containing the response attestation from the passkey, see https://www.w3.org/TR/webauthn-2/#iface-pkcredential 
      id // the base64-encoded string ID used to identify the newly generated credential during authentication
      rawId // the credential ID in binary
      type
      response
          clientDataJSON // a base64url-encoded JSON of client data, see https://developer.mozilla.org/en-US/docs/Web/API/AuthenticatorResponse/clientDataJSON
              challenge // base64url-encoded 32 bytes of randomly generated UUID
              origin
              type
          attestationObject // base64url-encoded bytes of CBOR ArrayBuffer, see https://www.w3.org/TR/webauthn-2/#iface-authenticatorattestationresponse or https://developer.mozilla.org/en-US/docs/Web/API/AuthenticatorAttestationResponse/attestationObject, containing:
              attStmt // the attestation statement used to verify the credential public key came from the authenticator, see https://www.w3.org/TR/webauthn/#attestation-statement
              authData // https://developer.mozilla.org/en-US/docs/Web/API/AuthenticatorAssertionResponse/authenticatorData
                  rpIdHash // the SHA-256 hash of the rpId for the credential
                  flags // bit-based indicators about user and authenticator data
                  signCount // 32-bit unsigned big-endian integer of the signature counter
                  attestedCredentialData // variable-length byte array for credential, see https://www.w3.org/TR/webauthn-2/#attested-credential-data
                      AAGUID // 128-bit identifier representing the type (such as make and model) of the FIDO authenticator
                      credentialIdLength 
                      credentialId 
                      credentialPublicKey

  The clientDataJSON and attestationObject arrays must be sent in the exact JSON format as in the WebAuthn response in the request (credential parameter) to register the FIDO credential.

• Optional transports parameter defines the method to communicate with the authenticator (based on AuthenticatorTransport) to obtain the credential's assertion and platform type

  This parameter can be retrieved from WebAuthn response and is stored in the credential information by HID Authentication Service.

  During the authentication, the parameter allows the browser to detect the FIDO platform and propose the appropriate user experience.

  The possible values are:

  • usb - removable USB device

  • nfc - Near Field Communication (NFC) device

  • ble - Bluetooth Smart (Bluetooth Low Energy / BLE) device

  • smart-card - ISO/IEC 7816 smart card

  • hybrid - a combination of mechanisms such as a computer and smartphone for passkeys

  • internal - non-removable client device-specific transport (see platform authenticators) for passkeys

  Note: If the browser does not support this parameter or the parameter is not present, the behavior of the passkey experience is based on the browser's implementation.

HTTP 201 Created
server-csrf-token": "urn:hid:256ab6ef-12c4-47e3-b220-0e96c161d283

POST https://[base-server-url]/{tenant}/authn/enroll/card
server-csrf-token: urn:hid:256ab6ef-12c4-47e3-b220-0e96c161d283 
{
    "request_uri": "urn:hid:aa407830-595b-42dd-90dd-8de5af9c1294",
    "code": "enrollaction1",
    "credential": {
        "UID": "EEDxsQAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA",
        "address": 770,
        "key": "XVdVVUUzVVV1VVVVcN3X4OywXzU1YYpnN5oXoFldxri1RwV33GV4_-8fe5A",
        "nickname": "MiFare Standard 1K, Contactless Writable",
        "version": 1
    }
}

HTTP/1.1 201 Created
{
 "server-csrf-token": "urn:hid:256ab6ef-12c4-47e3-b220-0e96c161d283"
}

Error Responses

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

HTTP/1.1 400 Bad Request
{
    "hid_failure": {
        "reason": 17,
        "authType": "AT_FIDO"
    },
    "error_description": "Invalid grant: Resource owner username or password is invalid",
    "error": "invalid_grant"
}

HTTP/1.1 403 Forbidden
{
    "error_description": "Access denied by resource owner or authorization server",
    "error": "access_denied"
}