SSO for Users

UDMG supports Single Sign-On (SSO) for User authentication in the UDMG Admin UI.

This feature enables centralized identity management, strengthens security, and provides a seamless login experience for Users. By allowing Users to authenticate through an external Identity Provider (IdP), UDMG acts as the Service Provider (SP) and integrates easily into your organization's existing identity infrastructure.

Each UDMG Domain supports a single SSO provider for Users. Upon SSO login, UDMG validates the IdP assertion/token, verifies authorization, issues its own session tokens, and performs Just-in-Time (JIT) provisioning of Users.

Before You Begin

Supported Protocols and IdPs

UDMG supports two widely adopted authentication protocols for SSO. These are open standards for exchanging authentication and authorization data between an Identity Provider (IdP) and a Service Provider (SP), such as UDMG:

• SAML (Security Assertion Markup Language) 2.0
• OIDC (OpenID Connect)/OAuth 2.0

UDMG supports any IdP that conforms to the SAML or OIDC/OAuth 2.0 specifications. The table below lists a selection of commonly used IdPs that have been tested and validated:

Identity Provider	SAML 2.0	OIDC / OAuth 2.0
Okta
Microsoft Entra ID (Azure AD)
Google Workspace
PingFederate
Auth0

info

If your IdP is not listed, it is still likely to work with UDMG, as unlisted providers may simply not have undergone our complete validation process.

Provisioning and Identity Management

UDMG supports automated Just-in-Time (JIT) provisioning for Users authenticated via SSO. When a User successfully signs in to the UDMG Admin UI through a configured SSO provider for the very first time, their Username is automatically created within UDMG; no manual setup is required.

On First Login

When a User signs in with SSO for the first time, UDMG processes the identity assertion or token returned by the IdP:

• If the Username Attribute or Username Claim is present and resolves to a unique username that does not already exist with a different Login Method, UDMG creates a new User and populates the mapped attributes (e.g., name, email, role).
• If the Username Attribute or Username Claim is missing, or if a User with the same username exists but has a different Login Method (e.g., Standard or LDAP), the login is denied.

On Subsequent Logins

When an SSO-provisioned User logs in again, UDMG re-evaluates authorization and:

• Updates mapped attributes (e.g., name, email, role) if they differ from the IdP response.
• Refreshes the Updated timestamp and Version number whenever any User data is modified.

info

The Username is immutable to preserve identity consistency. The Login Method (equal to SAML or OIDC) and the association with the originating SSO Provider are also immutable.

On User or SSO Removal/Change

If a User is removed from the IdP, or if the SSO provider is disabled or deleted in UDMG:

• The User remains visible in the list but will no longer be able to log in.
• If the User authenticates again after an SSO provider has been replaced, they may be re-provisioned as a new User depending on whether the new IdP emits a different value for the configured Username Attribute or Username Claim.

Group Attribute, Roles, and Authorization

After a User is authenticated through SSO, UDMG determines their Role based on the value returned by the IdP. This attribute contains one or more values, such as group names or role identifiers, which are compared against the Group Attribute or Group Claim defined in the SSO configuration.

For each UDMG role, you can configure the exact IdP value (group or claim) that grants that role. Leaving a role mapping blank disables assignment for that role. If all role mappings are blank, UDMG applies the Missing Or Unrecognized Role Policy instead:

• Deny login: The authentication attempt is rejected.
• Assign to default role: The User is allowed to log in with the specified Default Role (typically, Read-only).

If a User's IdP attributes contain multiple values that match configured role mappings, UDMG assigns the most privileged role from the following list (in descending order of privilege):

• Domain Administrator
• Pipeline Management
• Operator
• Read-only

If no values match, or if the IdP response does not contain the Group Attribute or Group Claim, UDMG applies the configured Missing Or Unrecognized Role Policy.

For SAML configurations, some IdPs return multiple values in a single <AttributeValue> element instead of multiple <AttributeValue> elements.

If you are unsure how values are represented in the SAML assertion, ask your IdP administrator:

• If values are returned as a single delimited string, configure the Role/Group Delimiter (For Single String Attributes) field with the delimiter character used to separate the values.
• If values are returned as multiple <AttributeValue> elements, leave this field empty.

