.. yubienroll-entra.rst


.. _entra-config:

================================
YubiEnroll with Microsoft Entra
================================

The following describes how to set up YubiEnroll in the Microsoft Entra tenant and configure the required user permissions.

Configuration Steps 
====================

The configuration steps involve the following:

* :ref:`Enabling multi-factor authentication for YubiKeys in Microsoft Entra <entra-mfa-enable>`.
* :ref:`Registering the YubiEnroll application in Microsoft Entra <entra-register>`. 
* :ref:`Configuring the YubiEnroll permissions in Microsoft Entra <entra-permissions>`. 
* :ref:`Adding the Microsoft Entra provider in YubiEnroll <entra-add>`.

When you have successfully completed these steps, you are ready to :ref:`enroll YubiKeys on behalf of end users in your organization <using-cli>`.


.. _entra-mfa-enable:

Enabling MFA for YubiKeys
=================================================

Ensure that Entra ID Multi-Factor authentication (MFA) for Passkey (FIDO2) is enabled and that the target user accounts for YubiEnroll enrollment are in the scope.

To enable MFA for target user accounts, log in to the `Entra admin center <https://entra.microsoft.com/>`_ and go to **Identity** > **Protection** > **Authentication methods** > **Policies** > **Passkey (FIDO2)**.

Enable the feature and either select all users, or select groups to be in the scope for YubiEnroll enrollment. For more information on configuring FIDO authentication with YubiKeys in Entra ID, see `Enable passkeys (FIDO2) for your organization (Microsoft documentation) <https://learn.microsoft.com/en-us/entra/identity/authentication/how-to-enable-passkey-fido2>`_.

.. image:: graphics/entra-mfa-enable.png
   :width: 600


.. _entra-register:

Registering the YubiEnroll App
=================================

When configuring the Microsoft Entra provider in YubiEnroll, the following parameter values are needed:

* ``client_id``
* ``tenant_id``
* ``redirect_uri``

These parameter values are created when registering the YubiEnroll (OAuth) application in Microsoft Entra. To register the YubiEnroll app, log in to the `Entra admin center <https://entra.microsoft.com/>`_, go to **Application > App registrations** and select **New registration**. 

When registering the YubiEnroll app, ensure the following:

* Select **Public client/native (mobile & desktop)** as the platform type. 
* The **Redirect URI** must start with “http://localhost”, for example “http://localhost/yubienroll-redirect”. You do not need to specify the port as Microsoft Entra supports ephemeral ports.

   .. image:: graphics/entra-register-app.png
      :width: 800

For more details on how to register the YubiEnroll app, see `Register an application with the Microsoft identity platform (Microsoft documentation) <https://learn.microsoft.com/en-us/graph/auth-register-app-v2>`_.


.. _entra-permissions:

Configuring Permissions 
========================

The YubiEnroll app requires the following two permissions in Microsoft Entra to be added as *Microsoft Graph Delegated permissions*:

* *User.ReadBasic.All*
* *UserAuthenticationMethod.ReadWrite.All*

To add these, open the YubiEnroll app in Microsoft Entra, select **API permissions** in the left menu, and click **Add a permission**.  

   .. image:: graphics/entra-permissions.png
      :width: 800

.. note:: When registering an app in Entra ID, two types of Microsoft Graph permissions can be assigned: *Application* and *Delegated*. For YubiEnroll it is crucial to only configure *Delegated* permissions to ensure that the app’s access is limited to the logged in user's permissions.

When combined with the Entra ID feature “Administrative units”, this setup allows for fine-grained control of access based on groups, users, or specific properties such as location. An example where this can be leveraged is where an administrator could be allowed to manage YubiKey enrollments only for users in their administrative unit. To review permissions granted to a registered app, check the **Type** settings under **API permissions** for the app.

For a user to be able to grant consent to these permissions when setting up the application in Entra ID, the user must be assigned the *Global Administrator* role.

For more information about app permissions, see `Overview of Microsoft Graph permission (Microsoft documentation) <https://learn.microsoft.com/en-us/graph/permissions-overview?tabs=http>`_.

The following applies when configuring permissions:

* *Authentication Administrator* role is required for managing passkeys of non-administrators.
* *Privileged Authentication Administrator* role is required for managing passkeys for any type of user including Global Administrators.

.. note:: Even with the *Privileged Authentication Administrator* role, the administrator will not be able to use YubiEnroll to manage passkeys for their own profile.

For more information, see `Authentication Administrator (Microsoft documentation) <https://learn.microsoft.com/en-us/entra/identity/role-based-access-control/permissions-reference#authentication-administrator>`_ and `Privileged Authentication Administrator (Microsoft documentation) <https://learn.microsoft.com/en-us/entra/identity/role-based-access-control/permissions-reference#privileged-authentication-administrator>`_.



.. _entra-add:

Adding the Microsoft Entra Provider
=====================================

Before you can run YubiEnroll with Microsoft Entra, you must add the provider configuration in YubiEnroll. 

When adding a provider configuration in YubiEnroll you will need the following values, created when the :ref:`app was registered <entra-register>`.

* Application (client) ID 
* Directory (tenant) ID 
* Redirect URI 

To find these values in Microsoft Entra, locate the YubiEnroll app and select **Overview**. The values are displayed in the **Essentials** section for the app. 

For information on how to add a provider configuration in YubiEnroll, see :ref:`idp-config-add`.