# Configure Microsoft Entra ID sign-in

Connect your Microsoft Entra ID tenant to your ATLAS organisation so people sign in with their Microsoft account. You register the application in Entra, and ilionx enters the values you collect on the ATLAS side.

To let Entra security groups decide who is an Admin or Member, continue with [Map Entra groups to ATLAS roles](https://docs.atlas.ilionx.dev/guides/admin/identity-and-access-map-entra-groups-to-roles.md). To also create, update and remove members automatically, see [Provision members with SCIM](https://docs.atlas.ilionx.dev/guides/admin/identity-and-access-provision-members-with-scim.md).

## Before you begin

- **Set up by ilionx:** your ilionx contact has set up your organisation for Microsoft Entra sign-in, with its email domains. They've also sent you the **Broker Callback URL**. Microsoft sends people back to ATLAS at this address after they sign in. Entra needs it as the **Redirect URI**. It looks like `https://<auth-host>/realms/<realm>/broker/<alias>/endpoint`, where `<auth-host>` is the address of ATLAS's sign-in service. Use the exact value you received instead of building it yourself. It must match character for character.
- **In Entra:** you need the **Application Administrator** or **Cloud Application Administrator** role to create an app registration and add a client secret.

## Connect sign-in

1. In the [Microsoft Entra admin center](https://entra.microsoft.com), go to **Identity** > **Applications** > **App registrations** > **New registration**.
2. Name the registration, for example "ATLAS sign-in". Keep the supported account types as single tenant unless your organisation needs otherwise. Set the platform to **Web**.
3. Set the **Redirect URI** to the **Broker Callback URL** you received from your ilionx contact.
4. Select **Register**.
5. Go to **Certificates & secrets** > **Client secrets** > **New client secret**. Note the **expiry date**. When the secret expires, sign-in stops until your ilionx contact saves a new one in ATLAS. Create the replacement about 2 weeks before the expiry date. See [Replace the client secret](https://docs.atlas.ilionx.dev/guides/admin/identity-and-access-configure-entra-sign-in.md#replace-the-client-secret).
6. Go to **API permissions** and confirm the delegated Microsoft Graph permissions `openid`, `profile` and `email` are present. Add them if they're missing.
7. From the registration's **Overview** page, note the **Directory (tenant) ID** and **Application (client) ID**. Note the client secret value too, because Entra shows it only once.
8. Send the **Directory (tenant) ID**, the **Application (client) ID** and the client secret value to your ilionx contact over a secure channel.
9. ilionx enters the values in ATLAS.

**Result:** your ilionx contact confirms that the connection is set up. Sign in as a test user from your tenant to confirm the round trip.

## Replace the client secret

1. In Entra, create a **new** client secret on the app registration before the old one expires. Start about 2 weeks ahead, so there's time for the hand-over.
2. Send the new secret value to your ilionx contact over a secure channel. They save it in ATLAS.
3. Confirm that sign-in works.
4. Delete the old secret in Entra.

> [!WARNING]
> **Replace before expiry**
>
> If the old secret expires first, nobody in the organisation can sign in until the new secret is saved in ATLAS.

## Troubleshooting

| Symptom                                                      | Cause and remedy                                                                                                                                                                                        |
| ------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Sign-in stopped working for everyone                         | The client secret has expired. Send a new one to your ilionx contact, as in [Replace the client secret](https://docs.atlas.ilionx.dev/guides/admin/identity-and-access-configure-entra-sign-in.md#replace-the-client-secret).                                                                    |
| Your ilionx contact reports that setup failed                | Check the tenant ID, client ID and secret you sent, and send corrected values.                                                                                                                          |
| A user is told they are not assigned to the application      | **Assignment required?** is on and the person is in no assigned group. See [Restrict sign-in to assigned groups](https://docs.atlas.ilionx.dev/guides/admin/identity-and-access-map-entra-groups-to-roles.md#restrict-sign-in-to-assigned-groups). |
| A person is told they already belong to another organisation | A person can belong to only one ATLAS organisation. This commonly happens when an email domain spans several customers.                                                                                 |

## Related

- [Map Entra groups to ATLAS roles](https://docs.atlas.ilionx.dev/guides/admin/identity-and-access-map-entra-groups-to-roles.md)
- [Provision members with SCIM](https://docs.atlas.ilionx.dev/guides/admin/identity-and-access-provision-members-with-scim.md)
- [Identity and access](https://docs.atlas.ilionx.dev/concepts/identity-and-access.md)