FIDO Settings
Note that FIDO can behave differently on different operating systems or browsers. Some browsers offer only limited support for FIDO. This might lead to some FIDO features not working on all browsers.
repository) relyingPartyId) The relying party ID (RPID) defines the scope of registered FIDO credentials. It determines the set of origins on which registered FIDO credentials may be used.
The RPID must either be the origin's domain or a registerable domain suffix. It is determined based on the fully-qualified domain name of the Airlock IAM (as seen by the browser or REST client).
Example:
- The browser communicates with IAM using the URLs of the form https://www.virtinc.com/auth/...
- The RPID can then be either "virtinc.com" or "www.virtinc.com".
- The RPID cannot be either of: "abc.virtinc.com", "com".
Caution: FIDO credentials are registered for a specific RPID and can only be used for this very RPID. The web domain can therefore not be changed without having to re-register the FIDO credentials!
If acceptable with your security requirements, we recommend to use only the domain suffix (e.g. "virtinc.com") as RPID. This gives you the freedom to use registered FIDO credentials on any subdomain (e.g. "login.virtinc.com" or "auth.viritinc.com").
relyingPartyName) Name of the relying party. The name may be displayed by the web browser (or REST client).
If not defined, the relying party ID is used.
additionalOrigins) List of additional origins that can be used with FIDO credentials.
Each configured entry contributes an additional allowed origin (e.g. android:apk-key-hash:<hash> for Android) that is accepted during FIDO registration and authentication, on top of the web origin derived from the Relying Party ID.
aaguidMappings) The order is important since in case multiple FIDO authenticators are defined with the same AAGUID, only the last entry in the list will be considered. This allows to override default information provided by the plugin' FIDO Default AAGUID Mappings' when configured in the list.
userInformationProvider) Specifies what user attribute (e.g. username, email address, etc.) is sent to the web browser (or REST client) during FIDO credential registration.
The user attribute is stored on the FIDO authenticator and may be displayed when using the registered FIDO credential. The stored user attribute cannot be changed on the FIDO authenticator, i.e. even if the attribute value changes in IAM (e.g. new email address), the value on the FIDO authenticator remains as it was during credential registration.
We strongly encourage to configure a User Information Provider if resident keys are required. This allows a user to easily identify and manage the credentials stored on the FIDO authenticator.
If no provider is configured or the configured provider provides no value, the string '-' is used.
Privacy warning: The user attribute is stored on the FIDO authenticator. IAM cannot influence how secure the information is stored.
residentKey) discouraged: This value indicates the Relying Party prefers creating a server-side credential, but will accept a client-side discoverable credential.preferred: This value indicates the Relying Party strongly prefers creating a client-side discoverable credential, but will accept a server-side credential. For example, user agents SHOULD guide the user through setting up user verification if needed to create a client-side discoverable credential in this case. This takes precedence over the setting of "User Verification".required: This value indicates the Relying Party requires a client-side discoverable credential, and is prepared to receive an error if a client-side discoverable credential cannot be created. This is the recommended option and necessary for using FIDO passwordless authentication.
requireResidentKey is also added to the credential creation options (true if "required" is selected, and false otherwise). allowedAuthenticatorType) Restricts the FIDO authenticator types that can be used during FIDO credential registration.
Roaming authenticators are FIDO authenticators that can be used with different devices (e.g. USB sticks, devices using NFC or Bluetooth).
Bound authenticators are "built-in" FIDO authenticators that cannot be used with different devices (e.g. fingerprint-based in laptop or smartphone).
registrationUserVerificationPreference) Tells the FIDO client (browser, REST client) whether user verification is required, preferred, or discouraged during FIDO credential registration.
"User verification" denotes the process by which a FIDO authenticator "locally" checks whether the key material may be accessed. Examples: fingerprint, PIN code, touching the authenticator.
- Required: User verification is required for a successful registration.
- Preferred: User verification is preferred but is not required for a successful registration. Whether or not user verification is actually performed depends on the FIDO authenticator.
- Discouraged: User verification should be avoided, but carrying it out will not fail registration. Whether or not user verification is actually performed depends on the FIDO authenticator.
Note that user verification can be configured separately for authentication.
attestationType) Tells the FIDO client (browser, REST client), what kind of attestation is expected by Airlock IAM.
- Direct: The FIDO client (browser, REST client) must pass the attestation unaltered from the authenticator to Airlock IAM.
- Indirect: The FIDO client (browser, REST client) may replace the attestation from the FIDO authenticator (e.g. for privacy reasons).
- None: Indicates that Airlock IAM is not interested in attestation data and the FIDO client (browser, REST client) may replace the attestation from the FIDO authenticator with a fixed string as defined in the Web Authentication specification.
Security warning: to enforce the type of an attestation, an "Attestation Verifier" other than the "None (FIDO Attestation Verification)" plugin must be configured. Otherwise, there is no guarantee that the provided attestation is of the desired type.
attestationVerifier) Defines how attestations and attestation certificates in particular are used to verify whether a FIDO authenticator is acceptable for registration or not.
This can be used, e.g. to restrict the set of allowed FIDO authenticators (i.e. only certain models and/or manufacturers).
The verification may be disabled by choosing the "None (FIDO Attestation Verification)" plugin.
registrationTimeout) Maximum time in seconds a registration process may last.
The value is both passed to the FIDO client (web browser or REST client) as a hint and used for server-side verification.
Responses to FIDO registration challenges after the defined timeout are rejected by Airlock IAM.
autoGenerateDisplayName) If enabled, the description of the AAGUID mapping is used as the display name during the registration flow. If no mapping matches, the display name is set to '-'.
The auto generated display name can be edited after the Fido Registration Step through a subsequent Fido Credential Display Name Change Step.
If disabled, the display name must be set explicitly during the registration flow.
preventDoubleRegistration) Limit the creation of multiple credentials for the same account on a single authenticator.
- If active, Airock IAM as Relying Party provides all known credentials of this user during registration. A FIDO client fails if new credentials are created on an authenticator that already has a credential for this user.
- If not active, Airock IAM as Relying Party does not provide known credentials of this user during registration. The FIDO client creates new credentials on an authenticator even if the authenticator already has a credential for this user.
Note: For most customers this setting should be active. In some scenarios, e.g., with older Android devices, deactivating this setting mitigates FIDO client limitations.
authenticationUserVerificationPreference) Tells the FIDO client (browser, REST client) whether user verification is required, preferred, or discouraged during an authentication with a FIDO credential.
"User verification" denotes the process by which a FIDO authenticator "locally" checks whether the key material may be accessed. Examples: fingerprint, PIN code, touching the authenticator.
- Required: User verification is required for a successful authentication.
- Preferred: User verification is preferred but is not required for a successful authentication. Whether or not user verification is actually performed depends on the FIDO authenticator.
- Discouraged: User verification should be avoided, but carrying it out will not fail authentication. Whether or not user verification is actually performed depends on the FIDO authenticator.
Note that user verification can be configured separately for registration.
authenticationTimeout) Maximum time in seconds an authentication or approval process may last.
The value is both passed to the FIDO client (web browser or REST client) as a hint and used for server-side verification.
Responses to FIDO verification challenges after the defined timeout are rejected by Airlock IAM.
allowedAuthenticationTransports) Tells the FIDO client (browser, REST client) which transports should be displayed to the user to choose from. A successful FIDO authentication is also possible with an empty list of transports.
This configuration is ignored in FIDO passwordless mode.
Possible transports:
- ble - External Bluetooth Low Energy (BLE) device
- nfc - External NFC device
- usb - External USB device
- internal - e.g. fingerprint sensor
- hybrid - combination of transports (e.g. scan QR code and use the fingerprint reader on your phone)
- smart-card - ISO/IEC 7816 smart card
allowedAlgorithms) Specifies the list of cryptographic algorithms to be used by FIDO authenticators to generate public and private key pairs during registration.
The order of the algorithms in the list defines the preference (first algorithm is most preferred by Airlock IAM).
Security warning: Usage of RS256 is not recommended for security reasons (see https://tools.ietf.org/html/rfc8812#section-2) and should only be configured for compatibility reasons if required. This is in particular the case if Windows Hello with bound authenticators needs to be supported.
- ES256: ECDSA with SHA-256
- EDDSA: Edwards-curve Digital Signature Algorithm (EdDSA)
- RS256: RSASSA-PKCS1-v1_5 using SHA-256
maximumAttestationObjectSizeInBytes) Security warning: It is recommended to keep this value as low as possible, especially if the attestation provided during registration is not verified (the plugin "None (FIDO Attestation Verification)" is configured), in order to prevent persisting unnecessary data, which could result in a denial of service.
type: FidoSettings
id: FidoSettings-xxxxxx
displayName:
comment:
properties:
aaguidMappings:
additionalOrigins:
allowedAlgorithms: [ES256, EDDSA]
allowedAuthenticationTransports:
allowedAuthenticatorType: ALL
attestationType: DIRECT
attestationVerifier:
authenticationTimeout: 60
authenticationUserVerificationPreference: PREFERRED
autoGenerateDisplayName: false
maximumAttestationObjectSizeInBytes: 6000
preventDoubleRegistration: true
registrationTimeout: 300
registrationUserVerificationPreference: PREFERRED
relyingPartyId:
relyingPartyName:
repository:
residentKey: required
userInformationProvider: