Skip to main content
Single sign-on (SSO) lets people sign in to Stout with their account at your identity provider. Stout supports SSO through OpenID Connect (OIDC). The SSO settings page includes setup steps for Okta.

​
Before you start

  • You must be an owner of the organization. An admin cannot configure SSO.
  • You must verify your email in Stout. Stout does not save an SSO configuration for an unverified email.
  • You need admin access to your identity provider.

​
How sign-in works

  1. The person opens the Stout sign-in page and types the slug of your organization in Organization Slug.
  2. The person selects Continue with SSO, and Stout sends the person to your identity provider.
  3. The person signs in at the identity provider within 10 minutes. The identity provider sends the person back, and Stout signs them in.
The first time that a person signs in through SSO, Stout creates their account and adds them to your organization. If an account with the same email already exists, Stout adds your organization to that account. When Stout creates the account, it uses the name that your identity provider sends as the display name of the person. A display name must be unique in the organization, because box locks are held under it. If another member already uses that name, the new account starts without a display name, and the person sets one on the Account page. After that, an SSO sign-in does not change the display name. The person changes it on the Account page. At each SSO sign-in, Stout copies only the picture that your identity provider sends.

​
Roles for SSO users

When Stout adds a person at their first SSO sign-in, it gives them a role:
  • If the person belongs to a group in Owner Groups, the role is Owner.
  • If not, the role is Member.
SSO never gives the Admin role. Later sign-ins do not change the role. To change a role, use Team Permissions.

​
Set up SSO with Okta

The SSO page has an Okta Setup Instructions section. Select it to show the steps. The values in that section use the addresses of your Stout install, so copy them from the page and not from these docs. The Okta steps are, in short:
  1. In the Okta Admin Console, create an app integration with the sign-in method OIDC – OpenID Connect and the application type Web Application.
  2. Add the Sign-in redirect URI and the Sign-out redirect URI that the Stout page shows.
  3. Assign the users or groups that can sign in.
  4. On the default authorization server, add an access policy with a rule for the Authorization Code grant.
  5. To map groups to roles, add a groups claim to the ID token.
  6. Copy the Client ID and the Client Secret of the app into the Stout form.
The sign-in redirect URI contains the ID of your organization, not the slug. Copy it exactly as the page shows it.
If Okta shows Enable immediate access with Federation Broker Mode, leave it off. When it is on, Okta blocks users, even the users that you assign to the app.
Use the issuer of the default custom authorization server, for example https://your-domain.okta.com/oauth2/default. The org authorization server cannot run the access policy and the claims from these steps. If you skip the access policy, sign-in fails with no_matching_policy after the person authenticates.

​
Configure Stout

Fill in the Configure OIDC form on the SSO page: Then select Save Configuration. Stout encrypts the client secret and never shows it again. After the first save, the form title changes to Update OIDC Configuration. Stout asks your identity provider for the openid, email, and profile scopes. Stout reads the groups from the ID token. If the identity provider does not send an email claim, sign-in fails. If your email is not verified, the form shows Resend verification email. Select it, open the link in the email that you get, and save the form again.

​
Test the connection

After you save the form, select Test Connection at the top of the page. Stout checks that it can reach the issuer and read its OIDC discovery document. A successful test does not prove that a person can sign in. To test a full sign-in, select Enable SSO, save the form, and sign in from a private browser window. When SSO is on, the page shows Share with your team and Your SSO login URL. The link opens the sign-in page with the slug of your organization already in Organization Slug. The person then selects Continue with SSO.

​
Remove a person

When you remove a person at your identity provider, also remove them in Team Permissions. Stout does not end a session because the identity provider removed the person.
A Stout session uses a refresh token that lasts 7 days. Each time the dashboard refreshes the session, Stout issues a new refresh token that lasts 7 days. A session also has a maximum age of 30 days from sign-in. After 30 days, the dashboard asks the person to sign in again, even if they used Stout every day. For an SSO account, that sign-in goes through your identity provider again. When you remove the person from the organization, they lose access to it at once.

​
Accounts that use SSO

An account that Stout creates at an SSO sign-in has no Stout password. That account signs in only through SSO. It cannot get a reset link from Forgot password?, it cannot change its email or password in Stout, and it cannot accept an invitation link. An account that was created from an invitation, with a password, becomes an SSO account the first time that it signs in through SSO. From then on, the same rules apply to it: it cannot get a reset link, and it cannot change its email or password in Stout.