Skip to main content

FIDO UAF Configuration

All UAF related configuration is located in the fido-uaf configuration section. This includes the UAF specific configuration options and files.

  • fido-uaf

    The root node of the FIDO UAF application configuration. It defines the application ID information.

  • fido-uaf.enabled

    FIDO UAF 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.

  • fido-uaf.app-id

    The application ID.

  • fido-uaf.facets

    The facets associated with the application ID. This is an array of strings. Note that changing the contents of the facets configuration in the nevisfido.yml file are automatically taken into account without requiring a server restart. Refer to the Access App Facet ID calulation chapter or the SDK Facet ID configuration chapter for more details.

Wildcard Facet IDs

The Nevis Access App as well as the Nevis Mobile Authentication SDK support wildcard facet entries such as android:apk-key-hash:* and ios:bundle-id:*. Wildcard facets are useful for development and demo purposes, for example using the mobile SDK example applications. They are not allowed in production environments, use specific facet ID entries instead.

FIDO UAF Metadata​

  • fido-uaf.metadata

The configuration of the metadata that nevisFIDO uses to process the requests. The default metadata contains the definitions of the Nevis Mobile Authentication authenticators.

  • fido-uaf.metadata.path

The path (file or directory) containing the metadata. If the path is a directory, nevisFIDO reads all the files in the directory and aggregates its content. This allows you to update the metadata by adding/removing/updating single files. nevisFIDO expects that each of the files contains one JSON object. The JSON object is either an object defining a single UAF Metadata Statement or a JSON array with several metadata statements.

  • fido-uaf.metadata.value

Inline JSON in the configuration yaml containing metadata. It takes precedence over the fido-uaf.metadata.path. 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!). The JSON object is either an object defining a single UAF Metadata Statement or a JSON array with several metadata statements.

Metadata Statements​

A minimal metadata configuration must include the following attributes:

  • aaid
  • description
  • authenticatorVersion
  • upv
  • assertionScheme
  • authenticationAlgorithm
  • publicKeyAlgAndEncoding
  • attestationTypes
  • userVerificationDetails
  • keyProtection
  • matcherProtection
  • attachmentHint
  • isSecondFactorOnly
  • tcDisplay
  • attestationRootCertificates
info

The possible configuration options are not explained in detail here. For more information, refer to the UAF Metadata Statement specification.

The default metadata statements shipped with nevisFIDO include all authenticators supported by the Access App and Mobile Authentication SDK.

UAF Policies​

  • fido-uaf.policy

    The configuration of the policy that nevisFIDO uses to process requests. nevisFIDO can support multiple policies. The default nevisFIDO policy accepts all the Nevis Mobile Authentication authenticators.

    • In case of a registration request from a user that already has registered other credentials, nevisFIDO adds one non-acceptable match criteria to each of the already registered credentials in the policy. This is to prevent the user from reregistering an already registered credential.
    • In case of a step-up authentication, nevisFIDO validates the user against the policy. If at least one credential is registered for the provided username, nevisFIDO returns a policy that only contains the user’s AAID and KeyIDs. If no valid credentials are found, the policy is sent as defined in the configuration files.

  • fido-uaf.policy.path

    The path to the file or directory containing the policies.

  • fido-uaf.policy.value

    Inline JSON in the configuration yaml containing policies. It takes precedence over the fido-uaf.metadata.path. 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!). Note that when defining policies, the policy typically has a name. In case of using the path configuration option the policy name is the name of the file, so the JSON inside the file does not contain the policy name. In the inline JSON configuration you must define a map (dictionary) where every entry have the policy name as the key and the policy itself as the value. The JSON object is representing a Policy as defined in the FIDO UAF specification.

Policy Configuration Details​

The policy defines which are the authenticators that can be used in a registration or authentication operation.

nevisFIDO must be configured to have at least one policy, which will be referred to, as the default policy. The policy to be used is specified in the GetUafRequest context (registration, or authentication). If no policy is provided in the GetUafRequest, the default policy is used.

The policy is configured using fido-uaf.policy.path. The nevisFIDO path specified in fido-uaf.policy.path can be either a file or a directory:

  • If it is a file, only one policy will be supported (the default policy). The policy defined in the file will be used when there is no policy specified in the GetUafRequest context (registration, or authentication), or if the specified policy is default.

  • If it is directory, the directory contains the different policies to be supported. Each file with .json extension in the directory contains a policy, and the name of the policy is the name of the file without the JSON extension.

    The directory must contain a file named default.json with the default policy. The policy defined in default.json will be used when there is no policy specified in the GetUafRequest context, or if the specified policy is default.

    If the directory contains a file named my-policy.json, then it contains the policy that will be used when the policy in the GetUafRequest context is my-policy.

