> For the complete documentation index, see [llms.txt](https://docs.ox.security/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.ox.security/get-started/onboarding-to-ox/connect-to-ox/sign-in-to-ox/logging-into-microsoft-entra-id.md).

# SSO with Microsoft Entra ID

Microsoft Entra ID (formerly Azure Active Directory) supports OpenID Connect (OIDC) for secure single sign-in.\
OX supports OIDC SSO with Entra ID so your users can sign in to OX with their company credentials.\
This section matches the structure and tone of your Okta SSO page for consistency.

## Prerequisites

* Entra admin permissions to register applications and manage Enterprise applications.
* OX Owner or Admin permissions.

## Step 1: Register the application \[Entra]

Create an application registration in Entra ID that represents OX. This app sets the redirect URI and provides the Application (client) ID you will use in OX.

To register the application:

1. In the **Entra admin center**, go to **Applications** > **App registrations** > **New registration**, and set the following parameters:

| Parameter                    | Description                                                                     |
| ---------------------------- | ------------------------------------------------------------------------------- |
| **Name:**                    | Set the app name, for example, **OX Security SSO**.                             |
| **Supported account types:** | **Accounts in this organizational directory only (Single tenant)**.             |
| **Redirect URI:**            | **Platform:** **Web** \| **URL:** `https://auth.app.ox.security/login/callback` |

2. Select **Register**.

## Step 2: Create a client secret \[Entra]

1. Open the app **Certificates & secrets** page.
2. Select **New client secret**.
3. Enter a description and select an expiry period.
4. Select **Add**.

<figure><img src="/files/x6JZLVQWCINCOPCTjk4I" alt="" width="563"><figcaption></figcaption></figure>

5. Copy and save the **Value** now. You will not see it again.

## Step 3: Configure SSO in OX \[OX]

1. In the OX platform, go to **Settings** > **Login Settings** and select **Microsoft Entra ID**. Take the values from the [Configuration ](https://app.ox.security/settings?tab=login\&loginOption=AzureAD)screen.

<figure><img src="/files/GfPPeHanz3NawFSIhz4F" alt="" width="513"><figcaption></figcaption></figure>

2. Fill the fields using as follows:

| Parameter                                 | Description                                                                                                                                                                                                                                                                                                                                                                            |
| ----------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Entra domain or Tenant (Directory) ID** | Enter your tenant primary domain (for example, `contoso.onmicrosoft.com`) or the Directory (tenant) ID GUID.                                                                                                                                                                                                                                                                           |
| **Application (client) ID**               | Paste the **Application (client) ID** from the Entra app registration **Overview**.                                                                                                                                                                                                                                                                                                    |
| **Client Secret (Value)**                 | Paste the client secret value you created in Entra.                                                                                                                                                                                                                                                                                                                                    |
| **Enable auto provisioning**              | Enable this if you want users to sign in without inviting them in the OX Members page and to control roles and scopes using Entra ID groups. **Note:** If you do not configure auto-provisioning with roles, users who are not invited sign in as **Read Only**. If you do configure roles, manage role assignments only in Entra ID. OX role changes are ignored for Entra SSO users. |
| **Sync OX Group Roles**                   | When enabled, OX assigns a role (Admin, Developer, Policy Manager, Read Only) based on the user’s Entra ID group membership. Manage memberships in Entra ID.                                                                                                                                                                                                                           |
| **Sync OX Group Scopes**                  | When enabled, OX grants data visibility based on Entra ID group names that represent application owner scopes or tag scopes. Manage memberships in Entra ID.                                                                                                                                                                                                                           |

3. Select **Save**.

## Step 4: Assign users to the Enterprise application \[Entra]

1. In the **Entra admin center**, go to **Enterprise applications** and open your app.
2. Go to **Users and groups**.
3. Select **Add user/group** and assign the people and groups who can sign in to OX.
4. Select **Assign**.

## Step 5: Enable app-initiated login and catalog visibility \[Entra]

1. In **App registrations** > your app > **Branding & properties**, set the following parameters:

| Parameter         | Value                                                                                                                                         |
| ----------------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
| **Home page URL** | `https://app.ox.security/sso-login?organization=<ORG_ID>&organization_name=<ORG_SLUG>&display_name=<DISPLAY_NAME>&connection=waad-<ORG_SLUG>` |

2. In **Enterprise applications** > your app > **Properties**, set the following parameters:

| Parameter                         | Value   |
| --------------------------------- | ------- |
| **Enabled for users to sign-in?** | **Yes** |
| **Assignment required?**          | **Yes** |
| **Visible to users?**             | **Yes** |

3. Select **Save**.

## Step 6: Map Entra ID groups to OX roles \[Entra and OX]

This step enables the automatic assignment of [OX Security roles](/admin-settings/roles.md) based on user groups in your IdP. There are the following types of roles:

* Roles predefined by OX,
* Custom roles.

### Create user groups for predefined roles

Each predefined role group requires a prefix. The default is: OXApp-. You can change the default prefix to a custom one.

**To change the default prefix:**

1. Go to **Settings > Login > \[IdP icon]** and enter a different prefix.

<figure><img src="/files/oRhlBQe1HzRypIE0yyAC" alt="" width="464"><figcaption></figcaption></figure>

2. **Create IdP role groups:** In your IdP, go to **Directory > Groups** and create groups using these exact names (case-sensitive) for each OX role you want to sync:

* OXApp-Admin
* OXApp-Developer
* OXApp-Dev Manager/Security Champion
* OXApp-Policy Manager
* OXApp-Read Only

### Create user groups for custom roles

In case you have custom role(s) defined in OX, you need to create groups using the exact labels OX generates for your custom roles. The label is different from the custom role name.

You can view the custom role label only in the instructions provided by OX within the Configuration dialog.

**To locate the custom role label:**

1. Go to **Settings > Login > \[IdP icon]** and in the instruction box, select **+**.
2. Scroll down in the instructions box until you get to **Advanced settings (auto provisioning) - Setting roles**.
3. Read the procedure. The custom role label appears next to the custom role name in brackets. You cannot change it.
4. Use this label as the name of your new group in IdP.

**For example:**

I know that the admin defined a custom role called Executive Viewer. If I am looking for the label that OX generated for the custom role Executive Viewer, first I locate the custom role Executive Viewer in brackets and then I can see that OX generated a label for this custom role "OXApp-CustomRole1".

<figure><img src="/files/E6mKkKR0D7NX0ifoUxIZ" alt="" width="489"><figcaption></figcaption></figure>

### **Complete the process**

1. **Map group attributes**: In your IdP, ensure you have groups attribute mapping enabled.
2. **Enable sync:** In OX, go to **Settings > Login > \[IdP icon]** and enable **Sync OX Group Roles** using the prefix you selected.
3. Select **Save**.
4. In the IdP, assign users who need that specific scope access as members of the corresponding group.

## Step 7: Map Entra ID groups to OX scopes \[Entra and OX]

### Step 7: Map Entra ID groups to OX scopes

Map your Microsoft Entra ID groups to the corresponding OX scopes.

#### For App owner and other UI-visible scopes

For scopes that are available in the OX scope selector:

1. In OX, click the **scope selector** in the top navigation bar (for example, **Entire Organization**).
2. Select the scope that you want to map.
3. Click the information icon next to the scope.
4. In the details panel, copy the value from the **SSO Group String** field.
5. In Microsoft Entra ID, use the copied value as the group name.

The **SSO Group String** is generated automatically by OX.

Example:

```
OXAppOwnerScope-Support-id:raz.levi@ox.security
```

#### For tag scopes

Tag scopes are not displayed in the scope selector, so OX does not generate an **SSO Group String** for them.

Instead, construct the group name by using the following format:

```
OXTagScope-<TAG_NAME>-id:<TAG_ID>
```

Example:

```
OXTagScope-Production-id:3b6d9f2a-8c4e-4d0f-9b2a-7d45f9f7b123
```

Replace:

* `<TAG_NAME>` with the tag name.
* `<TAG_ID>` with the unique ID of the tag.

The tag ID is not available in the OX user interface. To obtain it, use the OX API to retrieve the tag details, and then use the returned tag ID when constructing the group name.

> **Note:** Tag IDs can currently be retrieved only through the OX API. Use the **Get Single Tag** API endpoint to retrieve the tag ID.

## Step 8: Test the sign-in \[OX]

1. In the OX platform, go to `https://app.ox.security/` or your environment URL.
2. Select **Sign in with Microsoft** and sign in with an assigned user.
3. If you configured the **Home page URL** in Step 5, open that link to start the flow.

## Troubleshooting

| Symptom                                    | Where to fix | What to check                                                                                                                                                   |
| ------------------------------------------ | ------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Reply URL mismatch                         | Entra        | The **Redirect URI** must exactly match `https://auth.app.ox.security/login/callback`.                                                                          |
| Invalid client secret                      | Entra and OX | Paste the secret **Value** in OX and verify it is not expired.                                                                                                  |
| User not authorized to use the app         | Entra        | **Enterprise applications** → your app → **Users and groups**. Ensure the user or their group is assigned.                                                      |
| Roles or scopes do not match after sign-in | Entra and OX | Verify the user’s Entra group membership, ensure group claims are in the ID token, and confirm **Sync OX Group Roles** or **Sync OX Group Scopes** is on in OX. |


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.ox.security/get-started/onboarding-to-ox/connect-to-ox/sign-in-to-ox/logging-into-microsoft-entra-id.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.