Role assignments are re-evaluated on every login. If a User's group membership or mapped role changes in the IdP, UDMG updates the User's role accordingly.

Login Experience

Once an SSO provider has been configured and enabled for a Domain, a button for that provider appears on the Domain's login page beneath the standard Username and Password fields.

When a User clicks the SSO button, UDMG redirects them to the configured IdP to authenticate. After the IdP completes authentication, it returns the User to UDMG, redirecting them to their requested page or the default landing page.

Additionally, Users can automatically log in to the UDMG Admin UI by navigating to a direct SSO URL. To access this flow, append /auth/{domainName}/sso to your UDMG Base URL (hostname). This will redirect Users to their IdP login screen, and upon successful authentication, they will be automatically directed to the UDMG Admin UI landing page.

info

If the IdP is configured for IdP-initiated login, it can send a signed authentication response directly to the Full Redirect URI (the Assertion Consumer Service (ACS) endpoint for SAML or the redirect URI for OIDC).

Session Behavior

After a successful SSO login, UDMG establishes and manages its own application session; it does not reuse IdP tokens. When a User signs out, only the UDMG session ends. Single Logout (SLO) across the IdP or other applications is not supported.

If an SSO provider is disabled or deleted, new logins are blocked but existing sessions remain active until they expire. When a session expires, Users are returned to the login page; if their IdP session is still valid, they may be signed back in without re-entering credentials; otherwise, the IdP prompts the User to log in.

SAML Request Signing and Assertion Decryption

UDMG supports two optional security enhancements for SAML authentication:

• Request signing: UDMG signs outbound SAML authentication requests using the certificate pair specified in Credentials Name (SP Signing and Encryption Key Pair). This allows the IdP to verify that requests originate from a trusted SP.
• Assertion decryption: UDMG decrypts encrypted assertions in the IdP's SAML response using the certificate pair specified in Credentials Name (SP Signing and Encryption Key Pair). This requires that the IdP be configured to encrypt assertions using the corresponding SP certificate.

Both features rely on the same TLS Certificate Pair credential and operate independently. Assertion decryption is available whenever an SP key pair is configured, regardless of whether request signing is enabled.

To use either feature, create a TLS Certificate Pair credential on the Credentials page before configuring the SSO provider.

Login Error Codes

When SSO authentication fails, UDMG redirects to the login page with three query parameters:

• errorMessage: always login failed
• errorCode: one of the codes from the tables below
• errorDescription: a URL-encoded string with additional detail about the underlying error

For example:

<udmg-base-url>?errorMessage=login+failed&errorCode=SAML003&errorDescription=missing+SAMLResponse+or+RelayState

Each SSO authentication failure is also logged as an ERROR-level entry in the UDMG Server log. The messageCode field contains the error code and message contains a brief description of the stage that failed.

time=2026-09-03T17:44:51.761Z level=ERROR msg="sso auth provider" service=api api.requestId=c9f5bb0b-a8d1-4be2-8310-45193f5b0a51 api.method=GET api.path=/auth/primary/sso/callback api.domainUUID=329966f0-7fd3-4893-b074-4aabaf4b22ff api.domainName=primary api.messageCode=SAML003 api.message="missing SAMLResponse or RelayState"

SAML

Error Code	Description
SAML001	The Domain could not be resolved from the incoming request. Verify that the SSO URL contains a valid Domain name.
SAML002	The Domain configuration could not be loaded. Contact your administrator.
SAML003	The SSO callback is missing a required form value (SAMLResponse or RelayState). Verify your IdP's SAML assertion posting configuration.
SAML004	The relay state returned by the identity provider could not be decrypted (it may be invalid or tampered). Try logging in again; if the issue persists, check for browser session problems.
SAML005	The returned state value does not match the expected SAML flow. Try logging in again.
SAML006	The identity provider's SAML assertion could not be processed. Verify your IdP configuration, including the Entity ID, ACS URL, and assertion attributes.
SAML007	User provisioning failed. UDMG could not create or update the User record. Verify the Username Attribute, Email Attribute, and role mapping configuration.
SAML008	A session token could not be generated for the authenticated User. Contact your administrator.
SAML009	The login response could not be stored in the session cookie. Contact your administrator.

