> ## Documentation Index
> Fetch the complete documentation index at: https://neuraltrust-92b43583-develop.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Microsoft Entra ID SSO

> Step-by-step guide to configure Microsoft Entra ID (Azure AD) Single Sign-On for NeuralTrust. Enable corporate authentication for your organization.

# Microsoft Entra ID Single Sign-On

Single Sign-On (SSO) allows your organization members to sign in to NeuralTrust using their corporate Microsoft credentials instead of a separate password.

<Note>
  **Using a different identity provider?** For Google Workspace, see [Google Workspace SSO](/platform/google-workspace-sso) — it has a dedicated provider with directory group sync. For Okta, Auth0, or another OIDC-compliant provider, see [Generic OIDC SSO](/platform/generic-oidc-sso).
</Note>

## Benefits

* **Simplified access**: One less password for users to remember
* **Centralized control**: Manage access through your IT department
* **Automatic provisioning**: Combine with SCIM for seamless user management
* **Enhanced security**: Option to enforce SSO-only login (disable passwords)

## Prerequisites

Before you begin, ensure you have:

* Microsoft Entra ID (Azure AD) tenant
* Global Administrator or Application Administrator role in Azure
* Owner or Admin role in NeuralTrust

***

## Part 1: Configure Azure Portal

### Step 1: Create an App Registration

1. Go to <a href="https://portal.azure.com" target="_blank">Azure Portal</a>
2. Navigate to **Microsoft Entra ID** → **App registrations**
3. Click **+ New registration**
4. Enter the following:
   * **Name**: `NeuralTrust SSO`
   * **Supported account types**: Accounts in this organizational directory only
   * **Redirect URI**: Leave empty for now
5. Click **Register**

### Step 2: Copy Your Credentials

1. On the app's **Overview** page, copy:
   * **Application (client) ID**
   * **Directory (tenant) ID**
2. Save both values securely — you'll need them later

### Step 3: Create a Client Secret

1. Go to **Certificates & secrets**
2. Click **+ New client secret**
3. Enter a description: `NeuralTrust SSO`
4. Select expiration: **24 months** (recommended)
5. Click **Add**

<Warning>
  Copy the **Value** immediately after creating the secret. It's only shown once and cannot be retrieved later. Do not copy the Secret ID — you need the Value field.
</Warning>

### Step 4: Configure Redirect URI

1. Go to **Authentication**
2. Click **+ Add a platform**
3. Select **Web**
4. Enter Redirect URI:
   ```
   https://app.neuraltrust.ai/api/auth/callback/azure-ad
   ```
5. Click **Configure**

### Step 5: Add API Permissions (Optional)

<Note>
  Only required if you plan to use the Manual User Sync feature.
</Note>

1. Go to **API permissions**
2. Click **+ Add a permission**
3. Select **Microsoft Graph** → **Application permissions**
4. Add these permissions:
   * `User.Read.All`
   * `GroupMember.Read.All`
   * `Group.Read.All`
5. Click **Grant admin consent for \[Your Organization]**
6. Verify all permissions show ✓ Granted

***

## Part 2: Configure NeuralTrust

### Step 1: Open SSO Settings

1. Log in to <a href="https://app.neuraltrust.ai" target="_blank">NeuralTrust</a> as Owner or Admin
2. Open the sidebar gear → **Platform settings → SSO Configuration**
3. Select the **Microsoft Entra ID** tab

<Note>
  Only **one** identity provider can be active at a time. If Generic OIDC or Google Workspace
  is already configured, remove it before setting up Microsoft Entra ID.
</Note>

### Step 2: Enter Your Azure Credentials

1. Paste your **Tenant ID**
2. Paste your **Client ID**
3. Paste your **Client Secret**

### Step 3: Test the Connection

1. Click **Test Connection**
2. You should see "Connection successful"
3. Click **Save**

***

## Part 3: Verify Your Email Domain

