Microsoft Entra SSO and Team sync

This guide connects a single Microsoft Entra ID tenant—formerly Azure Active Directory—to Lunar Paper with OpenID Connect (OIDC). It also maps Entra security groups to Lunar Paper Teams.

For the complete Microsoft architecture and setup order, start with Microsoft Entra and Microsoft 365.

The primary path works with Microsoft Entra Free. It does not require Microsoft Graph application permissions, directory provisioning, dynamic groups, Conditional Access, or group assignment to the enterprise application.

What the integration does

Entra information	Lunar Paper result
OIDC sub claim	Stable external identity used to link future sign-ins
Email or email-shaped preferred_username	Account address used during provisioning
Entra security-group object IDs in groups	SSO-managed Team membership when the object ID is mapped to a Team
Provider alias	Stable identity source, shown by its friendly provider name in administration

New SSO accounts start with the Member platform role. A system administrator can grant a higher account role separately on the Users screen. Entra group claims manage Team membership; they do not grant platform administrator roles.

Before you begin

You need:

• a Lunar Paper system administrator account;
• permission to create an app registration, credential, security groups, and users in the intended Entra tenant;
• the public HTTPS origin of Lunar Paper, such as https://paper.example.com;
• an independent local Lunar Paper administrator account kept open while SSO is tested; and
• a securely stored SSO_ENCRYPTION_KEY in the Lunar Paper deployment.

The callback URI is the Lunar Paper origin plus this fixed path:

/api/auth/sso/azure-entra/callback

For example:

Production: https://paper.example.com/api/auth/sso/azure-entra/callback
Local test: http://localhost:3001/api/auth/sso/azure-entra/callback

Use the local URI only for a local evaluation environment. Production SSO must use HTTPS.

Keep a recovery administrator

Do not make SSO the only route to administration until at least two people have completed an end-to-end sign-in. Keep a local system administrator available so a broken provider, expired secret, or tenant outage cannot lock everyone out.

Use a separate application for email

If the same Microsoft 365 tenant will also send Lunar Paper email, do not add Graph Mail.Send to this SSO registration. Create a second registration for the email connector and scope its Exchange access separately. Entra security groups in an OIDC token control Lunar Paper Teams; they do not grant or restrict Microsoft Graph Send As access. See Outbound email connectors.

Use a separate application for directory sync

SSO provisions a user when they first sign in. If administrators also need to search never-signed-in Entra users, create a separate Lunar Paper Directory Sync registration with read-only Microsoft Graph access. Do not add that application permission to the interactive SSO registration. See Directory user sync (preview). The current Azure directory connector must not yet be enabled on a provider with SSO Team mappings because its user records do not contain group membership.

When documenting or asking for support, replace tenant, application, group, and user identifiers with placeholders. Do not include client-secret values, passwords, tokens, recovery information, or unredacted portal screenshots.

1. Register Lunar Paper in Microsoft Entra ID

1. Sign in to the Microsoft Entra admin center and select the tenant whose users will sign in to Lunar Paper.
2. Open Entra ID → App registrations → New registration.
3. Enter a recognizable name, such as Lunar Paper SSO.
4. Under Supported account types, select Accounts in this organizational directory only. This creates a single-tenant integration.
5. Under Redirect URI, select Web and enter the exact Lunar Paper callback URI.
6. Select Register.
7. On the application overview, record these non-secret identifiers:
   • Application (client) ID
   • Directory (tenant) ID

The registered URI and the redirectUri saved in Lunar Paper must match exactly, including scheme, host, port, path, and trailing slash. Do not register the frontend /login URL as the callback.

2. Create the client secret

1. In the app registration, open Certificates & secrets.
2. On Client secrets, select New client secret.
3. Give it a purpose-specific description, such as Lunar Paper production.
4. Choose the shortest lifetime allowed by your operating policy and select Add.
5. Copy the secret Value immediately into your approved password or secret manager.

The secret value is shown once. The Secret ID is not a usable client secret. Never paste the value into documentation, tickets, screenshots, chat, source control, or an environment file that is not access-controlled.

Set an expiry reminder before continuing. The rotation procedure is covered under Ongoing operations.

Current credential support

Lunar Paper’s current OIDC provider configuration accepts a client secret. Microsoft recommends certificate or federated credentials for production workloads. If your security policy prohibits client secrets, do not deploy this integration until Lunar Paper supports an approved credential type.

3. Create the Entra security groups

Open Entra ID → Groups → All groups → New group. For each Team membership:

1. Set Group type to Security.
2. Set Membership type to Assigned.
3. Use a name that makes the Lunar Paper purpose clear, such as:
   • LP-Admins
   • LP-Editors
   • LP-Viewers
4. Add the intended users as members.
5. Create the group, open it, and copy its immutable Object ID.

Keep an operator-only mapping record with placeholders filled from your tenant:

