Microsoft Entra ID SSO

Let your team sign in to the Capsule portal with their Microsoft credentials using SAML 2.0 or OIDC single sign-on.

Microsoft Entra ID (formerly Azure Active Directory) SSO lets your users authenticate to Capsule through your existing Entra tenant instead of an email magic link. Entra ID acts as the identity provider (IdP); Capsule uses Auth0 as its identity broker (the service provider, SP) and accepts the assertion or ID token Entra issues at sign-in.

Capsule supports two protocols, and you pick one or the other for your tenant:

• SAML 2.0 - Entra posts a signed SAML assertion to Capsule.
• OIDC - Capsule exchanges an authorization code with Entra for an ID token.

Both protocols give your users the same login experience and both support SCIM provisioning and group-to-role mappings. See Choosing a Protocol if you have no existing preference.

You configure SSO yourself from Settings → Single Sign On in the Capsule portal. Setup is a round trip with Entra: create the application in Entra, paste Entra's details into Capsule, then copy the values Capsule generates back into Entra.

1. A user opens the Capsule login page and enters their work email.
2. Capsule matches the email domain to your Entra connection and redirects the browser to Microsoft.
3. The user authenticates with Entra ID (password, MFA, or whatever Conditional Access policies your org enforces).
4. Entra returns the user's identity to Capsule - a signed SAML assertion posted to Capsule's ACS URL, or an authorization code that Capsule exchanges for an ID token at the callback URL.
5. Capsule validates the assertion or token and signs the user in, provisioning the account on first login.
6. If the account e-mail already exists in Capsule, it will be linked with the Entra one.

Before you begin, ensure you have:

• The Owner role in Capsule - only Owners can manage settings and open the Single Sign On tab. See User Roles & Permissions.
• The Cloud Application Administrator or Application Administrator role in Microsoft Entra ID (or higher)
• For OIDC only: the ability to grant admin consent for Microsoft Graph permissions, which requires a Privileged Role Administrator or Global Administrator
• A verified email domain your users sign in with (e.g., your-company.com)

If your organization has no standing preference, either protocol is a fine choice. The practical differences:

The protocol is locked once a connection exists - the other option is greyed out in the portal. To switch protocols, turn off Enable SSO configuration and Save to remove the current connection, then configure the new one. Users signing in during the gap fall back to email magic links.

Setup is a round trip between the Microsoft Entra admin center and the Capsule Single Sign On settings. The shape is the same for both protocols:

1. Create the application in Entra and collect the values Capsule needs
2. Configure the connection in Capsule - paste Entra's details, set your domains, then read back the values Capsule generates
3. Copy Capsule's values back into the Entra application
4. Assign users and test

Follow the section for the protocol you chose.

Create the Entra app first to obtain its Login URL and signing certificate. Capsule generates its SP values only after the connection is saved (Step 2), so enter temporary placeholder URLs here - you'll replace them in Step 3.

1. Sign in to the Microsoft Entra admin center as at least a Cloud Application Administrator.

2. Go to Entra ID → Enterprise apps → All applications, then select New application.

3. Select Create your own application, give it a name (e.g., Capsule Security), choose Integrate any other application you don't find in the gallery (Non-gallery), then select Create.

4. In the application's Manage section, select Single sign-on, then select SAML.

