FIDO2 Configuration

All FIDO2 related configuration is located in the fido2 configuration section. This includes the FIDO2 specific configuration options and files.

fido2
The root node of the FIDO2 application configuration.
fido2.enabled
FIDO2 can be enabled or disabled with this boolean property, without the need to remove or comment out it’s configuration. Note that at least one of FIDO UAF and FIDO2 must be enabled.
fido2.rp-name
Name of the relying party. This value allows spaces to be used and is intended to be human readable. An example would be Siven Inc..
fido2.rp-id
The ID of the relying party, where the public key credentials will be scoped to, see rpId in the specification. It is based on the host’s domain name and it restricts the set of origins that will be supported by the server. When evaluating a credential in context of a FIDO2 operation, the rpId must be equal to the origin’s effective domain, or a registrable domain suffix of the origin’s effective domain.
fido2.origins
List of origins that will be associated with this server, restricted by the server’s configured rp-id. When evaluating a credential in context of a FIDO2 operation, the rpId must be equal to the origin’s effective domain, or a registrable domain suffix of the origin’s effective domain.
fido2.signature-algorithms
The list of algorithms will be offered during registration for the client authenticator to generate the key material with. Supported values are EdDSA, ES256, ES384, ES512, RS256, RS384, RS512 and RS1. The default values are ES256 and EdDSA.
IANA recommendations:
- Recommended: EdDSA, ES256, ES384, ES512.
- Not recommended: RS256, RS384, RS512.
- Deprecated: RS1
fido2.timeout
Timeouts for FIDO2 are not related to different ceremonies (i.e. registration & authentication), but rather for whether user verification is required in a ceremony or not.
fido2.timeout.user-verification
Maximum time that a FIDO2 client has to send response in a ceremony where user-verification is required. Default value is 300s.
fido2.timeout.no-user-verification
Maximum time that a FIDO2 client has to send response in a ceremony where user-verification is not required. Default value is 120s.
fido2.display-name-source
Defines the attribute of the user that will be populated into the user.name property in the PublicKeyCredentialCreationOptions object that nevisFIDO sends to the FIDO2 client during the Registration ceremony. Some browsers choose this user.name property to display to the user when they prompt for user interaction (as opposed to user.displayName). Supported values are loginId, displayName, email and username - this latter does not correspond strictly to a nevisIDM user property, but instead is the same username what nevisFIDO received in the ServerPublicKeyCredentialCreationOptionsRequest object.
For a nevisIDM credential repository, the default is loginId, for an in-memory credential repository, the default is username.
fido2.authorization
Defines the authorization to be used when handling Options requests. See more in Authorization for FIDO2.

FIDO2 Metadata

fido2.metadata.mds3.urls
Allows specifying a list of FIDO2 authenticator metadata URLs. In normal scenarios you most likely want to use the official metadata endpoint of the FIDO alliance. Visit our configuration guide for additional information. Using this property requires the MDS3 metadata truststore configuration, see below.
fido2.metadata.mds3.proxy-url
This property allows specification of a proxy URL through which requests to the metadata service will be routed. It is useful in environments where direct internet access is restricted or security policies mandate proxy usage. By default, no proxy-url is configured.
fido2.metadata.mds3.proxy-user
This property defines the username required for authentication with the configured proxy. It should be provided if the proxy service requires authentication. By default, this property is unset.
fido2.metadata.mds3.proxy-password
This property sets the password used alongside the proxy username for authentication purposes. It must be defined if the proxy server requires password-based authentication. By default, this property is unset.
fido2.metadata.mds3.metadata-truststore
The truststore for storing the metadata service root certificates. This is necessary to ensure remote metadata services are trusted. This truststore configuration is the same as for all other key- and trust stores meaning that HSMs are supported if the truststore config parameter is left empty and other HSM-related configuration parameters are valid.
fido2.metadata.mds3.metadata-truststore-passphrase
The password needed to access the truststore. Use the mechanisms described in Application Configuration to avoid providing a plaintext password.
fido2.metadata.mds3.metadata-truststore-type
The type of the truststore. The recommended type is "pkcs12". Using the legacy Java key-/truststore "jks" is also possible. If this attribute is not set, the system will use the default truststore type of the Java Virtual Machine running nevisFIDO.
fido2.metadata.path
Configures either a single file or a directory path containing FIDO2 authenticator metadata. In both cases - file or directory, the following file structures are supported (and can even be mixed):
- JSON file containing a single metadataStatement object
- JSON file containing an array of metadataStatment objects
- JWS file represending and MDS3 metadata BLOB. Refer to the official documentation regarding the BLOB format.
Any authenticator listed in the metadata file will be allowed. Any authenticators not listed in the file will be denied. The metadata file reuses the metadataStatement structure of the FIDO MDS. The required attributes for each individual metadata are: aaguid, description, attestationRootCertificates. All other attributes can be removed to slim down the metadata file. Use the official FIDO Alliance Metadata Service to create your metadata file.
fido2.metadata.value
Inline JSON in the configuration yaml containing metadata. It takes precedence over the fido2.metadata.path. This property support only the JSON array of metadataStatment structure. A single entry needs to be added in array format as well. The JSON object must be provided as a one line string in double quotes or starting with | in the first line and than the formatted JSON in the next lines (indentation is very important!). For more information regarding the content see the metadataStatment structure description.

