.. commands.rst .. _commands: ========================== YubiEnroll Commands ========================== The following describes commands available when using the YubiEnroll CLI, together with usage examples. For more examples of how to add providers and enrollment profiles and enroll end users, see :ref:`using-cli`. yubienroll ============ ``yubienroll [OPTIONS] COMMAND [ARGS]...`` Run ``yubienroll`` at the command prompt to see available options and commands. **Options** .. table:: +--------------------------------------+---------------------------------------------------------------+ | Option | Description | +======================================+===============================================================+ |``-l, - -log-level | | Enable logging at given verbosity level. | |[ERROR|WARNING|INFO|DEBUG|TRAFFIC]`` | | | +--------------------------------------+---------------------------------------------------------------+ |``--log-file FILE`` |Write logs to a specified FILE. | +--------------------------------------+---------------------------------------------------------------+ |``-v, --version`` |Show version information about the app. | +--------------------------------------+---------------------------------------------------------------+ |``-h, --help`` |Show this message and exit. | +--------------------------------------+---------------------------------------------------------------+ **Commands** .. table:: +---------------------------------+-------------------------------------------------------------+ | Command | Description | +=================================+=============================================================+ | ``credentials`` | Manage FIDO credentials for users. | +---------------------------------+-------------------------------------------------------------+ | ``login`` | Authenticate to the active provider. | +---------------------------------+-------------------------------------------------------------+ | ``logout`` | Logout from the active provider. | +---------------------------------+-------------------------------------------------------------+ | ``profiles`` | Manage enrollment profiles. | +---------------------------------+-------------------------------------------------------------+ | ``providers`` | Manage authentication settings for identity providers. | +---------------------------------+-------------------------------------------------------------+ | ``status`` | Show which provider is active and its authentication status.| +---------------------------------+-------------------------------------------------------------+ | ``users`` | Search for users. | +---------------------------------+-------------------------------------------------------------+ yubienroll login =================== ``yubienroll login [OPTIONS] COMMAND [ARGS]...`` Authenticate to the active provider. Starts a web-based authentication flow to get access credentials for the user account. **Examples** * Show supported identity providers to select and log in to the desired one. ``> yubienroll login`` * Use ``--no-launch-browser`` if you do not want the command to launch the default system browser. This prints the authorization URL in the terminal so you can manually open the URL in a desired browser. ``> yubienroll login --no-launch-browser`` **Options** .. table:: +-------------------------------+------------------------------------+ | Option | Description | +===============================+====================================+ |``-h, --help`` | Show this message and exit. | +-------------------------------+------------------------------------+ |``--no-launch-browser`` | Do not open browser automatically. | +-------------------------------+------------------------------------+ **Commands** .. table:: +---------------------------+-----------------------------------------+ | Command | Description | +===========================+=========================================+ |``login`` | Authenticate with an identity provider. | +---------------------------+-----------------------------------------+ yubienroll logout =================== ``yubienroll logout [OPTIONS] COMMAND [ARGS]...`` Log out the YubiEnroll user from the active identity provider. .. note:: This command is currently only supported for the Okta identity provider. **Options** .. table:: +-------------------------------+------------------------------------+ | Option | Description | +===============================+====================================+ |``-h, --help`` | Show this message and exit. | +-------------------------------+------------------------------------+ **Commands** .. table:: +---------------------------+-----------------------------------------+ | Command | Description | +===========================+=========================================+ |``logout`` | Logout from the active provider. | +---------------------------+-----------------------------------------+ .. _command-credentials: yubienroll credentials ======================== ``yubienroll credentials [OPTIONS] COMMAND [ARGS]...`` Lets users enroll, list and delete credentials on behalf of an end user. Subcommands require a ``User_ID``, which can be the ID or username for an end user. Use the ``yubienroll users [query]`` command to get these values, see :ref:`command-users`. **Options** .. table:: +---------------------------+----------------------------------+ | Option | Description | +===========================+==================================+ |``-h, --help`` | Show this message and exit. | +---------------------------+----------------------------------+ **Commands** .. table:: +---------------------------+-----------------------------------------------+ | Command | Description | +===========================+===============================================+ |``add`` | Enroll a FIDO credential on behalf of a user. | +---------------------------+-----------------------------------------------+ |``delete`` | Delete a FIDO credential for a user. | +---------------------------+-----------------------------------------------+ |``list`` | List FIDO credentials for a user. | +---------------------------+-----------------------------------------------+ yubienroll credentials add --------------------------- ``yubienroll credentials add [OPTIONS] USER_ID`` Add credentials on behalf of an end user enrolling them with the identity provider. ``User_ID`` is the ID or username for an end user. Use the ``yubienroll users [query]`` command to get these values, see :ref:`command-users`. The ``yubienroll credentials add`` command creates a FIDO credential on the YubiKey and registers it with the identity provider for the specified user. You can configure YubiKey settings, for example minimum PIN code length or force PIN code change on first use, either through the CLI options or by using an enrollment profile. This can be specified with the ``--profile`` option or automatically applied if assigned to the active provider. If not specified, the enrollment profile associated with the active identity provider will be applied. If no authenticator settings or enrollment profile exist, you will be prompted to provide these. **Examples** * Add credentials and enroll end user with ``user_ID`` "firstname.lastname@email.com". ``> yubienroll credentials add firstname.lastname@mail.com`` * Apply a different (configured) enrollment profile than the one used by the active provider. ``> yubienroll credentials add firstname.lastname@email.com --profile another-profile`` **Options** .. table:: +----------------------------------+----------------------------------------------------+ | Option | Description | +==================================+====================================================+ |``-r, --reader NAME`` | Enroll a FIDO credential on behalf of a user. | +----------------------------------+----------------------------------------------------+ |``-p, --profile TEXT`` | Delete a FIDO credential for a user. | +----------------------------------+----------------------------------------------------+ |``--min-pin-length INTEGER RANGE``| Set the minimum length allowed for PIN [4<=x<=63]. | +----------------------------------+----------------------------------------------------+ |``--require-always-uv`` | Require always UV. | +----------------------------------+----------------------------------------------------+ |``--no-require-always-uv`` | Do not require always UV. | +----------------------------------+----------------------------------------------------+ |``--force-pin-change`` | Force PIN change before use. | +----------------------------------+----------------------------------------------------+ |``--no-force-pin-change`` | Do not force PIN change before use. | +----------------------------------+----------------------------------------------------+ |``--reset`` | Factory reset and re-initialize key. | +----------------------------------+----------------------------------------------------+ |``--no-reset`` | Do not factory reset and re-initialize key. | +----------------------------------+----------------------------------------------------+ |``--random-pin`` | Set a new random PIN. | +----------------------------------+----------------------------------------------------+ |``--no-random-pin`` | Do not set a new random PIN. | +----------------------------------+----------------------------------------------------+ |``-h, --help`` | Show this message and exit. | +----------------------------------+----------------------------------------------------+ yubienroll credentials delete ------------------------------- ``yubienroll credentials delete [OPTIONS] CREDENTIAL_ID`` Delete credentials available in the identity provider for an end user. **Examples** * Delete credentials in the identity provider for the end user with ``credential_ID`` “123XYZ”. ``> yubienroll credentials delete 123XYZ`` yubienroll credentials list ------------------------------- ``yubienroll credentials list [OPTIONS]`` List credentials available in the identity provider for an end user. **Examples** * List available credentials for end user with user_ID "firstname.lastname@email.com”. ``> yubienroll credentials list firstname.lastname@email.com`` .. _command-profiles: yubienroll profiles ======================== ``yubienroll profiles [OPTIONS] COMMAND [ARGS]...`` Manage enrollment profiles for an identity provider. Profiles are presets of configuration parameters used when enrolling credentials. You can for example edit profile settings or delete the profile from the provider configuration. Deleting an enrollment profile will remove it from any provider using it. **Examples** * Add an enrollment profile with the name “standard” to the (active) provider. ``> yubienroll profiles add standard`` * Show enrollment profiles available for the provider. ``> yubienroll profiles list`` * To unset a profile from a provider, run the following command and select “0”. ``> yubienroll profiles edit `` **Options** .. table:: +---------------------------+----------------------------------+ | Option | Description | +===========================+==================================+ |``-h, --help`` | Show this message and exit. | +---------------------------+----------------------------------+ **Commands** .. table:: +---------------------------+-----------------------------------------------+ | Command | Description | +===========================+===============================================+ |``add`` | Create a new profile. | +---------------------------+-----------------------------------------------+ |``delete`` | Delete a profile. | +---------------------------+-----------------------------------------------+ |``edit`` | Modify an existing profile. | +---------------------------+-----------------------------------------------+ |``list`` | List profiles. | +---------------------------+-----------------------------------------------+ yubienroll providers ======================== ``yubienroll providers [OPTIONS] COMMAND [ARGS]...`` Manage authentication configurations stored in named provider objects for identity providers. You can add, activate, or delete authentication configurations. The active provider is the provider and tenant with which YubiEnroll communicates. Only one provider at the time can be active. .. note:: If there are no existing provider configurations and you add one, YubiEnroll will automatically activate it. To explicitly activate a provider, use ``yubienroll providers activate``. An active provider configuration can be deleted. **Examples** * Add a provider configuration with the name “entra”. ``> yubienroll providers add entra`` * Show the configuration for the provider with the name “entra”. ``> yubienroll providers show entra`` **Options** .. table:: +---------------------------+----------------------------------+ | Option | Description | +===========================+==================================+ |``-h, --help`` | Show this message and exit. | +---------------------------+----------------------------------+ **Commands** .. table:: +---------------------------+-------------------------------------------------------+ | Command | Description | +===========================+=======================================================+ |``activate`` | Select which provider to use for other commands. | +---------------------------+-------------------------------------------------------+ |``add`` | Create a new provider configuration. | +---------------------------+-------------------------------------------------------+ |``delete`` | Delete a provider configuration. | +---------------------------+-------------------------------------------------------+ |``edit`` | Modify an existing provider configuration. | +---------------------------+-------------------------------------------------------+ |``list`` | List all provider configurations. | +---------------------------+-------------------------------------------------------+ |``show`` | Show full provider configuration. | +---------------------------+-------------------------------------------------------+ yubienroll status ======================== ``yubienroll status`` Shows the name of the active provider configuration (used by default when enrolling end users), the identity provider used, and whether the user is authenticated with the provider or not. .. _command-users: yubienroll users ======================== ``yubienroll users [OPTIONS] COMMAND [ARGS]...`` When enrolling an end user, you will need the user identifiers "ID" and "Username". Often “Username” is the same as the email address in the identity provider, but it does not have to be. You can search for users in the identity provider using the ``yubienroll users `` command where "query" can be for example the name of the end user. The user identifier "ID" and "Username" will be returned which is used in the enrollment. **Examples** * Search for an end user with the name “firstname lastname” in the identity provider. If no query is specified, all users are returned. ``> yubienroll users firstname lastname`` .. note:: When searching for a user in Okta, either enter the ``firstname + lastname`` or the ``primary email`` address as search criteria to retrieve the desired results. For more information, see :ref:`okta-user-search`. **Options** .. table:: +---------------------------+----------------------------------+ | Option | Description | +===========================+==================================+ |``-h, --help`` | Show this message and exit. | +---------------------------+----------------------------------+ **Commands** .. table:: +---------------------------+-----------------------------------------+ | Command | Description | +===========================+=========================================+ |``users`` | Search for users. | +---------------------------+-----------------------------------------+