Active Directory & Entra ID Single Sign-On Setup

AI Insights 365 — On-Prem Edition supports two complementary single sign-on methods: form-based Active Directory authentication for Windows-hosted, domain-joined environments, and Entra ID (Azure AD) authentication for organizations that have moved identity to the cloud. Both feed the same authorization model, so users land in the right organization and workspaces regardless of how they signed in.

This reference walks through configuring each provider, provisioning users automatically, mapping AD security groups to workspaces with inherited roles, and managing the tokens that govern sessions and shared report access. It closes with troubleshooting for the issues identity engineers hit most often.

Authentication Methods at a Glance

Both methods issue the same session token after a successful login, and both resolve to a user record inside a single organization. The difference is only in how the credential is verified.

Configuring On-Prem Active Directory Login

Form-based AD login presents a standard username and password form. The platform validates the supplied user@domain and password against your directory. Because the deployment is Windows-hosted, this path is compatible with Kerberos and integrated Windows authentication.

Steps

1. Open System Settings → Authentication → Active Directory.
2. Enter the domain settings for your forest:
   • Domain name (for example, corp.contoso.com)
   • Domain controller host(s) used for binding and validation
   • The service account, if your environment requires a bind account for directory lookups
3. Confirm the user principal name (UPN) format your users will type. The login form expects user@domain.
4. Save the configuration and test with a known account.

Login form input
  Username: jdoe@corp.contoso.com
  Password: ••••••••••••

When a user authenticates, the platform verifies the credential against AD and resolves the matching user record. If you have mapped AD security groups to workspaces (covered below), the user's effective membership and roles are applied at sign-in.

Security note: secrets such as bind credentials are stored using AES-256 encryption at rest. The encryption key is rotatable from System Settings.

What happens on a successful AD login

It helps to understand the sequence the platform runs so you can reason about failures later:

1. The user submits user@domain and a password on the login form.
2. The credential is validated against Active Directory. Because the host is Windows-based, this is compatible with Kerberos and integrated Windows authentication.
3. The platform applies find-or-create provisioning to resolve the user record.
4. Any WorkspaceGroup mappings the user qualifies for are evaluated, and the corresponding inherited roles are applied.
5. A JWT is issued for the session.

Each of those stages is a distinct place a sign-in can stall, which maps directly to the troubleshooting section at the end of this document.

Configuring Entra ID (Azure AD) Login

Entra ID login is configurable per deployment. You provide the tenant and application registration details, and the platform performs an OAuth redirect to Microsoft for authentication.

Prerequisites in Entra ID

Register an application in your Entra tenant and collect:

• Tenant ID — the directory (tenant) identifier.
• Client ID — the application (client) ID of the registration.
• Redirect URI — the callback the platform listens on after authentication.

Steps

1. In the Entra admin center, create (or select) an app registration.
2. Add the platform's redirect URI to the registration's authentication settings. Use the exact URI shown in the platform's Entra configuration screen — a trailing-slash or scheme mismatch is the most common cause of failed sign-ins.
3. In AI Insights 365, open System Settings → Authentication → Entra ID.
4. Enter the Tenant ID and Client ID, and confirm the Redirect URI matches the registration.
5. Save and test with an account that belongs to the configured tenant.

Entra ID configuration
  Tenant ID:    11111111-2222-3333-4444-555555555555
  Client ID:    66666666-7777-8888-9999-000000000000
  Redirect URI: https://insights.corp.contoso.com/auth/entra/callback

On the first successful sign-in, the platform applies find-or-create provisioning (see the next section) so the user does not need to be pre-created.

Find-or-Create User Provisioning

Both AD and Entra logins use find-or-create provisioning. When a user signs in:

1. The platform looks for an existing user record that matches the authenticated identity.
2. If a match exists, that record is used and the session proceeds.
3. If no match exists, a new user record is created automatically and attached to the appropriate organization.

This removes the need to manually pre-stage every account, while still keeping each user scoped to a single organization. Find-or-create does not grant any workspace access on its own — access comes from explicit assignment or from AD group mapping.

Mapping AD Security Groups to Workspaces

The most scalable way to manage access is to drive workspace membership from your existing AD security groups rather than assigning users one at a time. This is configured through a WorkspaceGroup mapping.

How mapping works

• You map an AD security group to a workspace.
• You assign a workspace role to the mapping — Admin, Editor, or Viewer.
• Members of that AD group inherit the assigned role in the mapped workspace.

Because the role is attached to the mapping, you manage access by editing group membership in Active Directory. Adding a user to the AD group grants the workspace role; removing them revokes it.

Steps

1. Open the target workspace and go to Members → Group Mappings.
2. Choose Map AD Group.
3. Select the AD security group.
4. Assign the inherited workspace role (Admin, Editor, or Viewer).
5. Save the mapping.

Workspace roles

Group Sync Behavior

WorkspaceGroup mappings use bidirectional sync so that AD group membership and workspace membership stay aligned:

• When a user is added to a mapped AD group, they gain the inherited role in the workspace.
• When a user is removed from the AD group, their group-derived membership is withdrawn.
• The inherited role assignment follows the mapping, so role changes made on the mapping propagate to members.

Direct (per-user) assignments and group-derived assignments can coexist. A user may be a direct Editor in one workspace and inherit Viewer in another through a group mapping. Where multiple authority sources apply, the platform's precedence rules resolve the effective permission.

Authorization precedence

The platform is multi-tenant: Organizations contain Workspaces, and users only see resources within their own organization. SuperAdmin is the exception and can operate across organizations.

Effective authority is resolved in this order:

1. Workspace owner — highest authority for that workspace.
2. OrgAdmin in the same organization.
3. SuperAdmin — cross-organization scope.

Keep this precedence in mind when a user's effective access does not match a single group mapping; a higher-precedence assignment may be in play.

Sessions, JWTs, and Embed Tokens

Interactive sessions

After a successful AD or Entra login, the platform issues a JWT that authenticates the user's session. These tokens are valid for 24 hours. When a token expires, the user re-authenticates through their configured SSO method.

Embed tokens for shared reports

For anonymous report viewers — dashboards shared outside the authenticated user base — the platform issues separate embed tokens. These tokens are:

• Signed — tamper-evident.
• Scoped — limited to the specific report or content being shared.
• Time-limited — they carry an expiration.
• Revocable — backed by a version counter. Incrementing the counter invalidates previously issued embed tokens, which lets you revoke shared access without disrupting interactive logins.

Use embed tokens when you need to surface a report to viewers who should not hold a full account, and rotate the version counter when a shared link should no longer work.

Choosing between a session and an embed token

Keeping these two token types distinct is deliberate: revoking shared report access through the version counter never forces your authenticated users to sign in again, and an expired user session never affects a still-valid embedded report.

Auditing SSO and Access Events

Every per-user action — create, edit, delete, and access — is written to the audit log. The log is queryable by organization, by user, and by timeframe, which supports access reviews and incident investigation. After changing SSO configuration or group mappings, use the audit log to confirm that the expected users are signing in and accessing the expected resources.

Troubleshooting Common SSO Issues

Entra sign-in fails immediately after the Microsoft prompt

Almost always a redirect URI mismatch. Confirm the URI in the Entra app registration matches the platform's configured Redirect URI exactly, including scheme and any trailing path. Also verify the Client ID and Tenant ID were entered without transposition.

User authenticates but sees no workspaces

The user signed in successfully (find-or-create created or matched the account) but has no membership. Confirm they belong to an AD security group that is mapped to a workspace, or add a direct assignment. Remember that find-or-create grants no access by itself. Also confirm the user landed in the organization you expect — users only see resources within their own organization, so a user provisioned into the wrong org will appear to have "no workspaces" even though mappings exist elsewhere.

AD login rejected for a valid account

Check the UPN format — the form expects user@domain. Verify domain controller reachability and, if a bind account is configured, that its credentials are current. Because secrets are encrypted at rest, a recent key rotation that did not complete cleanly can also surface here; reconfirm the bind credential in System Settings.

Group membership changes are not reflected

Group-derived access follows the WorkspaceGroup mapping and its bidirectional sync. Confirm the AD group is still mapped to the workspace and that the user is genuinely a member of that group in AD. If a higher-precedence assignment exists (workspace owner, OrgAdmin, or SuperAdmin), it can override what a group mapping alone would grant.

A shared report link still works after it should have been disabled

Embed tokens are revoked through the version counter. Increment the counter to invalidate previously issued embed tokens. Interactive JWT sessions are unaffected by this and continue under their normal 24-hour lifetime.

Wrong role applied to a group's members

The inherited role lives on the mapping. Edit the WorkspaceGroup mapping and reassign the correct role (Admin, Editor, or Viewer); the change propagates to members through sync.

Sessions expire sooner or later than expected

Interactive JWTs are valid for 24 hours by design. If users report being signed out earlier, confirm they are not actually hitting an embed-token boundary on a shared report rather than their interactive session, and verify their device clock is not badly skewed, which can cause a signed, time-limited token to be rejected as expired.

Configuration Checklist

Before declaring SSO production-ready, confirm each item:

• AD domain settings entered and a known account validates through the login form.
• Entra app registration created with the platform's exact redirect URI.
• Tenant ID and Client ID entered without transposition.
• Find-or-create verified by signing in with a brand-new account.
• At least one WorkspaceGroup mapping created and an inherited role confirmed for a test member.
• Embed token issued for a shared report and revocation tested by incrementing the version counter.
• Encryption key location confirmed in System Settings and rotation procedure documented.
• Audit log queried by user to confirm sign-in and access events are recorded.

Summary

AD and Entra ID logins both resolve into the same multi-tenant authorization model, so you can mix Windows-hosted directory authentication with cloud identity while keeping users scoped to their organization. Drive access from AD security groups through WorkspaceGroup mappings for scale, lean on the precedence rules when resolving conflicts, and use the 24-hour JWTs, revocable embed tokens, and queryable audit log to keep sessions and shared content under control.