Requirements
Component | Requirement | Comments |
---|---|---|
Airlock IAM |
| For licensing: |
Component | Requirement | Comments |
---|---|---|
Airlock IAM |
| For licensing: |
The following example illustrates how a FIDO-related self-service is configured and used over the REST API.
It covers the following use-case:
All following procedures are exemplary and will vary according to your setup or needs.
Before starting a flow, it's generally a good idea to end possibly ongoing other flows of the same type to avoid getting a UNEXPECTED_CALL response. To do so, we use the following request in our example:
DELETE /rest/protected/self-service/flow
To start the protected self-service flow with flow ID fido-registration, use:
POST /rest/protected/self-service/flows/fido-registration/select
The response tells the REST client, that a FIDO registration challenge must be retrieved:
HTTP/1.1 200 OK { "meta":{ "type":"jsonapi.metadata.document", "timestamp":"2021-02-16T11:46:07.806+01:00" }, "data":{ "type":"self-service.session", "id":"150932765365474699", "attributes":{ "nextStep":"FIDO_REGISTRATION_CHALLENGE_RETRIEVAL_REQUIRED" } } }
Getting the FIDO registration challenge also sets the display name for the FIDO authenticator. The display name later helps the end-user (or the helpdesk) to identify the authenticator. Identification is especially important if a user registers multiple authenticators. See note below for alternatives to set the display name.
POST /rest/protected/self-service/fido/registration/challenge/retrieve {displayName: "my usb stick"}
The response bears the FIDO challenge and information about the requirements imposed on the FIDO authenticator to be registered:
HTTP/1.1 200 OK { "meta":{ "type":"jsonapi.metadata.document", "timestamp":"2021-02-16T11:47:06.121+01:00" }, "data":{ "type":"self-service.fido.registration.challenge", "id":"2853364706", "attributes":{ "publicKeyCredentialCreationOptions":{ "rp":{ "name":"localhost", "id":"localhost" }, "user":{ "name":"-", "id":"zBcyYsonWQgxZ9NbeZz9n_N0G6Pu5DaF_D3E", "displayName":"my usb stick" }, "challenge":"XoL13o_ad3IZLQBm…oZg", "pubKeyCredParams":[ { "type":"public-key", "alg":-7 }, { "type":"public-key", "alg":-8 } ], "timeout":60000, "excludeCredentials":[ { "type":"public-key", "id":"AbXIsHnKwe9RfhLY…54g" } ], "authenticatorSelection":{ "requireResidentKey":false, "userVerification":"preferred" }, "attestation":"direct" } } } }
Auto-generate display name during FIDO passkey registration
IAM can automatically generate a display name based on the AAGUID of the passkey.
See FIDO Settings >> Auto Generate Display Name for further information. If enabled, the user is not asked to enter the display name before passkey registering a passkey.
It is best combined with the FIDO Credential Display Name Change Step after the registration step to allow the end user to edit the generated display name.
The FIDO client (browser or mobile app) now interacts with the end-user and asks to provide and activate the FIDO passkey (e.g. connect USB stick and touch it).
Once the FIDO passkey is selected and the end-user has granted permission to the FIDO client to use it, the challenge is signed and the response send back:
POST /rest/protected/self-service/fido/registration/attestation-response/check { "publicKeyCredential":{ "id":"hP_z3dA-1HapqU38nS3Xt5y…XSA", "response":{ "attestationObject":"o2NmbXRoZmlkby11MmZnYXR0U3RtdKJjc…aOX", "clientDataJSON":"{\"type\":\"webauthn.create\",\"challenge\":\"6BpohYAw1jN_xidTwda79HlXnYzo6ez4CFCP_1_gpt4\",\"origin\":\"https://localhost:8443\",\"crossOrigin\":false}" }, "type":"public-key" } }
The response is checked by Airlock IAM and information about the FIDO passkey extracted from the attestation object. If the registration was successful, the usual success response is sent back and the registration has succeeded.
HTTP/1.1 200 OK { "meta":{ "type":"jsonapi.metadata.document", "timestamp":"2021-02-16T11:48:29.504+01:00" }, "data":{ "type":"self-service.session", "id":"150932765365474699", "attributes":{ } } }