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 |
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:
- 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).
- Sign-out redirect URI:
https://app.stoutdata.ai/.
- Grant type: Authorization Code.
- Login initiated by: App Only (so Okta’s dashboard launches SSO correctly).
- 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.
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.
Configuring Stout (OIDC)
In Stout, open Settings → SSO:
- Select OIDC.
- Paste the Client ID, Client Secret, and Issuer URL.
- Add an optional group → role mapping: e.g.
hardware-admins → admin, hardware-eng → member. Users not in any mapped group become plain members.
- Click Save.
Testing the OIDC login
- Open an incognito window and go to
https://app.stoutdata.ai/login.
- Click Sign in with SSO and enter your org slug.
- 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 |
Configuring Stout (SAML)
In Stout, open Settings → SSO:
- Select SAML.
- Paste the IdP’s Entity ID, SSO URL, and X.509 certificate (PEM, with or without the
-----BEGIN CERTIFICATE----- markers).
- Add an optional attribute → role mapping (same model as OIDC groups).
- Click Save.
Stout requires both wantAuthnResponseSigned and wantAssertionsSigned, so your IdP must sign both the response and the assertion.
Testing the SAML login
- Open an incognito window and go to
https://app.stoutdata.ai/login.
- Click Sign in with SSO and enter your org slug.
- 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.
