Authentication settings | Data Observability platform

General options

Create user on first log in - Users from secondary authentication systems will be created automatically on initial login. The Default role dropdown (shown when enabled) selects the role assigned to them.
Enable OAuth - Enable secondary authentication for OAuth
Enable LDAP/AD - Enable secondary authentication for LDAP/AD

The OAuth and LDAP/AD sections below appear once their toggle is enabled. Changes are applied with the Save button at the bottom of the form.

Use OpenID – enable OpenID for OAuth endpoint
Self-signed cert – Force OAuth to validate self-signed certificate from provided certificates
Server URL – URL where current SelectZero deployment is hosted
Auth endpoint – OAuth server authentication endpoint
Token endpoint – OAuth server token endpoint
Client endpoint – OAuth user-info endpoint; shown and required only when Use OpenID is disabled
Client ID – OAuth client ID
Client secret – OAuth client secret. Click the padlock icon to unlock the field for entering a new value; the stored secret is never displayed
Scope – OAuth authorization scope
Username field – OAuth username field
Display name field – If Create user on first log in is enabled, the value of this attribute from the OAuth user-info response is used as the new user's display name (e.g. name for Google, preferred_username for some providers). Leave empty to skip and fall back to the username.
Groups field – ID-token claim (OpenID) or user-info field containing the user's groups, used for automatic role syncing. Leave empty to disable role syncing for OAuth logins. Note that Microsoft Entra ID emits group object IDs in the groups claim unless the app registration is configured to emit group names.

Type – LDAP
Server – LDAP server host (and port, e.g. ldap-server.domain.com:389); the ldap:///ldaps:// scheme is selected in front of the field
Base DN – LDAP server root distinguished name (If group name has whitespaces then wrap it between quotes e.g. OU=”group name”)
User DN – Optional user DN which will be prepended to base DN for user search
Search by – LDAP filter for search user (for example uid)
Name field – If "Create user on first log in" is enabled, we can assign display name from user attribute
Group DN – Group DN which will be prepended to base DN for group search. Required when role syncing is enabled, because it also bounds which groups are allowed to grant a role. Optional otherwise
Group filter – Restricts who may sign in: only users matched by this filter are let in. It does not affect which roles they receive (see automatic role syncing). For example:
(&(objectClass=groupOfUniqueNames)(uniqueMember=uid={username},ou=people,dc=selectzero,dc=io)(cn=developers))
- objectClass - searchable object class 'groupOfUniqueNames'
- uniqueMember - LDAP group unique member attribute, where {username} is the placeholder
- cn - group where we want to search the member from
Group attribute – Optional. User attribute holding group memberships, used for role syncing. Leave empty to detect it automatically

Type – Active Directory
Server – AD server host (and port); the ldap:///ldaps:// scheme is selected in front of the field
Domain – AD domain
Base DN – AD server root distinguished name (If group name has whitespaces then wrap it between quotes e.g. OU=”group name”)
Search by – AD filter for search user (for example sAMAccountName)
Name field – If "Create user on first log in" is enabled, we can assign display name from user attribute
Group DN – Group DN which will be prepended to base DN for group search. Required when role syncing is enabled, because it also bounds which groups are allowed to grant a role. Optional otherwise
Group filter – Restricts who may sign in: the filter is added to the AD user query, so only matching users are let in. It does not affect which roles they receive (see automatic role syncing). For example:
(memberOf=CN=Developers,OU=Groups,DC=selectzero,DC=io)
- memberOf - group DN to search for
Group attribute – Optional. User attribute holding group memberships, used for role syncing. Leave empty to use memberOf

Automatic role syncing

Roles of externally authenticated users (LDAP, AD and OAuth) can be managed entirely from the directory by mapping directory groups to SelectZero roles. The mapping is configured per role: each role (including the built-in admin and user roles) has an External directory group field in the role editor under Users & roles, holding one group per role — either the group's full DN (e.g. CN=Data Analysts,OU=Groups,DC=example,DC=com) or its plain name (Data Analysts). Matching is case-insensitive.

Role syncing is off by default and opted into per provider with the Sync roles from groups toggle, which appears in the LDAP/Active Directory and OAuth sections once that provider is enabled. Enabling it for one provider does not affect the other, which is useful when only one of them reports usable group names.

