Single sign-on

An enterprise deployment — one you run yourself — signs people in through your own identity provider: Entra ID, Okta, Ping, Keycloak, or anything else that publishes an OpenID Connect discovery document.

Note

This page is for the enterprise and OSS editions. The cloud edition at app.shield360.ai signs people in on Base316’s hosted pages instead and has no SSO settings of its own.

Connecting your provider

Register Shield360 as an OIDC application, with the redirect URI https://shield360.example.com/api/auth/callback/sso, then set:

SSO_OIDC_ISSUER=https://login.example.com/oauth2/default
SSO_OIDC_CLIENT_ID=<the application's client id>
SSO_OIDC_CLIENT_SECRET=<the application's client secret>

Shield360 reads the provider’s /.well-known/openid-configuration, so there is nothing else to configure, and sign-in uses PKCE.

Caution

Connecting a provider closes the email and password form. That provider becomes the only way in, so that there is no second front door past it — and no way to register an account around the joining rules below.

Everyone who already had an account keeps it: signing in through the provider attaches to the existing account with the same email address rather than creating a second one. The lever if the provider is ever unreachable is the configuration that selects it — unset SSO_OIDC_ISSUER and restart.

The older BASE316_OIDC_* names are still read underneath these, so a deployment configured before the two paths were separated keeps working.

Mapping groups to roles

Your provider knows which groups somebody is in. Shield360 knows what a role may do. SSO_OIDC_ROLE_MAP connects the two:

SSO_OIDC_ROLES_CLAIM=groups     # the claim your provider puts groups in
SSO_OIDC_ROLE_MAP='{"Security Team":"compliance","Platform":"admin","Engineering":"analyst"}'

• Keys are group names exactly as your provider sends them; values are Shield360 role keys, including any custom role you have created.
• When somebody is in several mapped groups, the first match in the map wins — the order you wrote it is the order it is read.
• Anybody no group matches gets the organisation’s default role, set under Organisation → Members → Roles. Nobody is left with no role at all.
• A map naming a role that does not exist falls through to the default and says so in the logs, rather than granting something arbitrary. A map that is not valid JSON maps nobody, for the same reason.
• An organisation’s own role of a given key wins over the system role of that key.

The groups scope is requested only when a mapping exists to read it with, since some providers reject a scope they do not recognise. Override the scopes entirely with SSO_OIDC_SCOPES if your provider needs different ones.

By default the mapping is re-applied on every sign-in, so removing somebody from a group at your provider takes that access away here. If you would rather assign roles in Shield360 and have the provider only authenticate:

SSO_OIDC_SYNC_ROLES_ON_LOGIN=false

Who is admitted at all

Authenticating is not the same as being admitted. Under Organisation → Members → Roles, Joining decides what happens when somebody your provider authenticates has no Shield360 membership yet:

• By invitation only (the default) — they are turned away and told to ask an administrator. No account is created.
• Anyone your identity provider signs in — they become a member on first sign-in, with the role their groups map to.

The second is right when your provider’s application assignment is already the gate. The first is right when it is not — a provider that authenticates every employee is not saying every employee belongs in Shield360.

Either way the refusal is recorded in the audit log, against the organisation that refused them, so an administrator can see who tried and why they were turned away.

On a deployment with more than one organisation nobody is admitted automatically, because guessing which one somebody belongs to is how data leaks between them.

How long access lasts

A session lasts a day. Roles are re-applied and admission is re-checked when somebody signs in, so this is also the longest that somebody removed at your provider keeps access here. Shortening it trades that lag against how often people are sent back to the provider.