5. In Basic SAML Configuration, select Edit and enter temporary placeholders (you'll update these in Step 3):

   • Identifier (Entity ID) - a placeholder such as https://example.com/placeholder
   • Reply URL (Assertion Consumer Service URL) - a placeholder such as https://example.com/placeholder

   Leave the optional fields (Sign on URL, Relay State, Logout URL) empty, then Save.

6. Review Attributes & Claims - the Entra defaults work as-is. The Unique User Identifier (Name ID) claim defaults to user.userprincipalname with the email address format.

   Capsule keys accounts on the Name ID, so it must be the user's email. If your users' UPN differs from their primary email address, edit the Unique User Identifier (Name ID) claim and set its source attribute to user.mail.

7. In the SAML Certificates section, select Download next to Certificate (Raw). This .cer file is the signing certificate you'll upload to Capsule in Step 2.

8. In the Set up <your app name> section, copy the Login URL - e.g., https://login.microsoftonline.com/<your-entra-tenant-id>/saml2. You'll enter it in Capsule in Step 2.

1. Sign in to the Microsoft Entra admin center as at least a Cloud Application Administrator.

2. Go to Entra ID → App registrations → New registration.

3. Give it a name (e.g., Capsule Security) and under Supported account types select Accounts in this organizational directory only (Single tenant).

4. Under Redirect URI, select platform Web and enter Capsule's callback URL: https://<capsule-login-domain>/login/callback.

   Capsule shows the exact value as Callback URL (Redirect URI) after you save the connection in Step 2. If you don't have it yet, enter a placeholder such as https://example.com/placeholder and correct it in Step 3.

5. Select Register. On the Overview blade, copy:

   • Application (client) ID - this is the Client ID you enter in Capsule
   • Directory (tenant) ID - you need it to build the issuer URL below

6. Go to Certificates & secrets → Client secrets → New client secret. Set a description and expiry, then Add.

   Copy the secret's Value, not its Secret ID. The Value is shown only once and cannot be retrieved later. Note the expiry date - when the secret expires, SSO stops working until you create a new secret and update it in Capsule.

7. Go to API permissions and confirm the Microsoft Graph → Delegated permissions openid, profile, and email are present (add any that are missing), then select Grant admin consent for <your tenant>.

8. Go to Token configuration → Add optional claim, choose token type ID, select email, then Add.

   This step is required. Entra v2.0 ID tokens do not reliably include an email claim on their own, and Auth0 does not call the IdP's /userinfo endpoint for OIDC connections - every claim Capsule needs must be present in the ID token itself. Without an email claim, Capsule's login and account-linking flow has nothing to match on.

   Entra also generally does not emit an email_verified claim. Capsule does not require it today, but it is worth knowing if you ever gate account linking on verified email.

9. Build the Issuer URL you'll enter in Capsule from the tenant ID you copied in step 5:

   https://login.microsoftonline.com/<your-entra-tenant-id>/v2.0

   This must be the tenant-specific v2.0 issuer. Do not use /common or /organizations - those multi-tenant authorities return a templated issuer in their discovery document, which fails OIDC issuer validation. Capsule derives the discovery document by appending /.well-known/openid-configuration to exactly the URL you enter, so use the form above with no trailing slash and no extra path.

Enter Entra's details in the Capsule Single Sign On settings, then read back the values Capsule generates.

1. Sign in to the Capsule portal as an Owner and go to Settings → Single Sign On.

2. Turn on Enable SSO configuration, then choose your protocol - SAML or OIDC.

3. Set Authorized Domains - the email domain(s) that should use this connection (e.g., your-company.com). Capsule routes sign-ins from these domains to Microsoft.

4. Fill in the protocol-specific fields.

   SAML:

   • Sign In Endpoint - paste the Entra Login URL from Step 1.
   • SSL/TLS Certificate - upload the Entra Certificate (Raw) file from Step 1 (.cer, .crt, or .pem). Capsule uses it to verify Entra's SAML signature.

   OIDC:

   • Client ID - paste the Application (client) ID from the app registration's Overview blade.
   • Client Secret - paste the client secret Value from Step 1.
   • Issuer URL - the tenant-specific v2.0 issuer you built in Step 1: https://login.microsoftonline.com/<your-entra-tenant-id>/v2.0. Capsule resolves the discovery document from it.

5. Click Save.

6. After saving, the Identity Provider Configuration section appears with the values Entra needs. Keep this page open for Step 3:

   • SAML - Identifier (Entity ID) and Reply URL (ACS URL)
   • OIDC - Callback URL (Redirect URI)

   Both protocols also show an IdP-initiated login URL. Entra doesn't need it for sign-in to work; you only need it if you want to give users a tile in the Microsoft My Apps portal. See IdP-Initiated Login.

Replace the Step 1 placeholders with the real values Capsule generated.

1. In the Entra admin center, open the application → Single sign-on, then select Edit in Basic SAML Configuration.

2. Update the two values:

   • Identifier (Entity ID) - paste the Capsule Identifier (Entity ID).
   • Reply URL (Assertion Consumer Service URL) - paste the Capsule Reply URL (ACS URL).

3. Select Save.

1. In the Entra admin center, open the app registration → Authentication.

2. Under Platform configurations → Web, make sure the Redirect URIs list contains the Capsule Callback URL (Redirect URI) exactly - same scheme, host, and path, no trailing slash. Remove the placeholder from Step 1.

3. Select Save.

1. Open the enterprise application for your connection. For SAML this is the application you created; for OIDC, Entra creates the matching enterprise application (service principal) alongside your app registration - find it under Entra ID → Enterprise apps → All applications.
2. In the Manage section, select Users and groups and assign the users or groups who should be able to sign in to Capsule.
3. Under Properties, keep Assignment required? set to Yes so only assigned users can complete SSO.

Capsule SSO is service-provider-initiated - users start from Capsule, not from the Microsoft My Apps portal:

• Go to the Capsule login page, enter a work email on an authorized domain, and confirm you're redirected to Microsoft and back into Capsule.

On first successful login, Capsule links the user's account automatically to existing Capsule users.

Sign-in always starts at Capsule. What that means for the Microsoft My Apps portal differs by protocol - see IdP-Initiated Login.

Capsule sign-in is always service-provider-initiated: the flow begins at Capsule, which picks the connection (from the email domain the user enters, or from an organization hint on the link) and then redirects to Microsoft. Whether you can offer users a launch point in the Microsoft My Apps portal depends on the protocol.

Capsule does not support IdP-initiated SAML sign-in. An unsolicited SAML response sent straight from Entra will not complete a login, so the Capsule tile in My Apps is a dead end.

Hide it to avoid confusion: open the enterprise application → Properties and set Visible to users? to No. Point users at the Capsule login page instead.

IdP-initiated login does not exist in OIDC - the protocol has no equivalent of an unsolicited SAML response. Every OIDC login is started by the service provider.

You can still give users a My Apps tile, because the tile is only a launch link: clicking it sends the browser to Capsule, which then starts the normal service-provider-initiated flow.

The tile cannot live on the OIDC application itself. Entra decides how to launch a tile from the service principal's single sign-on mode, and it never sets one for an app registration - the Single sign-on blade on that application offers no configuration, only a pointer back to the app registration. A tile on it fails with "App with ID <app-id> failed to launch" no matter what you set on the registration, including Home page URL.

Use a second Enterprise Application as the launcher instead. It carries the tile; your OIDC app registration still does the authentication.

1. In Capsule, go to Settings → Single Sign On → Identity Provider Configuration and copy the IdP-initiated login URL. It has the form:

   https://<capsule-portal-domain>/api/v1/auth/login?redirect_url=<capsule-portal-domain>&org=<your-organization-id>&auth0_org=<your-sso-organization-id>

2. In Entra, go to Entra ID → Enterprise apps → All applications and either open the Enterprise Application you created for SCIM provisioning, or select New application → Create your own application → Integrate any other application you don't find in the gallery (Non-gallery) if you don't have one. Reusing the SCIM application is fine and saves you an object to maintain.

3. In the application's Manage section, select Single sign-on → Linked, paste the IdP-initiated login URL as the sign-in page URL, then Save. Linked mode does no authentication of its own; it only sets where the tile sends the user, which is all that is needed here.

4. Under Users and groups, assign the users and groups who should see the tile, and under Properties set Visible to users? to Yes.

5. Open the enterprise application belonging to your OIDC app registration and set its Properties → Visible to users? to No, so users see one working tile instead of two.

Use the URL exactly as Capsule gives it to you, including the query string. The org and auth0_org parameters are what make the tile behave like IdP-initiated login: together they route the request straight to your organization's SSO connection, so the user is never asked for their email and goes directly to Microsoft, or straight into Capsule if they already have a live Entra session.

Do not point the tile at Capsule's Callback URL (Redirect URI), or at an Auth0 /authorize URL. Both only accept requests belonging to a login Capsule already started, and return an error page.

If the tile opens Capsule but still asks for the user's email, one of the two parameters was dropped - Capsule only applies the hint when both are present, and otherwise falls back to the email prompt rather than failing. Re-copy the URL from the settings page.

Because the launcher only opens a URL, assignment on it controls who sees the tile, not who can sign in. Access is still governed by assignment on the OIDC application, so keep the same users and groups on both.

An Enterprise Application with no single sign-on configured can never complete a login. If you are not using the SCIM application as a launcher, set its Properties → Visible to users? to No so users don't find a second Capsule tile in My Apps and try to sign in through it.

Entra's default SAML claims are all Capsule needs - no changes required:

The Name ID is the stable identifier Capsule keys the account on, so make sure it resolves to the user's email and stays consistent (see the UPN note in Step 1).

Capsule requests the openid profile email scopes and reads the claims from the ID token:

Because Auth0 does not call Entra's /userinfo endpoint for OIDC connections, a claim that is missing from the ID token is missing from Capsule. The email claim is the one Entra does not send by default, which is why the optional claim in Step 1 is mandatory.

With SSO alone, Capsule creates accounts just-in-time - a user exists in Capsule only after their first successful login. SCIM (System for Cross-domain Identity Management) upgrades this to full lifecycle management driven by Entra:

• Create - users assigned to the enterprise application are provisioned in Capsule before they ever sign in
• Update - profile changes in Entra (name, email) sync to Capsule automatically
• Deactivate - removing a user's assignment (or disabling them) deactivates their Capsule account, without waiting for a session to expire
• Groups - Entra groups sync to Capsule, where you can map them to Capsule roles

Capsule supports inbound SCIM 2.0 on top of either SSO connection type, SAML or OIDC - Entra pushes changes to a SCIM endpoint Capsule hosts; nothing flows back into Entra. Authentication uses bearer tokens you generate and revoke in the Capsule portal. SCIM does not change how users sign in - login still happens through SSO.

Using OIDC? SCIM needs a second Entra application. Entra only exposes the Provisioning blade on SAML-based and gallery enterprise applications, so an OIDC app registration has nowhere to enter Capsule's SCIM endpoint. Create a separate non-gallery Enterprise Application used only for provisioning (same steps as the SAML app in Step 1, but you never configure single sign-on on it) and set up Provisioning there. Sign-in keeps running through your OIDC app registration; the Capsule side is identical either way. Background: Microsoft Q&A - is SCIM provisioning not supported for OIDC-based apps.

The trade-off is that assignment lives in two places: a user must be assigned to the OIDC application to sign in, and to the provisioning application to be created and deactivated by SCIM. Assign the same users and groups to both.

As created, the provisioning application has no single sign-on configured, so a My Apps tile for it would lead users into a login that cannot work. Set its Properties → Visible to users? to No - unless you are also using it as the tile launcher described in IdP-Initiated Login, which is a supported way to get one object doing both jobs.

1. Go to Settings → Single Sign On. Below your SSO connection you'll find the SCIM provisioning section (it appears once SSO is configured).

2. In the identity provider dropdown, select Microsoft Entra ID.

   Capsule pre-selects Entra ID only for SAML connections, by recognizing a login.microsoftonline.com Sign In Endpoint. On an OIDC connection there is no detection and the dropdown defaults to Generic, so you must select Microsoft Entra ID yourself.

   The provider selection controls how Capsule matches SCIM-provisioned users to SSO logins. Entra sends the user's email as a work-typed address, so Capsule maps emails[type eq "work"].value to the account email. With the wrong provider selected, provisioned users can't be matched at login and end up as duplicate accounts.

3. Click Enable SCIM.

4. Copy the SCIM endpoint URL that appears. It already includes the ?aadOptscim062020 compatibility suffix Entra requires - use it as-is, don't append anything.

1. Under Provisioning tokens, click Generate token.
2. Copy the token from the dialog immediately - it is shown only once.

You can keep multiple tokens active (useful for rotation), see when each was created and last used, and revoke any token at any time.

1. In the Entra admin center, open the enterprise application that hosts provisioning - the SAML application you created in Step 1, or the separate provisioning-only Enterprise Application described in the callout above if you're using OIDC. Go to Provisioning and click on New configuration.

2. Fill in with Bearer authentication as the selected authentication method, and then click Create:

   • Tenant URL - paste the Capsule SCIM endpoint URL from Step 1 (the ?aadOptscim062020 suffix is already included)
   • Secret Token - paste the provisioning token from Step 2

3. Select Test Connection to verify, then Save.

Entra's default mappings match users on the wrong attribute, so one edit is required:

1. Under Manage → Provisioning → Mappings, open Provision Microsoft Entra ID Users.
2. Find the row that maps mail to emails[type eq "work"].value and edit it:
   • Match objects using this attribute - Yes
   • Matching precedence - 2
3. Save the mapping by clicking Ok, then Save.

While in Mappings, confirm Provision Microsoft Entra ID Groups is Enabled if you plan to map groups to Capsule roles (Step 6).

1. Users and groups assigned to the provisioning application are the ones Entra provisions. For SAML that is the same application you assigned in Step 4 of the SSO setup; for OIDC, assign them to the separate provisioning application as well.
2. To verify the setup immediately, use Provisioning → Provision on demand with an assigned user - the user should appear in Capsule under Settings → Users.
3. Under Provisioning, set Provisioning Status to On.

Entra runs an initial sync and then provisions incrementally, you can monitor the provisioning under Monitor → Provisioning logs.

Once Entra has provisioned your groups, you can drive Capsule roles from group membership:

1. In Capsule, go to Settings → Single Sign On → Group mappings and click Add mapping.
2. Pick an Entra group and the Capsule role its members should receive. The picker lists the built-in system roles alongside any custom roles your tenant has defined, and shows the permissions each one grants. If the group list is empty, assign the groups to the enterprise application, wait for a provisioning cycle, then click Refresh groups.

How group mappings behave:

• Roles are applied at every SSO sign-in, so membership changes in Entra take effect the next time the user logs in.
• While any mappings exist, group membership replaces manual role assignment - a user's role follows their groups.
• A user in multiple mapped groups is granted every matching role, and their effective permissions are the union of those roles.
• A user in no mapped group has their role removed at next sign-in.
• Removing all mappings returns the tenant to manual role management.

Click Disable SCIM to stop provisioning: the endpoint stops accepting requests and all provisioning tokens are revoked. Users that were already provisioned keep their access - manage or remove them from Settings → Users.

• No Provisioning blade on the application - you're looking at an OIDC app registration. Provisioning is only available on SAML-based and gallery enterprise applications; use a separate Enterprise Application as described above.
• Entra's "Test Connection" fails - confirm the Tenant URL matches the Capsule SCIM endpoint URL exactly (including the ?aadOptscim062020 suffix, exactly once) and the token hasn't been revoked in Capsule. Generate a fresh token if in doubt.
• Provisioned user can't sign in, or a duplicate account appears - the provider selection was likely wrong when SCIM was enabled, or the matching attribute wasn't updated. Confirm Microsoft Entra ID was selected in Capsule (it is not auto-detected on OIDC connections) and the work-email mapping has Matching precedence 2 (Step 4).
• No groups appear in the Capsule group-mapping picker - groups only appear after Entra provisions them. Assign the groups to the application, wait for a provisioning cycle (or select Provision on demand), then click Refresh groups in Capsule.

Cause: The email domain isn't in Authorized Domains for the connection.

Solution:

1. Confirm the address uses one of your configured domains (e.g., name@your-company.com).
2. In Capsule → Settings → Single Sign On, add the domain to Authorized Domains and click Save.

Cause: The user (or their group) isn't assigned to the enterprise application.

Solution:

1. In Entra → application → Users and groups, confirm the user or one of their groups is assigned.
2. Re-test SSO for that user.

Cause: A connection already exists, and Capsule locks the protocol for as long as it does.

Solution: Turn off Enable SSO configuration and click Save to remove the current connection, then enable SSO again and pick the other protocol. Configure the new Entra application before doing this, so the gap is short.

Cause: The SP values in Entra don't match what Capsule generated.

Solution:

1. AADSTS700016 (application not found) means the Identifier (Entity ID) doesn't match; AADSTS50011 (reply URL mismatch) means the Reply URL doesn't match.
2. In Entra → application → Single sign-on → Basic SAML Configuration, confirm both values match the Capsule Identifier (Entity ID) and Reply URL (ACS URL) exactly (no trailing spaces) - see Step 3.
3. Re-test after saving.

Cause: Capsule can't verify the SAML signature - usually because the Entra signing certificate was rotated or expired and Capsule has a stale copy.

Solution:

1. In Entra → application → Single sign-on → SAML Certificates, check the active certificate's expiry and download the current Certificate (Raw).
2. In Capsule, go to Settings → Single Sign On, re-upload the certificate under SSL/TLS Certificate, and click Save.

Cause: The Issuer URL isn't the tenant-specific v2.0 authority.

Solution:

1. Use https://login.microsoftonline.com/<your-entra-tenant-id>/v2.0 - no trailing slash, no extra path, and never /common or /organizations (their discovery documents return a templated issuer, which cannot pass issuer validation).
2. Capsule appends /.well-known/openid-configuration to the value you enter, so opening <issuer-url>/.well-known/openid-configuration in a browser is a quick way to confirm the URL is right - the issuer field in the response must match what you entered.
3. Correct the Issuer URL in Capsule and click Save.

Cause: The Entra app registration doesn't list Capsule's callback URL.

Solution:

1. Copy Callback URL (Redirect URI) from Capsule → Settings → Single Sign On → Identity Provider Configuration.
2. In Entra → app registration → Authentication → Web, add it to Redirect URIs exactly, then Save.

Cause: The client secret is wrong or expired - most often the Secret ID was copied instead of the secret Value.

Solution:

1. In Entra → app registration → Certificates & secrets, create a New client secret and copy its Value.
2. In Capsule → Settings → Single Sign On, paste it into Client Secret and click Save.

Cause: The ID token has no email claim. Auth0 does not call Entra's /userinfo endpoint for OIDC connections, so Capsule only sees claims that are in the token itself.

Solution:

1. In Entra → app registration → Token configuration, confirm the optional claim email is added for the ID token.
2. In API permissions, confirm openid, profile, and email (Microsoft Graph, delegated) are present with admin consent granted.
3. Have the user sign out and back in.

Cause: The tile is on the enterprise application belonging to an OIDC app registration. Entra launches a tile using the service principal's single sign-on mode, and it never sets one for an app registration, so there is nothing to open. Setting Home page URL on the registration does not fix it, and the Single sign-on blade on that application offers nothing to configure.

Solution: Put the tile on a separate Enterprise Application with Linked single sign-on pointing at Capsule's IdP-initiated login URL, and hide the OIDC application's own tile. Full steps in IdP-Initiated Login.

Cause: The name claims aren't being sent.

Solution:

1. SAML - in Entra → application → Single sign-on → Attributes & Claims, confirm the givenname and surname claims are present with sources user.givenname and user.surname.
2. OIDC - confirm the profile scope is granted in API permissions, which is what carries name, given_name, and family_name.
3. Have the user sign out and back in to refresh their profile.

• No passwords reach Capsule - authentication happens entirely in Microsoft Entra ID; Capsule only receives a signed SAML assertion or an OIDC ID token.
• Your policies stay in force - MFA, device compliance, session lifetime, and Conditional Access are enforced by Entra at sign-in.
• Verified assertions and tokens - for SAML, Capsule validates Entra's signature against your uploaded certificate. For OIDC, Capsule validates the ID token signature against the keys published in your tenant's discovery document and validates the issuer. Anything it can't verify is rejected.
• Secrets stay server-side - the OIDC connection uses the back-channel authorization code flow, so the client secret is never exposed to the browser. Capsule stores it write-only: it can be replaced, never read back.
• Owner-only configuration - only Capsule Owners can view or change the SSO connection.
• Access is governed in Entra - removing a user or group from the enterprise application immediately removes their ability to sign in via SSO.
• Email is the identity key - Capsule keys accounts on the email Entra sends (the SAML Name ID, or the OIDC email claim), so keep it stable to avoid duplicate accounts.

Need help with SSO?

• Documentation: docs.capsule.security
• Email Support: support@capsule.security

When contacting support, please include:

• Your Entra tenant ID
• The email domain(s) users sign in with
• Which protocol you configured, and the matching value - your Entra Login URL (SAML) or Issuer URL and Client ID (OIDC). Never send your client secret.
• Any AADSTS error codes, or screenshots of the error page (the error usually appears after the redirect back from Microsoft)
• Timestamp when the issue occurred