# Microsoft Entra ID identity provider integration

You can integrate your Microsoft Entra ID identity provider (IdP) with Axiad
Mesh to ensure that your users are securely signing in to the portal.

The integration requires updates on both Entra ID and Axiad Mesh.

## Entra ID configuration steps

> **warning**

These steps are Axiad's current understanding of the configuration. Because
Entra ID is a third-party product, there may be slight variations between your
experience and what this guide describes. We work hard to keep things as up to
date as possible, but depending on the versions in use, the latest updates, and
so on, there may be some mismatches.

If you find any significant differences or anything that doesn't make sense,
contact Axiad support so we can update this guide.

> **note**

The Entra ID steps are similar for both integrations with Axiad Mesh — as an
IdP and as a [connector](../../connectors/idp/microsoft-entra-id.mdx). However, it's important
that each integration type has its own enterprise application in Entra ID to
ensure that the permissions are assigned accordingly.

### Create a new enterprise application

1. Sign in to the Microsoft Entra admin center as at least a Cloud Application
   Administrator.
2. Navigate to **Identity > Enterprise applications**.
3. Select **New application**.
4. On the **Browse Microsoft Entra Gallery** page, select **Create your own
   application**.
5. In the **Create your own application** pane, set the **Name** to a friendly
   name.
6. Select **Register an application to integrate with Microsoft Entra ID (App
   you're developing)**.
7. Select **Create**.

   ![Create your own application pane in the Microsoft Entra admin center](/img/imported/microsoft-entra-id-idp-integration/entra-create-new-app.png)

8. On the **Register an application** page, set the **Name** to the friendly
   name.
9. Select **Accounts in this organizational directory only (Single tenant)**.
   The option label includes your directory name, for example *Eagle 101 only -
   Single tenant*.

   :::tip[Axiad recommendation]

   We recommend that you create and test the integration with Axiad Mesh using
   a single tenant. Upon success, you can then change this setting to a
   multitenant environment as needed.

   :::

10. Select **Register**.

    ![Register an application page with the single-tenant account type selected](/img/imported/microsoft-entra-id-idp-integration/entra-register-app.png)

### Configure application properties

1. In the Entra admin center, navigate to **Identity > Enterprise
   applications > All applications**.
2. Locate and open your newly created application.
3. Under **Manage** in the menu, select **Properties**.
4. Select **Yes** for **Enabled for users to sign-in?**.
5. Select **Yes** for **Assignment required?**.
6. Select **No** for **Visible to users?**.
7. Select **Save**.

   ![Application properties page with sign-in enabled, assignment required, and visibility disabled](/img/imported/microsoft-entra-id-idp-integration/entra-app-properties.png)

8. Copy the **Application ID** — you need it for the Axiad Mesh configuration
   steps.

### Configure application owners

1. In the Entra admin center, navigate to **Identity > Applications >
   Enterprise applications > All applications**.
2. Locate and open your newly created application.
3. Under **Manage** in the menu, select **Owners**.
4. In the **Owners** pane, search for and add the desired application owners.
5. After they're all added, select **Save**.

### Assign users and groups

1. In the Entra admin center, navigate to **Identity > Applications >
   Enterprise applications > All applications**.
2. Locate and open your newly created application.
3. Under **Manage** in the menu, select **Users and groups**.
4. Search for and select the application users and groups allowed to use Axiad
   Mesh.

   ![Users and groups page listing the groups assigned to the application](/img/imported/microsoft-entra-id-idp-integration/entra-app-groups.png)

5. After the users and groups are added, select **Save**.

### Generate a client secret

1. In the Entra admin center, navigate to **Identity > Applications >
   Enterprise applications > All applications**.
2. Locate and open your newly created application.
3. Under **Manage** in the menu, select **Single sign-on**.
4. On the **OIDC-based Sign-on** page, select **Go to application** in the
   **Configure application properties** section.
5. Under **Manage** in the menu, select **Certificates & secrets**.
6. Select **New client secret**.
7. On the **Add a client secret** page, provide a **Description**, set
   **Expires** to the expiration time, and then select **Add**.
8. After the secret is created, copy the **Value** from the **Certificates &
   secrets** page.

   :::warning[Important]

   You can only copy this value immediately after creating it, and it's
   required for the Axiad Mesh configuration steps. Be sure to copy this value
   now — you won't have another opportunity, and you would need to create a new
   client secret instead.

   :::

   ![Certificates and secrets page showing the newly created client secret value](/img/imported/microsoft-entra-id-idp-integration/entra-client-secret.png)

## Axiad Mesh configuration steps

> **note**

You can integrate your Entra ID IdP with Axiad Mesh in the initial onboarding
process as the primary IdP, or as a secondary IdP after you've configured
another IdP as the primary IdP.

For more information about the initial onboarding process, see the
[getting started guide](../../getting-started/index.md).

### Initial onboarding configuration

If you're adding Entra ID as your primary IdP during your initial onboarding,
complete the following steps.

1. After you open the access link from the Axiad Mesh welcome email, you're
   prompted to set up your primary IdP.
2. Set the **Domain** to the domain of your Entra ID environment.
3. Select **Microsoft Entra ID** from the **Provider** dropdown.
4. Set the **Microsoft Entra Tenant ID** to the **Tenant ID** of your Entra ID
   environment.
   [Learn how to locate your Tenant ID](https://learn.microsoft.com/en-us/entra/fundamentals/how-to-find-tenant).
5. Fill in the fields with the values copied in the Entra ID configuration
   steps:
   - Set the **Application (client) ID** to the **Application ID** value copied
     in [Configure application properties](#configure-application-properties),
     step 8.
   - Set the **Client secret value** to the **Value** copied in
     [Generate a client secret](#generate-a-client-secret), step 8.

   ![Primary IdP setup form with domain, provider, tenant ID, client ID, and client secret fields](/img/imported/microsoft-entra-id-idp-integration/onboarding-idp-form.png)

6. On the next screen, set the **Admin groups** based on which users you would
   like to be Axiad Mesh admins when signing in with Entra ID.

   :::warning[Entra ID group limitations]

   Only users that are in the groups included in the
   [Assign users and groups](#assign-users-and-groups) section can access Axiad
   Mesh. For any groups you add here, be sure that the users are members of any
   group limitations made in Entra ID.

   :::

   ![Admin groups step of the initial onboarding flow](/img/imported/microsoft-entra-id-idp-integration/onboarding-admin-groups.png)

7. Select **Continue**, and you're signed in to the Axiad Mesh portal for the
   first time.

### Secondary IdP configuration

If you already have your initial IdP connected and need to add a new one, or
you need to replace the existing one, you can connect your Entra ID IdP from
the Axiad Mesh administrative portal.

1. From the homepage, select the gear icon to open the **Settings** page.

   ![Axiad Mesh homepage with the settings gear icon highlighted](/img/imported/microsoft-entra-id-idp-integration/settings-gear.png)

2. Select **Identity providers** from the left menu and select **+ Add identity
   provider**.

   ![Identity providers settings page with the Add identity provider button](/img/imported/microsoft-entra-id-idp-integration/add-identity-provider.png)

3. On the **Add identity provider** page, set the **Domain** to the domain of
   your Entra ID environment.
4. Select **Microsoft Entra ID** from the **Provider** dropdown.
5. Set the **Microsoft Entra Tenant ID** to the **Tenant ID** of your Entra ID
   environment.
   [Learn how to locate your Tenant ID](https://learn.microsoft.com/en-us/entra/fundamentals/how-to-find-tenant).
6. Fill in the fields with the values copied in the Entra ID configuration
   steps:
   - Set the **Application (client) ID** to the **Application ID** value copied
     in [Configure application properties](#configure-application-properties),
     step 8.
   - Set the **Client secret value** to the **Value** copied in
     [Generate a client secret](#generate-a-client-secret), step 8.
7. Set the **Admin groups** based on which users you would like to be Axiad
   Mesh admins when signing in with Entra ID.

   :::warning[Entra ID group limitations]

   Only users that are in the groups included in the
   [Assign users and groups](#assign-users-and-groups) section can access Axiad
   Mesh. For any groups you add here, be sure that the users are members of any
   group limitations made in Entra ID.

   :::

   ![Add identity provider form filled out for Microsoft Entra ID](/img/imported/microsoft-entra-id-idp-integration/add-identity-provider-form.png)

8. After the fields are filled out, select **Test Connection**.
9. Upon a successful test, select **Add & Connect**.
10. After the setup completes, the new IdP is listed on the **Identity
    providers** page.

    ![Identity providers page listing the newly added Entra ID provider](/img/imported/microsoft-entra-id-idp-integration/identity-providers-list.png)