> For the complete documentation index, see [llms.txt](https://docs.mediarithmics.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.mediarithmics.io/setup-and-monitor/manage-the-platform/set-up-single-sign-on.md).

# Set up single sign-on

Route your users to your own identity provider instead of mediarithmics email and password login.

## Your goal

Let your teams log in to mediarithmics through your own identity provider, so that account access follows your existing identity policies.

## Expected outcome

Users created in a given organisation are redirected to your identity provider when they log in, and the organisations you did not configure keep the default email-and-password flow.

## Prerequisites

* **You are at community level.** Identity providers are created at community level. If you do not see the **Identity providers** section under **Settings > Organisation > Single Sign On**, you are not on a community. See [How your instance is organised](/setup-and-monitor/plan-and-integrate/set-up-the-environment/prerequisites-organisation-and-datamart.md#organisations-and-communities).
* **The users exist in mediarithmics first.** In both authentication models you must create the user in the platform before they can connect. This is deliberate: it ensures only intended users get access to the tools, even when your own identity provider handles the login. See [Manage users and roles](/setup-and-monitor/manage-the-platform/manage-users-and-roles.md).
* **Your identity provider speaks SAML 2.0.**

{% hint style="info" %}
OAuth 2.0 and OpenID Connect are not currently supported. They are considered candidates on the product roadmap - contact your account manager if this is an important requirement for your organisation.
{% endhint %}

## Set it up

{% stepper %}
{% step %}

### Declare the identity provider

Go to **Settings > Organisation > Single Sign On** and click **New identity provider**. Provide:

| Field                        | What it is                                                                                                            |
| ---------------------------- | --------------------------------------------------------------------------------------------------------------------- |
| **Name**                     | How you will recognise the provider in the configuration screen.                                                      |
| **Description**              | Optional additional detail.                                                                                           |
| **Type**                     | `SAML_V2_0`. This is currently the only supported value; contact your account manager if you need another.            |
| **Import metadata.xml**      | The URL of the `metadata.xml` on your server.                                                                         |
| **Want assertion signed**    | Optional. Indicates whether this provider expects a signed assertion.                                                 |
| **Post logout redirect URI** | Optional. Where users are sent after logging out. By default they are redirected to `https://auth.mediarithmics.com`. |

Click **Save**.
{% endstep %}

{% step %}

### Authorise mediarithmics in your identity provider

You need to authorise the mediarithmics application on your side. Doing so requires information from the platform - such as the `redirectURL` and the `identityId`. Click on your external SSO entry in the platform to read those values.
{% endstep %}

{% step %}

### Associate the provider with an organisation

In the **Associations organisations and identity providers** card, click **Edit**, select an identity provider for each organisation, and save.

From then on, every user created in that organisation is redirected to your identity provider during their authentication flow.

{% hint style="info" %}
You can create several identity providers and assign them to different organisations, but **an organisation can only have one identity provider**.
{% endhint %}
{% endstep %}
{% endstepper %}

## Worked example

Take this hierarchy:

```
Community_A
|- Organisation_B
|- Organisation_C
```

Declare `Identity_Provider_1` in `Community_A` and associate it with `Community_A` only. Users created directly at community level are redirected to `Identity_Provider_1`; a user of `Organisation_B` still uses the default email-and-password process.

Then declare `Identity_Provider_2` for users of `Organisation_C`. It must still be created at community level, but it only starts routing users once you associate it with `Organisation_C`.

The result:

| Where the user was created | How they log in            |
| -------------------------- | -------------------------- |
| `Community_A`              | `Identity_Provider_1`      |
| `Organisation_B`           | Default email and password |
| `Organisation_C`           | `Identity_Provider_2`      |

## Remove an external SSO

An external SSO can only be removed when it is not associated with any organisation.

{% stepper %}
{% step %}

### Remove the associations

For each organisation associated with the provider, select `mediarithmics standard login` as its identity provider.
{% endstep %}

{% step %}

### Delete the provider

Once no association remains, find the identity provider, open its menu, and choose **Delete**.
{% endstep %}
{% endstepper %}

## Verify

* A user created in a configured organisation is redirected to your identity provider on login.
* A user in a non-configured organisation still sees the standard login.
* Logging out lands on the redirect URI you configured, if you set one.

## Troubleshooting

| Symptom                                                      | Likely cause                                                                                                                                                                  |
| ------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| The **Identity providers** section is missing                | You are not at community level.                                                                                                                                               |
| A user is not redirected to your provider                    | The organisation they were created in has no association, or has a different provider associated with it.                                                                     |
| A user can authenticate with your provider but has no access | Authentication is not authorisation. The user still needs at least one role - see [Manage users and roles](/setup-and-monitor/manage-the-platform/manage-users-and-roles.md). |
| The provider cannot be deleted                               | It is still associated with at least one organisation.                                                                                                                        |

## Related pages

<table data-view="cards" data-search="false"><thead><tr><th></th><th></th><th data-hidden data-card-target data-type="content-ref"></th></tr></thead><tbody><tr><td><strong>Manage users and roles</strong></td><td>Create the users, and give them access.</td><td><a href="/setup-and-monitor/manage-the-platform/manage-users-and-roles.md">Manage users and roles</a></td></tr><tr><td><strong>Manage API access</strong></td><td>Authentication for machine-to-machine access.</td><td><a href="/setup-and-monitor/manage-the-platform/manage-api-access.md">Manage API access</a></td></tr></tbody></table>


---

# 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 by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.mediarithmics.io/setup-and-monitor/manage-the-platform/set-up-single-sign-on.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.