Single sign-on

Each team can let its members sign in through the organisation's identity provider: Microsoft Entra ID, any OpenID Connect provider, or Active Directory / LDAP through an OpenID Connect broker such as Keycloak. Directory groups can grant team roles automatically, and removing someone from the directory removes their access.

1. Enable single sign-on on the server

Add these settings to the .env file in ~/apps/scansuite and restart ScanSuite:

If the provider supports it, also register the back-channel logout URL https://<scansuite host>/sso/backchannel-logout. ScanSuite then ends a person's sessions as soon as the provider signs them out.

2. Register ScanSuite with the provider

Microsoft Entra ID

1. 01
   Create an app registration

   Single tenant, with the web redirect URI https://<scansuite host>/sso/callback and a client secret.

2. 02
   Add the groups claim

   Token configuration → Add groups claim → Security groups, emitted as Group ID in the ID token.

3. 03
   Grant GroupMember.Read.All

   API permissions → Microsoft Graph → Application permissions, with admin consent. ScanSuite uses it to read group members every 30 minutes and to read the groups of people in many groups. Without it, group changes apply only at the next sign-in, and people in very many groups cannot sign in through groups.

Issuer: https://login.microsoftonline.com/<tenant ID>/v2.0. Discovery URL: the issuer followed by /.well-known/openid-configuration.

Other OpenID Connect providers

Register a confidential client with the redirect URI above and use the provider's issuer and discovery URL. To grant roles through groups, the provider must put a groups claim (a list of group names or IDs) into the ID token. Without it, link members individually.

Active Directory / LDAP

ScanSuite does not connect to LDAP directly and never sees directory passwords. It trusts a broker that federates the directory. With Keycloak:

• add an LDAP user federation (Active Directory, ldaps://, read-only), with objectGUID as the UUID attribute so identities never change;
• add a group LDAP mapper;
• create a confidential OpenID Connect client with the redirect URI above;
• add a Group Membership mapper that writes groups into the ID token with the full group path, for example /corp/security/scanners.

Disabling a user in Active Directory takes effect at their next sign-in, when the broker sends a back-channel logout, or at the latest after SSO_MAX_STALE_SECONDS.

3. Connect the team

A team admin opens Teams → Team settings → Single sign-on, chooses the provider type (Microsoft Entra ID, OpenID Connect or AD / LDAP federation broker), enters the issuer, discovery URL, client ID and client secret, and saves.

Test connection checks the provider's discovery document, its signing keys and, for Entra with group mappings, access to Microsoft Graph. The result of the last test stays visible, next to the last successful sign-in.

zoom_inEnlarge

Members then sign in at https://<scansuite host>/sso/<team>.

4. Decide who gets access

The provider proves who someone is; the team decides what they may do.

Members who come from directory groups show as managed by directory. Their role follows their groups: it is read again at every sign-in and, for Entra, every 30 minutes. Someone who leaves every mapped group loses access. Team admins can still suspend them, but not change their role. Groups never change the role of members the team added itself.

zoom_inEnlarge

5. Require single sign-on (optional)

Under Sign-in policy, Require single sign-on refuses password sign-ins for the team. To avoid locking the team out, it can be switched on only:

• by a team admin who is signed in through the team's single sign-on right now;
• with at least one emergency account: an active team admin with a password, who can still sign in if the provider is down. Every emergency sign-in is recorded in the team audit log.

zoom_inEnlarge

Checking that it works