.. use-cli.rst


.. _using-cli:


==========================
Using YubiEnroll CLI
==========================

The following describes examples of how to work with the YubiEnroll CLI. The examples reference the default installation path. If you choose a different installation path, update the command to point to the path you used. For more information, see also :ref:`commands`. 

.. note:: Due to Windows restrictions, many commands will require administrator privileges. To avoid running the YubiEnroll CLI tool as administrator, the tool itself will prompt for elevation when needed through the Windows user account control (UAC) prompt. Launching the YubiEnroll CLI tool as administrator is not recommended.

Launching on Windows
======================

Open a terminal, for example Windows PowerShell, navigate to the installation path (default is ``C:\Program Files\Yubico\YubiEnroll\``) and run ``yubienroll.exe`` to see the usage, options, and commands that may be used. Then run the YubiEnroll commands from the command prompt.

.. _idp-config-add:

Adding Provider Configurations
===============================

The following describes how to add an identity provider configuration and an enrollment profile. The example uses identity provider Microsoft Entra, but the procedure is similar for Okta. In this example we assume you log in to YubiEnroll for the first time, and no providers or enrollment profiles exist. However, you can add providers and enrollment profiles at any time.

.. note:: When adding a provider configuration, you will need to provide identity provider-specific input values for "Client ID", "Redirect URI", and "Tenant/Domain ID". For information on how to obtain these values, see :ref:`idp-config`.

The ``yubienroll providers add`` command adds a provider configuration of a supported type (Okta or Microsoft Entra). If no provider configuration exists and you choose to add one, this will automatically be activated and will be the default provider used when enrolling end users. 

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

To add a provider configuration and an enrollment profile, do the following:

1. In the terminal, run ``yubienroll providers add entra`` where “entra” is the provider name in this example (you can choose a name of your choice).
2. Select the desired provider type, “ENTRA” (1) in this example. 
3. Enter the **Client ID**, **Redirect URI**, and **Microsoft Entra Tenant ID** when prompted. For provider-specific input values, see :ref:`idp-config`. 
4. When prompted to specify if you want to add a new enrollment profile [y/N], enter “y”.
5. Enter the following when prompted:

   a. **Profile name [default]** - the name to be used for the profile. In this example, the profile is named "entra-main". If you do not enter a name, “default” will be used. 
   b. **Min PIN length [4]** - enter the desired PIN code length, for example 6. If you do not enter a PIN code length, the value “4” will be used. Note that the minimum PIN code length can never be shorter than “4”.
   c. **Require always UV? [y/N]** - define if the “Always require user verification” setting should always be overridden. Default is “no”.
   d. **Force PIN change before use? [y/N]** - Define if the end user must change the PIN code when using the YubiKey for the first time. Default is “no”.
   e. **Factory reset the Security Key? [Y/n]** - Enter “n” if you will be enrolling a new key. Enter “y” if you will be enrolling a key that has previously been in use. This option will clear the key completely from previous configurations.
   f. **Set a new random PIN [Y/n]** - Enter “y” if you want YubiEnroll to set a new PIN code for the key. Enter “n” if you want to specify a specific PIN code.

6. The provider configuration is added together with the enrollment profile. Because no provider existed previously, the “entra” provider is automatically activated.

   .. image:: graphics/add-provider-config1.png
      :width: 800

7. To check provider and authentication status and see available enrollment profiles you can run ``yubienroll status`` and ``yubienroll profiles list``.

   .. image:: graphics/status-list-profiles.png
      :width: 800

For more information about the ``yubienroll providers`` command, see :ref:`commands`.


.. _enrollment-profile-create:

Creating Enrollment Profiles
=============================

The following describes how to create and add an enrollment profile. You can add an enrollment profile at the same time when you add an identity provider to YubiEnroll. You can also add an enrollment profile at a later occasion and assign this to the active provider.

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

To create an enrollment profile for a provider, do the following:

1. In the terminal, run ``yubienroll profiles add entra-reset`` where “entra-reset” is the profile name in this example (you can choose a name of your choice).
2. Enter the following when prompted:
   
   a. **Min PIN length [4]** - Enter the desired PIN code length, for example 6. If you do not enter a PIN code length, the value “4” will be used.
   b. **Require always UV? [y/N]** - Define if the “Always require user verification setting” should always be overridden. Default is “no”.
   c. **Force PIN change before use? [y/N]** - Define if the end user must change the PIN code when using the YubiKey for the first time. Default is “no”.
   d. **Factory reset the Security Key? [Y/n]** - Enter “n” if you will be enrolling a new key. Enter “y” if you will be enrolling a key that has previously been in use. This option will clear the key completely from previous configurations.
   e. **Set a new random PIN [Y/n]** - Enter “y” if you want YubiEnroll to set a new PIN code for the key. Enter “n” if you want to specify a specific PIN code.
   f. **Assign this profile to the active provider (entra)? [y/N]** - Enter “y” to replace the enrollment profile that is currently assigned to the active provider with the one you are creating. Enter “n” to keep the current enrollment profile for the active provider.

3. The new enrollment profile is stored.

   .. image:: graphics/add-profile.png
      :width: 800

For more information about the ``yubienroll profiles`` command, see :ref:`commands`.

Enrolling End Users
======================

The following describes how to enroll a YubiKey adding credentials on behalf of a specific end user. Ensure you have the YubiKey you want to enroll available, as well as the “ID” or “Username” of the end user. For information on how to find an end user identifier, see the command :ref:`command-users`.

.. note:: To enroll YubiKeys on behalf of end users, you need to be an administrator with IDP-specific permissions. For more information, see the Configuring Permissions section for the IDP you are using.

To enroll a YubiKey on behalf of an end user, do the following:

1. In the terminal, run ``yubienroll login`` to authenticate with the identity provider.
2. Select the desired provider, “ENTRA” (1) in this example.
3. When prompted, confirm the **Client ID**, **Redirect URI**, and **Tenant ID** for the active provider to continue. For information on how to obtain these values for a provider, see :ref:`idp-config`.
4. Follow the steps to complete the authentication. When successfully authenticated, return to the terminal.

   .. image:: graphics/login-success.png
      :width: 500

5. Insert or present the YubiKey you want to enroll.
6. Run the command ``yubienroll credentials add firstname.lastname@email.com`` where "firstname.lastname@email.com” is the end users’ account identifier in this example.
7. YubiEnroll fetches the provider-specific options for creating credentials, and the settings for the enrollment profile to be used are displayed. To use a different enrollment profile than the one assigned to the active provider, see the command :ref:`command-profiles`. In this example, the key is reset before the credentials are added.
8. When prompted, touch the YubiKey you are enrolling.
9. When prompted, enter “y” to proceed with the configuration.
10. When the credentials have been successfully added, the serial number and temporary PIN code to be used is displayed.

   .. image:: graphics/credentials-add1.png
      :width: 800

11. Provide the YubiKey and the temporary PIN code to the end user.
12. To authenticate with identity provider (Microsoft Entra in this example), the end user presents the provided YubiKey and the temporary PIN code. If the “Force PIN change” was set to “On”, the end user is prompted to change the PIN code upon first log in.

   .. image:: graphics/login-pin-reset.png
      :width: 400

For more information about the ``yubienroll credentials`` command, see :ref:`command-credentials`.