Microsoft Entra ID

Where group membership is mastered, mirrored into Atrium.

Capability: directory · Directory (group source). This is a core capability: the platform asks it questions, so exactly one connected instance is marked Primary and answers. The first instance you enable becomes Primary automatically; a second one never steals the role.

Vendor site · Vendor docs

Configure Microsoft Entra ID in Atrium → (admins only)

Setup

Atrium reads groups and their members from your Entra tenant as an app-only (daemon) client. Read-only — Entra stays the source of truth and Atrium never writes back. Do this once as a Global Administrator (or an Application + Privileged Role Administrator).

Register an application. Entra admin center → Identity → Applications → App registrations → New registration. Name it e.g. "Atrium group sync", choose "Accounts in this organizational directory only" (single tenant), leave the redirect URI blank, and register. Open the console page ↗
Add Microsoft Graph application permissions. On the app → API permissions → Add a permission → Microsoft Graph → Application permissions. Add exactly Group.Read.All, GroupMember.Read.All and User.Read.All — least-privilege for reading groups, memberships and mapping users to Atrium by email. (Directory.Read.All also works but is broader.)
Grant admin consent. Still on API permissions, click "Grant admin consent for <your tenant>". App-only permissions do nothing until an admin consents — every row must read "Granted".
Create a client secret. Certificates & secrets → Client secrets → New client secret. Set a 12–24 month expiry and copy the secret VALUE immediately (it is shown only once). Diarise a rotation before it expires.
Copy the three identifiers back here. From the app Overview copy the Directory (tenant) ID and the Application (client) ID. Paste those plus the secret value into the fields below and hit Test connection — Atrium proves it can read Graph groups before trusting them.

What you paste back into Atrium

In order, the values the steps above produce:

Directory (tenant) ID
Application (client) ID
Client secret VALUE (not its ID)

How it works

Connecting Entra moves the system of record for group membership out of the Atrium database and into your tenant. Atrium authenticates as an app-only daemon client (OAuth2 client credentials, no signed-in user) and READS groups and their members from Microsoft Graph. It never writes back, so nothing Atrium does can alter your directory.

What Atrium does, and when

When this happens	Atrium does this
Any directory read	Mints a Graph bearer token against login.microsoftonline.com for the configured tenant, using the client id and secret.
Groups are listed	Reads the tenant's groups over Graph, following the pagination links to completion rather than taking the first page.
A group's membership is read	Reads its members, then maps each one to an Atrium person by email address. Someone whose Entra mail does not match an Atrium account will not resolve.
Downstream access is reconciled	The membership Entra reports becomes the input to grant reconciliation. Removing a person from a group in Entra is what eventually removes their access, and Atrium is not the place to undo that.

Guarantees and limits

Read-only by construction. The documented permission set (Group.Read.All, GroupMember.Read.All, User.Read.All) contains no write scope, and the client issues no write calls. Directory.Read.All also works but grants strictly more than is needed.
App-only permissions do nothing until a tenant administrator grants admin consent. Until then every call fails with a consent error even though the credentials are correct.
Directory is a core capability: exactly one connected instance is Primary and answers lookups.
The Graph base URL is overridable for sovereign clouds; blank means the commercial endpoint.

What "Test connection" proves

Mints a token with the client-credentials flow and performs one read against Graph. A pass proves the tenant id, client id and secret are all correct AND that admin consent has been granted, since an unconsented app fails at exactly this call.

Troubleshooting

Symptom	Cause	Fix
Test connection fails with an authorisation or consent error.	Admin consent was never granted, so the app has permissions listed but not effective.	Entra → the app → API permissions → Grant admin consent. Every row must read "Granted" before this will pass.
It worked for months and then stopped.	The client secret expired. Entra secrets are time-limited and expiry is silent.	Create a new client secret, copy the VALUE (not the ID), and paste it here. Diarise the next expiry.
Groups appear but several members are missing.	Members are matched to Atrium accounts by email. A person whose Entra mail differs from their Atrium address does not resolve, and so does not appear.	Align the addresses, or check the account exists in Atrium at all. It is a matching gap, not a permission gap.
A person removed in Entra still has access.	Reconciliation has not run since the change, or the access came from somewhere other than this group.	Check the person's access in Atrium for a second source (a direct grant, or another group) before assuming the sync is broken.

Required scopes

Grant the credential exactly these scopes; they are the least-privilege set the connector needs:

Group.Read.All
GroupMember.Read.All
User.Read.All

Configuration fields

Field	Type	Required	Notes
`tenantId` Directory (tenant) ID	`text`	yes	GUID from the app registration Overview. Used in the token endpoint https://login.microsoftonline.com/<tenant>/oauth2/v2.0/token. e.g. `00000000-0000-0000-0000-000000000000`
`clientId` Application (client) ID	`text`	yes	GUID of the app registration itself. e.g. `00000000-0000-0000-0000-000000000000`
`clientSecret` Client secret	`password` secret	yes	The secret VALUE (not the secret ID). Encrypted at rest (AES-256-GCM). Rotate before its Entra expiry.
`graphBaseUrl` Graph base URL	`text`	no	Override only for sovereign clouds (e.g. GCC High, 21Vianet). Defaults to https://graph.microsoft.com. e.g. `https://graph.microsoft.com`

Operating notes

Secret fields are encrypted at rest (AES-256-GCM) and never returned to the client. Editing an instance and leaving a secret field masked keeps the stored value.
Adding a connector from the marketplace creates a disabled, credential-less instance ("Added, not yet connected"); it does nothing until an admin opens it, pastes credentials, and enables it.
Use Test connection on the instance page before enabling: it performs a read-only probe with the credentials you entered.
Connector credentials live in the Atrium database, not in container env vars; changing them here takes effect without a redeploy (within the resolver's 30-second cache).