OIDC / OAuth 2.0

OIDC Code	OAuth 2.0 Code	Description
OIDC001	OAUTH001	The Domain could not be resolved from the incoming request. Verify that the SSO URL contains a valid Domain name.
OIDC002	OAUTH002	The Domain configuration could not be loaded. Contact your administrator.
OIDC003	OAUTH003	The state parameter returned by the identity provider is missing, invalid, or could not be decrypted. Try logging in again; if the issue persists, verify your IdP's redirect URI configuration.
OIDC004	OAUTH004	The returned state value does not match the expected flow. Try logging in again.
OIDC005	OAUTH005	The identity provider's callback could not be processed. Verify your IdP configuration, including the redirect URI, Client ID, and Client Secret.
OIDC006	OAUTH006	User provisioning failed. UDMG could not create or update the User record. Verify the Username Claim, Email Claim, Name Claim, and role claim configuration.
OIDC007	OAUTH007	A session token could not be generated for the authenticated User. Contact your administrator.
OIDC008	OAUTH008	The login response could not be stored in the session cookie. Contact your administrator.

Configuring an SSO Provider

SSO is configured at the Domain level, meaning it can only be used to authenticate Users within that specific Domain. If you want to use the same SSO provider across multiple Domains, it must be configured separately in each Domain.

To configure an SSO provider for Users, follow these steps:

1. From the Sidebar, click General > Settings.
2. Click Single Sign-On (SSO) - Users.
3. Fill out the fields for the new SSO settings using the Field Descriptions table, which includes separate tabs for SAML and OIDC / OAuth 2.0.
4. Click Add.

Field Descriptions

SAML

Name	Description	Specifications	Required
Name	The name of the SSO configuration.	Must be unique. Must follow the Standard Naming Pattern.	Yes
Description	The description of the SSO configuration.		No
Protocol	Select SAML.	Cannot be modified after creation. If a different protocol is needed, the current SSO provider must be deleted and a new one added.	Yes
Identity Provider (IdP)	The selected IdP's name and icon are displayed on the login page under the single sign-on section. If your IdP is not listed below, then it is displayed as "Other". Options: Microsoft Entra ID (Azure AD) Okta Google Workspace PingFederate Other		Yes
UDMG Base URL	The base URL of your UDMG instance, prefixed by HTTPS. This should be the hostname where your UDMG application is accessible.	Must be a valid HTTPS URL. Example: https://my-udmg.company.com.	Yes
Full Redirect URI	The complete redirect URI that is automatically generated and should be configured in your IdP as the callback URL for SAML authentication.		No, it is automatically generated
IdP SSO URL	The IdP's SSO endpoint URL that Users or Accounts are redirected to for login.	Must be a valid HTTPS URL.	Yes
Identity Provider (IdP) Entity ID (Issuer)	The unique identifier for your Service Provider (entity issuer) that the IdP recognizes.	Must be a valid HTTPS URL.	Yes
Audience URI (Service Provider Entity ID)	The URI that specifies which Service Provider the SAML assertion is intended for. Only change the field if your IdP sends a different audience value than your Service Provider Entity ID.	Must be a valid HTTPS URL.	Yes
Credentials Name (IdP Signing Certificate)	The X.509 Certificate that references the CA Certificate that is used to verify the signature on the SAML response from the Identity Provider.	Must reference an existing X.509 Certificate.	Yes
Credentials Name (SP Signing and Encryption Key Pair)	The TLS Certificate Pair used to sign SAML authentication requests and decrypt encrypted assertions from the Identity Provider. All credentials must first be created on the Credentials page before they can be selected here.	Must reference an already created TLS Certificate Pair.	No
Sign Requests	A toggle switch to enable or disable signing of outbound SAML authentication requests. When enabled, requests are signed using the SP signing certificate's private key. Disabled unless a Credentials Name (SP Signing and Encryption Key Pair) is selected.	Default value: Disabled.	No
Canonicalizer	The XML Canonicalization algorithm applied to the authentication request before signing. Options: Canonical XML 1.0 Exclusive Canonical XML 1.0 Exclusive with Comments Canonical XML 1.0 (Inclusive) Canonical XML 1.0 with Comments (Inclusive) Canonical XML 1.1 Canonical XML 1.1 with Comments		Yes, if Sign Requests is Enabled.
Signature Algorithm	The cryptographic algorithm used to compute the SAML request signature. Options: rsa-sha1 rsa-sha256 rsa-sha384 rsa-sha512 ecdsa-sha1 ecdsa-sha256 ecdsa-sha384 ecdsa-sha512		Yes, if Sign Requests is Enabled.
Username Attribute	The name of the SAML attribute to use as the unique User identifier. This value should be globally unique and not change over time.	Examples: email uid userPrincipalName	Yes
Email Attribute	The name of the SAML attribute containing the User's email address.		Yes
Group Attribute	The name of the SAML attribute from which the User's role will be derived. This may be an existing attribute or a custom one.	Example: mftRole	Yes
Role/Group Delimiter (For Single String Attributes)	If the Group Attribute is returned as a single <AttributeValue> containing multiple roles or groups, specify the delimiter used to separate the values (for example, , or ;). If the SAML assertion returns multiple <AttributeValue> elements, this field is not required.		No
Role/Group Attribute to Role/Group Mapping	Map IdP group/role values to UDMG Roles. For each row, provide an IdP Role/Group and select its matching UDMG Roles.		No
Missing Or Unrecognized Role Policy	Specifies the action to take when the group attribute is missing or does not match any configured role mapping. Options: Deny login Assign to default role		Yes
Default Role	Specifies the default role to assign if the role attribute is missing or does not contain a recognized role. Options: Read-only Domain Administrator Operator Pipeline Management		Yes, if Missing Or Unrecognized Role Policy is Assign to default role.