Each of the policy configuration files contains one JSON object, representing a Policy as defined in the FIDO UAF specification.

You can find a number of predefined policies under the conf/policy directory of the nevisFIDO installation:

  • all-authenticators.json allows to execute the registration or authentication with all Nevis authenticators.
  • only-pin-authenticators.json allows only the PIN authenticators.
  • only-biometric-authenticators.json allows only biometric authenticators.
  • only-password-authenticators.json allows only (alphanumeric) password authenticators.
Policy configuration examples

The possible configuration options are not explained in detail here. For more information, visit our concept and configuration guide policy examples.

Client Timeouts​

  • fido-uaf.timeout

    The configuration of the client timeouts.

  • fido-uaf.timeout.registration

    Defines the maximum time duration between the generation of the RegistrationRequest by nevisFIDO and the RegistrationResponse by the FIDO UAF client. If the client has not sent the response after this time, a client timeout occurs. The default value is 5 minutes. If no time unit is provided, seconds will be used.

  • fido-uaf.timeout.authentication

    Defines the maximum time duration between the generation of the AuthenticationRequest by nevisFIDO and the AuthenticationResponse by the FIDO UAF client. If the client has not sent the response after this time, a client timeout occurs. The default value is 2 minutes. If no time unit is provided, seconds will be used.

  • fido-uaf.timeout.token-registration

    Defines the maximum time a client has to redeem a registration token after the generation of the token by nevisFIDO. Once the token is redeemed, the value of the registration timeout applies: from the moment of the redemption of the token the client has a maximum time (the registration timeout) to send a RegistrationResponse to nevisFIDO). The default value is 5 minutes. If no time unit is provided, seconds will be used.

  • fido-uaf.timeout.token-authentication

    Defines the maximum time a client has to redeem an authentication token after the generation of the token by nevisFIDO. Once the token is redeemed, the value of the authentication timeout applies: from the moment of the redemption of the token the client has a maximum time (the authentication timeout) to send an AuthenticationResponse to nevisFIDO). The default value is 2 minutes. If no time unit is provided, seconds will be used. In case this property is set explicitly, and you are using FCM dispatching, make sure to also adjust fido-uaf.dispatchers.firebase-cloud-messaging.message-ttl to the same value.

  • fido-uaf.timeout.token-deregistration

    Defines the maximum time a client has to redeem a deregistration token after the generation of the token by nevisFIDO. The default value is 2 minutes. If no time unit is provided, seconds will be used.

  • fido-uaf.timeout.token-deregistration

    Defines the maximum time a client has to redeem a deregistration token after the generation of the token by nevisFIDO. The default value is 2 minutes. If no time unit is provided, seconds will be used.

  • fido-uaf.timeout.device-request

    Defines the maximum time divergence that is accepted between the time specified in the creationTimeInEpochMillis attribute in device service requests and the time the server processes the request. This value is close to the time divergence that is accepted between the mobile device clock and the server clock. If the clock divergence is bigger than this value, false positives will occur validating the device requests and the requests will be refused. The default value is 5 minutes. If no time unit is provided, seconds will be used.

Transaction Confirmation​

  • fido-uaf.transaction-confirmation

    The configuration of the transaction confirmation.

  • fido-uaf.transaction-confirmation.max-text-length

    The maximum length of the transaction content when the content type of the transaction is text-plain. For example, if the transaction is of type text-plain, the value of max-text-length is 1000 and the content of the transaction in base64 URL encoded format has more than 1000 characters, the transaction will result in an error. The default value is 200 (as defined in the FIDO UAF specification) . The minimum value is 200, the maximum value is 2000. See Transaction Confirmation for more details.

Full Basic Attestation​

  • fido-uaf.full-basic-attestation

    The configuration to specify the validation that nevisFIDO must do for registrations using the full basic attestation. Visit our concept guide for more information.

  • fido-uaf.full-basic-attestation.android-verification-level

    This property defines what nevisFIDO verifies when an Android authenticator from the Nevis Mobile Authentication SDK uses full basic attestation during registration.

    The property can take two values: 'default' and 'strict'.

    If default is provided, when the authenticator provides a full basic attestation, the server will validate what is described in the FIDO UAF specification. For Nevis Mobile SDK Android authenticators, this means that only devices that store the keys in a TEE certified by Google will be accepted. In addition:

    • The key revocation list configured by fido-uaf.full-basic-attestation.android-attestation-key-revocation is checked for revoked keys.
    • The AttestationApplicationId signature digest matches one of the known Android Facets

    If strict is specified, additional checks are done when the Nevis SDK Android authenticator provides a full basic attestation during registration (visit the verification levels documentation for additional details):

  • fido-uaf.full-basic-attestation.android-permissive-mode-enabled

    Setting this property to true will perform all the full basic attestation checks specified by the full-basic-attestation.android-verification-level attribute. However, in the case of a validation failure, the registration will not fail, only a warning message will be logged. Visit the permissive mode concept documentation for additional information.

  • fido-uaf.full-basic-attestation.android-attestation-key-revocation.url

    This property specifies the URL used to retrieve the Android attestation key revocation list. The list is essential for validating the security status of attestation keys on Android devices. By default, the property is set to https://android.googleapis.com/attestation/status. Typically, no custom configuration is required.

  • fido-uaf.full-basic-attestation.android-attestation-key-revocation.reload-interval

    This property determines the interval at which the Android attestation key revocation list is automatically refreshed. Updates ensure that the system remains protected against revoked or compromised keys. The default interval is configured to 6 hours, which provides a balanced trade-off between freshness and network usage.

  • fido-uaf.full-basic-attestation.android-attestation-key-revocation.proxy-url

    This property allows specification of a proxy URL through which requests to the Android attestation key revocation 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.

  • fido-uaf.full-basic-attestation.android-attestation-key-revocation.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.

  • fido-uaf.full-basic-attestation.android-attestation-key-revocation.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.