Entra security group	Object ID	Lunar Paper Team
LP-Admins	<admin-group-object-id>	LP-Admins
LP-Editors	<editor-group-object-id>	LP-Editors
LP-Viewers	<viewer-group-object-id>	LP-Viewers

Lunar Paper matches membership by object ID, not group display name. Renaming an Entra group therefore does not change the membership key, although its friendly name should also be updated in Lunar Paper for administrators.

Why this guide does not assign groups to the enterprise application

Group-based enterprise-application assignment requires Microsoft Entra ID P1 or P2. The Entra Free path leaves Assignment required? off and sends Security group object IDs in the OIDC token instead. Lunar Paper then applies its Team mappings.

Dynamic group membership also requires a premium license. Assigned/static Security groups avoid that dependency.

4. Add the security-group claim

1. Return to Entra ID → App registrations → Lunar Paper SSO.
2. Open Token configuration.
3. Select Add groups claim.
4. Select Security groups.
5. Keep the group claim in its default object-ID format and apply it to the ID token. The portal may also display Access and SAML token types.
6. Save the claim.

Do not select Groups assigned to the application for the Entra Free path; that option depends on premium group-based application assignment. Do not change the claim to group names: the Lunar Paper mapping expects immutable object IDs.

Group-claim size limit

Microsoft Entra emits at most 200 group memberships in an OIDC/JWT token. Above that limit it emits an overage marker instead of the group IDs. Lunar Paper’s claim-only integration does not currently expand an overage marker through Microsoft Graph. Use test users with fewer memberships and plan a separate Graph-backed design before rolling this pattern out to users above the limit.

5. Configure the Lunar Paper identity provider

In Lunar Paper, open:

Administration → Security & Access → SSO & Identity Providers

or go directly to:

/administration/security-access/sso-providers

Select New Provider and set:

Field	Value
Alias	azure-entra
Name	Microsoft Entra ID
Protocol	OIDC
Enabled	On
Issuer URL	https://login.microsoftonline.com/<tenant-id>/v2.0
Client ID	The Entra Application (client) ID
Client secret	The secret Value copied when it was created
Redirect URI	The exact HTTPS callback registered in Entra
Scopes	openid email profile
Group claim	groups
Team membership source	Sign-in group claims

The alias becomes part of the callback URI and cannot be changed after the provider is created. If you choose another alias, use it consistently in both Entra and Lunar Paper.

Use the tenant-specific v2.0 issuer. Do not use common, organizations, a tenant display name, or the portal URL.

Lunar Paper encrypts the stored client secret with SSO_ENCRYPTION_KEY. The secret is not returned to the browser after it is saved.

Directory Sync

For the claim-only Entra integration, set Directory Sync to:

{
  "enabled": false
}

Directory sync is not required for sign-in or Team mapping. This also avoids Microsoft Graph application permissions and admin consent.

To make never-signed-in Entra users searchable, keep this SSO configuration and add a separate read-only Graph application by following Directory user sync (preview). The current Azure connector synchronizes users but not their Entra group memberships. Its current claim-replacement behavior can remove SSO-derived Team membership during a directory run, so this combination remains an isolated evaluation path until the connector is updated.

Select Save Provider, then select Discovery beside the provider. A green Discovery test passed message confirms that Lunar Paper can read the tenant-specific OIDC metadata. It does not test a user, client secret, or group membership.

The enabled provider now appears on the login screen using its friendly name.

6. Map Entra groups to Lunar Paper Teams

Open:

Administration → Security & Access → Teams

or:

/administration/security-access/teams

For each Entra security group:

1. Create or select the Lunar Paper Team that should receive its members.
2. Select the Team name to open its settings.
3. Open SSO mappings, then select Microsoft Entra ID (azure-entra).
4. Enter the Entra group’s friendly name in Group display name.
5. Enter the immutable Entra Object ID in Group object ID.
6. Select Map group.

An empty discovered-group list is expected when directory sync is disabled. Enter the name and object ID directly; do not enable Graph permissions solely to populate the picker.

How membership changes flow

• On successful SSO sign-in, Lunar Paper reads the user’s groups claim and reconciles the sso_group source for every mapped Team.
• Sync and Sync All SSO reconcile group claims already stored from the user’s most recent sign-in. They do not query Entra for fresh membership.
• After an administrator adds or removes an Entra membership, the user must sign out and complete a fresh SSO sign-in before Lunar Paper receives the new claim and recalculates Team membership.
• Manual Team membership is stored as an independent source. Removing an SSO mapping does not erase an unrelated manual membership source.
• Linking a Team to a service remains a separate step. In the service, select Team → Teams → Link team, choose the mapped Team and its service role, then use Effective access to confirm the user inherits access through the Team. On a service that shows Access model update available, review and activate the transition before the Team grant takes effect. See Manage people and access.

7. Test the complete flow

Use a private browser window so the test does not silently reuse the Entra administrator’s session.

