.. config-entra.rst


.. _config-entra-id:

==============================
Configuring Microsoft Entra ID
==============================

In this step you will configure Microsoft Entra ID for authentication and authorization management. 

To complete all configuration steps described in this section, the following roles are required: 

* *Application Administrator*
* *Authentication Policy Administrator*
* *Global Administrator*
* *Privileged Role Administrator*


Enabling Passkey (FIDO2) Authentication
=========================================

In this step you will configure the authentication methods policies used in Microsoft Entra ID.

.. note:: To complete these configuration steps you must have either the Authentication Policy Administrator or the Global Administrator role.

To configure the Microsoft Entra ID policies to allow the use of YubiKeys, do the following:

1. Log in to the `Microsoft Entra admin center <https://entra.microsoft.com/>`_ with *at least the Authentication Policy Administrator* role.
2. Go to **Protection > Authentication methods > Policies**.
3. Under the method **Passkey (FIDO2)**, set the toggle to “Enable”. Select “All users” or “Add groups” to select specific groups. Only security groups are supported (you cannot use dynamic groups or individual users).
4. **Save** the configuration.

The **Configure** tab has additional settings to control the type of passkeys supported in the customer tenant, and their registration requirements:

* **Allow self-service set up:** Must be set to “Yes”. If this is disabled, YubiKeys cannot be registered, not even using administrative registration processes.

* **Enforce attestation:** Recommended setting “Yes”. Using cryptographic evidence attestation ensures that registered authenticators are genuine YubiKeys and not fraudulent products or low-assurance passkey credentials (which might not be able to support attestation).

* **Enforce key restrictions:** Recommended setting “Yes”. This lets your organization  allowlist specific YubiKey models by their associated Authenticator Attestation GUID (AAGUID). For more information, see `YubiKey hardware FIDO2 AAGUIDs <https://support.yubico.com/hc/en-us/articles/360016648959-YubiKey-hardware-FIDO2-AAGUIDs>`_.

.. important:: If security keys such as device-bound passkeys or other types of passkeys are already used in your Microsoft Entra ID environment, ensure that these configuration changes do not break the sign-in for existing users.

For more information, see `Enable passkeys (FIDO2) for your organization (Microsoft documentation) <https://learn.microsoft.com/en-us/entra/identity/authentication/how-to-enable-passkey-fido2#passkey-optional-settings>`_.


.. _register-apps:

Registering Apps
===================

In this step you will register the Yubico FIDO Connector App and the Yubico FIDO Pre-reg Test Client (optional).

An app must be registered to allow the app itself to connect to the Microsoft Graph API, and to allow other clients such as Entra ID IGA, test clients, ServiceNow and other custom applications, to connect to the app to invoke requests.

It is recommended that any forms, processes, and workflows used to call the Yubico FIDO Connector App follow a similar registration pattern with distinct credentials as described in the following.

.. note:: Most of the registration steps can be performed by an admin user with the *Application Administration* role. However, to complete some steps a user with the *Global Administrator* role is required as indicated in the procedure.


Yubico FIDO Connector App
----------------------------

To register the Yubico FIDO Connector App, do the following:

1. Log in to the `Microsoft Entra admin center <https://entra.microsoft.com/>`_ and go to **Applications** > **App registrations**.
2. Click **+ New registration**.
3. Provide a descriptive name, for example “Yubico FIDO Pre-reg Service”, and click **Register**.
4. Under **Manage**, click **API permissions**.
5. Click **+ Add a permission**.
6. Select "Microsoft Graph".
7. Click **Application permissions**.
8. Search for “UserAuthMethod-Passkey.ReadWrite.All” and select the permission.
9. Click **Add permissions**.
10. Next to the list of permissions, select “Grant admin consent for {tenant name}”.
      
    .. note:: The *Global Administrator* role is required for this step.
      
11. Under **Manage**, click **Expose an API**. 
12. Click **Add** next to the **Application ID URI**.
13. Edit the **Application ID URI** to a value like “api://fido-connector-api.{verified domain name}.

    * The verified domain name can be either a custom domain that has been verified by the tenant, or you can use the default domain that ends with “.onmicrosoft.com”.
    * The Application ID URI represents the scope that clients will use when authenticating to call the API. This value will be populated as an ARM template parameter ``FIDO_Connector_Allowed_Audiences``. The URI does not need to be resolvable, but should have a descriptive scope name.

14. Click **+ Add a scope** and set the following:

    * **Scope name:** “create_request”
    * **Display name fields:** “create_request”
    * **Description fields:** “Allows Yubico FIDO Pre-reg requests”

15. Click **Add scope**.
16. Under **Manage**, click **Certificates & secrets**.
17. Click **+ New client secret**.
18. Provide a name for your client secret and accept the recommended expiration.
19. Click **Add**.
20. Copy the client secret. This will be used in the ARM template as ``FIDO_Connector_Client_Secret``.
21. Go to **Overview** and copy the **Application (client) ID** value. This will be used in the ARM template as ``FIDO_Connector_Client_Id.``

For more information, see `Register an application with the Microsoft identity platform (Microsoft documentation) <https://learn.microsoft.com/en-us/entra/identity-platform/quickstart-register-app?tabs=certificate>`_.


Yubico FIDO Pre-reg Test Client
---------------------------------

Registering this app is *optional*. However, the app is useful when testing direct calls to the Yubico FIDO Connector App. The application credentials created here can be used in a Postman test client or any other HTTP test client when testing the app deployment.

To register the Yubico FIDO Pre-reg Test Client app, do the following:

1. Log in to the `Microsoft Entra admin center <https://entra.microsoft.com/>`_ and go to **Applications** > **App registrations**.
2. Click **+ New registration**.
3. Provide a descriptive name like “Yubico FIDO Pre-reg Test Client” and click **Register**.
4. Under **Manage**, click **Certificates & secrets**.
5. Click **+ New client secret**.
6. Provide a name for your client secret and accept the recommended expiration.
7. Click **Add**.

The app credentials you created here will be used later when testing the app deployment. For more information, see :ref:`testing`.