> ## Documentation Index
> Fetch the complete documentation index at: https://docs.streampixel.io/llms.txt
> Use this file to discover all available pages before exploring further.

# SSO access

> Restrict a stream to people who can sign in with your organisation's own identity provider.

SSO access puts your own login in front of a stream. Viewers are sent to your identity provider, sign in there, and come back to the stream only if they succeed. Streampixel never sees their password; it only receives the signed identity your provider issues.

Use it when a stream is for your staff, your customers, or a partner organisation, and a shared password is not good enough.

<Info>
  SSO works with any provider that supports **OpenID Connect**: Microsoft Entra ID (Azure AD), Okta, Auth0, Google Workspace, Keycloak and others. It is an access control for *viewers of a stream*. It is separate from how you sign in to the dashboard.
</Info>

## How it fits with the other access controls

A project has one access mode. **Password** and **SSO** are alternatives: turning one on turns the other off. **Domain restrictions** work alongside either, and SSO requires them, see below.

|                      | Public               | Password                 | SSO                                                                                       |
| -------------------- | -------------------- | ------------------------ | ----------------------------------------------------------------------------------------- |
| Who can watch        | Anyone with the link | Anyone with the password | Anyone who can sign in with your provider, optionally narrowed by domain, group or person |
| What the viewer does | Nothing              | Types a password         | Signs in with the account they already have                                               |
| Where it is set      | Project Settings     | Project Settings         | Settings → SSO, then Project Settings                                                     |

## Step 1: connect your identity provider

This is done once per account, under **Settings → SSO**. A connection can then be used by any number of projects.

1. In your identity provider, create an **OpenID Connect web application** and register this redirect URL exactly:

   ```text theme={"dark"}
   https://platform.streampixel.io/api/v1/stream/sso/callback
   ```

2. In Streampixel, open **Settings → SSO** and click **Add connection**. Fill in:

| Field             | What to enter                                                                                                                                                                                                      |
| ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **Name**          | Anything you like. Viewers see it on the sign-in button.                                                                                                                                                           |
| **Issuer**        | Your provider's issuer URL, for example `https://login.microsoftonline.com/<tenant-id>/v2.0` or `https://<your-org>.okta.com`. It must be public `https` and match what the provider's discovery document reports. |
| **Client ID**     | From the application you created.                                                                                                                                                                                  |
| **Client secret** | From the same application. It is stored encrypted and never shown again; to change it, enter a new one.                                                                                                            |
| **Scopes**        | Leave the default `openid profile email` unless your provider needs more.                                                                                                                                          |
| **Groups claim**  | The token claim that carries group membership. `groups` for most providers. Only matters if you restrict by group.                                                                                                 |

3. Save. The connection appears in the list with its issuer.

## Step 2: turn it on for a project

1. Open the project and go to **Project Settings**.
2. Under **Domain restrictions**, make sure at least one allowed domain is listed. SSO delivers a one-time sign-in grant to the page that embeds the stream, and that page must be one you trust. The dashboard refuses to enable SSO on a project with an empty list, with the message *Add at least one allowed domain to the allowlist before enabling SSO*.
3. In the **SSO Access** card, choose your connection from the **Identity provider** dropdown. *Off — no SSO* switches it off again.
4. **Save**.

With just these steps, **any user who can sign in with that provider may view the stream**, and Password protection is off for the project.

## What viewers see

1. The stream page shows a sign-in button instead of the stream.
2. They are sent to your provider. If they are already signed in there, this can be instant.
3. They land back on the stream and it loads.

If they are refused, they see *Your account does not have access to this stream.* A sign-in that took too long shows *That sign-in link expired. Please try again.* Both are safe to retry.

The same gate applies to the private preview link in [Test Locally](/resources/dashboard/test-locally), so you can check the experience before sharing anything.

## Narrowing who gets in

<Note>
  These rules are part of the project's SSO policy and are applied on every sign-in. They are not yet editable in the dashboard; ask support to set them for a project, or set them through the API.
</Note>

Three lists can be attached to a project. All three are optional.

| List                      | Rule                                                                                                             |
| ------------------------- | ---------------------------------------------------------------------------------------------------------------- |
| **Allowed email domains** | The signed-in user's email address must end in one of these domains, for example `example.com`.                  |
| **Allowed groups**        | The user's token must carry at least one of these group values in the groups claim configured on the connection. |
| **Allowed users**         | Specific users, by email address or by the provider's subject id.                                                |

How they combine:

* A user on the **allowed users** list is always admitted, whatever the other lists say.
* If neither domains nor groups are set, signing in is the only requirement. If *only* an allowed-users list is set, everyone else is refused.
* If domains are set, the address must match one of them. A provider that explicitly marks an address as unverified is refused. Providers that simply do not report verification, which includes Microsoft Entra, are accepted; enable **Require verified email** on the connection if you want the strict behaviour.
* If groups are set, the user must be in at least one.

## Troubleshooting

| Symptom                                                                | Cause                                                                                                                                          |
| ---------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
| Provider shows a redirect URI error                                    | The callback URL was not registered on the application, or was registered with a typo. It must match character for character.                  |
| Sign-in fails immediately after returning from the provider            | The client secret is wrong. A common slip is pasting the client ID into the secret field.                                                      |
| *Your account does not have access to this stream* for everyone        | A domain or group rule that nobody matches. Check the groups claim name on the connection against what the provider actually emits.            |
| Entra users refused by a group rule despite being in the group         | Entra stops including groups in the token for users in more than about 150 groups. Use a domain rule or an allowed-users list for those users. |
| Cannot enable SSO on the project                                       | The domain allow-list is empty. Add the domains that embed the stream first.                                                                   |
| Viewers on an embedded page see the stream page reload with no sign-in | The embedding page's domain is not on the allow-list, so the grant is not delivered there. Add it.                                             |