Microsoft Entra ID Integration

Enable enterprise Single Sign-On (SSO) with Microsoft Entra ID and optionally sync users from your directory.

Overview

This integration enables:

• One-click SSO using Entra ID credentials
• Automatic user provisioning (optional)
• Deprovisioning when users leave
• Role mapping between Entra and Noxys
• MFA support (inherits from Entra)

Benefits:

• Reduce password management burden
• Enforce organization's identity policies
• Automatic offboarding
• Audit trail of all authentications

Prerequisites

• Azure AD / Microsoft Entra ID tenant
• Global Administrator or Application Administrator role in Entra
• Admin role in Noxys
• HTTPS enabled (required for OAuth redirects)

Architecture

User → Noxys Login → Redirect to Entra → User authenticates → Token issued → User logged in

Step 1: Register Noxys in Entra ID

Create an app registration for Noxys in your Azure directory.

1. Go to Azure Portal → Entra ID → App registrations
2. Click New registration
3. Configure:
   • Name: Noxys
   • Supported account types: Accounts in this organizational directory only
   • Redirect URI: Platform: Web
     • URI: https://api.noxys.cloud/auth/callback
   • For self-hosted: https://your-domain.com/auth/callback
4. Click Register
5. Note the Application ID (Client ID)

Step 2: Create Client Secret

Generate credentials for Noxys to authenticate with Entra.

1. In app registration → Certificates & secrets
2. Click New client secret
3. Configure:
   • Description: Noxys SSO
   • Expires: 24 months
4. Click Add
5. Copy the Value (this is shown only once!)
6. Store securely — you'll need it in Noxys

Step 3: Configure API Permissions

Grant Noxys permission to read user data.

1. In app registration → API permissions
2. Click Add a permission
3. Select Microsoft Graph
4. Choose Application permissions (for user sync) or Delegated permissions (for SSO only)

For SSO only:

Delegated permissions:
- openid
- profile
- email
- User.Read

For user sync:

Application permissions:
- User.Read.All
- Group.Read.All

5. Click Grant admin consent for [Organization]

Step 4: Get Tenant ID

Find your Entra tenant ID.

1. Entra ID → Overview
2. Copy Tenant ID (GUID format: 00000000-0000-0000-0000-000000000001)

Step 5: Configure SSO in Noxys

Enable Entra ID SSO in Noxys admin panel.

1. Noxys Admin Panel → Settings → Single Sign-On
2. Click Enable SSO
3. Choose Microsoft Entra ID
4. Configure:

Field	Value
Tenant ID	From step 4
Client ID	From step 1
Client Secret	From step 2

5. Click Test Connection
   • Should show: "✓ Successfully connected to Entra ID"
6. Click Enable

Step 6: Test SSO Login

Verify SSO is working before rolling out to users.

1. Logout of Noxys (clear session)
2. Go to Noxys Login Page: https://api.noxys.cloud/auth/login
3. Click Sign in with Microsoft
4. Should redirect to Entra login
5. Enter your Entra credentials
6. Grant permissions if prompted
7. Should redirect back and log you in

If this fails:

• Check redirect URI matches exactly in Entra app registration
• Verify client secret is correct
• Check browser console for errors

Step 7: User Provisioning (Optional)

Automatically sync users from Entra when they first log in.

1. In Noxys → Settings → SSO → User Provisioning
2. Enable: Auto-provision users on first login
3. Configure default role:
   • admin — Full permissions
   • viewer — Read-only (recommended)
4. Choose which fields to sync:
   • ✓ Email
   • ✓ Display name
   • ✓ Department
   • ✓ Job title
5. Click Save

Now when users log in via SSO, they're automatically created in Noxys with the configured role.

Step 8: Test with Users

Invite a test user to verify the flow.

1. In Entra ID, add a test user to your organization
2. Have the user go to: https://api.noxys.cloud/auth/login
3. Click Sign in with Microsoft
4. User should be auto-provisioned and logged in

Configuration Reference

SSO Settings

Setting	Options	Default	Description
Type	OIDC, SAML, Entra	-	Authentication protocol
Tenant ID	UUID	-	Entra tenant identifier
Client ID	UUID	-	Application ID in Entra
Client Secret	String	-	Application secret (secure)
Redirect URI	URL	-	Where to send users after login
Auto-provision	true/false	false	Create users on first login
Default Role	admin/viewer	viewer	Role for new users
Sync Fields	Array	email, name	Which fields to copy from Entra

