About YubiEnroll

YubiEnroll lets organization IT admins configure and register YubiKeys on behalf of users in the organization and is a complementary solution to Yubico FIDO Pre-reg and part of the Yubico Enrollment Suite.

With Yubico FIDO Pre-reg organizations use the YubiEnterprise API and the organizations’ identity provider to request pre-registered, factory-new YubiKeys. Yubico pre-registers the keys which are then shipped to end users or offices through YubiEnterprise Delivery services.

YubiEnroll works as an independent application in an organizations’ environment and only communicates with the identity provider. A user, for example the organizations’ IT admin, configures and enrolls the YubiKey on behalf of an end user in the organization with YubiEnroll, and delivers the key locally to that end user.

The following are typical enrollment steps performed by an IT admin using YubiEnroll:

  1. The IT admin runs the YubiEnroll CLI and authenticates to the identity provider.
  2. The IT admin uses YubiEnroll CLI to initiate the enrollment process for an end user’s account in the identity provider.
  3. YubiEnroll gets the credential creation options from the identity provider.
  4. YubiEnroll creates the credentials on a YubiKey which is locally connected or presented to the enrollment workstation.
  5. YubiEnroll sets a randomized PIN on the YubiKey.
  6. The YubiKey returns the attestation data for the end user’s credential to YubiEnroll.
  7. YubiEnroll registers the credential for the end user in the identity provider.
  8. The IT admin provides the YubiKey and PIN to the end user.

YubiEnroll CLI

The YubiEnroll CLI tool provides an intuitive command line interface for interacting with the underlying YubiEnroll solution. You can for example:

  • Factory reset the YubiKey
  • Set and change the PIN
  • Configure Forcing PIN change
  • Increase the minimum PIN length
  • Configure Always require user verification (AlwaysUV)

For more information, see Using YubiEnroll CLI.

Enrollment Profiles

Enrollment profiles is a YubiEnroll feature that lets users define a combination of preferred configuration option settings, for example “Minimum PIN length” and “Force PIN change” configurations.

Note

The configuration options “Min PIN length”, “Require always UV”, and “Force PIN change before use” are only supported for YubiKeys with firmware version 5.5 and higher.

_images/add-profile.png

The following explains the enrollment profile settings in more detail.

  1. Minimum PIN length: This setting defines the minimum number of characters required for the PIN code used with the YubiKey. If not specifically set, the default value is 4. The minimum PIN length can never be lower than 4.
  2. Require always UV: The “Always require user verification” setting enforces PIN code request in all cases regardless of whether the relying party requests it or not. If set to “on”, user verification will always be performed. If set to “off” (default) user verification is overridden.
  3. Force PIN change before use: If set to “on”, this setting forces the end user to change the provided PIN code when using the YubiKey the first time. Default is “off”.
  4. Factory reset the Security Key: If set to “true” all credentials on the YubiKey will be removed and the key is completely cleared from previous configurations. This setting is mostly used for keys that have previously been in use. Default is “false”.
  5. Set a new random PIN: If set to “true”, YubiEnroll generates a random PIN code. If set to “false”, the user can specify as specific PIN code.

The enrollment profile settings are stored with a specific profile name locally on the workstation running YubiEnroll, to be applied when enrolling credentials for end users. Only one enrollment profile can be linked to a provider.

Enrollment profiles can be used with different identity provider configurations, and can also be configured for a provider to be automatically used during enrollment. For more information, see Identity Provider Configuration.

Identity Provider Configuration

When configuring a supported identity provider for YubiEnroll, the following provider-specific configuration parameters are required:

  • NAME - Name of identity provider.
  • CLIENT_ID - Identity provider client identifier.
  • REDIRECT_URI - Authentication resource location.
  • DATA - Provider-specific data such as “tenant_id” or “domain_name”.

For information on how to obtain these values for supported providers, see the following:

All provider configurations used by YubiEnroll are stored in a single TOML file located at

%APPDATA%\yubienroll\yubienroll.toml

This expands by default to

C:\Users\username\AppData\Roaming\yubienrolll\yubienroll.toml

where “username” is the user name of the current user. The file can be manually edited.

The following example shows a typical provider configuration file. The enrollment profile with the name profiles.default is configured to be used by both the providers, and its profile settings are displayed at the end of the file.

yubienroll.toml

active_provider = "entra”

[providers.entra]
provider = "ENTRA"
client_id = "78a1a…"
redirect_uri = "http://localhost/yubienroll-callback"
tenant_id = "220b41…"
profile = "default"

[providers.okta]
provider = "OKTA"
client_id = "0oahi…"
redirect_uri = "http://localhost:8080/yubienroll-callback"
domain = "domain.com"
profile = "default"

[profiles.default]
reset = true
min_pin_length = 4
override_always_uv = true
force_pin_change = true
random_pin = true

The active_provider setting shows the identity provider that will automatically be used when enrolling end users. In the previous example, the active provider is the one named “entra”. There can only be one active provider at the time.

If there are multiple providers configured for an environment, the user can change the active provider by using the command yubienroll providers activate name where “name” is the name of a configured identity provider.

In addition to activating providers, a user can also create, edit, and delete provider configurations. For more information, see YubiEnroll Commands.

Authentication and Authorization

The user (IT admin, enrollment administrator etc.) authenticates to the identity provider via the system’s default browser which is automatically launched by YubiEnroll during the login procedure. This includes entering the user’s account email, and presenting the YubiKey and PIN code associated with the user’s identity provider account.

During the login procedure an access token is obtained for the identity provider’s API. The access token lets YubiEnroll interact with the identity provider’s API to manage end user credentials. The required configuration to connect to the provider, for example tenant name and URL, are either set manually in the configuration file, or added through YubiEnroll.

YubiEnroll users can log in to the identity provider through the configured system options. Refer to the specific identity provider documentation for details. When setting up and using YubiEnroll, there are a set of user categories typically involved. The permissions for these are defined in the identity provider (Okta or Microsoft Entra).

The following are typical user categories and their tasks:

  • System administrator: An employee of an organization responsible for obtaining, installing and configuring the YubiEnroll application.
  • Enrollment administrator: An employee of an organization responsible for enrolling YubiKey credentials on behalf of their organization’s users. Can for example configure PIN code settings as required by the organization.
  • End user: An employee or contractor receiving an enrolled YubiKey to be used to authenticate with services. Might have been granted permission to reset, change the PIN code and/or enroll additional keys for themself as a self-service.
  • Auditor: An employee of the organization or an external contractor responsible for inspection of logs for audit purposes. Will only have read access to the logs.