Application Attestation​

  • fido-uaf.policy.app-attestation.android-service-account-value

    The service-account contents used to do the app attestation against the Google Cloud. The contents of this attribute will take precedence over android-service-account-path.

  • fido-uaf.policy.app-attestation.android-service-account-path

    The file containing the service-account used to validate policy. This is the alternative of providing android-service-account-value.

  • fido-uaf.policy.app-attestation.ios-team-identifier

    The 10-character identifier of the team which signs your iOS applications, as referred on your Apple developer account. This is also known as app identifier prefix (without the trailing dot).

  • fido-uaf.policy.app-attestation.ios-device-check-key-identifier

The 10-character identifier of the Device Check key This is used to validate the attestation receipts during iOS app attestation.

  • fido-uaf.policy.app-attestation.ios-device-check-key-value

    The private key contents used to validate policy. The contents of this attribute will take precedence over ios-device-check-key-path. The key is obtained as described in the official documentation.

  • fido-uaf.policy.app-attestation.ios-device-check-key-path

    The file containing the APN service private key. The file must be encoded in PEM format. The key is obtained as described in the official documentation.

  • fido-uaf.policy.app-attestation.ios-attestation-keys-per-month-limit

    The maximum number of app attestation keys that a given device can create in the last 30 days. Typically the Application Attestation key is generated once in the lifetime of the application, unless it expires or if the application gets reinstalled. If an iOS device gets compromised, it can generate attestation keys for malicious clients. A high number of keys generated in a given device may indicate that the device has been compromised. You must set this limit considering how many times it is reasonable for your application to be reinstalled in the last 30 days. Note that in the context of application development, the application is very often reinstalled, so for development environments, you may want to set a high number or "unlimited". Check the Apple documentation for more details.

    Use "unlimited" to set no limit, the default value is 20.

  • fido-uaf.policy.app-attestation.proxy-url

    This property allows specification of a proxy URL through which requests to the Android & iOS backend services 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.

  • fido-uaf.policy.app-attestation.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.

  • fido-uaf.policy.app-attestation.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.

Authorization​

  • fido-uaf.authorization

    Defines the authorization to be used when handling GetUAFRequest requests. See more in Authorization for FIDO UAF.

Dispatchers​

  • fido-uaf.dispatchers

    The list of dispatchers that can be used to dispatch tokens.

    nevisFIDO can generate and dispatch tokens through one of the configured dispatchers (see Dispatch Token Service). The HTTP client specifies the dispatcher to be used in the HTTP request to generate the token.

    The dispatching mechanism is used in the out-of-band case. In this case, one device triggers the FIDO operation by asking to generate a token. Then the token is dispatched to another device through a dispatcher. This FIDO UAF enabled device redeems the token and proceeds with the FIDO UAF operation. Usually, the device that triggers the operation is a desktop computer whereas the device receiving the token is a mobile device with FIDO UAF capabilities.

    The available dispatchers are:

    nevisFIDO allows to configure several dispatchers. The HTTP client specifies the dispatcher to be used by providing the value of the type attribute. Currently only one dispatcher for a given type can be configured (that is, you cannot configure two FCM dispatchers).

      dispatchers:
        - type: logger
Configuratin details

Visit FCM Dispatcher for detailed configuration information.

dispatchers:
  - type: firebase-cloud-messaging
    service-account-json: /var/opt/nevisfido/default/conf/service-account.json
    registration-redeem-url: https://siven.ch/nevisfido/token/redeem/registration
    authentication-redeem-url: https://siven.ch/nevisfido/token/redeem/authentication
    deregistration-redeem-url: https://siven.ch/nevisfido/token/redeem/deregistration