OIDC / OAuth 2.0

Name	Description	Specifications	Required
Name	The name of the SSO configuration.	Must be unique. Must follow the Standard Naming Pattern.	Yes
Description	The description of the SSO configuration.		No
Protocol	Select OIDC / OAuth 2.0.	Cannot be modified after creation. If a different protocol is needed, the current SSO provider must be deleted and a new one added.	Yes
Identity Provider (IdP)	The selected IdP's name and icon are displayed on the login page under the single sign-on section. If your IdP is not listed below, then it is displayed as "Other". Options: Microsoft Entra ID (Azure AD) Okta Google Workspace PingFederate Other		Yes
UDMG Base URL	The base URL of your UDMG instance, prefixed by HTTPS. This should be the hostname where your UDMG application is accessible.	Must be a valid HTTPS URL. Example: https://my-udmg.company.com.	Yes
Full Redirect URI	The complete redirect URI that is automatically generated and should be configured in your IdP as the callback URL for OIDC / OAuth 2.0 authentication.		No, it is automatically generated
Issuer URL	The base URL of the OpenID Provider. Used to validate the issuer (iss) claim in the ID token returned by the IdP during authentication.	Must be a valid HTTPS URL.	Yes
Credentials Name (Client ID & Secret)	The Credential that contains the Client ID (unique identifier assigned to your application Service Provider by the IdP) and authentication password for OIDC/OAuth 2.0.	Must reference an existing Key Pair.	Yes
Authorization Endpoint	The endpoint for initiating the authentication flow.	Must be a valid HTTPS URL.	Yes
User Info Endpoint URL	The URL of the OIDC endpoint used to retrieve additional user or account profile information.		Yes
Token Endpoint	The endpoint for exchanging the authorization code for tokens.	Must be a valid HTTPS URL.	Yes
Scopes	The permissions or identity data the Service Provider Client is requesting, such as "openid email profile" or 'openid'.	Must be a valid, space-separated string.	Yes
Username Claim	The name of the claim in the ID Token or Access Token to use as the unique User identifier. This value should be globally unique and not change over time (e.g., sub, email, preferred_username).		Yes
Email Claim	The name of the claim in the ID Token or Access Token containing the User's email address.		Yes
Name Claim	The name of the claim in the ID Token or Access Token containing the User's name.		Yes
Group Claim	The name of the claim in the ID Token or Access Token from which the User's role will be derived (e.g., roles, groups, mftRole).		Yes
Role/Group Attribute to Role/Group Mapping	Map IdP group/role values to UDMG Roles. For each row, provide an IdP Role/Group and select its matching UDMG Roles.		No
Missing Or Unrecognized Role Policy	Specifies the action to take when the group attribute is missing or does not match any configured role mapping. Options: Deny login Assign to default role		Yes
Default Role	Specifies the default role to assign if the role attribute is missing or does not contain a recognized role. Options: Read-only Domain Administrator Operator Pipeline Management		Yes, if Missing Or Unrecognized Role Policy is Assign to default role.

