Security

Admin → Security configures how people authenticate. By default, SEMANTIX uses local accounts. Enabling SSO switches sign-in to your identity provider.

Supported providers

Provider	Protocol	User provisioning
Microsoft Entra ID (Azure AD)	OIDC	Manual
Okta	OIDC	Manual

These two are what is supported. Other OIDC providers may work, but they are not tested configurations.

What you need

• Issuer URL — e.g. https://login.microsoftonline.com/<tenant-id>/v2.0
• Client ID
• Client secret — stored encrypted, displayed masked thereafter
• Scopes — defaults to openid email profile
• Redirect URI — add this in your provider: <your-semantix-domain>/api/auth/sso/callback
• Email claim — which claim carries the email address; the email claim is used by default. This is the field the local user is matched on, so it must match the email in Admin → Users exactly.

Caution

The redirect URI must match byte for byte, including scheme and trailing path. A mismatch here is the single most common SSO failure, and the error usually points somewhere unhelpful — check the URI in your provider first.

What happens on first sign-in

The person is matched to an existing local user by email address. If there is no match, SSO does not create one: an admin creates the user first, assigns a role, and grants a scope.

This is deliberate. Auto-provisioning on first sign-in would let anyone with an email at your provider get a tenant account, and a scope grant is a decision someone should make on purpose.

Migrating existing users

Existing local accounts keep working. Their email is the join key, so confirm the email claim in your provider returns the same value the local account holds — otherwise a user signs in successfully and lands with no access.

Sessions

• Sessions are stateless JWTs signed with the deployment secret.
• Sessions are not revocable individually. Shortening the token lifetime shortens the window in which a leaked token remains useful.
• Disabling SSO in the configuration does not invalidate tokens already issued.

Self-hosted and the deployment secret

SSO token signing depends on a secret key in the deployment environment. If it is not set, one is generated and written to the backend data volume. On a multi-instance deployment, set it explicitly and identically everywhere — otherwise instances issue tokens the others reject, which presents to users as random logouts.