FIDO2 metadata example
[
  {
    "aaguid": "d94a29d9-52dd-4247-9c2d-8b818b610389",
    "description": "VeriMark Guard Fingerprint Key",
    "attestationRootCertificates": [
      "MIICfDCCAiOgAwIBAgIJAP4fSRQpRp3qMAoGCCqGSM49BAMCMIGZMQswCQYDVQQGEwJVUzELMAkGA1UECAwCQ0ExETAPBgNVBAcMCFNhbiBKb3NlMRgwFgYDVQQKDA9TeW5hcHRpY3MsIEluYy4xDDAKBgNVBAsMA1BDRDEVMBMGA1UEAwwMU3luYXB0aWNzIENBMSswKQYJKoZIhvcNAQkBFhxjZXJ0LWF1dGhvcml0eUBzeW5hcHRpY3MuY29tMCAXDTIwMDYwODIzNTAwOVoYDzIwNTEwNjA4MjM1MDA5WjCBmTELMAkGA1UEBhMCVVMxCzAJBgNVBAgMAkNBMREwDwYDVQQHDAhTYW4gSm9zZTEYMBYGA1UECgwPU3luYXB0aWNzLCBJbmMuMQwwCgYDVQQLDANQQ0QxFTATBgNVBAMMDFN5bmFwdGljcyBDQTErMCkGCSqGSIb3DQEJARYcY2VydC1hdXRob3JpdHlAc3luYXB0aWNzLmNvbTBZMBMGByqGSM49AgEGCCqGSM49AwEHA0IABLPQm50DgB980rdIIp6HYNo+nfQeUhPsm4s78NROeLMOheuKn8ZxPXDHD+SKqBHAnXNbtoQ8g4ch+qiS+sWvJuOjUDBOMB0GA1UdDgQWBBRDnWo24C2PpESzVbJPz1ZFTebSJzAfBgNVHSMEGDAWgBRDnWo24C2PpESzVbJPz1ZFTebSJzAMBgNVHRMEBTADAQH/MAoGCCqGSM49BAMCA0cAMEQCIESkk76ktFnDBDySebJHtw3TcJIXTfNo5Ng4Aj88BI7RAiBtEb5oxui8SzsUZ6wcQQjn5aB5nd2aNJBhZK+iFHHGxg=="
    ]
  },
  {
    "aaguid": "eb3b131e-59dc-536a-d176-cb7306da10f5",
    "description": "ellipticSecure MIRkey USB Authenticator",
    "attestationRootCertificates": [
      "MIICYTCCAeegAwIBAgIBATAKBggqhkjOPQQDAjBpMSQwIgYDVQQDDBtlbGxpcHRpY1NlY3VyZSBGSURPIFJvb3QgQ0ExGzAZBgNVBAsMEmVsbGlwdGljc2VjdXJlLmNvbTEXMBUGA1UECgwOZWxsaXB0aWNTZWN1cmUxCzAJBgNVBAYTAlVTMB4XDTE5MDQwNjEzMzEyNFoXDTM0MDQwNjEzMzEyNFowaTEkMCIGA1UEAwwbZWxsaXB0aWNTZWN1cmUgRklETyBSb290IENBMRswGQYDVQQLDBJlbGxpcHRpY3NlY3VyZS5jb20xFzAVBgNVBAoMDmVsbGlwdGljU2VjdXJlMQswCQYDVQQGEwJVUzB2MBAGByqGSM49AgEGBSuBBAAiA2IABIcioLldLnxvSp//GaJ0sq7hM92PQ4zW7CPlZlUm2syippwb/WXPwPROTdmQf2GDbg5UAA2IYpNZppUeq1vgnWvLmuJ7+u+KWBK23dz1S6SYOPtk5vHfGompC7IKi8MujKNjMGEwDgYDVR0PAQH/BAQDAgGGMA8GA1UdEwEB/wQFMAMBAf8wHQYDVR0OBBYEFCFR6t9+i/f6D9meogOLYpUlbqazMB8GA1UdIwQYMBaAFCFR6t9+i/f6D9meogOLYpUlbqazMAoGCCqGSM49BAMCA2gAMGUCMQD2KZdzs66h1kCEGqmFVr0Ue3jaN/BwffYuX4Km+YTDiU7jKEZdxzjArwFSmtiAIzACMENeLKDaAbOFIviqY5Kt2cXQkWzTgr134VlA8hUBPGE6KHg6giJaHgPZLSY6AFWH2A=="
    ]
  }
]

