Enterprise SSO (SAML 2.0 / OpenID Connect)
Connect sign-in to the Pushizo dashboard to your identity provider (Okta, Microsoft Entra ID, Google Workspace, Keycloak, OneLogin…). SSO is on the Enterprise plan. Decisions: ADR-0023.
Connect sign-in to the Pushizo dashboard to your identity provider (Okta, Microsoft Entra ID, Google Workspace, Keycloak, OneLogin…). SSO is on the Enterprise plan. Decisions: docs/adr/0023-kurumsal-kimlik-sso-scim-jwt.md.
1. Verify your domain
Add your company email domain (e.g. sirket.com) under Organization → Security & SSO → Domains. Add the TXT record shown to your DNS and click Verify:
| Name | Value |
|---|---|
_pushizo-verify.sirket.com | pushizo-verify=<token> |
SSO only accepts emails on verified domains; even if the identity provider vouches for another domain, the account is not matched. A domain can be verified in only one organization at a time.
2. Create a connection
SSO connections → New connection. The connection is saved as a draft; enter the SP values from the Values to enter in your identity provider section into your IdP.
OpenID Connect
| Pushizo field | Description |
|---|---|
| Issuer URL | e.g. https://sirket.okta.com, https://login.microsoftonline.com/<tenant>/v2.0, https://keycloak.sirket.com/realms/<realm> — endpoints are filled in from .well-known/openid-configuration |
| Client ID / Client secret | The values of the "Web" application you created in the IdP (the secret is stored encrypted and never shown again) |
| Groups claim | The claim that carries groups for role mapping (default groups) |
In the IdP, enter https://<API>/sso/oidc/<connection>/callback as the redirect URI. Flow: Authorization Code + PKCE (S256) + nonce; the id_token signature, issuer, audience and expiry are validated. The email claim is required; email_verified: false is rejected.
SAML 2.0
| Pushizo field | IdP value |
|---|---|
| IdP Entity ID | Issuer / Entity ID |
| IdP SSO URL | SAML 2.0 HTTP-Redirect SSO address |
| IdP signing certificate | X.509 (PEM or base64). When rotating certificates, add the new one |
Enter in the IdP: SP Entity ID / Audience = https://<API>/sso/saml/<connection>/metadata, ACS (Reply) URL = https://<API>/sso/saml/<connection>/acs, NameID format emailAddress. The metadata file can be downloaded from the same address. The assertion must be signed; InResponseTo, Audience and NotBefore/NotOnOrAfter (120 s tolerance) are checked, and the same assertion is not accepted twice.
Attributes: email from email/mail/NameID; name from displayName/name; groups from groups or Entra ID's groups claim. IdP-initiated sign-in (app catalog) is off by default; if you turn it on, sign-in CSRF protection is only complete in the SP-initiated flow.
3. Role mapping and JIT
- Default role: assigned when no group matches.
- Group → role: one
group=roleper line (e.g.hs-admins=admin). With multiple matches, the most privileged role applies;owneris never granted or revoked via SSO. The role is synced on every sign-in. - JIT: if the account or membership doesn't exist, it is created automatically (when off, only existing members can sign in). The plan's role gate and member quota apply.
4. Test and enable
Test sign-in goes to the IdP without creating a session; on return it shows the claims, the mapped role and the domain status. Then set the connection to Active (a verified domain is required). Users click Sign in with enterprise SSO on the login screen and enter their email.
5. "SSO only"
When on, members can access this organization only through SSO; sessions opened with a password or Google/GitHub get 403 HS_SSO_REQUIRED, and they are closed when the setting is turned on. To prevent lockouts:
- Only the owner can turn it on, and a successful test sign-in (or a session opened with SSO) is required first.
- The owner is given 10 single-use recovery codes (only their digests are stored). If SSO stops working, the owner uses I have an SSO recovery code on the login screen and enters their password + a code.
- While enforcement is on, the last active connection or the last verified domain cannot be removed.
API
All management endpoints are part of the session-authenticated dashboard API (org.manage): GET/POST /internal/v1/orgs/{orgId}/sso/connections, …/domains, PUT …/sso/enforcement, POST …/sso/recovery-codes. Details: API Explorer → internal:sso.
Data residency (EU / Turkey regions)
Pushizo runs each data region as a separate cell: the EU (Frankfurt) and Turkey (Istanbul) cells each have their own database, queue, analytics store and file storage. An organization's subscription,…
Member provisioning with SCIM 2.0
Your identity provider (Okta, Microsoft Entra ID, OneLogin, JumpCloud…) automatically adds Pushizo members, updates their roles and removes those who leave via SCIM 2.0. SCIM is on the Enterprise plan and is used together with SSO…