Microsoft Entra ID Single Sign-On
Single Sign-On (SSO) allows your team members to sign in to NeuralTrust using their corporate Microsoft credentials instead of a separate password.Using a different identity provider? If you use Okta, Auth0, Google Workspace, or another OIDC-compliant provider, see Generic OIDC SSO instead.
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
- Go to Azure Portal
- Navigate to Microsoft Entra ID → App registrations
- Click + New registration
- Enter the following:
- Name:
NeuralTrust SSO - Supported account types: Accounts in this organizational directory only
- Redirect URI: Leave empty for now
- Name:
- Click Register
Step 2: Copy Your Credentials
- On the app’s Overview page, copy:
- Application (client) ID
- Directory (tenant) ID
- Save both values securely — you’ll need them later
Step 3: Create a Client Secret
- Go to Certificates & secrets
- Click + New client secret
- Enter a description:
NeuralTrust SSO - Select expiration: 24 months (recommended)
- Click Add
Step 4: Configure Redirect URI
- Go to Authentication
- Click + Add a platform
- Select Web
- Enter Redirect URI:
- Click Configure
Step 5: Add API Permissions (Optional)
Only required if you plan to use the Manual User Sync feature.
- Go to API permissions
- Click + Add a permission
- Select Microsoft Graph → Application permissions
- Add these permissions:
User.Read.AllGroupMember.Read.AllGroup.Read.All
- Click Grant admin consent for [Your Organization]
- Verify all permissions show ✓ Granted
Part 2: Configure NeuralTrust
Step 1: Open SSO Settings
- Log in to NeuralTrust as Owner or Admin
- Go to Settings → SSO
Step 2: Enter Your Azure Credentials
- Paste your Tenant ID
- Paste your Client ID
- Paste your Client Secret
Step 3: Test the Connection
- Click Test Connection
- You should see “Connection successful”
- 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
- Go to Settings → SSO → Domains
- Click Add Domain
- Enter your company domain (e.g.,
yourcompany.com) - Click Add
Step 2: Get the Verification Token
You’ll receive a verification token like:Step 3: Add DNS TXT Record
- Log in to your DNS provider (GoDaddy, Cloudflare, Route53, etc.)
- 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) |
- Save the record
Step 4: Verify
- Back in NeuralTrust, click Verify
- If verification fails, wait up to 48 hours for DNS propagation
- Once verified, status changes to ✓ Verified
DNS changes can take up to 48 hours to propagate globally. If verification fails immediately, try again later.
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
- Go to Azure Portal → Groups
- Click + New group
- Create groups for your team structure (e.g., “NeuralTrust Admins”, “NeuralTrust Members”)
- Set Group type to Security
- Click Create
Step 2: Add Users to Groups
- Go to Azure Portal → Users
- Select a user
- Go to Groups → + Add memberships
- Select the appropriate group(s)
- 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 |
- Go to Azure Portal → App registrations
- Select your NeuralTrust SSO app
- Go to API permissions
- Verify all three permissions show ✓ Granted
Step 4: Configure Role Mappings in NeuralTrust
- Log in to NeuralTrust as Owner
- Go to Settings → SSO → Entra ID User Sync tab
- Click Add Group Mapping
- Select an Azure AD group from the dropdown
- Choose the NeuralTrust role to assign:
| Role | Access Level |
|---|---|
| Owner | Full team access, all settings, billing |
| Admin | Manage members, most settings |
| Member | Basic access to team resources |
-
Configure Product Access (for Member role only):
- Select which products/features the group members can access
- Admin and Owner roles automatically have full access
- Enable Auto Sync to include this group in synchronization
- Click Save
Step 5: Sync Users
After creating mappings:- Go to Settings → SSO → Sync Users tab
- Click Preview Sync to see which users will be imported
- Review the list of users and their assigned roles
- Click Sync Now to import users
Users are assigned the role from the first matching group mapping. If a user belongs to multiple mapped groups, they receive the role from the highest-priority mapping (based on creation order).
Role Mapping Table Reference
| Column | Description |
|---|---|
| Azure AD Group | The source group in Microsoft Entra ID |
| NeuralTrust Role | Role assigned to group members |
| Product Access | Specific products accessible (Member role only) |
| Auto Sync | Whether group is included in sync operations |
Part 5: Enable SSO-Only Mode (Optional)
Enforcing SSO-only mode disables password login for your entire team, requiring all users to sign in with Microsoft.- Go to Settings → SSO
- Toggle Enforce SSO to ON
- Confirm the action
To prevent lockouts during identity provider outages, configure Break the Glass users who can log in with password even when SSO is enforced.
User Experience
Once SSO is configured, users will see a Sign in with Microsoft button on the login page. After clicking it:- Users are redirected to Microsoft’s login page
- They enter their corporate credentials
- They’re automatically signed in to NeuralTrust
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
- Rotate client secrets before they expire (24 months recommended)
- Enable SSO-only mode once all users are onboarded
- Verify all email domains your organization uses
- Combine with SCIM for automatic user lifecycle management
- Monitor audit logs for suspicious login patterns
Next Steps
- Generic OIDC SSO — Configure SSO with Okta, Auth0, or other providers
- Configure Break the Glass — Set up emergency access for IdP outages
- Manual User Sync — Import users on-demand with role mappings
- Configure SCIM Provisioning — Automate user account creation and removal
- Set Up Audit Logs — Monitor SSO-related security events