Domain verification prevents unauthorized users from claiming your company's domain and ensures only legitimate employees can use SSO.

### Step 1: Add Your Domain

1. Open **Platform settings → SSO Configuration** → **Domains**
2. Click **Add Domain**
3. Enter your company domain (e.g., `yourcompany.com`)
4. Click **Add**

### Step 2: Get the Verification Token

You'll receive a verification token like:

```
neuraltrust-verify-abc123-def456-ghi789
```

Copy this token for the next step.

### Step 3: Add DNS TXT Record

1. Log in to your DNS provider (GoDaddy, Cloudflare, Route53, etc.)
2. Add a new TXT record with:

| Field | Value                                      |
| ----- | ------------------------------------------ |
| Type  | `TXT`                                      |
| Name  | `@` (or leave empty depending on provider) |
| Value | Your verification token                    |
| TTL   | 3600 (or default)                          |

3. Save the record

### Step 4: Verify

1. Back in NeuralTrust, click **Verify**
2. If verification fails, wait up to 48 hours for DNS propagation
3. Once verified, status changes to ✓ **Verified**

<Note>
  DNS changes can take up to 48 hours to propagate globally. If verification fails immediately, try again later.
</Note>

***

## Part 4: Configure Role Mapping (Optional)

Role mapping allows you to automatically assign NeuralTrust roles based on Azure AD group membership. This is useful for organizations that want to manage access permissions through their existing Azure AD groups.

### Prerequisites for Role Mapping

Before configuring role mapping, ensure:

* SSO is configured and tested
* API permissions are granted (see Step 5 in Part 1)
* You have created security groups in Azure AD

### Step 1: Create Security Groups in Azure AD

1. Go to <a href="https://portal.azure.com/#view/Microsoft_AAD_IAM/GroupsManagementMenuBlade/~/AllGroups" target="_blank">Azure Portal → Groups</a>
2. Click **+ New group**
3. Create groups for your organization structure (e.g., "NeuralTrust Admins", "NeuralTrust Members")
4. Set **Group type** to **Security**
5. Click **Create**

### Step 2: Add Users to Groups

1. Go to <a href="https://portal.azure.com/#view/Microsoft_AAD_IAM/UsersManagementMenuBlade/~/AllUsers" target="_blank">Azure Portal → Users</a>
2. Select a user
3. Go to **Groups** → **+ Add memberships**
4. Select the appropriate group(s)
5. Click **Select**

### Step 3: Verify API Permissions

Ensure your app registration has these **Application permissions** (not Delegated):

| Permission             | Purpose                |
| ---------------------- | ---------------------- |
| `User.Read.All`        | Read user profiles     |
| `GroupMember.Read.All` | Read group memberships |
| `Group.Read.All`       | List available groups  |

1. Go to <a href="https://portal.azure.com/#view/Microsoft_AAD_RegisteredApps/ApplicationsListBlade" target="_blank">Azure Portal → App registrations</a>
2. Select your NeuralTrust SSO app
3. Go to **API permissions**
4. Verify all three permissions show ✓ **Granted**

<Warning>
  If permissions don't show "Granted", click **Grant admin consent for \[Your Organization]** and confirm.
</Warning>

### Step 4: Map groups to roles in Role Provisioning

Group-to-role mapping lives in one place — the **Role Provisioning** section — for every
provider. See [Role Provisioning](/platform/role-provisioning) for the full guide. In short:

1. Log in as Owner or Admin → **Platform settings → Role Provisioning**
2. Turn on **User provisioning & role mapping**
3. Set a **Default Access** role for users who match no group
4. Choose an **Enforcement** mode — *At sign-up only*, *At sign-up and login*, or
   *Automatically via SCIM*
5. Under **Role Mapping**, add a row per Azure AD group and pick its platform role:

| Role                    | Access Level                                                         |
| ----------------------- | -------------------------------------------------------------------- |
| **Global Admin**        | Full admin across products and platform settings; billing visibility |
| **Admin**               | Manage members, most settings                                        |
| **Editor** / **Viewer** | Product permission levels — see [Users & groups](/platform/users)    |

<Warning>
  A user in **several** mapped groups gets the **highest-privilege** role among them — not
  the first match. Do **not** map IdP groups to **Owner**; transfer ownership in
  [Users & groups](/platform/users) instead.
</Warning>

***

## Part 5: Enable SSO-Only Mode (Optional)

Enforcing SSO-only mode requires all users to authenticate through the IdP configured
for your organization.

1. Open **Platform settings → SSO Configuration**
2. Toggle **Enforce SSO** to ON
3. Confirm the action

<Note>
  When enabled, members whose email domain is **verified** for the organization must
  authenticate through the configured IdP.

  Exceptions:

  * **Break the Glass** accounts sign in with **password only** (skip SSO and magic link).
  * **External-domain members** (invited with an email whose domain is *not* among the
    organization's verified domains — e.g. a guest `@partner.com`) sign in with a
    **magic link**, even when Enforce SSO is on. They cannot use the corporate IdP
    for that address.

  **Prerequisites:** Add at least one break-the-glass account under
  [Users & groups](/platform/users) and configure your **Email Domain** first.
</Note>

<Warning>
  Before enabling SSO-only mode, ensure members on verified domains can sign in with
  Microsoft. Keep a [Break the Glass](/platform/break-glass) emergency account for IdP
  outages. External-domain guests continue to use magic link — they are not locked out
  by Enforce SSO.
</Warning>

***

## User Experience

Once SSO is configured, users will see a **Sign in with Microsoft** button on the login page. After clicking it:

1. Users are redirected to Microsoft's login page
2. They enter their corporate credentials
3. They're automatically signed in to NeuralTrust

For new users whose email domain is verified, accounts are created automatically on first login.

***

## Troubleshooting

| Error                      | Cause                   | Solution                                                                                                                               |
| -------------------------- | ----------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
| `AADSTS50011`              | Redirect URI mismatch   | Verify the redirect URI in Azure matches exactly: `https://app.neuraltrust.ai/api/auth/callback/azure-ad` (check for trailing slashes) |
| "Connection failed"        | Invalid credentials     | Verify your Tenant ID, Client ID, and Client Secret are correct                                                                        |
| "Unauthorized team access" | Domain not registered   | Add and verify your email domain in SSO settings                                                                                       |
| "Domain not verified"      | DNS not propagated      | Wait up to 48 hours, then click Verify again                                                                                           |
| "SSO enforced"             | Password login disabled | Use the "Sign in with Microsoft" button instead                                                                                        |
| `AADSTS7000215`            | Invalid client secret   | Generate a new client secret in Azure and update NeuralTrust                                                                           |
| `AADSTS700016`             | App not found in tenant | Verify the Application ID and ensure you're using the correct Azure tenant                                                             |

***

## Security Best Practices

1. **Rotate client secrets** before they expire (24 months recommended)
2. **Enable SSO-only mode** once all users are onboarded
3. **Verify all email domains** your organization uses
4. **Combine with SCIM** for automatic user lifecycle management
5. **Monitor audit logs** for suspicious login patterns

## Next Steps

* [Google Workspace SSO](/platform/google-workspace-sso) — Configure SSO with Google Workspace
* [Generic OIDC SSO](/platform/generic-oidc-sso) — Configure SSO with Okta, Auth0, or other providers
* [Role Provisioning](/platform/role-provisioning) — Map groups to roles and choose enforcement
* [Configure Break the Glass](/platform/break-glass) — Set up emergency access for IdP outages
* [Manual User Sync](/platform/user-sync) — Import users on-demand with role mappings
* [Configure SCIM Provisioning](/platform/scim) — Automate user account creation and removal
* [Set Up Audit Logs](/platform/audit-logs) — Monitor SSO-related security events