7.5 Federated sign-in

Included from Basic tieridentity:builtinidentity:sso

After this you can: register an identity provider connection, test it, say who a federated user becomes, shape who gets in and as whom, and know where step-up fits.

Before you start — tick each one:

• Lesson 7.2 — Users, groups, rules, policies (opschain learn 7.2)

In the GUI: the Identity providers panel in the Operations area lists the connections with their group mappings, test and sweep; each enabled connection is a button on the login page.

Local users (lesson 7.2) are always available, but an enterprise estate signs in through its directory. An identity provider connection federates sign-in to OIDC, GitHub or LDAP — registered at runtime from the admin plane, no server restart, one connection per provider instance. The steps on the provider's own side (the GitHub App, the Google Cloud client, the Entra ID app registration, the directory service account) are the guide opschain docs getting-started/identity-providers-setup; this lesson is the connection itself.

1. Register the connection

Each connection is addressed by its code — the immutable /auth/login/{code} path segment users sign in through — and carries a kind (oidc | github | ldap), the sign-in presentation (display name and button order on the login page), the kind's adapter configuration (issuer, claims and scopes for OIDC; directory fields for LDAP), a step-up mode and an enabled flag. The client secret (OIDC, GitHub) or service bind password (LDAP) is encrypted and write-only: requests carry it via env or prompt, and reads report only whether one is stored.

OPSCHAIN_IDP_SECRET=cs.xxxx opschain admin identity providers create okta-prod \
  --kind oidc --issuer https://example.okta.com --client-id my-client \
  --display-name Okta --credential-env OPSCHAIN_IDP_SECRET

Created identity provider okta-prod (kind oidc) — run 'opschain admin identity providers test okta-prod'

Microsoft Entra ID takes --tenant-id instead of --issuer; an ldap connection takes --directory-url, --bind-dn and the directory attributes (opschain docs cli/admin-identity-providers-create). The built-in packaged providers (GitHub, Google, Entra ID) register under the baseline identity:builtin feature; customer-configured OIDC instances and group-to-role mapping are the enterprise SSO capability (identity:sso in opschain admin licence features).

2. Test it

Probe the connection the way a sign-in would start — OIDC discovery and the key set, or an LDAP service bind and user search — before anyone tries the button:

opschain admin identity providers test okta-prod

Identity provider okta-prod: connection test succeeded

The lifecycle verbs follow the same shape: list (code, kind, display, step-up, enabled, order), show, update (a supplied credential rotates the secret), delete (its users can no longer sign in through it), and for LDAP sweep — import users by directory query, re-key identities and disable leavers in one audited pass, so the directory stays the source of truth over time, not just at first sign-in.

3. Who the user becomes

A federated sign-in resolves to one principal with a stable identity per provider — the same person signing in through two providers is two principals unless you map them. Two levers shape what a federated user may do:

• Group→role mappings translate the provider's group claims into platform roles and group memberships, so directory membership drives authority — declared, listable, audited:

  opschain admin identity mappings create --provider okta-prod \
      --provider-group platform-ops --group-name app-operators

  Created group mapping 019a…2e11: okta-prod:platform-ops -> group app-operators

  A mapping grants exactly one of --group-name (a group whose policies then apply, lesson 7.2) or --role (a security role, lesson 7.4).

• Password login is local-only: a federated principal has no platform password, and opschain passwd refuses — credential lifecycle belongs to the directory.

4. Shape who gets in, and as whom

Four optional per-connection controls shape auto-provisioning (create/update, or the GUI dialog):

• Default group (--default-group): every identity that matches no explicit group mapping resolves into the named group — the catch-all for providers that emit no usable groups. Precedence per connection: explicit mapping > email-domain rule > default group.
• Email-domain rules (--email-domain-rule yourcompany.com=staff, repeatable): place identities by verified email domain ahead of the default group — your staff land in a wider-access group while every other domain falls through to the default.
• Company-email policy: --require-hosted-domain (oidc kind) refuses sign-ins whose verified ID token carries no hosted-domain (hd) claim — work Google accounts only; and --deny-public-email-domains refuses auto-provisioning from public mail providers (a built-in list covering gmail, outlook, yahoo and friends; override it with repeatable --public-email-domain entries). Refusals tell the visitor to use their work identity — they never echo the address.
• Pseudonymous provisioning (--pseudonymous-provisioning): auto-provisioned users get an opaque Visitor-<n> name on every surface other users can read, while the real name and email stay on the user record for administrators and exports. First provisioning only — existing users keep their names.

To cut a whole provider's population off at once, disable the connection: every identity of that connection stops signing in, and its live sessions end with it (lesson 7.3).

5. Step-up

A connection's step-up mode (--step-up idp|platform; GitHub and LDAP kinds are platform-only) controls how its sessions re-authenticate for the verbs on the step-up floor: platform demands a platform TOTP factor, idp sends the session back to the provider's own MFA. The ceremony itself is lesson 7.4.

Check yourself

• What does --default-group do, and what does a user from an unmapped group become without it?
• Which verb proves a connection before anyone signs in through it?

What you learned

• A connection is a code, a kind, a presentation and a write-only credential, registered at runtime.
• test probes it the way a sign-in would start; sweep keeps an LDAP population true over time.
• A federated user is one principal per provider; group mappings drive their authority.
• Default group, domain rules, company-email policy and pseudonymous provisioning shape auto-provisioning.
• The step-up mode decides whether the provider or the platform re-proves the user.

Next: this closes the module Who may act — back to your track (opschain learn).