Attribute Mapping

By default, Noxys maps Entra attributes to user fields:

Entra Attribute	Noxys Field	Example
mail	email	alice@contoso.com
displayName	display_name	Alice Martin
department	metadata.department	Engineering
jobTitle	metadata.job_title	Security Engineer
officeLocation	metadata.office	Paris

To customize mappings, contact support.

Advanced: Group-Based Role Assignment

Map Entra security groups to Noxys roles.

1. In Entra ID, create security groups:

   • Noxys Admins
   • Noxys Viewers

2. Add users to groups

3. In Noxys → Settings → SSO → Role Mapping:

   Group: Noxys Admins → Role: admin
   Group: Noxys Viewers → Role: viewer

4. Enable: Assign role based on group membership

Now users' roles are automatically assigned based on their Entra groups.

Deprovisioning

When a user is deleted from Entra ID:

Option 1: Manual (default)

• User remains in Noxys with inactive status
• Admin must manually delete in Noxys if needed

Option 2: Automatic

• Enable: Settings → SSO → Auto-deprovision users
• When deleted from Entra, automatically deactivated in Noxys after 24 hours

Troubleshooting

"Invalid client secret"

• Verify you copied the secret value (not the ID)
• Secret expires after 24 months — regenerate if needed
• Check no extra whitespace in secret

"Redirect URI mismatch"

• In Noxys: https://api.noxys.cloud/auth/callback
• In Entra app registration: Must match exactly (including https://)
• For self-hosted: Use your domain instead

"User not found in directory"

• Verify user has mail attribute set in Entra
• Check user account is enabled
• Verify in Entra: Users → User → Verify Mail field is populated

"SSO button not appearing"

• SSO must be enabled in Noxys: Settings → SSO → Enabled = ✓
• Clear browser cache
• Try incognito window

Users can't log in after SSO enabled

• Check Settings → SSO → Enable SSO for all users = ✓
• Verify email/password login is disabled (if desired)
• Users must use Sign in with Microsoft button

MFA Support

Entra ID automatically enforces your organization's MFA policies.

If MFA is enabled in Entra:

1. User clicks Sign in with Microsoft
2. Entra prompts for MFA (authenticator app, SMS, security key)
3. After MFA verification, user is logged into Noxys

No additional MFA configuration needed in Noxys.

Audit & Compliance

All SSO logins are logged in Noxys audit log:

Event: "user.sso_login"
Details: {
  "provider": "entra_id",
  "email": "alice@contoso.com",
  "timestamp": "2026-03-20T14:32:00Z"
}

Export audit logs for compliance:

• Settings → Audit Log → Export

Best Practices

1. Test with pilot group first

   • Enable SSO for admins first
   • Verify working before rolling out to all users

2. Set email as identifier

   • Ensure all users have mail attribute in Entra
   • Use email for both Entra and Noxys

3. Use group-based role assignment

   • Simplifies role management at scale
   • Aligns with org structure

4. Enable auto-deprovisioning

   • Removes access when users leave
   • Reduces manual admin work

5. Monitor MFA adoption

   • Encourage MFA in Entra policies
   • Check audit logs for successful logins

6. Review permissions quarterly

   • Audit Entra app permissions
   • Remove unnecessary scopes

Disabling SSO

If you need to disable SSO:

1. Settings → SSO → Disable SSO
2. Users can still log in with email/password
3. No data is lost

To re-enable:

1. Go through configuration steps again
2. Users can use either SSO or email/password

Monitoring

Monitor SSO health in Settings → SSO → Status:

Provider: Microsoft Entra ID
Status: Connected ✓
Last sync: 2026-03-20 14:32:00
Users synced: 42
Failed logins (24h): 0

If status shows Disconnected:

1. Verify client secret hasn't expired
2. Check network connectivity to Azure
3. Review Noxys error logs
4. Contact support@noxys.eu

Support

• Entra ID Docs: https://learn.microsoft.com/en-us/entra/identity/
• OAuth 2.0 Guide: https://learn.microsoft.com/en-us/entra/identity-platform/
• Noxys Support: support@noxys.eu
• Status: status.noxys.cloud

Related Integrations

• Okta SSO — Alternative identity provider
• SAML SSO — Standard SAML protocol
• Users API — Programmatic user management