Skip to main content
Version: 3.4

SSO for Accounts

UDMG supports Single Sign-On (SSO) for Account authentication in the Web Transfer Client (WTC).

This feature enables centralized identity management, strengthens security, and provides a seamless login experience for Accounts. By allowing Accounts 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 Accounts. Upon SSO login, UDMG validates the IdP assertion/token, verifies authorization, issues its own session tokens, and performs Just-in-Time (JIT) provisioning of Accounts.

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. 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.

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

Provisioning and Identity Management​

UDMG supports automated Just-in-Time (JIT) provisioning for Accounts authenticated via SSO. When an Account successfully signs in to the Web Transfer Client (WTC) 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 an Account 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 Account and populates the mapped Account Group associations.
  • If the Username Attribute or Username Claim is missing, or if an Account with the same Username exists but has a different Login Method (e.g., Standard or LDAP), the login is denied.
  • If an Account with the same Name already exists — regardless of its Login Method or letter case — SSO provisioning is rejected and the login fails with an error.

On Subsequent Logins​

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

  • Updates mapped attributes (e.g., name, email, Account Group associations) if they differ from the IdP response.
  • Refreshes the Updated timestamp and Version number whenever any Account 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 Account or SSO Removal/Change​

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

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

Group Attribute and Account Group Assignment​

After an Account is authenticated through SSO, UDMG determines their Account Group association 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 Account Group, you can configure the exact IdP value (group or claim) that grants that Account Group association.

If an Account's IdP attributes contain multiple matching values, UDMG associates all of the Account Groups.

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.

Account Group assignments are re-evaluated on every login. If an Account's group membership changes in the IdP, UDMG updates the Account's Account Group associations 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 authenticates through SSO, UDMG establishes a session for the corresponding Account and redirects them to their requested page or the default 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 an Account 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, Accounts 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 them to authenticate again.

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-08-27T17:16:14.485Z level=ERROR msg=unknown service=wtc wtc.requestId=e615ccee-cc7a-46d4-b0c9-408df2a5575e wtc.method=GET wtc.path=/workspace/primary/sso/callback wtc.messageCode=SAML010 wtc.message="insufficient permissions"
Error CodeDescription
SAML001The Domain could not be resolved from the incoming request. Verify that the SSO URL contains a valid Domain name.
SAML002The Domain configuration could not be loaded. Contact your administrator.
SAML003The SSO callback is missing a required form value (SAMLResponse or RelayState). Verify your IdP's SAML assertion posting configuration.
SAML004The 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.
SAML005The returned state value does not match the expected SAML flow. Try logging in again.
SAML006The identity provider's SAML assertion could not be processed. Verify your IdP configuration, including the Entity ID, ACS URL, and assertion attributes.
SAML007Account provisioning failed. UDMG could not create or update the Account record. Verify the Username Attribute, Email Attribute, and Account Group mapping configuration.
SAML008A session token could not be generated for the authenticated Account. Contact your administrator.
SAML009The login response could not be stored in the session cookie. Contact your administrator.
SAML010The Account authenticated successfully but does not have the permissions required to access the workspace. Contact your administrator.

Configuring an SSO Provider​

SSO is configured at the Domain level, meaning it can only be used to authenticate Accounts 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 Accounts, follow these steps:

  1. From the Sidebar, click General > Settings.
  2. Click Single Sign-On (SSO) - Accounts.
  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​

NameDescriptionSpecificationsRequired
NameThe name of the SSO configuration.Yes
DescriptionThe description of the SSO configuration.No
ProtocolSelect 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 URLThe 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 URIThe 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 URLThe 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 RequestsA 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 AttributeThe name of the SAML attribute to use as the unique Account identifier. This value should be globally unique and not change over time (e.g., email, uid, userPrincipalName).Yes
Email AttributeThe name of the SAML attribute containing the Account's email address.Yes
Group AttributeThe name of the SAML attribute from which the Account's group will be derived. This may be an existing attribute or a custom one (e.g., mftGroup).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 Account Group Mapping

Map IdP group/role values to Account Groups.

For each row, provide an IdP Role/Group and select its matching Account Group.

For more information, see Group Attribute and Account Group Assignment.

No

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) - Accounts.

SSO Provider Metadata​

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

NameDescription
UUIDThe universally unique identifier of this SSO provider.
VersionVersion number of the latest configuration of the SSO provider.
CreatedDate and time this SSO provider was created.
UpdatedDate 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) - Accounts.
  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 Account 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 Accounts.
  • Disabled: The provider is inactive, and Accounts 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) - Accounts.
  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 Accounts. Existing Account sessions remain active until they expire or the Account holder 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 Accounts that have already been provisioned via the provider. Those options include:

OptionWhen to ChooseResult
Delete the AccountsNo plans to migrate to a new provider, or do not want to preserve Account records.Accounts are removed from UDMG; if they authenticate later via an active SSO provider, they will be re-provisioned.
Retain as orphanedYou need the records for auditing but do not want Accounts to log in.Accounts 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) - Accounts.
  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 Accounts. Existing Account sessions remain active until they expire or the Account holder logs out.

Managing SSO-Provisioned Accounts​

Editing SSO-Provisioned Accounts​

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

  1. From the Sidebar, click Configuration > Accounts.
  2. Click the Name of the SSO-provisioned Account you want to edit.
  3. Click the Edit button above the Account details.
  4. Edit details for the Account using the Field Descriptions table as a guide. The following fields are not editable for SSO-provisioned Accounts, as they are managed by the SSO system and must be updated there:
    • Account Name
    • Description
    • Username
    • Password
    • Account Group
    • Require Two-Factor Authentication (TOTP)
  5. Click Update.

Deleting SSO-Provisioned Accounts​

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

  1. From the Sidebar, click Configuration > Accounts.
  2. Click the Name of the Account you want to delete.
  3. Click the Delete button above the Account details.
  4. You will be asked to confirm the deletion. Click Continue.
info

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