User Authentication with FIDO

The HID Authentication Service supports self-enrollment of FIDO device-bound (USB key or card) and synced (mobile device) passkeys by end users, which can then be used as first and second authentication factors.

This functionality leverages the WebAuthn API and standard for secure web-based authentication supported by the most popular browsers and platforms.

The HID Authentication Service identifies passkeys using the global FIDO AAGUID (Authenticator Attestation Global Unique Identifier) definitions for established device manufacturers that is maintained by the FIDO Alliance.

For example:

  • HID Crescendo® Key V2 - 2d3bec26-15ee-4f5d-88b2-53622490270b

  • YubiKey® 5C - ee882879-721c-4913-9775-3dfcce97072a

The AAGUID is returned by the WebAuthn signed attestation, and the FIDO metadata is used at registration to get the associated description which can be used as the "friendly name" for the FIDO passkey in the HID Authentication Service system.

The official FIDO metadata containing the complete list of FIDO AAGUIDs is available from the FIDO Alliance Metadata Service.

The metadata is integrated into the HID Authentication Service environment and dynamically updated every day.

You can define both the enrollment and authentication workflows to include specific factors and criteria to meet your organization's security and branding policies.

End users and operators can manage the lifecycle of enrolled FIDO passkeys via the relevant HID Authentication Service portal. The passkeys can also be managed using the various SCIM API endpoints.

If your deployment includes a custom front-end application via which you want users to enroll and authenticate with their FIDO passkeys, you can also enable the APIs to implement your workflows.

Note:

  • Users can enroll and authenticate with their own FIDO passkeys or those provided by their organization.

    If you allow users to use their own devices (under a BYOD policy), you can secure your system by only allowing verified devices that meet your security requirements. For further information, see Enable Attestation Verification.

  • Configuring the enrollment workflow is currently only supported for FIDO authenticators.

  • FIDO passkey support and the user experience during enrollment and authentication varies according to the browser.

Prerequisites:  

  • A registered and active Client ID (see Managing Users, Groups and Roles)

  • A bearer token of an Organization Administrator, obtained by authenticating the Organization Administrator against the HID Authentication Service OpenID API

    To get such a token, refer to any of the sections under Enabling User Authentication.

  • The Internal ID of the existing user (see Managing Users, Groups and Roles) for who you want to register the FIDO passkey

  • The user has an existing authenticator (for example, a static password) allowing to log on to the IdP

Define the FIDO Workflow

The IdP workflows are designed to guide the user through the enrollment and authentication process.

Using the Customization endpoint, you can define the JSON payload to define how you want users to enroll and authenticate with their FIDO passkey.

Note: The following sample illustrates a FIDO-specific enrollment and authentication workflow. For complete details, see Configuring the Identity Provider.
Copy

FIDO enrollment protected by static password and authentication as a first factor that does not require secondary/step-up authentication

{
	"schemas": [
		"urn:hid:scim:api:idp:2.0:Customization"
	],
	"id": "ID_FLOWFIDO",
	"payload": {
		"accessCriteria": [
			{
				"accessCriteriaId": "access_criteria.common_to_all",
				"authenticators": {
					"firstFactorsFiltering": false,
					"secondFactorsFiltering": false
				}
			}
		],
		"enrollProtectionFactors": [
			{
				"protectionFactorId": "enroll_protection.user_password",
				"code": "AT_EMPPWD",
				"type": "LOGIN",
				"retry": 3
			}
		],
		"enrollActions": [
			{
				"enrollId": "enroll_action.fido",
				"accessCriteriaId": "access_criteria.common_to_all",
				"type": "FIDO",
				"code": "AT_FIDO",
				"rpId": "hostname"
				"userVerification": "required",
				"residentKey": "required",
				"authenticatorAttachment": "cross-platform",
				"allowedAAGUIDs": ["b93fd961-f2e6-462f-b122-82002247de78","ea9b8d66-4d01-1d21-3ce4-b6b48cb575d4"],
				"retry": 1,
				"deviceType": "DT_FIDO",
				"credentialType": "CT_FIDOU2F",
				"deviceBinding": "required",
				"attestationVerification": "direct",
				"enrollValidation": true,
				"protectionFactor": "enroll_protection.user_password"
			}
		],
		"firstFactors": [
			{
				"factorId": "factor.user_password",
				"accessCriteriaId": "access_criteria.common_to_all",
				"type": "LOGIN",
				"code": "AT_EMPPWD",
				"acr": "1",
				"stepUp": "required",
				"retry": 3,
				"actions": [
					"action.change_password",
					"action.forgot_password"
				]
			},
			{
				"factorId": "factor.fido",
				"accessCriteriaId": "access_criteria.common_to_all",
				"type": "FIDO",
				"code": "AT_FIDO",
				"rpId": "hostname"
				"acr": "acr_fido",
				"stepUp": "notRequired",
				"retry": 3,
				"userVerification": "required",
				"discoverCredentialsInDevice": "true",
				"enrollActions": [
					"enroll_action.fido"
				]
			}
		],
		"secondFactors": [
			{
				"factorId": "factor.fido.2fa",
				"accessCriteriaId": "access_criteria.common_to_all",
				"type": "FIDO",
				"code": "AT_FIDO",
				"acr": "acr_fido",
				"retry": 3,
				"upon": [
					"factor.user_password"
				],
				"userVerification": "discouraged",
				"enrollActions": [
					"enroll_action.fido"
				]
			}
		]
	}
}