Authenticator Allow-listing

fido2.metadata.allow-listing-enabled
Configures allow-listing for FIDO2 Registration and Authentication ceremonies by either using the metadata file(s) provided in the path or using MDS3 metadata endpoints. The allow-listing uses the AAGUID and Attestation root certificate to identify a certain authenticator. The default value is false.

caution

To use the allow list functionality you need to be aware of some details as it restricts the FIDO2 authenticators which can be used. Read the FIDO 2 Authenticator allow-listing chapter in the concept and integration guide.

User Presence

fido2.user-presence-requirement
Defines the user presence requirement of nevisFIDO during FIDO2 ceremonies.
This setting is closely related to the user verification requirement, which is defined by the Relying Party in the ceremony's options request. User verification is the process of verifying the user through biometric recognition or by manually entering a PIN, while a user presence test is a simple interaction, such as pressing a button, to confirm human presence. Together, the user presence and user verification requirements define the characteristics of the required authorization gesture from the user during the ceremony.
Currently, two values are supported:
- always (default, required by the WebAuthn specification): the authorization gesture must always include a test of user presence, even if user verification was not requested by the Relying Party.
- only-at-user-verification: the authorization gesture must include a test of user presence only if user verification was requested by the Relying Party.
The following table helps in understanding the configuration option in relation to the UP (user presence) and UV (user verification) flags:
- User presence (UP): requires user interaction (for example pressing a button)
- User verification (UV): requires user verification (for example with biometrics)

	user verification `false`	user verification `true`
user presence `false`	`user-presence-requirement = only-at-user-verification` ⚠️ outside WebAuthn specification _{1 2}	❌ invalid configuration
user presence `true`	`user-presence-requirement = always`	`user-presence-requirement = always` or `user-presence-requirement = only-at-user-verification`

Authorization for FIDO2

nevisFIDO provides authorization validation mechanisms for each ceremony, to meet the ceremonies' different security requirements. For example, the registration ceremony usually requires authorization to ensure that only known clients can register a FIDO2 credential. To trigger the authentication ceremony however, authorization is typically not required.

FIDO2 Configuration Example
fido2:
  authorization:
  # The username will be retrieved from the SecToken for the creation options requests and validated against the incoming one
    registration:
      type: sectoken
      truststore: /var/opt/nevisfido/default/conf/truststore-with-nevisauth-signature-keys.p12
      truststore-passphrase: password
      truststore-type: pkcs12
      username-attribute-names:
        - loginid
        # The username will be retrieved from the get options requests
    authentication:
      type: none

