Microsoft Entra directory user sync (preview)

Directory sync lets administrators find Microsoft Entra users in Lunar Paper before those people have signed in. It runs in the background, reads users from Microsoft Graph, and stores inactive directory records that are claimed when the person later signs in through SSO.

Directory sync is optional. Microsoft Entra SSO and Team sync works without it by provisioning each person on their first successful sign-in.

For the complete Microsoft architecture and the distinction between Team sync and directory user sync, start with Microsoft Entra and Microsoft 365.

Preview limitation: do not combine with SSO Team mappings

Do not enable the current Azure directory sync on a provider that also has Entra-to-Team group mappings. The Azure connector does not fetch group membership. A directory run replaces the identity’s stored sign-in claims with the Graph user record and then reconciles missing group data as removals. This can remove SSO-derived Team membership until each affected user completes a fresh sign-in.

The setup below documents the implemented user-cache path for isolated evaluation. Production use with mapped Teams requires a connector update that preserves sign-in claims or synchronizes Graph group membership first.

Keep the Microsoft applications separate

A corporate deployment should normally use purpose-specific Entra app registrations:

Entra application	Purpose	Typical access
Lunar Paper SSO	Interactive user sign-in and group claims	OpenID Connect scopes; no Graph application permission
Lunar Paper Directory Sync	Background user discovery	Microsoft Graph application User.Read.All
Lunar Paper Mail	Unattended Exchange Online sending	Microsoft Graph application Mail.Send, restricted in Exchange

Lunar Paper Directory Sync is an application identity, not a person, mailbox, or Microsoft 365 licence seat. It has no interactive sign-in and needs no redirect URI. Separating it from SSO and email keeps credentials, consent, rotation, audit evidence, and revocation independent.

The directory-sync credential is configured on the existing Lunar Paper SSO provider because that provider owns the resulting identities. The client ID in Directory Sync therefore belongs to Lunar Paper Directory Sync, while the client ID in Provider Config continues to belong to Lunar Paper SSO.

What is synchronized

The current Microsoft connector reads the paginated Graph /users collection and requests these fields:

• immutable Entra user object ID;
• display, given, and family names;
• mail address or user principal name; and
• account-enabled state.

Lunar Paper stores a never-signed-in account as cached and inactive. It has no usable local password and does not claim an active-user licence seat. On the first successful SSO sign-in, Lunar Paper matches the provider identity, changes the account to authed and active, applies current SSO roles and Team claims, and then claims a licence seat.

Future syncs update names and enabled state. With Disable removed users on, an identity that is no longer returned by the directory is disabled rather than deleted. Its sessions and SSO-derived Team membership are revoked, while audit history remains.

Current Entra limitations

The current Azure connector reads every user returned by the tenant and does not yet provide a group or user filter. This can include guest user objects. Review the resulting cached directory before enabling it for a large or mixed tenant.

It also does not retrieve Entra group membership. Set syncGroups to false; do not expect Discover Groups or a directory run to pre-populate Team members. Until the identity-claim replacement behavior described above is fixed, evaluate user caching only with a provider that has no SSO Team mappings.

Before you begin

You need:

• a working, tenant-specific Lunar Paper Entra SSO provider;
• permission to create an app registration and grant tenant-wide admin consent;
• a Lunar Paper system administrator account;
• a configured and backed-up SSO_ENCRYPTION_KEY; and
• outbound HTTPS access to login.microsoftonline.com and graph.microsoft.com, either directly or through the selected network proxy.

Keep a local recovery administrator available. A directory sync must not become the only way to administer the platform.

1. Register the directory application

1. Open the Microsoft Entra admin center and select the tenant used by Lunar Paper SSO.
2. Open Entra ID → App registrations → New registration.
3. Enter Lunar Paper Directory Sync or another purpose-specific name.
4. Select Accounts in this organizational directory only.
5. Leave Redirect URI empty and select Register.
6. Record the Application (client) ID and Directory (tenant) ID.

Creating the registration also creates its service principal under Enterprise applications. That is where tenant consent and sign-in activity can be reviewed; it does not create a user or mailbox.

2. Grant the read-only Graph permission

1. Open API permissions → Add a permission → Microsoft Graph.
2. Select Application permissions, not Delegated permissions.
3. Add User.Read.All.
4. Select Grant admin consent for the tenant and confirm that its status is granted.

User.Read.All allows an unattended application to read user profiles. Do not grant User.ReadWrite.All, Directory.ReadWrite.All, or mail permissions for this integration. Lunar Paper does not need them.

Microsoft documents the required permission on its List users reference.

3. Create the client secret

1. Open Certificates & secrets → Client secrets → New client secret.
2. Use a purpose-specific description and the shortest lifetime permitted by your operating policy.
3. Copy the secret Value immediately into an approved secret manager.

