Skip to content

CEP FIDO2 / Webauthn

The CEP allows for the limitation of FIDO2 tokens by providing vendor root CAs and specifying certain features that the token must provide. This includes requirements such as the token storing private keys in a secure element, being cross-platform compatible, and other parameters that govern the usage of tokens by your users.

Configuration

Vendor Limitations

The following configuration example limits the usage of tokens to YubiKey devices from Yubico. Multiple vendors can be added by including more than one root CA in the container.

Example Of Vendor CA Validation
    volumes:
      # https://developers.yubico.com/U2F/yubico-u2f-ca-certs.txt
      - ./certs/yubico-root-ca.pem:/var/www/html/var/certs/yubico-root-ca.pem
    environment:
      - CEP_FIDO2_REQUIRE_VENDOR_CERTIFICATE=true

Feature Requirements

This example configures the requirement for a token to provide an AAGUID, which is used to look up the features the token provides. Most modern tokens support this feature. The CEP will reject the token if the attestation of the token does not provide an AAGUID and these parameters are enabled.

Example Of Token Features Requirements
    environment:
      - CEP_FIDO2_REQUIRE_KEY_PROTECTION_HARDWARE=true
      - CEP_FIDO2_REQUIRE_KEY_PROTECTION_SECURE_ELEMENT=true
      - CEP_FIDO2_REQUIRE_MATCHER_PROTECTION_ON_CHIP=true

CEP_FIDO2_AUTHENTICATOR_ATTACHMENT

This parameter enforces the authenticator attachment of WebAuthn/FIDO2 attestation. It can be configured for cross-platform and platform-specific devices. Cross-platform devices are typically roaming authenticators that can be used on different clients.

Example
    environment:
      - CEP_FIDO2_AUTHENTICATOR_ATTACHMENT=cross-platform
Default
    environment:
      - CEP_FIDO2_AUTHENTICATOR_ATTACHMENT=

CEP_FIDO2_USE_DOMAIN

If set to true, the domain of the FQHN will always be used for the enrollment for FIDO2. This is best practice to ensure that user enrollments are available under every FQHN under this domain.

Example
    environment:
      - CEP_FIDO2_USE_DOMAIN=false
Default
    environment:
      - CEP_FIDO2_USE_DOMAIN=true

CEP_FIDO2_REQUIRE_KEY_PROTECTION_HARDWARE

This parameter should be set to true if the authenticator must use hardware-based key management.

Example
    environment:
      - CEP_FIDO2_REQUIRE_KEY_PROTECTION_HARDWARE=true
Default
    environment:
      - CEP_FIDO2_REQUIRE_KEY_PROTECTION_HARDWARE=false

CEP_FIDO2_REQUIRE_KEY_PROTECTION_SECURE_ELEMENT

This parameter should be set to true if the authenticator must use secure element for key management.

Example
    environment:
      - CEP_FIDO2_REQUIRE_KEY_PROTECTION_SECURE_ELEMENT=true
Default
    environment:
      - CEP_FIDO2_REQUIRE_KEY_PROTECTION_SECURE_ELEMENT=false

CEP_FIDO2_REQUIRE_MATCHER_PROTECTION_ON_CHIP

This parameter should be set to true if the authenticator's matcher must run on the chip.

Example
    environment:
      - CEP_FIDO2_REQUIRE_MATCHER_PROTECTION_ON_CHIP=true
Default
    environment:
      - CEP_FIDO2_REQUIRE_MATCHER_PROTECTION_ON_CHIP=false

CEP_FIDO2_REQUIRE_ATTACHMENT_HINT_EXTERNAL

This parameter should be set to true if the authenticator must be hardware-based, meaning that it is removable or remote from the FIDO user device.

Example
    environment:
      - CEP_FIDO2_REQUIRE_ATTACHMENT_HINT_EXTERNAL=true
Default
    environment:
      - CEP_FIDO2_REQUIRE_ATTACHMENT_HINT_EXTERNAL=false

CEP_FIDO2_REQUIRE_ATTACHMENT_HINT_WIRED

This parameter should be set to true if the external authenticator must have an exclusive wired connection, for example, through USB, firewire, or a similar interface. Please keep in mind that some authenticators support multiple connection types.

Example
    environment:
      - CEP_FIDO2_REQUIRE_ATTACHMENT_HINT_WIRED=true
Default
    environment:
      - CEP_FIDO2_REQUIRE_ATTACHMENT_HINT_WIRED=false

CEP_FIDO2_REQUIRE_VENDOR_CERTIFICATE

If this parameter is set to true, the CEP will check the allowed vendor root CA's during enrollment. If the chain cannot be validated, the CEP will deny the enrollment.

Example
    environment:
      - CEP_FIDO2_REQUIRE_VENDOR_CERTIFICATE=true
Default
    environment:
      - CEP_FIDO2_REQUIRE_VENDOR_CERTIFICATE=false