> For the complete documentation index, see [llms.txt](https://docs.cogram.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.cogram.com/organization-administration/single-sign-on-sso.md).

# Single sign-on (SSO)

SAML-based SSO is supported as part of Cogram's Enterprise plan. Includes the service provider details and the Microsoft Entra ID (Azure AD) setup steps.

Cogram supports user authentication through SAML 2.0. Single Sign-On lets your team sign in to Cogram with your existing identity provider, under your own password, MFA, and conditional access policies.

Setup is a joint exercise: you configure Cogram as an application in your identity provider, send Cogram the resulting metadata, and Cogram registers your domain. Email <mark style="color:blue;"><support@cogram.com></mark> to start, and we will confirm each step with you.

## Service provider details

Cogram is the service provider. Use these values wherever your identity provider asks for them.

| Field                                        | Value                                                          |
| -------------------------------------------- | -------------------------------------------------------------- |
| Identifier (Entity ID)                       | `https://prod1.us-east-1.cogram.com/auth/v1/sso/saml/metadata` |
| Reply / Assertion Consumer Service (ACS) URL | `https://prod1.us-east-1.cogram.com/auth/v1/sso/saml/acs`      |
| Metadata URL                                 | `https://prod1.us-east-1.cogram.com/auth/v1/sso/saml/metadata` |
| NameID format                                | `emailAddress` or `persistent`                                 |

## Microsoft Entra ID (Azure AD)

> **Who:** an administrator who can create enterprise applications in your Microsoft Entra ID tenant.

### 1. Create the application

1. Open the [Microsoft Azure portal](https://portal.azure.com/).
2. Go to [**Enterprise applications**](https://portal.azure.com/#view/Microsoft_AAD_IAM/StartboardApplicationsMenuBlade/~/AppAppsPreview) and click **New application**.

<figure><img src="https://1170756420-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FxpPm3rHOzFMoBqV20UQl%2Fuploads%2Fgit-blob-15cf80e88cec4f290a70290b172c37ddda6a2462%2Fentra-new-application.png?alt=media" alt="Enterprise applications page with the New application button highlighted in the toolbar" width="1420"><figcaption><p>Enterprise applications → New application</p></figcaption></figure>

3. Click **Create your own application**.
4. Name the application, for example `Cogram SAML SSO`, choose **Integrate any other application you don't find in the gallery (Non-gallery)**, and click **Create**.

<figure><img src="https://1170756420-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FxpPm3rHOzFMoBqV20UQl%2Fuploads%2Fgit-blob-2cc14080d5d2a4153eeff57774180cefefc4b6f7%2Fentra-create-own-app.png?alt=media" alt="Create your own application panel with the name field and the Non-gallery option highlighted" width="584"><figcaption><p>Name the app and pick Non-gallery</p></figcaption></figure>

### 2. Configure SAML

1. On the application's landing page, click **Set up single sign on** → **Get started**. If that tile is not there, open **Manage** → **Single sign-on** in the left sidebar.
2. Choose **SAML**.
3. Under **1. Basic SAML Configuration**, click **Edit** and enter the [service provider details](#service-provider-details): the Entity ID as **Identifier**, and the ACS URL as **Reply URL**. Click **Save**. **Sign on URL**, **Relay State**, and **Logout Url** stay empty.

<figure><img src="https://1170756420-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FxpPm3rHOzFMoBqV20UQl%2Fuploads%2Fgit-blob-d501aeeb4283e1d6111e77c4cc728051a1a4de59%2Fentra-basic-saml-config.png?alt=media" alt="Basic SAML Configuration card showing the Cogram Identifier and Reply URL, with the optional fields left blank" width="760"><figcaption><p>Basic SAML Configuration, filled in with Cogram's Entity ID and ACS URL</p></figcaption></figure>

### 3. Map the attribute claims

Cogram reads the user's email address and name from the assertion, so these four claims have to be present. Some are mapped by default.

1. Under **2. Attributes & Claims**, click **Edit**.
2. Open **Required claim** → **Unique User Identifier** and confirm the **Name identifier format** is **Email address**.
3. Check the following under **Additional claims** and add anything missing:

| Claim name                                                           | Source attribute         |
| -------------------------------------------------------------------- | ------------------------ |
| `http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress` | `user.mail`              |
| `http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname`    | `user.givenname`         |
| `http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name`         | `user.userprincipalname` |
| `http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname`      | `user.surname`           |

Entra shortens the claim names in the summary card. A correct configuration looks like this:

<figure><img src="https://1170756420-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FxpPm3rHOzFMoBqV20UQl%2Fuploads%2Fgit-blob-dc9edccf62fd24854bf73c271c5aff24b238a6c6%2Fentra-attributes-claims.png?alt=media" alt="Attributes and Claims card listing givenname, surname, emailaddress, name, and Unique User Identifier with their source attributes" width="760"><figcaption><p>Attributes &#x26; Claims: four additional claims plus the Unique User Identifier</p></figcaption></figure>

### 4. Send Cogram your metadata

Under **3. SAML Certificates**, download the **Federation Metadata XML** and send the file to <mark style="color:blue;"><support@cogram.com></mark>. Cogram uses it to register your identity provider and link it to your email domain.

<figure><img src="https://1170756420-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FxpPm3rHOzFMoBqV20UQl%2Fuploads%2Fgit-blob-ddab344585f826c8bd10aefb85c771bfda6f79f5%2Fentra-federation-metadata.png?alt=media" alt="SAML Certificates card with the Federation Metadata XML download link highlighted" width="760"><figcaption><p>SAML Certificates → Federation Metadata XML → Download</p></figcaption></figure>

### 5. Assign users

Go to **Manage** → **Users and groups** and assign the people and groups who should have Cogram. Add yourself at minimum, so you can test the connection before rolling it out.

## Testing the connection

Once Cogram confirms your identity provider is registered, go to [**Sign in**](https://app.cogram.com/auth/login) and click **SSO**.

<figure><img src="https://1170756420-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FxpPm3rHOzFMoBqV20UQl%2Fuploads%2Fgit-blob-6d436740efa530a4bab1b0424f0e3878dab04fe0%2Fcogram-login-sso-button.png?alt=media" alt="Cogram sign-in page with the SSO button below the Google and Microsoft options highlighted" width="713"><figcaption><p>The SSO button on the Cogram sign-in page</p></figcaption></figure>

Enter a work email address on your SSO domain and click **Sign in**. Cogram reads the domain, redirects you to Microsoft, and returns you to your Cogram dashboard after you authenticate.

## Troubleshooting

**Sign-in fails with an assertion or audience error.** The Identifier in Entra ID does not match Cogram's Entity ID exactly. Copy it again from [Service provider details](#service-provider-details), including the trailing path.

**Sign-in succeeds at Microsoft but Cogram shows an error.** An attribute claim is missing or empty. Check the four claims in step 3, and confirm the user account has a value in `user.mail`.

**A user gets "you do not have access to this application".** They are not assigned to the enterprise application. Assign them under **Manage** → **Users and groups**.

**Users still sign in with a password.** Cogram can enforce SSO for your organization so password sign-in is refused. Ask <mark style="color:blue;"><support@cogram.com></mark> to turn this on once your rollout is complete.

## Next steps

* [Organization roles](/organization-administration/organization-roles.md): what each role can do once users are signed in
* [Groups](/organization-administration/groups.md): syncing group membership from Microsoft Entra ID


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.cogram.com/organization-administration/single-sign-on-sso.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.