The value is shown once. The secret ID is not a credential. Never place the value in documentation, source control, screenshots, tickets, or chat.

Lunar Paper’s current Azure directory connector supports client-secret authentication. Microsoft recommends certificates or federated credentials for higher-assurance production workloads, but those credential modes are not yet implemented by this connector.

4. Configure Lunar Paper

Open Administration → Security & Access → SSO & Identity Providers, select the existing Microsoft Entra provider, and leave Provider Config unchanged.

Turn on Directory Sync. The form changes Team membership source to Directory Sync and displays Configuration (JSON object). Enter the following object, using identifiers from the new directory application:

{
  "enabled": true,
  "connector": "azure",
  "tenantId": "<directory-tenant-id>",
  "clientId": "<directory-sync-application-client-id>",
  "clientSecret": "<directory-sync-client-secret-value>",
  "population": "all",
  "syncGroups": false,
  "disableRemovedUsers": true
}

Select Save Provider. Lunar Paper encrypts clientSecret before storage and returns only a configured placeholder on later edits. Leaving the placeholder unchanged keeps the existing credential.

Do not mix the application IDs

Provider Config uses the SSO application’s client ID and redirect URI. Directory Sync uses the separate directory application’s client ID and has no redirect URI. An object ID, enterprise-application object ID, secret ID, or secret placeholder cannot replace the application client ID or secret value.

5. Test and run the first sync

1. Confirm the provider has no SSO Team mappings, then select Test Sync. This obtains an app-only token and reads Graph without creating or changing Lunar Paper users. The current screen reports pass or failure but does not display the returned sample.
2. Stop if the tenant identifier, application, or consent is not the isolated evaluation configuration you intended.
3. Select Sync to cache the directory.
4. Review Sync History for success, the number seen, and the number created or updated.
5. Open Administration → Security & Access → Users and filter Source to the Microsoft provider.
6. Confirm never-signed-in users show a cached/inactive provisioning state.

User search on this screen filters the currently loaded page. Increase the page size or select All before assuming a person is missing from a large cached directory.

Once enabled, the scheduler runs the provider automatically. The default interval is 24 hours and can be changed with SSO_SYNC_INTERVAL_MS. Use the manual action when a directory change must be visible immediately.

Groups and Teams

User discovery and group authorization are currently different paths:

1. Directory sync makes an Entra user searchable before first sign-in.
2. SSO sign-in supplies that user’s current groups claim.
3. Lunar Paper maps matching group object IDs to Teams.
4. A Lunar Paper Team must then be linked to a service before it grants access to that service.

Changing Entra membership does not immediately change Lunar Paper Team access. The affected user must sign out and complete a fresh SSO sign-in. The Team’s Sync action only replays group data already stored from the most recent sign-in; it does not query Microsoft Graph.

This describes the intended separation of responsibilities. In the current release, do not run Azure directory sync against the same provider until the claim-preservation limitation at the top of this guide has been resolved.

For the complete claim and Team setup, see Microsoft Entra SSO and Team sync.

Network proxy behavior

Token and Graph calls use the SSO provider’s network service key:

sso_provider:<provider-alias>

The chosen route must reach both login.microsoftonline.com:443 and graph.microsoft.com:443. A successful OIDC Discovery test proves access to the sign-in metadata endpoint only; Test Sync separately proves the Graph application credential and directory permission.

See Network proxy administration.

Troubleshooting

Symptom	Check
Directory sync is disabled	Save "enabled": true on the intended provider.
No directory sync connector	Use "connector": "azure".
AADSTS700016	Enter the directory app’s Application (client) ID, not an object ID.
Invalid client secret	Enter the secret Value, not the secret ID, and check expiry.
Graph returns 403	Confirm User.Read.All is an Application permission and tenant admin consent is granted.
Users sync but groups are empty	This is a current connector limitation; use the OIDC group claim and map object IDs manually.
A user is not found in search	Review sync history, confirm the user has an email or UPN, then load a larger user-directory page.
A removed user was disabled	This is expected when disableRemovedUsers is true; verify the account was intentionally removed or excluded before re-enabling it.

Rotate or revoke the credential

1. Create a replacement secret before the old one expires.
2. Enter its Value in Directory Sync and save.
3. Run Test Sync, then a complete Sync.
4. Remove the old secret from Entra only after both succeed.

To stop synchronization, save "enabled": false. This stops future directory runs; it does not delete cached users. Revoke the secret or remove the enterprise application when the integration is permanently retired.

Microsoft reference material

• OAuth 2.0 client credentials flow
• Microsoft Graph: list users
• Microsoft Graph permissions reference
• Configure application access to web APIs
• Add application credentials

Use placeholders such as <directory-tenant-id> and <directory-sync-application-client-id> in support material. Never publish tenant domains, user lists, client-secret values, tokens, or unredacted Entra screenshots.