# Microsoft Entra ID
URL: /docs/reference/single-sign-on/microsoft-entra
LLM index: /llms.txt
Description: Let your team sign in with Microsoft Entra ID and manage their Limrun access from Entra.

# Microsoft Entra ID

Connect your Microsoft Entra tenant to Limrun with OIDC SSO. To manage organization membership from Entra, also configure SCIM through a non-gallery enterprise application. This setup does not require a Limrun gallery listing.

This guide uses two applications in your tenant: **Limrun SSO** for authentication and **Limrun SCIM** for provisioning. Keep their user and group assignments aligned.

## Prerequisites

- Admin access to the Limrun organization and DNS access for its email domains.
- Entra permissions to create app registrations, grant admin consent, manage credentials, assign users, and configure enterprise application provisioning.
- An Entra license that supports the provisioning and group assignment features you plan to use. Check [Microsoft's licensing guidance](https://learn.microsoft.com/en-us/entra/identity/app-provisioning/user-provisioning).
- Work email addresses populated in Entra that belong to a verified Limrun domain.

## Configure SSO

### Verify your domain in Limrun

1. Open [console.limrun.com](https://console.limrun.com) and go to **Settings > Domain Verification**.
2. Add the email domain your users sign in with.
3. Publish the TXT record shown in Limrun, then select **Verify DNS**.

Once you save an SSO connection, users with that verified domain must use **Continue with SSO**, including existing users. The separate Microsoft social sign-in flow does not satisfy the organization's SSO requirement.

### Register the SSO application

1. Open the [Microsoft Entra admin center](https://entra.microsoft.com) in your organization's tenant.
2. Go to **App registrations > New registration** and name the app `Limrun SSO`.
3. Select **Accounts in this organizational directory only**.
4. Add a **Web** redirect URI:

   ```text
   https://api.limrun.com/authn/oidc/callback
   ```

5. Register the application. Copy its **Application (client) ID** and **Directory (tenant) ID**.
6. Under **Certificates & secrets**, create a client secret and copy its **Value**. The secret ID is not the secret value. Record its expiration date so you can replace it in Limrun before it expires.

Use the Web platform and authorization code flow. Limrun does not need implicit grant enabled. For registration details, see [Microsoft's app registration guide](https://learn.microsoft.com/en-us/graph/auth-register-app-v2).

### Configure the email claim and assignments

1. In the app registration, open **Token configuration > Add optional claim**.
2. Select **ID**, add `email`, and save. If prompted, enable the permission needed to include the claim.
3. Confirm each assigned user's email is populated and belongs to a verified Limrun domain. The ID token must contain `email`; Limrun does not fall back to `preferred_username` or the user's principal name.
4. Open the corresponding **Limrun SSO** application under **Enterprise applications**. Under **Properties**, set **Assignment required?** to **Yes** and save.
5. Under **Users and groups**, assign the users or groups allowed to sign in, including the administrator configuring Limrun.
6. Return to the app registration's **API permissions**. Add Microsoft Graph delegated permissions for `openid`, `email`, and `profile`, then select **Grant admin consent** for your tenant. Assignment-required apps need admin consent before assigned users can sign in.

See Microsoft's guides to [optional claims](https://learn.microsoft.com/en-us/entra/identity-platform/optional-claims) and [assignment and consent](https://learn.microsoft.com/en-us/entra/identity/enterprise-apps/what-is-access-management).

### Save the Entra connection in Limrun

Open **Settings > Single Sign-On** and enter:

| Limrun field | Value |
|---|---|
| Issuer URL | `https://login.microsoftonline.com/<tenant-id>/v2.0`, replacing `<tenant-id>` with your Directory ID. |
| Client ID | Application ID of **Limrun SSO**. |
| Client Secret | The secret **Value** from that app registration. |

Select **Save**. Use the tenant-specific issuer, not `/common` or `/organizations`. You can confirm the issuer in `https://login.microsoftonline.com/<tenant-id>/v2.0/.well-known/openid-configuration`.

## Log in with Microsoft Entra ID

1. Open [console.limrun.com/authn/login](https://console.limrun.com/authn/login).
2. Select **Continue with SSO** and enter your work email.
3. Complete authentication in your organization's Microsoft tenant.

Without SCIM, successful SSO creates or links the account and joins the organization. If you plan to use SCIM, test with an existing Limrun admin, then complete provisioning before inviting users to sign in.

## Configure SCIM provisioning

Entra's non-gallery provisioning supports a SCIM URL and bearer token. The steps below use Limrun's generated credential directly. See [Microsoft's non-gallery SCIM guide](https://learn.microsoft.com/en-us/entra/identity/app-provisioning/use-scim-to-provision-users-and-groups#integrate-your-scim-endpoint-with-the-microsoft-entra-provisioning-service).

### Create the provisioning application

1. In Entra, open **Enterprise applications > New application > Create your own application**.
2. Name it `Limrun SCIM` and choose **Integrate any other application you don't find in the gallery**.
3. In Limrun, open **Settings > Single Sign-On > Directory provisioning (SCIM)** and generate a credential.
4. In **Limrun SCIM**, open **Provisioning** and configure automatic provisioning. Depending on your Entra portal, select **Get started** or **New configuration**.
5. Enter Limrun's **SCIM base URL** as the **Tenant URL**, and its generated credential as the **Secret Token**. Copy the credential without a `Bearer ` prefix.
6. Select **Test Connection**, then save.

The SCIM credential is separate from the **Limrun SSO** client secret and Limrun API keys. Generating it starts SCIM setup: existing members retain access, while invitations, auto-join, and admission of new users are disabled.

### Configure attribute mappings

Enable both user and group provisioning. Under the provisioning configuration's attribute mappings, map only attributes Limrun supports. Remove mappings for enterprise-extension fields such as `manager` and `department`.

| Entra source | SCIM user attribute | Configuration |
|---|---|---|
| `mail` | `userName` | Use as the matching attribute. Must equal the OIDC `email` claim. |
| `objectId` | `externalId` | Stable directory identifier. |
| `displayName` | `displayName` | Optional profile field. |
| `givenName` | `name.givenName` | Optional profile field. |
| `surname` | `name.familyName` | Optional profile field. |
| `mail` | `emails[type eq "work"].value` | Same work email. |
| Entra's account-enabled and assignment status mapping | `active` | Preserve the default lifecycle expression so deprovisioning sends `false`. |

Use `userPrincipalName` for `userName` only when it equals the OIDC email. A guest's `#EXT#` principal name is not a work email. Every provisioned user's email domain must be verified in the Limrun organization.

For groups, keep `objectId` mapped to `externalId`, `displayName` to `displayName`, and `members` to `members`. Use distinct group names for Entra matching, even though Limrun identifies groups by their SCIM IDs.

See [Microsoft's attribute mapping guide](https://learn.microsoft.com/en-us/entra/identity/app-provisioning/customize-application-attributes) and Limrun's [supported SCIM attributes and operations](/docs/reference/single-sign-on/scim#protocol-support).

### Synchronize groups and activate access management

1. Assign pilot access groups under **Limrun SCIM > Users and groups**. Include an admin group and its direct user members.
2. Scope provisioning to **Sync only assigned users and groups**. Ensure those users can also sign in through **Limrun SSO**. See [Microsoft's scoping guidance](https://learn.microsoft.com/en-us/entra/identity/app-provisioning/define-conditional-rules-for-provisioning-user-accounts).
3. Start provisioning. Check Entra's provisioning logs and wait for both users and group memberships to appear in Limrun. A successful connection test alone does not synchronize the directory.
4. In Limrun, map the synchronized groups to **Admin**, **Member**, or **Viewer**. Confirm that every existing member who should retain access, including administrators, is active and belongs to a mapped group.
5. Select **Activate SCIM**. Test a provisioned user's SSO login, then test group removal, deactivation, and reactivation with a pilot account.

Activation is permanent and can remove or demote the last admin. A user needs both an active SCIM record and membership in a mapped group. Direct application assignment without a mapped group does not grant Limrun access after activation. Nested groups are not supported; provision direct user memberships.

For role precedence, recovery, and credential rotation, see [SCIM provisioning](/docs/reference/single-sign-on/scim).

## Troubleshoot

**"Your organization requires SSO".** Use **Continue with SSO** and your work email. The separate Microsoft sign-in route cannot bypass the configured organization connection.

**"SSO not configured".** Verify the email domain under **Settings > Domain Verification** and save the OIDC connection for the same organization.

**Microsoft rejects the redirect URI.** Register `https://api.limrun.com/authn/oidc/callback` as a Web redirect URI on **Limrun SSO**. Do not use `/authn/microsoft/callback` for this setup.

**The ID token is missing email.** Add the optional `email` ID-token claim and populate the user's email in Entra. Check that the value matches SCIM `userName`.

**Microsoft rejects the client secret.** Use the secret's Value, not its ID. If it expired, create a replacement and update the Limrun SSO connection.

**Microsoft asks for admin approval.** Have an Entra administrator grant consent to the sign-in permissions on **Limrun SSO**, then retry with an assigned user.

**Provisioning returns 401 or 403.** Check the SCIM base URL and Secret Token. After rotating the Limrun SCIM credential, replace the token in Entra; the previous credential stops working immediately.

**A provisioned user cannot enter Limrun.** Confirm SCIM is activated, the user is active, and a synchronized group containing the user maps to a role. Also check assignment to **Limrun SSO**. Review both Entra provisioning logs and Limrun provisioning history for failed or pending changes.

**Users synchronize but groups do not.** Enable group mappings, assign the groups to **Limrun SCIM**, and check the provisioning scope. Limrun calculates roles from SCIM group membership, not from OIDC group claims.