1. Keep the local Lunar Paper recovery-administrator session open elsewhere.
2. Add a dedicated test user to one mapped Entra Security group.
3. Open Lunar Paper /login in the private window.
4. Select Microsoft Entra ID.
5. Complete Microsoft sign-in, MFA registration, or a first-login password change manually.
6. On a Free installation, the first callback may return with ?error=licence_user_limit. This provisions the account without signing it in. In the recovery-administrator session, open Administration → Security & Access → Users, find the new Microsoft Entra ID user, and select Keep enabled. Then repeat the SSO sign-in.
7. Confirm that the callback returns to Lunar Paper without an error.
8. Filter Source to Microsoft Entra ID and confirm the test user has the Member role and the expected Team.
9. Grant a higher platform role on the Users screen only when that person needs it; a group claim does not grant that role.
10. Open the Team and confirm the member source reads azure-entra: <group-name>.
11. Link that Team to a test service without adding the user directly, activate the service’s access-model transition if prompted, and confirm Effective access names the Team as the source.
12. Sign in as the test user, open Services, and confirm the service appears and opens successfully.

Repeat the test with one non-administrator group before rollout. Also test removing the user from the Entra group, signing in again, and confirming the SSO-managed Team source is reconciled. An explicitly assigned platform role is preserved.

Expected no-cost configuration

Capability	Required for this guide?	Cost-sensitive note
Single-tenant OIDC app registration	Yes	Available with Entra Free
Assigned/static Security groups	Yes	Available with Entra Free
Security-group token claim	Yes	No Graph application permission required
Security defaults and MFA registration	Keep enabled	Available with Entra Free
Dynamic group membership	No	Premium feature
Group assignment to the enterprise application	No	Requires Entra ID P1 or P2
Conditional Access	No	Requires Entra ID P1 or later
Microsoft Graph directory sync	Optional	Separate application and consent scope; synchronizes users, not group membership

Troubleshooting

AADSTS50011 or redirect URI mismatch

Compare the URI in all three places:

• Entra app registration under Authentication;
• Lunar Paper Redirect URI; and
• the alias in the Lunar Paper provider.

The URI must match exactly. Use the backend callback path, not the login page.

?error=sso_failed after Microsoft sign-in

Check, in order:

1. the provider is enabled;
2. Discovery passes;
3. the issuer contains the correct Directory tenant ID and /v2.0;
4. the Application client ID belongs to the same app registration;
5. clientSecret contains the secret Value, not its ID; and
6. the secret has not expired.

The first Free-mode sign-in asks for a licence seat

The first SSO callback creates the user and identity binding, but Free mode allows only selected users to sign in. Keep the recovery-administrator session open, reload Administration → Security & Access → Users, select Keep enabled for the new identity, and have the user select Microsoft Entra ID again. If all three seats are selected, release one or activate a licence with more capacity first.

The user signs in but has no mapped Team

• Confirm the user is a member of an assigned/static Security group.
• Confirm Token configuration contains the Security groups claim.
• Compare the Entra group Object ID character-for-character with the Lunar Paper Team mapping.
• Sign the user out and complete a fresh SSO sign-in after changing membership.
• Check whether the user is above Entra’s 200-group OIDC/JWT claim limit.

The Entra email claim is missing

Entra can omit email for a cloud-only member whose directory mail field is empty. Lunar Paper resolves claims from the ID token and UserInfo response and can use an email-shaped preferred_username to provision the account. The immutable sub claim remains the external identity key; email and username claims are never authorization keys.

If preferred_username is not email-shaped, correct the Entra user profile or choose a tenant-approved address before retrying.

Discover Groups is empty

This is expected with the documented claim-only Entra configuration. The current Azure directory connector does not populate the cached group picker. Map the friendly name and immutable object ID directly on the Teams screen.

Ongoing operations

Rotate the client secret

1. Create a new secret in the same Entra app registration.
2. Copy its Value directly into Lunar Paper Client secret.
3. Save the provider and run Discovery.
4. Complete a private-window SSO sign-in.
5. Only after that succeeds, remove the old secret from Entra.

Lunar Paper currently stores one active client-secret value for the provider, so rotation requires a short coordinated change rather than overlapping two secrets in its configuration.

Change group access

Manage membership in Entra, not by repeatedly adding manual Lunar Paper Team members. After the Entra change, have the affected user sign in again. Use the Users source filter and Team membership-source labels as the verification surfaces.

Remove or disable the integration

1. Keep the recovery administrator available.
2. Disable the provider in Lunar Paper.
3. Verify local administration still works.
4. Remove the client secret from Entra when rollback is no longer required.
5. Remove Team mappings that are no longer valid and review any remaining manual membership sources.

Microsoft reference material

• Register an application in Microsoft Entra ID
• Add a Web redirect URI
• Configure group claims
• Review ID-token claims
• Manage access to enterprise applications
• Configure security defaults

All screenshots on this page are cropped and re-encoded to remove browser chrome, account menus, user addresses, tenant and application identifiers, credentials, tokens, cookies, and image metadata. The examples contain only placeholders or non-secret interface labels.