EL resolution in dispatcher configuration​

Expression resolution in dispatcher configuration has a limitation, which is only relevant for developers implementing custom dispatchers. Expressions resulting in integer or Boolean values require special escaping to result in strings. For example, assuming that the value of the environment variable BOOLEAN_VALUE is "true":

    dispatchers:
      - type: logger
        value: ${ENV:BOOLEAN_VALUE}

value is boolean "true".

    dispatchers:
      - type: logger
        value: "${ENV:BOOLEAN_VALUE}"

value is boolean "true".

    dispatchers:
      - type: logger
        value: '"${ENV:BOOLEAN_VALUE}"'

value is string "true".

Authorization for FIDO UAF​

nevisFIDO provides several authorization validation mechanisms for each operation, to meet the operations' different security requirements. For example, the deregistration operation usually requires authorization, to ensure that only known clients can deregister a FIDO UAF credential. To trigger authentication, however, authorization is typically not required.

info

The Modify Dispatch Target Service uses JWS to verify whether a request is sent by a trusted client. Therefore, the authorization validation configuration does not apply to this service.

Configuration Example
fido-uaf:
  authorization:
    # The username will be retrieved from the SecToken for the registration requests
    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 Context for the authentication requests
    authentication:
      type: none

    # The username will be retrieved from the SecToken for the deregistration requests
    deregistration:
      type: sectoken
      truststore: /var/opt/nevisfido/default/conf/truststore-with-nevisauth-signature-keys.p12
      truststore-passphrase: password
      truststore-type: pkcs12
      username-attribute-names:
        - userid

Currently, you can configure two authorization validation modes: Authorization validation with SecToken, or no authorization validation.

SecToken Authorization​

The SecToken authorization mode expects that the username is 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 (which is provided, for example, in the context of the GetUAFRequest).

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

  1. The FIDO UAF client tries to register a credential.
  2. nevisProxy detects that the FIDO UAF client is not authenticated. It redirects the client to nevisAuth for authentication.
  3. nevisAuth generates a SecToken upon successful authentication of the client.
  4. The authenticated FIDO UAF client will now be able to access the registration endpoint of nevisFIDO. nevisProxy will include the SecToken generated in the previous step in the Basic authorization header.
  5. nevisFIDO validates the SecToken, by verifying that the token was signed by nevisAuth and is not expired.
  6. nevisFIDO also checks whether the SecToken contains the username provided in the request (for example, in the context of the GetUAFRequest or in the username attribute of the "Create dispatch target" 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>

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 non-authentication operations (registration, deregistration, creation and deletion dispatch targets).

To enable a SecToken authorization for a specific operation, 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 deleted. 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 must delete the FIDO credentials of a given user whose user device was lost or stolen. In this case, the username associated with the operation 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 deleted). To be able to cover both use cases, the configuration attribute username-attribute-names can take several values.

info

There is no username provided in the delete dispatch target request, so the SecToken authorization works in a different way as for the other endpoints: the element that is used to validate that the request is authorized is the user identifier used by the repository (extId when the user is stored in nevisIDM) of the user owning the dispatch target to be deleted. This is why the value of the username-attribute-names attribute of the SecToken configuration should contain in most cases the value userId; with this configuration the userId in the SecToken is compared to the user identifier (as stored by the repository) of the owner of the dispatch target.

Configuration Example
fido-uaf:
  authorization:
    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

No Authorization Validation​

It is not recommended using the "no authorization" validation mode for non-authentication operations, such as registration, deregistration as well as creating and deleting dispatch targets. This is because the "no authorization"s ralidation mode is not secure. It allows everyone to perform an operation and thus makes impersonation possible. Fors rxample, the malicious client "Mallory" could send a registration request providing Alice’s name. This would generate credentials in Mallory’s FIDO device that would be associated with Alice, allowing Mallory to authenticate as Alice.

To not perform authorization validation for a specific operation, set the value of the type attribute to none.

Configuration Example
fido-uaf:
  authorization:
    authentication:
      type: none

FIDO UAF Credential Configuration​

All UAF credential related configuration is located in the fido-uaf.credential configuration section. Includes configuration properties which are more protocol specific than the credential-repository section.

  • fido-uaf.credential.uaf-policy-id

    The nevisIdm policy extId to be used for FIDO UAF credential creation. Modify operations do not update existing credentials.

  • fido-uaf.credential.dispatch-target-policy-id

    The nevisIdm policy extId to be used for Dispatch Target generic credential creation. Modify operations do not update existing credentials.

  • fido-uaf.credential.ios-app-attestation-policy-id

    The nevisIdm policy extId to be used for iOS App Attestation generic credential creation. Modify operations do not update existing credentials.This includes the UAF specific configuration options and files