Where the enrollment action (enroll.action.fido) will be available to the user in the logon interface with the following configuration:

  • The user is required to prove their physical presence (such as tapping the FIDO passkey or pressing the button):

    "userVerification": "required"

  • The device must allow the creation of a resident key for the HID Authentication Service credential:

    "residentKey": "required"

  • The user will be able to select the platform experience according to the type of their FIDO passkey (device-bound or synced):

    "authenticatorAttachment": "cross-platform"

  • The user can only enroll FIDO passkeys that correspond to a defined list of AAGUIDs:

    "allowedAAGUIDs": ["b93fd961-f2e6-462f-b122-82002247de78","ea9b8d66-4d01-1d21-3ce4-b6b48cb575d4"]

  • The user must have a have a "pending" device of the specified device type:

    "deviceBinding": "required"

    You must create and assign a FIDO device authenticator for the user before they can enroll their passkey.

  • The user can only enroll a FIDO passkey verified for use by your organization:

    "attestationVerification": "direct"

  • The user must validate their enrollment by successfully authenticating with their FIDO passkey:

    "enrollValidation": true

  • The user must successfully authenticate with their static password to access the protected enrollment process:

    "protectionFactor": "enroll_protection.user_password"

After successful enrollment, FIDO authentication is then available for the user as a:

  • First authentication factor (factor.fido) where secondary/step-up authentication is not required:

    "stepUp": "notRequired"

  • Second authentication factor if the user authenticates with the static password as their first factor:

    "upon": ["factor.user_password"]

  • The user can only authenticate with a credential from a list of discoverable keys proposed by the workflow:

    "discoverCredentialsInDevice": "true",

Enable Attestation Verification

Based on the WebAuthn standard, the signed attestation is proof of the FIDO passkey's origin and validity of the data it provides (such as credential information, signatures, capabilities, etc).

The attestation statement itself contains the required signed data about the public key credential and the FIDO passkey, as well as the attestation signature.

During enrollment, the FIDO passkey uses the FIDO metadata URL to generate an attestation via WebAuthn, including the signature and certificate of the signing key.

The HID Authentication Service uses the public key from the attestation certificate to verify the attestation signature and that the certificate is trusted with the root certificate provided by FIDO metadata.

If the verification is successful, the HID Authentication Service creates a new authenticator, device and credential (based on the FIDO authentication policy, device and credential type parameters) and stores the counter from the attestation data.

To enable attestation verification during FIDO enrollment, add the following parameter to the authentication workflow:

attestationVerification - define if attestation verification is required:

  • none - attestation verification is not required

    This is the default value.

  • direct - verification of the attestation statement generated by the FIDO passkey is required

Using Resident Keys

The HID Authentication Service supports discoverable FIDO passkeys, where resident keys containing user and credential information are stored on the passkey (device-bound or synced) instead of the server.

During enrollment, the HID Authentication Service creates a resident key on the FIDO passkey containing a unique identifier for the user. The FIDO passkey then associates this resident key with the credential to be used with the HID Authentication Service URL/domain.

During authentication, the FIDO passkey provides the identifier from the resident key, allowing the HID Authentication Service to get the associated user and credential.

By default, the HID Authentication Service does not require resident keys, so user and credential information is stored on the server.

If you want to use resident keys for additional security, you can add the requirement to the FIDO enrollment workflow.

The possible values for residentKey are:

  • discouraged - a non-resident key is preferred (that is, the user information and credential ID is stored on the server) but will accept a resident key

  • preferred - the resident key is preferred (that is, the user information and credential ID is stored on the FIDO passkey) but will accept a non-resident key

  • required - the resident key is required

    If the request is denied by the user or FIDO passkey, enrollment will fail.

Note: It is strongly recommended that you also set userVerification to required for FIDO authentication if you require/prefer resident keys.
Important: Reusing a FIDO passkey with a Resident Key