Managing an SSO Provider

Viewing SSO Provider Details

To view the details of an SSO provider, follow these steps:

1. From the Sidebar, click General > Settings.
2. Click Single Sign-On (SSO) - Users.

SSO Provider Metadata

SSO provider details include all parameters given in the Field Descriptions table above, plus the following read-only metadata:

Name	Description
UUID	The universally unique identifier of this SSO provider.
Version	Version number of the latest configuration of the SSO provider.
Created	Date and time this SSO provider was created.
Updated	Date and time this SSO provider was last updated.

Editing SSO Provider Details

To edit the details of an SSO provider, follow these steps:

1. From the Sidebar, click General > Settings.
2. Click Single Sign-On (SSO) - Users.
3. Click the Edit button above the SSO provider details.
4. Edit fields for the SSO settings using the Field Descriptions table, which includes separate tabs for SAML and OIDC / OAuth 2.0.
5. Click Update.

Enabling/Disabling SSO

danger

Before disabling an SSO provider, ensure that at least one Admin User with Standard authentication remains available. Otherwise, you may lose administrative access to UDMG.

SSO providers can be Enabled or Disabled to control whether they can be used for User authentication. By default, new providers are Enabled, but their status can be changed at any time.

• Enabled (default): The provider is active and available for authenticating Users.
• Disabled: The provider is inactive, and Users associated with it will be unable to log in.

To enable or disable an SSO provider, follow these steps:

1. From the Sidebar, click General > Settings.
2. Click Single Sign-On (SSO) - Users.
3. Click the Enable or Disable button above the SSO provider details, depending on the current status.

info

Disabling an SSO provider blocks new login attempts for associated Users. Existing sessions remain active until they expire or the User logs out.

Deleting an SSO Provider

danger

Before deleting an SSO provider, ensure that at least one Admin User with Standard authentication remains available. Otherwise, you may lose administrative access to UDMG.

Deleting an SSO provider configuration is straightforward. However, you must plan what to do with any orphaned Users that have already been provisioned via the provider. Those options include:

Option	When to Choose	Result
Delete the Users	No plans to migrate to a new provider, or do not want to preserve User records.	Users are removed from UDMG; if they authenticate later via an active SSO provider, they will be re-provisioned.
Retain as orphaned	You need the records for auditing but do not want Users to log in.	Users remain visible but cannot authenticate; even with a new provider configured, their Username values remain tied to the deprecated provider.

To delete an SSO provider, follow these steps:

1. From the Sidebar, click General > Settings.
2. Click Single Sign-On (SSO) - Users.
3. Click the Delete button above the SSO provider details.
4. You will be asked to confirm the deletion. Click Continue.

info

Deleting an SSO provider blocks new login attempts for associated Users. Existing sessions remain active until they expire or the User logs out.

Managing SSO-Provisioned Users

Editing SSO-Provisioned Users

To edit the details of an SSO-provisioned User, follow these steps:

1. From the Sidebar, click General > Users.
2. Click the Username of the User you want to edit.
3. Click the Edit button above the User details.
4. For SSO-provisioned Users, only the Assigned Business Services field is editable.
5. Click Update.

Deleting SSO-Provisioned Users

To delete an SSO-provisioned User, follow these steps:

1. From the Sidebar, click General > Users.
2. Click the Username of the User you want to delete.
3. Click the Delete button above the User details.
4. You will be asked to confirm the deletion. Click Continue.

info

Deleting an SSO-provisioned User removes them from the list, but they will reappear if they authenticate again. To permanently prevent access, first remove the User from your IdP, and optionally delete them from the Users list.