Identity Provider (IdP) connection

This section explains how to connect an external Identity Provider (IdP) to a DS3 Composer Tenant so that users can sign in to the DS3 Console through single sign-on (SSO). The platform redirects users to the IdP, validates the authentication result returned by the IdP, and creates or matches the corresponding account in the Tenant.

The SAML 2.0 integration settings and the PingOne walkthrough are covered below.

How the sign-in flow works

The integration supports sign-in initiated from the DS3 Console only. The flow is:

1. The user opens the DS3 Console sign-in page of the Tenant. The console shows one button for each provider configured in the Tenant settings.
2. The user selects the provider button. The platform initiates the sign-in with the IdP and redirects the browser to it.
3. The user authenticates with the IdP.
4. The IdP returns the authentication result to the platform.
5. The platform validates the result and reads the user information. On the first successful sign-in, the account is created in the Tenant automatically (just-in-time provisioning).
6. The platform redirects the browser back to the DS3 Console, and the user is signed in.

warning

Users must always start the flow from the DS3 Console sign-in page. IdP-initiated sign-in, where the flow starts from the IdP portal, is not supported.

Troubleshooting

Symptom	Likely cause	Resolution
403 Forbidden after returning from the IdP	The account could not be matched or created. Common causes: sign-up is disabled for the Tenant, the email domain is not allowed, the account is banned, or the email already belongs to an account created with a different sign-in method.	Review the sign-up settings and the user account data.

Protocol-specific errors, such as 400, 401, and 502 responses or mismatched Entity ID and ACS URL values, are covered in the SAML troubleshooting and PingOne troubleshooting sections below.

SAML 2.0 integration

The SAML 2.0 settings are shared by every SAML Identity Provider (IdP) that you can connect to a DS3 Composer Tenant: the connection values, the assertion attributes, and the recommended IdP settings. Provider-specific steps are covered in the PingOne section below.

info

SAML SSO must be enabled on the Coordinator by a platform administrator before it can be configured on a Tenant. For the platform prerequisites, the Tenant settings fields, and the SAML metadata endpoint, see Sign in with SAML 2.0 in the Tenant configuration page. If the SAML SSO section is not visible in your Tenant settings, contact your platform administrator.

Connection values

Most integration issues come from a mismatch between the IdP application and the Tenant settings. The Entity ID and the ACS URL must be identical on both sides, while the IdP metadata URL is entered only in the Tenant settings:

Value	Where it is configured	Description
Entity ID	IdP application and Tenant settings	A unique identifier for the Service Provider, chosen by you. The exact same string must be configured on both sides. Some IdPs label this field as Audience or SP Entity ID.
IdP metadata URL	Tenant settings	The HTTPS URL where the IdP publishes its SAML metadata. The platform fetches this URL to discover the IdP SSO endpoint and signing certificates.
ACS URL	IdP application and Tenant settings	https://{console-domain}/api/iam/v1/auth/saml/acs. It must use the console domain, not the API domain.

Assertion attributes

The platform reads user information from the attributes of the SAML assertion. Attribute names are case-sensitive and must match exactly. The following names are accepted for the sign-in identity fields:

Purpose	Accepted SAML attribute names	Required
Email	email, mail, urn:oid:0.9.2342.19200300.100.1.3	Yes. Sign-in fails when the email attribute is missing.
First name	given_name, givenName, firstName, http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname	No
Last name	family_name, sn, lastName, http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname	No

When an attribute contains more than one value, the platform uses the first value.

Recommended IdP settings

• Sign the assertions. The platform verifies the signature using the certificates published in the IdP metadata.
• Use the RSA-SHA256 signature algorithm. The platform signs its authentication requests with RSA-SHA256.
• Use the HTTP-Redirect binding for the authentication request and the HTTP-POST binding for the response.
• Set the Subject NameID format to emailAddress (recommended).

SAML troubleshooting

Symptom	Likely cause	Resolution
400 Bad Request on /api/iam/v1/auth/saml/acs	The sign-in attempt was interrupted or retried, so the request is no longer valid. Each attempt can be completed only once.	Restart the flow from the DS3 Console sign-in page.
401 Unauthorized on the ACS URL	The SAML assertion was rejected by the platform.	Check the attribute mapping. The most common cause is a missing email attribute, or an email attribute with a name outside the accepted list (see the table above).
502 Bad Gateway right after selecting the provider button	The platform could not fetch or parse the IdP metadata.	Verify that the IdP metadata URL is reachable, uses HTTPS, and returns the IdP metadata XML.
Error on the IdP side about the application or the ACS URL	The Entity ID or the ACS URL configured in the IdP does not match the Tenant settings.	Verify that both values are identical on the IdP side and in the Tenant settings.
Tenant settings save error: "SAML provider URL is malformed"	The URL field contains an invalid value.	Enter a full absolute https:// URL with no surrounding spaces.

