SSO Setup

Overview

Envtracker supports tenant-level Single Sign-On (SSO) using the OpenID Connect (OIDC) standard.

With SSO enabled, users authenticate via your Identity Provider (IdP) (Azure AD, Okta, Auth0, Keycloak, etc.). Envtracker uses the returned token claims to identify the user (email/name) and optionally assign project access based on role/group claims.

Before you start: create an application in your IdP

Before configuring SSO in Envtracker, create a new client/application in your Identity Provider (IdP):

• Log in to your IdP’s admin console
• Create a new client/application using the standard OpenID Connect flow
• Set the redirect URI to:
  • https://tenant.envtracker.io/auth/sso-callback
  • Replace tenant with your tenant subdomain (your tenant name)
• Note the Client ID and Client Secret provided by your IdP
• Obtain the Authorization endpoint, Token endpoint, and email field mapping from your IdP’s documentation

SSO settings

Enable / Disable SSO

• Enabled: users can sign in using the configured IdP.
• Disabled: SSO is turned off (existing configuration can remain saved).

Required fields

Client ID (required)

The OIDC client/application identifier from your IdP.

Client Secret (required)

The OIDC client/application secret from your IdP.

Keep this secret secure and rotate it if you suspect it has been exposed.

Authorization Endpoint (required)

The IdP authorization URL used to start the OIDC login flow.

Token Endpoint (required)

The IdP token URL used to exchange the authorization code for tokens.

Claim mapping (token fields)

Envtracker needs to know which token claims contain the user identity information.

Email Field/claim Mapping

• Default: email
• Description: the field name in your IdP’s user profile / token claims that contains the email address.

Most IdPs include email, but some may use a different claim depending on configuration.

Name Field Mapping

• Default: name
• Description: the field name in your IdP’s user profile / token claims that contains the user’s display name.

Roles Field Mapping

• Default: roles
• Type requirement: must be an array of strings
• Description: the claim that contains the user’s roles/groups used for project role mappings.

If your IdP returns roles as a string, nested object, or in a different claim, you must adapt the IdP configuration so the claim resolves to an array of strings.

Roles Scope (optional)

Only add this input if required by your IdP.

Some IdPs require a custom scope to inject roles into the ID token.

• Example: Keycloak often needs an additional scope to include realm/client roles in the token.

Project role mappings

Why mappings are needed

Envtracker can authenticate users via SSO without any role mappings, but without mappings users will have no project access.

To grant access, map IdP roles/groups to project roles. In your IdP (Azure AD, Okta, Auth0, Keycloak…), configure group/role claims in the token or app registration so that roles are present in the token claim you configured as Roles Field Mapping.

How mappings work

• Mappings are evaluated on every login
• This makes access dynamic: if a user’s roles change in the IdP, their Envtracker project access updates on next sign-in

Mapping inputs

SSO Roles

• Comma-separated roles from the IdP
• Example: admin,developer,devops

These roles must match values contained in the configured roles claim.

Project Role

The role granted within the selected project.

Current options:

• viewer
• member
• analyst
• manager

Matching Method

Controls how the IdP roles are compared.

• included: all listed SSO roles must exist in the user’s roles claim
• overlap: at least one listed SSO roles must exist in the user’s roles claim

Project

Select which project the mapping applies to.

Example

A mapping like:

• SSO Roles: devops,platform
• Matching Method: overlap
• Project Role: manager
• Project: Production

means any user with either devops or platform in their roles claim will be granted manager role for the Production project.

IdP-specific notes

OIDC authentication is standard across IdPs, but role/group claims differ.

Azure AD (Microsoft Entra ID)

• Use App Roles for role mapping.
• Avoid relying on Security Groups for role claims because they return group ids not their names.

Keycloak

• Role claims may require additional configuration.
• You may need a Roles Scope so that roles are included in the ID token.

Troubleshooting checklist

• Redirect URI matches exactly (including protocol, host, port, and path)
• Authorization endpoint and token endpoint are correct for your IdP tenant
• Email claim exists and is correctly mapped
• Roles claim exists and is an array of strings when using project role mappings
• If roles do not appear in the token for Keycloak, add/configure the required scope