...
change the property idp.authn.webauthn.registration.userid.strategy to reference the bean shibboleth.authn.webauthn.registration.AttributeContextUserIdLookupStrategy.
ensure the attribute resolver is enabled after authentication, idp.authn.webauthn.admin.registration.resolveIdentityAttributesresolveAttributes=true.
decide which attribute from the resolver context to use using idp.authn.webauthn.registration.userid.attributeId.
Note, the AttributeContextUserIdLookupStrategy requires the attribute to be a single StringAttributeValue converted to a byte array assuming a UTF-8 character set.
...
| Anchor | ||||
|---|---|---|---|---|
|
The user WebAuthn name (user.name) is a human-palatable identifier for a user’s account a credential is associated with. During authentication, it will become the UsernamePrincipal of the subjectThis is separate from the internal username the IdP uses to store the credential against and is only used by the authenticator to help the user select the correct credential to authenticate with. It may be truncated by the authenticator to 64 bytes.
By default, this is taken from the principal name of the user who authenticated (contained in the SubjectContext). This can be changed by creating a bean in conf/authn/webauthn-config.xml referenced by the idp.authn.webauthn.registration.usernamename.strategy in conf/authn/webauthn.properties.
User Display Name Population
The user display name (user.displayName) is a human-palatable name for the user’s account. It is only intended for display to the user during registration. It is not used during authentication.
By default, the user display name is taken from the principal name in the SubjectContext. That is, the canonical principal name of the subject that authenticated to the registration endpoint. However, you may prefer to pull this value from the attribute resolver. This is supported by changing the following properties in conf/authn/webauthn.properties:
...
change the property idp.authn.webauthn.registration.displayname.strategy to reference the bean shibboleth.authn.webauthn.AttributeContextDisplayNameLookupStrategy.
...
You may decide to pull this value from the attribute resolver. This is supported out of the box by utilizing a built-in strategy, which can be activated by modifying the following properties in conf/authn/webauthn.properties:
change the property idp.authn.webauthn.registration.name.strategy to reference the bean shibboleth.authn.webauthn.registration.AttributeContextWebAuthnNameLookupStrategy.
ensure the attribute resolver is enabled after authentication, idp.authn.webauthn.admin.registration.resolveIdentityAttributesresolveAttributes=true.
decide which attribute from the resolver context to use using idp.authn.webauthn.registration.displaynamename.attributeId.
Complete control over the strategy is possible by defining your own bean of type Function<ProfileRequestContext, String>.
...
Discoverable Credentials (Passkeys)
A Discoverable Credential, formally a Resident Key, stores the private key and associated metadata on the authenticator. This allows usernameless flows and is strictly what is required for a FIDO2 credential to be a ‘passkey’. The alternative allows the private key to be stored, in a protected format, at the relying party (for example, packaged inside the credential ID). Noting that some security keys have limited space for Discoverable Credentials.
Technically, a Discoverable Credential can either be synchronised via some sync fabric (a multi-device or synched passkey e.g, cloud-synched via iCloud Keychain) or bound to the device (single-device or device-bound passkey e.g, a security key). Note that currently there is no way in the plugin to set or detect the different types, the W3C work on this is still a working draft.
During the registration of a FIDO2 credential, you can explicitly configure the ResidentKeyRequirement by setting the idp.authn.webauthn.registration.residentKey property. The possible values, set in conf/authn/webauthn.properties, are listed below:
...
Option
...
Default
...
Description
User Display Name Population
The user display name (user.displayName) is a human-palatable name for the user’s account. It is only intended for display to the user during registration. It is not used during authentication.
By default, the user display name is taken from the principal name in the SubjectContext. That is, the canonical principal name of the subject that authenticated to the registration endpoint. However, you may prefer to pull this value from the attribute resolver. This is supported by changing the following properties in conf/authn/webauthn.properties:
change the property idp.authn.webauthn.registration.displayname.strategy to reference the bean shibboleth.authn.webauthn.registration.AttributeContextDisplayNameLookupStrategy.
ensure the attribute resolver is enabled after authentication, idp.authn.webauthn.admin.registration.resolveAttributes=true.
decide which attribute from the resolver context to use using idp.authn.webauthn.registration.displayname.
...
preferred
...
Require a residentKey/DiscoverableCredential (passkey) to be created when registering a credential. One-of 'discouraged', 'preferred', 'required'
If you ‘preferred’ Discoverable Credentials during registration but require them for authentication, you may end up in a situation where the user registers a credential they can not later use.
Authenticator Attachment Options
Authenticator attachment modality specifies the mechanism by which a client can communicate with an authenticator. For example, can the authenticator be removed and ‘roam’ across platforms like a security key, or is the authenticator internal to the device and attached to the given platform like a Trusted Platform Module.
This distinction between roaming and platform attachments can be confusing when a platform authenticator can also be used in a roaming context. The most common example of this is that of a mobile device authenticator: when authenticating on the device itself it acts as a platform authenticator, but when authenticating another client via cross-device authentication (QR code and Bluetooth) it acts as a roaming authenticator.
...
attributeId.
Complete control over the strategy is possible by defining your own bean of type Function<ProfileRequestContext, String>.
| Anchor | ||||
|---|---|---|---|---|
|
Discoverable Credentials (Passkeys)
A Discoverable Credential, formally a Resident Key, stores the private key and associated metadata on the authenticator. This allows usernameless flows and is strictly what is required for a FIDO2 credential to be a ‘passkey’. The alternative allows the private key to be stored, in a protected format, at the relying party (for example, packaged inside the credential ID). Noting that some security keys have limited space for Discoverable Credentials.
Technically, a Discoverable Credential can either be synchronised via some sync fabric (a multi-device or synched passkey e.g, cloud-synched via iCloud Keychain) or bound to the device (single-device or device-bound passkey e.g, a security key). Note that currently there is no way in the plugin to set or detect the different types, the W3C work on this is still a working draft.
During the registration of a FIDO2 credential, you can explicitly configure the ResidentKeyRequirement by setting the idp.authn.webauthn.registration.authenticatorAttachment residentKey property. The possible values, set in conf/authn/webauthn.properties, are listed below:
Option | Default | Description |
|---|---|---|
idp.authn.webauthn.registration. |
residentKey |
any
preferred | Require a residentKey/DiscoverableCredential (passkey) to be created when registering a credential. One-of ' |
discouraged', ' |
preferred', |
' |
Attestation Conveyance
Attestation allows the IdP (acting as a WebAuthn RP) to verify the provenance of the authenticator used when registering a FIDO2 credential. This is provided in the form of an attestation statement. Attestation is optional as it can provide a poor user experience (the user must consent to the release of the attestation statement during registration), has an unclear meaning if the credential is synchronised around multiple devices (what created it might not be the same as what eventually uses it), and is a possible privacy concern (adds another data point for fingerprinting).
...
required' |
If you ‘preferred’ Discoverable Credentials during registration but require them for authentication, you may end up in a situation where the user registers a credential they can not later use.
Authenticator Attachment Options
Authenticator attachment modality specifies the mechanism by which a client can communicate with an authenticator. For example, can the authenticator be removed and ‘roam’ across platforms like a security key, or is the authenticator internal to the device and attached to the given platform like a Trusted Platform Module.
This distinction between roaming and platform attachments can be confusing when a platform authenticator can also be used in a roaming context. The most common example of this is that of a mobile device authenticator: when authenticating on the device itself it acts as a platform authenticator, but when authenticating another client via cross-device authentication (QR code and Bluetooth) it acts as a roaming authenticator.
During the registration of a FIDO2 credential, you can explicitly configure the AuthenticatorAttachment by setting the idp.authn.webauthn.registration.authenticatorAttachment property. The possible values, set in conf/authn/webauthn.properties, are listed below:
Option | Default | Description |
|---|---|---|
idp.authn.webauthn.registration.authenticatorAttachment | any | The authenticator attachment (authenticator type) requirement. One-of 'any', 'cross-platform', or 'platform' |
| Anchor | ||||
|---|---|---|---|---|
|
Attestation allows the IdP (acting as a WebAuthn RP) to verify the provenance of the authenticator used when registering a FIDO2 credential. This is provided in the form of an attestation statement. Attestation is optional as it can provide a poor user experience (the user must consent to the release of the attestation statement during registration), has an unclear meaning if the credential is synchronised around multiple devices (what created it might not be the same as what eventually uses it), and is a possible privacy concern (adds another data point for fingerprinting).
During registration of a FIDO2 credential, you can explicitly configure the AttestationConveyencePreference by setting the idp.authn.webauthn.registration.attestationConveyancePreference property. The possible values, set in conf/authn/webauthn.properties, are listed below:
Option | Default | Description |
|---|---|---|
idp.authn.webauthn.registration.attestationConveyancePreference | none | How should the attestation be conveyed during registration? One-of 'none', 'indirect', 'direct', or 'enterprise'. Indirect allows the client to anonymise the attestation. Enterprise may include uniquely identifying information and might be required to only allow organizationally attested authenticators. |
Noting, if you want to use the basic support for only allowing credentials to be registered from ‘trusted’ authenticators that are contained within the FIDO metadata feed, you’d typically need to enable ‘direct’ attestation.
User Verification
User verification requires an authenticator to authorise a user to create or use credentials. Typically this involves some kind of authorization guester such as fingerprint recognition, face recognition, or a pin.
During the registration of a FIDO2 credential, you can explicitly configure the AttestationConveyencePreference by setting the idp.authn.webauthn.registration.userVerification property. The possible values, set in conf/authn/webauthn.properties, are listed below:
Option | Default | Description |
|---|---|---|
idp.authn.webauthn.registration.userVerification | discouraged (so a registered key can be used as a second factor as well as a first factor) | Require User Verification on registration. One-of ‘discouraged’, ‘preferred’, ‘required’. |
Note that if user verification is required during registration, you may exclude authenticators that are usable in second-factor scenarios (which don’t require a user-verification capable authenticator).
Other Registration Options
The following additional registration options can be set in conf/authn/webauthn.properties, are listed below:.
Option | Default | Description |
|---|---|---|
idp.authn.webauthn. |
none
How should the attestation be conveyed during registration? One-of 'none', 'indirect', 'direct', or 'enterprise'.
Indirect allows the client to anonymise the attestation. Enterprise may include uniquely identifying information and might be required to only allow organizationally attested authenticators.
Noting, if you want to use the basic support for only allowing credentials to be registered from ‘trusted’ authenticators that are contained within the FIDO metadata feed, you’d typically need to enable ‘direct’ attestation.
User Verification
User verification requires an authenticator to authorise a user to create or use credentials. Typically this involves some kind of authorization guester such as fingerprint recognition, face recognition, or a pin.
During the registration of a FIDO2 credential, you can explicitly configure the AttestationConveyencePreference by setting the idp.authn.webauthn.registration.userVerification property. The possible values, set in conf/authn/webauthn.properties, are listed below:
Option | Default | Description |
|---|---|---|
idp.authn.webauthn.registration.userVerification | discouraged (so a registered key can be used as a second factor as well as a first factor) | Require User Verification on registration. One-of ‘discouraged’, ‘preferred’, ‘required’. |
Note that if user verification is required during registration, you may exclude authenticators that are usable in second-factor scenarios (which don’t require a user-verification capable authenticator).
Other Registration Options
The following additional registration options can be set in conf/authn/webauthn.properties.
Option
Default
Description
idp.authn.webauthn.preferredPublicKeyParams
EdDSA,ES256,ES384,ES512,RS1,RS256,RS384,RS512
preferredPublicKeyParams | EdDSA,ES256,ES384,ES512,RS1,RS256,RS384,RS512 | The preferred set of COSE signature algorithms which a created credential will use. The sequence is ordered from the most preferred to the least. The client makes a best effort to create the most preferred it can. |
Credential Registration Policies
The registration flow comes with a basic, extendable, policy engine for accepting and rejecting credentials based on the authenticator that created them. To enable policy checks, set the property idp.authn.webauthn.registration.authenticator.policy.enabled to true in conf/authn/webauthn-registration.properties.
Policies typically work off an Authenticator’s Attestation GUID (AAGUID) and require attestation statements from the authenticator. See the attestation conveyance section on how to configure this.
The default policy is defined by a list shibboleth.authn.WebAuthn.registration.ChainedRegistrationPolicyList of policies configured in conf/authn/webauthn-registration-config.xml. Out of the box, the following policies are included:
Policy Name | Description | Value |
|---|---|---|
AllowlistAuthenticatorPolicy | An allowed list of authenticators based on their Authenticator Attestation GUID (AAGUID) | The comma-separated list of authenticators can be directly specified in the XML configuration or, for convenience, set by the idp.authn.webauthn.registration.authenticator.policy.allowedAuthenticators property. |
Reference
| Expand | ||
|---|---|---|
| ||
...