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

## Overview

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](#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.

## How It Works

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.


## Prerequisites

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](/guides/user-roles).
- 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`)


## Choosing a Protocol

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

|  | SAML 2.0 | OIDC |
|  --- | --- | --- |
| Entra object | Enterprise application (non-gallery) | App registration |
| Secret you manage | Signing certificate (Entra rotates it, typically every 3 years) | Client secret (you choose the expiry, max 24 months) |
| Extra Entra config | Name ID must resolve to the user's email | Optional `email` claim must be added to the ID token |
| SCIM provisioning | Configured on the same enterprise application | Requires a **second** Enterprise Application, see [SCIM Provisioning](#scim-provisioning-optional) |


> 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 Overview

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


## Step 1: Create the Application in Entra

Follow the section for the protocol you chose.

### SAML: create an enterprise application

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](https://entra.microsoft.com) 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.


### OIDC: create an app registration

1. Sign in to the [Microsoft Entra admin center](https://entra.microsoft.com) 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.


## Step 2: Configure the Connection in Capsule

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](#idp-initiated-login).


## Step 3: Copy Capsule's Values Back into Entra

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

### SAML

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


### OIDC

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


## Step 4: Assign Users and Test

### Assign access in Entra

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.


### Test the connection

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](#idp-initiated-login).


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

### SAML

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.

### OIDC

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.

#### If you use SCIM but don't want a tile

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.

## Attribute Mapping

### SAML claims

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

| Entra claim (default source) | Maps to in Capsule | Required |
|  --- | --- | --- |
| **Unique User Identifier (Name ID)** - `user.userprincipalname` | User identity (unique ID) | Yes |
| `emailaddress` - `user.mail` | Email | No |
| `givenname` - `user.givenname` | First name | No |
| `surname` - `user.surname` | Last name | No |


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

### OIDC claims

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

| ID token claim | Source | Maps to in Capsule | Required |
|  --- | --- | --- | --- |
| `sub` | Entra | User identity (unique ID) | Yes |
| `email` | Optional claim you added in Step 1 | Email, account linking | Yes |
| `name`, `given_name`, `family_name` | `profile` scope | Display name | No |


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.

## SCIM Provisioning (Optional)

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](https://learn.microsoft.com/en-us/answers/questions/274675/is-scim-provisioning-not-supported-for-oidc-based).
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](#idp-initiated-login), which is a supported way to get one object doing both jobs.


### Step 1: Enable SCIM in Capsule

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.


### Step 2: Generate a Provisioning Token

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.

### Step 3: Configure Provisioning in Entra

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


### Step 4: Fix the Matching Attribute

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

### Step 5: Assign and Start

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

### Step 6: Map Entra Groups to Capsule Roles (Optional)

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.


### Disabling SCIM

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

### SCIM Troubleshooting

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


## Troubleshooting

### "Email" entered on the Capsule login page doesn't redirect to Microsoft

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


### User gets AADSTS50105 ("not assigned to a role")

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


### Can't switch the protocol - the other option is greyed out

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

### SAML: redirected to Microsoft, but login fails with an AADSTS error

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


### SAML: login succeeds in Microsoft but Capsule rejects the assertion

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


### OIDC: saving the connection fails, or login fails on issuer validation

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


### OIDC: login fails with AADSTS50011 (redirect URI mismatch)

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


### OIDC: Microsoft returns `invalid_client` or AADSTS7000215

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


### OIDC: user signs in but Capsule can't link the account, or their email is blank

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


### My Apps tile fails with "App with ID <app-id> failed to launch"

**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](#idp-initiated-login).

### User reaches Capsule but their name is blank

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


## Security & Privacy

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


## Support

Need help with SSO?

- **Documentation**: [docs.capsule.security](https://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