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

# Single sign-on

> Configure OIDC or SAML so your team signs in with their corporate identity.

Stout supports single sign-on via either **OpenID Connect (OIDC)** or **SAML 2.0**. Pick whichever your identity provider and security team prefer — both schemes are shipping features and share the same group-to-role mapping model.

## What SSO gives you

* Users sign in through your identity provider — no per-app password to manage.
* You can mandate MFA, conditional access, and session policies centrally at the IdP.
* Group claims from OIDC (or attributes from SAML) can be mapped to Stout roles, so new hires in the `hardware-eng` group become Stout members automatically.
* Deprovisioning a user at the IdP also blocks them from Stout at next login.

Secrets and certificates you upload are encrypted at rest with AES-256 using a key derived from the server's `SSO_ENCRYPTION_KEY`, and they're never echoed back in API responses.

## Choosing OIDC or SAML

| You want                                                                      | Pick     |
| ----------------------------------------------------------------------------- | -------- |
| Modern OAuth 2.0 flow, JSON claims, easy to test with curl                    | **OIDC** |
| Legacy IdP, SAML-only policy, or XML-signed assertions required by compliance | **SAML** |

Both end up at the same place: the user lands on the Stout dashboard as a member of your org, with their role derived from the group/attribute mapping.

***

## OIDC

Stout's OIDC flow is a standard Authorization Code flow with PKCE. Okta is the most common IdP; Auth0, Azure AD, Google, and any OIDC-compliant provider work the same way.

### Setting up Okta (OIDC example)

In Okta, create a new **OIDC - Web Application**:

1. **Sign-in redirect URI:** `https://api.stoutdata.ai/api/orgs/<your-org-slug>/sso/oidc/callback` (Stout shows the exact URL on the config page).
2. **Sign-out redirect URI:** `https://app.stoutdata.ai/`.
3. **Grant type:** Authorization Code.
4. **Login initiated by:** App Only (so Okta's dashboard launches SSO correctly).
5. **Group claims:** add a `groups` claim filter scoped to the groups you want Stout to see.

After saving, copy the **Client ID**, **Client Secret**, and **Issuer URL**.

<Note>
  If you enable Okta's *Federation Broker Mode*, individual users may be
  blocked from the app even when "Allow everyone" is selected. The reliable
  fix is to disable Federation Broker Mode and assign users/groups directly.
</Note>

### Configuring Stout (OIDC)

In Stout, open **Settings → SSO**:

1. Select **OIDC**.
2. Paste the Client ID, Client Secret, and Issuer URL.
3. Add an optional **group → role mapping**: e.g. `hardware-admins → admin`, `hardware-eng → member`. Users not in any mapped group become plain members.
4. Click **Save**.

### Testing the OIDC login

1. Open an incognito window and go to `https://app.stoutdata.ai/login`.
2. Click **Sign in with SSO** and enter your org slug.
3. The IdP should redirect through its auth flow and drop you back on the Stout dashboard.

***

## SAML

Stout acts as the SAML Service Provider. Your IdP signs the `SAMLResponse`; Stout validates the signature, checks `InResponseTo` against request IDs it actually issued, and enforces a 60-second clock-skew window.

### Endpoints you'll give your IdP

| Endpoint                              | URL                                                                   |
| ------------------------------------- | --------------------------------------------------------------------- |
| **ACS (Assertion Consumer Service)**  | `https://api.stoutdata.ai/api/orgs/<your-org-slug>/sso/saml/acs`      |
| **Entity ID / SP metadata**           | `https://api.stoutdata.ai/api/orgs/<your-org-slug>/sso/saml/metadata` |
| **SSO initiation URL** (SP-initiated) | `https://api.stoutdata.ai/api/orgs/<your-org-slug>/sso/saml/login`    |

The metadata endpoint returns standard SAML SP metadata XML you can upload directly to most IdPs.

### Configuring Stout (SAML)

In Stout, open **Settings → SSO**:

1. Select **SAML**.
2. Paste the IdP's **Entity ID**, **SSO URL**, and **X.509 certificate** (PEM, with or without the `-----BEGIN CERTIFICATE-----` markers).
3. Add an optional **attribute → role mapping** (same model as OIDC groups).
4. Click **Save**.

Stout requires both `wantAuthnResponseSigned` and `wantAssertionsSigned`, so your IdP must sign both the response and the assertion.

### Testing the SAML login

1. Open an incognito window and go to `https://app.stoutdata.ai/login`.
2. Click **Sign in with SSO** and enter your org slug.
3. Stout redirects to your IdP, which posts a signed SAMLResponse back to the ACS URL. On success you land on the Stout dashboard.

***

## Troubleshooting

* **"You are not allowed to access this app"** (Okta) — usually Federation Broker Mode. Disable it and assign users/groups directly.
* **Loops back to the login page** — the redirect URI or ACS URL in the IdP doesn't exactly match the one Stout generated. Check for trailing slashes and `http` vs `https`.
* **SAML response rejected for clock skew** — Stout accepts 60 seconds of clock drift. If your IdP and your control-plane host differ by more than that, sync both against NTP.
* **SAML response rejected for missing `InResponseTo`** — Stout rejects IdP-initiated SAML by design. Start the flow from Stout (`/api/orgs/<slug>/sso/saml/login`) or configure your IdP to issue a matching `InResponseTo`.
* **New SSO users land in the wrong org** — Stout routes a user to their first/personal org by default. Use the org switcher in the top-left to navigate to the intended org, and confirm the group/attribute mapping is producing the right role.