FIDO2 Authorization supports validation with SecToken, or no authorization validation.

SecToken Authorization

The SecToken authorization mode expects the username to be provided in the HTTP headers as part of the SecToken. The SecToken is validated by nevisFIDO. For the authorization to be successful, the username in the SecToken must match the username in the request (that is for example provided in the options sent to trigger the registration ceremony).

Assuming that the username is provided in the SecToken for registration operations, the process is as follows:

The FIDO2 client tries to register a credential.
nevisProxy detects that the FIDO2 client is not authenticated. It redirects the client to nevisAuth for authentication.
nevisAuth generates a SecToken upon successful authentication of the client.
The authenticated FIDO2 client will now be able to access the creation options endpoint of nevisFIDO (which is accessed in the registration ceremony). nevisProxy will include the SecToken generated in the previous step in the Basic authorization header.
nevisFIDO validates the SecToken, by verifying that the token was signed by nevisAuth and is not expired.
nevisFIDO also checks whether the SecToken contains the username provided in the request.

The Basic authorization header has the following value:

    Basic <base64Value>

where <base64Value> is a string encoded with base64 and with the following format:

    <username>:<sectoken>

info

Note that nevisFIDO does not take into account the first part of the base64 value (username), but retrieves the username from the SecToken. The reason for this is that the username used to log in may differ from the username required in nevisFIDO. The content of the SecToken is configurable, thus allowing for flexibility in scenarios where one user can have several user identifiers.

However, it is still recommended that you include a username in the Basic authorization header. This is because nevisProxy must provide two values to meet the definition of a correct Basic header.

See nevisProxy Configuration for configuration details.

info

The use of a SecToken implies a preceding validation of the user identity by nevisAuth. So for security reasons, we recommend the usage of this type of authorization for the registration ceremony.

To enable a SecToken authorization for a specific ceremony, set the value of the type attribute to sectoken.

The SecToken authorization has the following additional configuration attributes:

truststore
Defines the path to the truststore with the public key that is used by nevisAuth to sign the SecToken.
truststore-passphrase
The password needed to access the truststore. Use the mechanisms described in Application Configuration to avoid providing a plaintext password.
truststore-type

The type of the truststore. The recommended type is "pkcs12". Using the legacy Java key-/truststore "jks" is also possible. If this attribute is not set, the system will use the default truststore type of the Java Virtual Machine running nevisFIDO.

username-attribute-names
Defines the attributes that the server will use to retrieve the username. If any of the SecToken attributes listed in this property contains the expected username, then the request will be authorized. By default, the value is userId. Typically, the authorized user and the user associated with the nevisFIDO operation are the same. For example, the authorized user is also the user whose FIDO credentials must be created. The authorized user is normally the user defined by the userId attribute of the SecToken. But in some cases, the authenticated user must perform an operation on behalf of another user. For example, an administrator might create the FIDO credentials on behalf of another user. In this case, the username associated with the ceremony is not the user defined in the SecToken (that is, the userId attribute of the SecToken does not contain the username of the FIDO credentials to be created) To be able to cover both use cases, the configuration attribute username-attribute-names can take several values.

FIDO2 Authorization Example
fido2:
  authorization:
    # The username will be retrieved from the SecToken for the creation options requests and validated against the incoming one
    registration:
      type: sectoken
      truststore: /var/opt/nevisfido/default/conf/truststore-with-nevisauth-signature-keys.p12
      truststore-passphrase: password
      truststore-type: pkcs12
      username-attribute-names:
        - userid
    # The username will be retrieved from the get options requests
    authentication:
      type: none

FIDO2 Authorization supports validation with SecToken, or no authorization validation.

FIDO2 Configuration

FIDO2 Metadata​

Authenticator Allow-listing​

User Presence​

Authorization for FIDO2​

SecToken Authorization​

FIDO2 Metadata

Authenticator Allow-listing

User Presence

Authorization for FIDO2

SecToken Authorization