PingOne

This section walks through connecting PingOne as a SAML 2.0 Identity Provider (IdP) for a DS3 Composer Tenant, from the PingOne application configuration to the Tenant settings and a test sign-in.

Before you start, review the sign-in flow above, the connection values, and the assertion attributes of the SAML 2.0 integration. Verify with your platform administrator that SAML SSO is enabled on the Coordinator; see Sign in with SAML 2.0.

The following placeholders are used throughout this section:

Placeholder	Meaning
{console-domain}	The domain of the Tenant DS3 Console (for example console.example.com).
{environment-id}	The ID of your PingOne environment.
{application-id}	The ID of the PingOne application created in this section.

info

PingOne admin consoles are region-specific. This section uses the European region (console.pingone.eu, auth.pingone.eu) as an example; replace the domain with the one for your region, for example console.pingone.com and auth.pingone.com in North America. The admin console sign-in URL includes your environment ID, for example https://console.pingone.eu/?env=<environment-id>. Keep the same region for the admin console and for the metadata URL.

Create the SAML application in PingOne

1. Sign in to the PingOne admin console for your region, for example https://console.pingone.eu/?env=<environment-id>.
2. Go to Applications → Applications and click + Add Application.
3. Enter a name, for example Cubbit, and select SAML Application as the application type.

Configure the PingOne application

1. In the Configuration tab, set the Service Provider values:
   • ACS URLs: https://{console-domain}/api/iam/v1/auth/saml/acs
   • Entity ID: the Entity ID you chose for this integration, identical to the value you will enter in the Tenant settings (see Connection values).
2. In the Attribute Mappings tab, add one mapping for each row, using the exact case-sensitive attribute names expected by the platform:
   • SAML attribute email → PingOne attribute user.email (required)
   • SAML attribute given_name → PingOne attribute user.name.given
   • SAML attribute family_name → PingOne attribute user.name.family
3. Back in the Configuration tab, keep Sign Assertion enabled (the default) with RSA-SHA256 as the signature algorithm, and set the Subject NameID format to emailAddress (recommended).
4. Enable the application with the Enabled toggle.
5. Open the Overview tab and copy the IdP metadata URL from Connection Details. The URL has the form https://auth.pingone.eu/<environment-id>/saml20/metadata/<application-id>, where <environment-id> and <application-id> identify your environment and application. You can also use Download Metadata to review the metadata XML.

Configure the Tenant in DS3 Composer

1. Sign in to DS3 Composer, open Tenants, and select the Tenant.
2. Open Settings and find the SAML SSO section in General.
3. Enable the SAML toggle and fill in the fields:
   • Entity ID: the same Entity ID configured in the PingOne application.
   • Name: a name for this provider, for example PingOne. The console uses this name to label the sign-in button.
   • IdP Metadata URL: the PingOne metadata URL copied in the previous section.
   • ACS URL: https://{console-domain}/api/iam/v1/auth/saml/acs, the same URL configured in PingOne.
4. Save the settings.

Test the sign-in

1. Open the DS3 Console sign-in page of the Tenant (for example https://{console-domain}/signin) and select the PingOne button.
2. Sign in at PingOne with the username of a directory user, not the email address, and the corresponding password.
3. On the first successful sign-in, the platform creates the account in the Tenant and redirects the browser back to the DS3 Console.

warning

If PingOne requires a password change on the first sign-in, complete it and then start the flow again from the DS3 Console sign-in page. A password change can exceed the validity of the sign-in attempt, so the first attempt may time out and require a second login attempt from the DS3 Console.

PingOne troubleshooting

For the generic SAML errors (400, 401, 502, mismatched Entity ID or ACS URL, and malformed URL messages), see SAML troubleshooting above.

PingOne-specific checks:

• PingOne rejects the email address on its sign-in page: PingOne expects the directory username, not the email address, on its own sign-in form.
• 401 Unauthorized after a successful sign-in at PingOne: verify that the directory user has an email address set in PingOne and that the email attribute mapping exists exactly as shown above.
• PingOne rejects the user before DS3 receives a response: if application access is restricted to selected groups, assign the user or their group to the application (Access tab).