Introduction

• The JS7 - Identity Services offer management of user accounts for authentication and authorization.
• FIDO is a set of authentication standards based on the work of the FIDO Alliance and W3C.
  • The underlying WebAuthn API is used by the FIDO2 protocol and Passkeys.
  • Users can configure the FIDO Identity Service to work compatible with FIDO2 and Passkeys.
  • The FIDO Identity Service can act as a single factor and as 2nd factor in MFA.
• The FIDO Identity Service integration is available from JOC Cockpit:
  • As a prerequisite JOC Cockpit has to be set up for JS7 - JOC Cockpit HTTPS Connections.
  • Compliant software and hardware based Authenticators can be used.
  • JS7 implements a FIDO Client and Server for use with an Authenticator. JS7 does not ship with an Authenticator.
  • Examples for Authenticators include Windows® Hello (Platform Authenticator) and YubiKey® (Roaming Authenticator).
• FEATURE AVAILABILITY STARTING FROM RELEASE 2.6.0
  JOC-1546 - Getting issue details... STATUS

Terminology

The FIDO protocol knows the following roles involved in authentication:

• Security Key is a physical device that can connect using USB, NFC, BLE etc. and that hosts an Authenticator. Examples include YubiKey®, TrustKey® etc. 
• Authenticator is a system that provides credential services such as creating private/public key pairs. Authenticators are available as Roaming Authenticators (=hosted on Security Keys) and as Platform Authenticators (=hosted with the Client's device, phone or in a cloud service).
• Client is the JOC Cockpit GUI that performs login by use of Authenticator services.
• Relying Party is the JS7 - REST Web Service API that verifies Client signatures to prove the identity of a user.

Further technical terms are used from the WebAuthn API specification.

Identity Service Type

The following integration level is available from the FIDO Identity Service Type:

Explanation:

• Service Type: FIDO
  • Management of user accounts and private/public keys is performed by the Authenticator
  • The assignment of roles to user accounts is performed by JOC Cockpit acting as the Relying Party.
  • The JOC Cockpit stores user accounts and role assignments in the JS7 - Database.
  • The JOC Cockpit does not know Private Keys of user accounts. JOC Cockpit knows the user account's Certificate that is used to verify authentication requests.
• The FIDO Identity Service identifies the user, not the device used for authentication. To protect the user's privacy no Attestation is performed.

Identity Service Configuration

The  icon in the JOC Cockpit main menu is used to select the Manage Identity Services page:

Adding the Identity Service

To add an Identity Service use the button Add Identity Service from the page shown above, listing the available Identity Services:

The remaining input fields for the popup window look like this:

Explanation:

• The Identity Service Name is a unique identifier that can be freely chosen.
• The Identity Service Type can be selected as available from the above matrix.
• The Ordering specifies the sequence in which a login is performed with available Identity Services.
• The Required attribute specifies if the respective Identity Service is mandatory for login to JOC Cockpit.
• The Used as Second Factor attribute specifies if the Identity Service is used as an additional factor in multi-factor authentication with other Identity Services or is used a single factor or first factor Identity Service.
  • The FIDO2 and Passkeys protocols can be used as a single factor or as a second factor in MFA.
• The Identity Service Authentication Scheme allows to select
  • single-factor authentication: FIDO authentication works as the only factor for login with the Identity Service.
  • two-factor authentication: in addition to use of the FIDO Identity Service a second Identity Service such as the JS7 - Certificate Identity Service is required - see the JS7 - Certificate based Authentication article for more information.

Identity Service Settings

Having added a FIDO Identity Service, it is required to add settings from the Identity Service's Manage Settings action menu item:

Choosing the FIDO Protocol

When clicking the Manage Settings action menu item a popup window is displayed to choose the desired FIDO protocol and to manage related settings:

• FIDO2
  • User Verification is mandatory, i.e. a gesture when performing registration and authentication such as touching a USB Stick.
  • Resident Key ("Discoverable Credentials") is required, i.e. user credentials reside in a Security Key device.
  • Attachment specifies a Roaming Authenticator being used that resides in the Security Key device, for example in a USB Stick.
  • Basically this means that the FIDO2 protocol forces to store credentials on an external Security Key device and denies to store credentials on the Client's device or platform. Security Key devices typically do not allow to create copies of the device or of credentials. As a consequence there is no key recovery procedure if a Security Key is lost or damaged.
• Passkeys
  • User Verification can be specified to be required, preferred or discouraged.
  • Resident Key ("Discoverable Credentials") is required, i.e. user credentials reside with the Authenticator's platform.
  • Attachment specifies a Platform Authenticator being used that resides in the Client's device, for example in a computer or phone using Windows® Hello and using browsers such as Firefox, Chrome, Edge. 
  • As a summary Passkeys store credentials in the Client's device and make use of a Platform Authenticator that allows to copy credentials and to synchronize between a number of devices such as notebooks, tablets, phones. Authenticator vendors typically offer key recovery procedures from copies of credentials that are stored in the cloud.

JS7 administrators might want to take an educated decision about the protocol used. FIDO2 offers the best security, particularly when used with certified Security Key devices (FIPS compliant). Passkeys are the more lightweight protocol for relaxed security requirements as credentials are trusted to be managed safely by the Platform Authenticator's vendor.

The JS7 offers to manage separate Identity Services for FIDO2 and Passkeys. This allows to set up a number of Identity Services that authenticate users from different FIDO protocols, for example depending on the user's role.

The JS7 does not perform Attestation:

• During registration the Authenticator might provide an Attestation to the Relying Party. The attestation statement includes information such as the Authenticator's certificate, that can be used to verify the authenticity of the Authenticator. The attestation statement is used by the Relying Party to verify that the Authenticator is genuine and to trust the generated key pair.
• Attestation can contribute to identifying users from the uniqueness of the Security Key device in use. Typically a batch of 100 000 Security Keys will use the same certificate, However, if Security Keys and related certificates are provisioned from a centralized organization then this number might be drastically reduced.

FIDO2 Protocol Settings

When clicking the Manage Settings action menu item a popup window is displayed to manage settings for the FIDO2 protocol:

Explanation:

• Require Account
  • Optionally specifies that for authentication the user has to indicate an account. For registration it is mandatory to indicate an account.
• Timeout
  • The time in seconds that is waited for a user's response when being prompted for registration or authentication, for example to specify a PIN using the Authenticator.
• Transports
  • Transports can be specified if the Require Account setting is checked.
  • The Identity Service can limit the accepted type of connection between the Client and the Authenticator for example using USB, Bluetooth, NFC.
  • For example, specifying usb will limit acceptable Authenticators to use of USB Sticks. The Relying Party will deny registration if no matching connection is provided by an Authenticator.
  • For explanations see https://w3c.github.io/webauthn/#enum-transport
• User Verification
  • User verification is mandatory and includes that a user performs a gesture during registration and authentication to prove the user's presence and consent.
• Resident Key
  • Credentials are required to be stored in the Security Key device.
• Attachment
  • A Roaming Authenticator is required.

Passkeys Protocol Settings

The following settings are available when choosing the Passkeys protocol:

Explanation:

• Require Account
  • Optionally specifies that for authentication the user has to indicate an account. For registration it is mandatory to indicate an account.
• Timeout
  • The time in seconds that is waited for a user's response when being prompted for registration or authentication, for example to specify a PIN using the Authenticator.
• Transports
  • Transports can be specified if the Require Account setting is checked.
  • The Identity Service can limit the accepted type of connection between the Client and the Authenticator similar to the FIDO2 protocol.
• User Verification
  • User verification includes that a user performs a gesture during registration and authentication to prove the user's presence and consent.
  • Possible values include:
    • Preferred: User verification is optional. The Authenticator should perform user verification if possible.
    • Discouraged: User verification should be avoided by the Authenticator.
    • Required: User verification is mandatory.
• Resident Key
  • Credentials are required to be stored with the Platform Authenticator in the related platform, for example on the user's computer, phone or in the cloud.
• Attachment
  • A Platform Authenticator is required.

E-Mail Settings

Tab: Connection

This tab holds settings for connections to the mail server.

Explanation:

• Job Resource: A job resource has to be selected from the inventory that holds settings for the connection to the mail server, for download and explanation see JS7 Job Environment Variables, Job Resource eMailDefault
• Content Type:  The values text/html and text/plain are applicable for HTML mail and text mail.
• Charset:  The character sets ISO-8859-1 and UTF-8 are frequently used.
• Encoding: The ISO-8859-1, UTF-8 and 7-bit encodings are frequently used.
• Priority: The values Normal, Low, High are applicable.

Tab: Confirmation E-Mail to User

This tab holds a mail template that is used to ask users to follow a link in order to confirm their mail address:

Explanation:

• Send mail to user to confirm e-mail address: If the checkbox is checked then related mails will be sent.
• Cc: Send mail as carbon copy to additional recipients. A number of recipients are separated by a comma or semicolon.
• Bcc: Send mail as blind carbon copy to additional recipients. A number of recipients are separated by a comma or semicolon.
• Subject: The subject of the mail. Users can modify the subject at their will.
• Body: The body of the mail. Users are free to adjust the mail body.
  • By default an HTML template is provided that holds the following variables that will be substituted when sending mail:
    • ${REGISTRATION_EMAIL_ADDRESS}: The user account's mail address.
    • ${FIDO_IDENTITY_SERVICE}: The name of the Identity Service.
    • ${REGISTRATION_VERIFY_LINK}: The link to JOC Cockpit that is used for confirmation of the user's mail address.
  • When sending HTML mails then the Content Type setting in the Connection tab should carry the value text/html. For plain text mails the value accordingly should be text/plain.
  • Users can toggle between source and preview of the HTML e-mail body.

Tab: Notification E-Mail to User

This tab holds a mail template that is used to notify a user about approval of the registration.

Explanation:

• Send mail to user to notify about successful registration: If the checkbox is checked then related mail will be sent.
• Cc: Send mail as carbon copy to additional recipients. A number of recipients are separated by a comma or semicolon.
• Bcc: Send mail as blind carbon copy to additional recipients. A number of recipients are separated by a comma or semicolon.
• Subject: The subject of the mail. Users can modify the subject at their will.
• Body: The body of the mail. Users are free to adjust the mail body.
  • By default an HTML template is provided that holds the following variables that will be substituted when sending mail:
    • ${FIDO_IDENTITY_SERVICE}: The name of the Identity Service.
    • ${JOC_URL}: The JOC Cockpit URL.
    • ${JOC_REVERSE_PROXY_URL}: The JOC Cockpit URL that is used if a reverse proxy is in place. The variable makes use of the joc_reverse_proxy_url setting in the JS7 - Settings.
  • When sending HTML mail then the Content Type setting in the Connection tab should carry the value text/html. For plain text mails the value accordingly should be text/plain.
  • Users can toggle between source and preview of the HTML e-mail body.

Tab: Notification E-Mail to Administrator

This tab holds a mail template that is used to notify an administrator about receipt of a user's e-mail confirmation:

Explanation:

• Send mail to administrator to notify about successful confirmation: If the checkbox is checked then related mail will be sent.
• Cc: Send mail as carbon copy to additional recipients. A number of recipients are separated by a comma or semicolon.
• Bcc: Send mail as blind carbon copy to additional recipients. A number of recipients are separated by a comma or semicolon.
• Subject: The subject of the mail. Users can modify the subject at their will.
• Body: The body of the mail. Users are free to adjust the mail body.
  • By default an HTML template is provided that holds the following variables that will be substituted when sending mail:
    • ${FIDO_IDENTITY_SERVICE}: The name of the Identity Service.
    • ${JOC_URL}: The JOC Cockpit URL.
    • ${JOC_REVERSE_PROXY_URL}: The JOC Cockpit URL that is used if a reverse proxy is in place. The variable makes use of the joc_reverse_proxy_url setting in the JS7 - Settings.
  • When sending HTML mail then the Content Type setting in the Connection tab should carry the value text/html. For plain text mails the value accordingly should be text/plain.
  • Users can toggle between source and preview of the HTML e-mail body.

Resources