Microsoft Entra ID SSO (SAML)

Let your team sign in to the Capsule portal with their Microsoft credentials using SAML 2.0 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 SAML identity provider (IdP); Capsule uses Auth0 as its identity broker (the service provider, SP) and accepts the SAML assertion Entra issues at sign-in.

You configure SSO yourself from Settings → Single Sign On in the Capsule portal. Setup is a round trip with Entra: create an enterprise application in Entra, paste Entra's Login URL and certificate into Capsule, then copy the SP 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 posts a signed SAML assertion back to Capsule's ACS URL.
5. Capsule validates the assertion 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)
• A verified email domain your users sign in with (e.g., your-company.com)

Setup is a round trip between the Microsoft Entra admin center and the Capsule Single Sign On settings:

1. Create an enterprise application in Entra and enable SAML (with placeholder URLs for now)
2. Configure the connection in Capsule - paste Entra's Login URL and certificate, set your domains, then copy the SP values Capsule generates
3. Copy Capsule's SP values back into the Entra application
4. Assign users and test

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.

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

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

2. Turn on Enable SAML SSO configuration. SAML is the supported protocol; others are coming soon.

3. Fill in the fields:

   • 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.
   • 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.

4. Click Save.

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

   • Identifier (Entity ID)
   • Reply URL (ACS URL)

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 application's Manage section, select Users and groups and assign the users or groups who should be able to sign in to Capsule.
2. 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.

Capsule does not support IdP-initiated sign-in, so the Capsule tile in the My Apps portal won't complete a login. To avoid confusion, hide it: in the application's Properties, set Visible to users? to No.

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).

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 the SAML connection you configured above - 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 SAML SSO.

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, confirm Microsoft Entra ID is selected. Capsule pre-selects it when your Sign In Endpoint is a login.microsoftonline.com URL.

   The provider selection controls how Capsule matches SCIM-provisioned users to SAML 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 same enterprise application you created for SAML, then 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 application (Step 4 of the SSO setup) are the ones Entra provisions.
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 - Admin, Security Admin, Viewer, or Legal Discovery. 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 gets the highest-privilege role among them.
• 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.

• 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 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 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 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: The givenname / surname claims aren't being sent, or were removed from the default claim set.

Solution:

1. In Entra → application → Single sign-on → Attributes & Claims, confirm the givenname and surname claims are present with sources user.givenname and user.surname.
2. 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.
• Your policies stay in force - MFA, device compliance, session lifetime, and Conditional Access are enforced by Entra at sign-in.
• Signed assertions - Capsule validates Entra's SAML signature against your uploaded certificate and rejects anything it can't verify.
• 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 Name ID (email), 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
• Your Entra Login URL
• Any AADSTS error codes, or screenshots of SAML error pages (the error usually appears after the redirect back from Microsoft)
• Timestamp when the issue occurred