Once a provider has the toggle on and at least one role has an external group configured, syncing is active for logins through that provider. The directory is then authoritative over the roles it owns, and only those: a role is directory-managed exactly when it has an external group configured.

On every external login, directory-managed roles are added or removed to match the user's current groups, so group changes take effect on their next login.
Roles without an external group are left alone. A directory user can be granted an extra role by hand and keep it, which is the way to give someone access that the directory does not express.
The Default role counts as directory-managed: it is removed as soon as the directory grants something and comes back when the directory grants nothing, so it never lingers alongside real roles.
If Create user on first log in is enabled, new users are provisioned with their mapped roles, or the Default role if their groups match none.
Only external users are synced. Internal users (those with a password, see Users & roles) are never touched, so a break-glass internal admin keeps its roles whatever the directory says.
A failed sync never blocks the login; the user keeps their previous roles.

The External directory group field only appears once role syncing is enabled for an enabled provider, since the mapping has no effect on password logins. Turning the toggle back off leaves configured mappings untouched; they simply stop being applied.

For LDAP and AD the Group DN is required whenever the toggle is on. It is the container that decides which groups are allowed to grant a role: only groups underneath it are considered, so a group created elsewhere in the directory cannot be named after a mapped one to obtain its role. Point it at the branch your role groups actually live in, and keep it as narrow as that branch allows. If it is left blank or cleared later, role syncing is skipped for LDAP and AD logins and users keep the roles they have.

For OAuth the Groups field is required whenever its toggle is on, because there is no group source to fall back on and syncing would otherwise silently do nothing. Unlike LDAP and AD, OpenID Connect defines no standard groups claim, so the name differs per provider and usually has to be enabled there first:

Provider	Claim	Also needed
Keycloak	`groups`	Add a group-membership mapper to the client. Realm roles instead live at `realm_access.roles`
Microsoft Entra ID	`groups`	Enable the groups claim on the app registration. It emits group object IDs unless configured to emit names
Okta	`groups`	Configure the claim on the authorization server, and add `groups` to Scope
Auth0	custom	No groups by default; add an Action that sets a claim, e.g. `https://your-app/groups`
Google Workspace	none	Cannot drive role syncing at all

Nested claims are addressed with dots, so realm_access.roles reads the roles array inside the realm_access object.

Group membership is read from the AD memberOf attribute (direct memberships only, nested groups are not resolved; AD omits the attribute for a user who is in no group, in which case the group entries under Group DN are searched instead), from LDAP group entries (member, uniqueMember or memberUid, searched under the configured Group DN in addition to the attribute), or from the OAuth Groups field claim. Directories that publish memberships under a different attribute name are supported through the optional Group attribute field, for example isMemberOf (Oracle, Ping) or groupMembership (eDirectory); leaving it empty keeps the automatic detection above.

Running LDAP/AD and OAuth together

A role's external group is matched against whichever provider the user actually logged in with, so one value serves both. Because matching accepts either the full DN or the plain group name, entering the plain name (Data Analysts) is what makes a single mapping work for an AD login (which reports CN=Data Analysts,OU=Groups,...) and an OAuth login (which typically reports Data Analysts) alike.

This only needs attention when the two providers name the same group differently — most notably Entra ID emitting group object IDs while LDAP reports names. A user would then receive different roles depending on which login they used. Configure the providers to report matching group names, or give those users a single sign-in route.

Setting up OAuth providers

Select identity provider below for step-by-step setup and the values to enter in the OAuth tab. First enable OAuth in General options (and Create user on first log in if users should be provisioned automatically on their first login).

Register the application in Google Cloud Console:

Open Google Cloud Console and go to APIs & Services -> Credentials
If you have not configured the OAuth consent screen yet, do so first (choose the user type and set an app name and support email)
Press Create Credentials -> OAuth client ID
- Application type – Web application
- Name – an app name for the integration (e.g. SelectZero)
- Authorized redirect URIs – add your callback URL, e.g. https://example.selectzero.com/oauth
Press Create and copy the Client ID and Client secret

Enter these values in the OAuth tab:

Use OpenID – Enabled
Server URL – your SelectZero deployment URL, e.g. https://example.selectzero.com
Auth endpoint – https://accounts.google.com/o/oauth2/v2/auth
Token endpoint – https://oauth2.googleapis.com/token
Client ID – Client ID from Google Cloud Console
Client Secret – Client secret from Google Cloud Console
Scope – openid email
Username field – email
Display name field – name

Register the application in Okta:

In the Okta Admin Console go to Applications -> Applications and press Create App Integration
- Sign-in method – OIDC - OpenID Connect
- Application type – Web Application
Configure the application
- App integration name – an app name for the integration (e.g. SelectZero)
- Sign-in redirect URIs – add your callback URL, e.g. https://example.selectzero.com/oauth
- Assignments – choose which users or groups may sign in
Press Save and copy the Client ID and Client secret from the application's General tab

Enter these values in the OAuth tab:

Use OpenID – Enabled
Server URL – your SelectZero deployment URL, e.g. https://example.selectzero.com
Auth endpoint – https://{yourOktaDomain}/oauth2/v1/authorize
Token endpoint – https://{yourOktaDomain}/oauth2/v1/token
Client ID – Client ID from Okta
Client Secret – Client secret from Okta
Scope – openid email
Username field – email
Display name field – name

Replace {yourOktaDomain} with your Okta org domain (e.g. selectzero.okta.com). If you use a custom Okta authorization server, the endpoints include its id, e.g. https://{yourOktaDomain}/oauth2/{authServerId}/v1/authorize.

Microsoft Entra ID (formerly Azure AD) can be used as an OAuth provider for SelectZero logins. Register the application in Microsoft Entra ID:

Log into Azure portal and search for Microsoft Entra ID
Under Manage -> App registrations create a new registration
- Name – choose an app name for the integration (e.g. SelectZero)
- Supported account types – choose Accounts in this organizational directory only (Single tenant)
- Redirect URI – select Web and enter your callback URL, e.g. https://example.selectzero.com/oauth
Navigate to Manage -> Certificates & secrets
- Under Client secrets press New client secret, set a description and expiry
- Copy the secret Value immediately (it is shown only once). This is the Client Secret, not the secret ID
Navigate to Overview
- Copy the Application (client) ID – this is the Client ID
- Copy the Directory (tenant) ID – needed to build the endpoint URLs below

Enter these values in the OAuth tab:

Use OpenID – Enabled (recommended – SelectZero reads the user from the id_token, so no Microsoft Graph permissions are required)
Server URL – your SelectZero deployment URL, e.g. https://example.selectzero.com
Auth endpoint – https://login.microsoftonline.com/{tenant-id}/oauth2/v2.0/authorize
Token endpoint – https://login.microsoftonline.com/{tenant-id}/oauth2/v2.0/token
Client ID – Application (client) ID from the app registration
Client Secret – Client secret Value from Certificates & secrets
Scope – profile email
Username field – preferred_username
Display name field – name

Replace {tenant-id} with the Directory (tenant) ID from the app registration.

Certificates

On the Certificates sub-tab you can add custom certificates in case any authentications/connections uses TLS/SSL. The table shows each certificate's alias, issuer, owner and validity period (expired dates are shown in red).

Adding a certificate

Press “Add” button above the certificates table
Give certificate an alias for distinction
Choose a certificate file (.cert, .cer, .crt, .pem or .p12)
Press “Add new certificate”

Adding an https certificate (Enabling HTTPS for SelectZero)

Press “Add” button above the certificates table
Give certificate the alias “https” (which is only used for https enabling. Certificate file has to be either .p12 keystore containing RSA private key or .pem file containing RSA private key and certificate chain)
Insert password if certificate is protected by one (the password field appears for the “https” alias)
Choose the certificate file
Press “Load 'https' certificate and shut down tool”
Tool will shut down automatically
Manually start SelectZero container/WAR file from server side

Replacing or deleting a certificate

Open the dropdown at the end of the certificate's row and select “Replace” (or “Delete”, which asks for confirmation — deleting the “https” certificate shuts the tool down)
Choose new certificate file (the alias cannot be changed)
Press “Change certificate”
If you replaced the “https” certificate, restart the application — an admin can use the Restart button under Settings → General