SSO · SAML & OIDC
Sign in to Industric through your identity provider. Register Industric as an app in the IdP, enter the provider values in the dashboard, and the browser sign-in flow mints the same User JWT a password login would.
Industric does browser single sign-on over SAML 2.0 and OIDC (OpenID Connect). Configure both per tenant under Dashboard → Identity providers, with the idp:write permission. Use whichever protocol your IdP exposes. Okta, Microsoft Entra, Google, Auth0, Ping, and Keycloak all support one or both.
How sign-in works
A user enters their work email on the login page. Industric looks up which provider serves that domain and bounces the browser to your IdP. The IdP authenticates them and redirects back with an assertion (SAML) or an id_token (OIDC). Industric validates it, creates or updates the user, applies their group memberships, and issues a User JWT, the same token a password login mints. There's no separate SSO session store. The JWT is the session.
Add a provider
Open Identity providers, choose SAML 2.0 or OIDC, and give it a display name (what users see on the login page). The editor has a form view for the common fields and a YAML view for the full config. Secrets (client secrets, signing keys) are write-only: once saved they never render back, and leaving a secret field blank on edit keeps the stored value.
Configure SAML 2.0
Industric is the service provider (SP). Create the IdP side first so you have the SSO URL, entity ID, and signing certificate to paste in. Industric publishes its SP metadata for the IdP to consume:
1SP metadata GET /api/v1/sso/saml/{idp-id}/metadata2ACS (reply) POST /api/v1/sso/saml/{idp-id}/acs3SP entity ID https://exo/sp/{idp-id} (override if your IdP needs a URL)Then fill the Industric side:
| Field | Maps to | Notes | Example |
|---|---|---|---|
| IdP SSO URL | sso_url | Where Industric sends the auth request | https://acme.okta.com/app/exo/abc123/sso/saml |
| IdP entity ID | entity_id | Issuer of the assertion | http://www.okta.com/exkabc123 |
| IdP signing cert | x509_cert | PEM, used to verify the assertion | -----BEGIN CERTIFICATE----- MIIC… |
| SP entity ID | sp_entity_id | Optional; defaults to https://exo/sp/{id} | https://exo/sp/{id} |
| ACS URL | acs_url | Optional; defaults to the /acs route above | https://exo.acme.com/api/v1/sso/saml/{idp-id}/acs |
| Email attribute | attribute_mapping.email | Claim carrying the user's email | email |
| Name attribute | attribute_mapping.name | Claim carrying display name | displayName |
| Groups attribute | attribute_mapping.groups | Multi-valued claim of group names | groups |
email/groups; Entra uses claim URIs). Email links the assertion to an Industric user, so it's required.Configure OIDC
Register Industric as a web app in your IdP, set the redirect URI to the callback below, and copy the client credentials in. Industric reads the IdP's /.well-known/openid-configuration from the issuer, so you supply the issuer URL, not every endpoint.
GET /api/v1/sso/oidc/{idp-id}/callback| Field | Maps to | Notes | Example |
|---|---|---|---|
| Issuer URL | issuer | Base URL; Industric fetches the discovery doc | https://login.microsoftonline.com/acme.onmicrosoft.com/v2.0 |
| Client ID | client_id | From the IdP app registration | 12345678-9abc-def0-1234-56789abcdef0 |
| Client secret | client_secret | Write-only after save | wxy8Q~… |
| Redirect URI | redirect_uri | Must equal the callback registered above | https://exo.acme.com/api/v1/sso/oidc/{idp-id}/callback |
| Scopes | scopes | Optional; defaults to openid email profile groups | openid email profile groups |
| Email claim | email_claim | Optional; defaults to "email" | email |
| Name claim | name_claim | Optional; defaults to "name" | name |
| Groups claim | groups_claim | Optional; defaults to "groups" | groups |
The flow uses Authorization Code with PKCE. Industric validates the id_token's issuer, audience, and expiry, then reads email, name, and groups from the claims you named above.
groups claim by default, and when you add one (App registration → Token configuration → Add groups claim) it carries group object IDs, GUIDs, not names. If your synced groups show up GUID-named, that's why. Either configure the claim to emit names (possible for on-prem-synced groups) or pair SSO with directory sync, which reads proper group names over Graph.Default provider & discovery
Mark one provider Default for SSO discovery so users who land on the login page without a matched email still get a sign-in button. Email discovery is rate-limited and nonce-protected against account enumeration. Nothing to configure there.
Groups & roles
Every group name in the assertion or token reconciles into an Industric group on each sign-in, but groups don't carry roles: a user's role is assigned directly, one per user, and first-time SSO users land as Member. Groups scope access instead; use them as principals on per-agent access lists. See Roles & permissions. To keep the full directory in sync between logins, including deactivations, pair SSO with SCIM or directory sync.
Test & roll out
Save the provider disabled first, use the row's Test button to check the config, then enable it and run a real sign-in end to end. Enable is reversible: toggling a provider off stops new SSO logins through it at once, without deleting the config.