Before reusing a FIDO passkey for another user, it should reinitialized to remove any PINs and reset to remove all the resident keys using vendor-specific tools.

Define the Allowed FIDO Passkeys

  • Using the workflow definition, you can define the types of FIDO passkeys allowed for enrollment by listing the corresponding AAGUID values in the allowedAAGUIDs parameter.

    If the parameter is missing or empty, no restriction is applied.

  • Using the FIDO device type adapter, you can define the number of FIDO passkeys a user is allowed using the maximumDevicePerUser parameter.

Create and Assign a FIDO Device Authenticator

If you set deviceBinding to required, you must create and assign (bind) a FIDO device authenticator to the user. The user can then 'bind' their passkey (device-bound or synced) to this authenticator using the IdP enrollment workflow.

Important:

Choosing the right authentication policy and device type when using FIDO passkeys with the HID Authentication Service is very important.

Authentication Policy Adapter Device type Credential type

AT_FIDO

FIDO

DT_FIDO

CT_FIDOU2F

Create a FIDO Device Authenticator

Use the Device endpoint to create the FIDO device authenticator in the HID Authentication Service.

Copy

Sample request to a create a FIDO device authenticator

POST https://[base-server-url]/scim/{tenant}/v2/Device HTTP/1.1
Connection: close
Content-Type: application/scim+json
Authorization: Bearer RTp7HwAAAYNaPRn0EF8SAifAr62AFVQjcWITci7w
Content-Length: 229
Host: <hostname>
User-Agent: Apache-HttpClient/4.5.5 (Java/16.0.1)

{
	"schemas": ["urn:hid:scim:api:idp:2.0:Device"],
	"externalId": "myFIDODevice",
	"type": "DT_FIDO",
	"status": {
		"status": "PENDING",
		"expiryDate": "2050-06-12T14:46:58+0200",
		"startDate": "2017-06-12T14:46:58+0200"
	}
}
Copy

Sample response with the FIDO device authenticator status as 'pending', ready to be assigned

HTTP/1.1 200 OK

{
	"schemas": ["urn:hid:scim:api:idp:2.0:Device"],
	"id": "11992",
	"externalId": "myFIDODevice",
	"meta":    {
		"resourceType": "Device",
		"created": "2022-09-20T09:31:59Z",
		"location": https://[base-server-url]/scim/{tenant}/v2/Device/11992,
		"version": "1"
	},
	"type": "DT_FIDO",
	"status":    {
		"status": "PENDING",
		"active": false,
		"expiryDate": "2050-06-12T12:46:58Z",
		"startDate": "2017-06-12T12:46:58Z"
	}
}

Assign the FIDO Device Authenticator to the User

You can now assign the FIDO device authenticator to the user using the Device endpoint.

The first step is to get the internal ID of the user using their external ID (for example, jsmith@company.com).

For further information, see Internal IDs VS External IDs and Managing Users, Groups and Roles (creating users).

Copy

Sample request to get a user's internal ID

POST https://[base-server-url]/{tenant}/v2/Users/.search HTTP/1.1
Authorization: Bearer YOUR_BEARER_TOKEN
Content-Type: "application/scim+json" 
{
   "schemas":[
      "urn:ietf:params:scim:api:messages:2.0:SearchRequest"],
   "filter":"externalId eq \"jsmith@company.com\"",
   "sortBy":"id",
   "sortOrder":"descending",
   "startIndex":0,
   "count":100
}
Copy

Sample response with the internal ID (11453)

{
   "schemas":[
      "urn:ietf:params:scim:api:messages:2.0:ListResponse"],
   "totalResults":1,
   "resources":[
      {
         "schemas":[
            "urn:ietf:params:scim:schemas:core:2.0:User",
            "urn:hid:scim:api:idp:2.0:UserDevice",
            "urn:hid:scim:api:idp:2.0:UserAttribute",
            "urn:hid:scim:api:idp:2.0:UserAuthenticator"],
         "id": "11453",
         "externalId": "jsmith@company.com" 
         (...)     
 
      }
   ]
}
Copy

Sample request to assign the FIDO device authenticator

PUT https://[base-server-url]/scim/{tenant}/v2/Device/11992 HTTP/1.1
Connection: close
Content-Type: application/scim+json
Authorization: Bearer RTp7HwAAAYNaPRn0EF8SAifAr62AFVQjcWITci7w
Content-Length: 271
Host: <hostname>
User-Agent: Apache-HttpClient/4.5.5 (Java/16.0.1)

{
         "schemas": ["urn:hid:scim:api:idp:2.0:Device"],
         "id": "11992",
         "type": "DT_FIDO",
         "status":          {
            "status": "PENDING",
            "active": false
         },
                   "owner": {
                       "value": "11453"
                   }
}
Copy

