Single sign-on (SSO)
With single sign-on (SSO), the users of your Verified Domains sign in through your company’s identity provider (IdP), such as Microsoft Entra ID, Okta or Google Workspace, with SAML 2.0 or OpenID Connect (OIDC). You set it up on the Sign-in page of the Admin App, with the Right to manage sign-in. Admins hold it.
Your IdP is trusted only for emails of your Verified Domains, so verify at least one domain first. Users of other domains, such as guests and contractors, keep signing in with a password while you allow it.
On the Sign-in page, under Single sign-on (SSO), choose SAML 2.0 or OpenID Connect first. The page then shows the values your IdP needs, with buttons to copy them.
Set up SAML
Section titled “Set up SAML”Register the Strategy Agent at your IdP as a SAML application, in Microsoft Entra ID an enterprise application, with:
| Setting | Value |
|---|---|
| Reply URL (ACS URL) | https://scavenger-strategy-agent-<environment>.auth.eu-central-1.amazoncognito.com/saml2/idpresponse |
| Identifier (audience) | urn:amazon:cognito:sp:<user pool ID> |
| Email attribute (claim) | http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress |
| Name ID | A value that never changes for the user, such as their object ID |
The Sign-in page shows the exact ACS URL and audience of your environment to copy. Microsoft Entra ID sends the email in that attribute by default; with other IdPs, such as Okta or Google Workspace, add an attribute statement of that name with the user’s email.
Then give the Strategy Agent your IdP’s metadata:
- In the Admin App, select Sign-in.
- Under Single sign-on (SSO), choose SAML 2.0.
- Choose From a URL and enter your IdP’s metadata URL, in Microsoft Entra ID the App Federation Metadata URL, or choose From a file and select the metadata XML file your IdP offers for download, up to 128 KB.
- Select Set up SSO.
Amazon Cognito, which signs your users in, reads the metadata when you save. If it is refused, check that the URL is reachable from the internet or that the file is your IdP’s SAML metadata. When your IdP’s signing certificate changes, give the metadata again and select Save.
Set up OpenID Connect
Section titled “Set up OpenID Connect”Register the Strategy Agent at your IdP as a web application, often called an OIDC or OAuth client, with:
| Setting | Value |
|---|---|
| Redirect URI | https://scavenger-strategy-agent-<environment>.auth.eu-central-1.amazoncognito.com/oauth2/idpresponse |
| Scopes | openid email |
| Grant type | Authorization code, with a client secret |
The Sign-in page shows the exact redirect URI of your environment to copy. Your IdP then gives you a client ID and a client secret. It must send the user’s email in the email claim.
- In the Admin App, select Sign-in.
- Under Single sign-on (SSO), choose OpenID Connect and enter your IdP’s issuer URL, such as
https://login.example.com, the client ID and the client secret. - Select Set up SSO.
The issuer URL is the address your IdP publishes its discovery document under, at /.well-known/openid-configuration. If the details are refused, check that this document is reachable.
The client secret goes to Amazon Cognito and is never stored by us nor shown again. To change the details later, enter them again with the secret and select Save.
To switch from one protocol to the other, remove SSO and set it up again.
How your users sign in
Section titled “How your users sign in”Your users enter their email on the sign-in page as before. For an email of one of your Verified Domains, the page offers to continue with your Tenant’s name and sends the user on to your IdP. When several Tenants with SSO verified the same domain, the user chooses theirs by name. Every user may also choose Sign in with password instead: a user who belongs to another Tenant that accepts passwords gets in there.
A user who already has an account, because they signed up with a password before you set up SSO, keeps it at their first sign-in through your IdP: their Roles, their Conversations and their memberships of other Tenants stay as they are. A user who isn’t a member of your Tenant yet joins it as a Member. You change their Roles on the Users page like anyone else’s. Your IdP’s own multi-factor authentication counts: users who sign in through it aren’t asked for two-step verification.
Passwords once SSO is on
Section titled “Passwords once SSO is on”Once SSO is on, users of your Verified Domains sign in to your Tenant only through your IdP, not with a password. Users of other domains may keep signing in with a password while Allow passwords for users of other domains is on. You may now also turn Allow sign-in with a password off: then everyone signs in through your IdP. See Sign-in and MFA.
A user who works in several Tenants and switches into yours from a password session is asked to sign in through your IdP first.
Remove SSO
Section titled “Remove SSO”To switch IdPs or go back to passwords, select Remove SSO on the Sign-in page and confirm. This deletes your IdP’s connection to the Strategy Agent. Every account stays as it is, with its memberships and Conversations.
- Users of your Verified Domains sign in with a password again. Users who never set one choose Forgot your password? at sign-in and set one with the code they get by email.
- If you had turned Allow sign-in with a password off, it is turned on again, so that nobody is locked out.
- Whoever is signed in through your IdP can’t renew their session and is signed out within 15 minutes, you too if you are.
What the Audit Log shows
Section titled “What the Audit Log shows”Setting up SSO, changing its details and removing it each leave an entry in the Audit Log with who did it and when, never the details. Every user who joins through SSO leaves an entry too, and so does turning passwords on again when you remove SSO.