Documentation
Single sign on (SSO)
Let your team sign in through your identity provider with OpenID Connect, and turn password sign in off for the workspace.
Ansengine signs people in through any identity provider that speaks OpenID Connect, with the authorization code flow and PKCE. Every plan includes it. The workspace owner sets it up under Settings, Security; an admin can read the settings and cannot change them.
SAML is not supported. If your provider offers both, choose OpenID Connect.
Set up your identity provider
| In your provider | Use |
|---|---|
| Application | A web application using OpenID Connect and the authorization code flow. |
| Sign in redirect URI | Copy it from Settings, Security, where it is shown as Redirect URI. It is the Ansengine web address followed by /auth/sso/callback, and it must match exactly. |
| Scopes | openid, email and profile. Ansengine asks for these three and no others. |
| Client authentication | Client secret, sent in the body of the token request (the method OpenID Connect calls client_secret_post). |
| Token signing | RS256, with the signing key published at your provider's JWKS address. A token signed any other way is refused. |
| Initiate login URI, if asked | The Ansengine web address followed by /auth/sso. A link in your provider's app list then opens the Ansengine sign in page, with the address filled in when your provider passes login_hint. |
Connect it in Ansengine
| Field | What it takes |
|---|---|
| Issuer | Your provider's issuer URL, over https. When you save, Ansengine reads the issuer's /.well-known/openid-configuration and refuses the connection unless that document names the same issuer and https addresses for authorization, tokens and signing keys. |
| Client ID | From the application you created in your provider. |
| Client secret | From the same application. It is encrypted when saved and never shown again, here or in the account export. It is required the first time you connect; after that, leave the field blank to keep the stored one, or type a new one to replace it. |
| Email domains | The domains whose addresses sign in through this connection, from 1 to 20, such as yourcompany.com. Your provider can sign a token for any address, so only these domains are accepted from it, and each one only after you prove you control it, as the next section explains. |
| New members join as | Viewer, member or admin; member unless you choose. Never owner, so a sign in can never create the seat that can delete the account. |
Prove each email domain
Listing a domain only claims it. A claim sends nobody to your provider and signs nobody in: Ansengine acts on a domain once you prove you control it with a DNS record.
- 1Save the connection. Settings, Security lists each email domain as not verified, with the TXT record to add for it.
- 2Add that record where the domain's DNS is managed. Its name is _ansengine-sso, a dot, then the domain (_ansengine-sso.yourcompany.com for yourcompany.com). Its value is ansengine-sso= followed by your workspace's code, exactly as Settings shows it.
- 3Press Verify beside the domain. Ansengine looks the record up and marks the domain verified when a TXT record at that name holds exactly that value. When it finds no record, or one that holds something else, nothing changes and Settings says which. A new record can take a while to be seen, so try again later.
- One code serves every domain your workspace claims. It stays the same when you edit the connection; removing the connection and connecting again gives a new one, and each domain has to be verified again.
- A domain can be verified by one Ansengine workspace at a time. If another workspace verified it first, Verify says so, and that workspace has to remove the domain from its email domains before yours can verify it.
- Removing a domain from the list, or removing the connection, gives up its verification, and another workspace can then verify it.
- Only the owner can verify a domain.
How a person signs in
- 1On the Ansengine sign in page they choose Use single sign on, or they follow your provider's link to it.
- 2They enter their work email. If its domain is one you verified, Ansengine sends them to your provider. That sign in link works once and expires after 10 minutes.
- 3Your provider signs them in and sends them back. Ansengine checks the ID token: its signature against your provider's published keys, the issuer, that it was issued for your client ID, the one time value of this sign in (the nonce), its expiry with two minutes of clock tolerance, and an email address your provider does not mark unverified.
- 4The address must be at a domain you verified, and it must not belong to a member of another Ansengine workspace. Either one refuses the sign in.
- 5They land in the workspace with the same 30 day session a password sign in gives.
A member your provider has deactivated through SCIM is refused too. No session is opened, and the page tells them their access has been turned off and to ask the workspace owner.
People new to the workspace
The first time someone at a verified domain signs in, Ansengine adds them with the role under New members join as, and marks their email verified, because your provider proved it. They have no password; they can set one only with the password reset link. Change their role later under Settings, Team: your provider's groups and claims are not read.
Each person added this way takes a seat on your plan, as an invited member does. A viewer takes no paid seat, and a workspace holds at most 100 viewers. When no seat is left, the sign in is refused, nobody is added, and the page names the workspace owner, who can free a seat or change the plan.
Someone you invited who signs in through your provider joins as the member you invited, with the role you chose.
Enforcing single sign on
Enforced, the password sign in refuses every member of the workspace, whatever their address, before it checks the password. The owner turns it on and off under Settings, Security.
- It can be turned on only once a domain is verified and at least one person has signed in through the connection, so an untested provider cannot lock everyone out.
- It holds only while at least one domain is verified. If you remove the last one, your provider can sign nobody in, so password sign in works again instead of locking everyone out.
- Turning it on ends no session and revokes no API key. They keep working until they expire, are revoked, or their holder is removed or deactivated.
- A member whose address is not at a verified domain cannot sign in at all while it is on: the password is refused, and your provider is offered only to verified domains. Change their address or remove them first.
- An invitation sets no password while it is on. Accepting one sends the person to your provider's sign in instead, and they join when they sign in there, so invite people at a verified domain.
- Removing the connection turns password sign in back on for everyone. People who joined through your provider have no password until they reset one.
The audit log under Settings records each change to the connection and to enforcement, each domain verified, each sign in through your provider, and each person it added. The client secret is never written to it.
If Settings, Security says single sign on is not available on this deployment, the server has no key to encrypt your client secret with, and nothing on your side can turn it on.