Sample response with the FIDO device authenticator assigned to the user, ready to be enrolled

HTTP/1.1 200 OK

{
	"schemas": ["urn:hid:scim:api:idp:2.0:Device"],
	"id": "11992",
	"externalId": "myFIDODevice",
	"meta":    {
		"resourceType": "Device",
		"created": "2022-09-20T09:31:59Z",
		"location": https://[base-server-url]/scim/{tenant}/v2/Device/11992,
		"version": "1"
	},
	"type": "DT_FIDO",
	"status":    {
		"status": "PENDING",
		"active": false,
		"expiryDate": "2050-06-12T12:46:58Z",
		"startDate": "2017-06-12T12:46:58Z"
	},
	"owner":    {
		"type": "User",
		"externalId": "jsmith@company.com",
		"value": "11453",
		"$ref": https://[base-server-url]/scim/{tenant}/v2/Users/11453
	}
}

Enroll a FIDO Passkey

Once you have deployed your FIDO workflow, the next time the user authenticates to the IdP, the option to enroll their FIDO passkey is displayed in the logon interface.

The IdP guides them through the process, based on the settings and criteria you have defined in the enrollment workflow.

For example:

  • If you have protected the enrollment with an authentication factor (for example, static password), the user must authenticate with that factor to access the enrollment process

  • If you set residentKey to required, the user must authorize the creation of the key for the HID Authentication Service credential on their FIDO passkey

If the enrollment is successful, the HID Authentication Service creates a new authenticator, device and credential (based on the FIDO authentication policy, device and credential type parameters) for the user. The description obtained from the FIDO AAGUID-related information is used to define the 'friendly name' for the device, making it easily identifiable for device management operations.

For details of the API enrollment flow, see the Enrollment endpoint.

Authenticate with a FIDO Passkey

To authenticate with their enrolled FIDO passkey as either a first or second factor, the user experience depends on the settings and criteria you have defined in the authentication workflow.

When the user enters their User ID, if FIDO authentication is configured, the HID Authentication Service checks if the user has an enrolled FIDO credential.

  • If the user has a credential, the authentication is allowed and the HID Authentication Service communicates with the FIDO passkey to get a signed response

    The HID Authentication Service verifies the FIDO signature with the enrolled public key:

    • If user verification is not required, the user is authenticated without requiring additional action

    • If user verification is required, the user must provide proof of their presence, such as providing the PIN or biometric credential

  • If the user does not have an enrolled FIDO credential, authentication is not allowed

    Depending on the defined workflow, the user can either enroll a FIDO passkey or authenticate with another method if available

For details of the API authentication flow, see the Code endpoint.

Manage the FIDO Token Lifecycle

Once enrolled, the FIDO passkeys can then be managed (update, suspend, delete) by end users and operators via the HID Authentication Service portal, or using the SCIM API endpoints.

Update a FIDO Passkey

Copy

Update the friendly name for a FIDO passkey

PUT [base-server-url]/scim/{tenant}/v2/Device/<device id>
Authorization : Bearer CJsTFgAAAYYnYMv5l6RZznFoqrgSB7V64eP/XWAX
{
    "schemas": ["urn:hid:scim:api:idp:2.0:Device"],
    "status": {
		"status": "ACTIVE"
    },
	"friendlyName": "HID Crescendo Key 2",
   	"owner": {
		"type": "User",
		"externalId": "jsmith@company.com",
		"value": "11453",
		"$ref": https://[base-server-url]/scim/{tenant}/v2/Users/11453
    }
}

Update a FIDO Authenticator

Copy

Disable a FIDO device authenticator

PUT https://[base-server-url]/scim/{tenant}/v2/Authenticator/{id}.AT_FIDO
{
	"schemas": [ "urn:hid:scim:api:idp:2.0:Authenticator" ],
	"status": {
		"status": "DISABLED",
	}
}

Revoke a FIDO Passkey

Copy

Unassign/unbind the FIDO passkey

PUT https://[base-server-url]/scim/<tenant>/v2/Device/<device id>
Authorization : Bearer CJsTFgAAAYYnYMv5l6RZznFoqrgSB7V64eP/XWAX
{
	"schemas": ["urn:hid:scim:api:idp:2.0:Device"],
	"id": "260134",
	"owner": {
		"value": ""
	}
}
Copy

Then delete the device

DELETE https://[base-server-url]/scim/<tenant>/v2/Device/<device id>
Authorization : Bearer CJsTFgAAAYYnYMv5l6RZznFoqrgSB7V64eP/XWAX