Prepare the Platform for a Product Integration

Every Digital.ai product integration starts the same way: you need administrator access to the Platform, a working connection to your corporate identity provider, user data flowing correctly from that provider into the Platform, and the product itself registered as an application. This topic sequences that work and links to the topic that covers each step in detail.

Once you finish here, continue with the guide for the product you're integrating. See Next Steps.

Understand How the Integration Works

The Platform uses your existing single sign-on (SSO) infrastructure to authenticate users in Digital.ai products with the same corporate credentials they already use. It acts as a bridge between your identity provider (IdP) and each product: the Platform grants access based on user data from your IdP, so no product needs its own set of credentials.

That bridge carries two kinds of information:

• Who the user is. First name, last name, email address, and username travel from your IdP into the Platform, which creates the user on first sign-in.
• What the user can do. Group memberships from your IdP become user groups in the Platform, and some products then map those groups to their own roles.

For the bridge to reach a product at all, that product has to be registered in the Platform as an application. Registering it creates the OIDC client the product authenticates against, and produces the client ID, client secret, and configuration file you apply on the product side. For what an application is and how the registration wizard works, see Manage Applications.

Get Administrator Access

Before doing anything else, you need an administrator user for your Platform account.

An initial administrator may already exist, created when your Digital.ai account was established, so check with your organization before you contact Digital.ai. If you have no record of an administrator, contact your Digital.ai representative to request an initial set of credentials. That first administrator can then invite others as needed.

You should also have received a unique URL for your Platform account. You use it for every task in this topic and in the product guides.

Your account URL is formatted like this: https://CUSTOMERNAME.REGION.digital.ai

For example: https://exampletech.us.digital.ai

For more information about this URL and how to change it, see Vanity Subdomains.

Complete the Setup Sequence

Work through these steps in order. Steps 1 through 6 apply to every product integration.

1. Gather your identity provider details. You need a client ID, a client secret, and a metadata URL for OIDC, or a metadata URL for SAML, plus the claim or assertion names your IdP uses for first name, last name, username, and email. You can find these by reviewing the Digital.ai application configured in your IdP. If no such application exists yet, create one first, working with whoever manages SSO administration at your company. For the full prerequisite list, see Connect to OIDC Provider or Connect to SAML Provider.
2. Connect your identity provider. Run the identity provider configuration wizard. The process differs by protocol, so follow Connect to OIDC Provider or Connect to SAML Provider.
3. Map user attributes. Mappers translate your IdP's claims or assertions into the fields the Platform expects. They're required for SAML and optional for OIDC unless your IdP uses non-standard claim names. See Map User Attributes.
4. Set the identity provider as default. We recommend this, because it skips the Platform login screen and sends users straight to your IdP. See Set a Default IdP.
5. Test the SSO connection. See Test the SSO Connection.
6. Assign the administrator role to your SSO user. See Assign the Administrator Role to Your SSO User.
7. Map user groups to product roles. This step depends on the product you're integrating. See Map User Groups to Product Roles.
8. Register the product as an application. This gives you the client ID, client secret, and configuration file the product needs. The wizard is the same for every product; the values you enter and what you do with the configuration file afterward are product-specific. For the wizard, see Manage Applications. For the product-specific values, see the guide for your product in Next Steps.

Test the SSO Connection

Confirm the connection works before you configure anything on the product side.

1. Sign out of the Platform.
2. Sign in again using the button for your newly configured IdP. If you set that IdP as the default, you're redirected to it automatically.
3. Confirm you reach the Platform. As long as you have an active session with your IdP, you're signed in without entering credentials again.

If the sign-in fails, review your IdP configuration. See Manage Identity Providers.

Assign the Administrator Role to Your SSO User

Your SSO user has no administrator permissions by default. Because we recommend completing the rest of the integration as your SSO user, grant that user the administrator role now, using your local administrator account.

1. Sign in with your local administrator account. If you set a default IdP, append /?loginIdp=local to your account URL to reach the local login screen. For example: https://exampletech.digital.ai/?loginIdp=local. For more information, see Override a Default IdP.
2. In the left navigation, under User Management, click Users.
3. Find your SSO user, then click the Edit icon in the Actions column.
4. In Roles, assign the account-admin role.
5. Save your changes, then sign back in as your SSO user.

For the full list of roles and what each one grants, see Map User Roles.

Map User Groups to Product Roles

Some Digital.ai products determine a user's permissions from the Platform user groups that user belongs to. For those products, you create matching user groups in the Platform, map your IdP's groups onto them, and then reference those group names in the product's own roles.

Product	Applies?	How permissions are determined
Release	Yes	Platform user group names are added as Principals on Release roles.
Deploy	Yes	Platform user group names are added as Principals on Deploy roles.
Agility	No	Agility matches users to an existing member account by username instead. Skip this section.

note

Group mapping is available only for OIDC connections.

Understand What Group Mapping Achieves

Suppose your IdP has these user groups:

• allAdmins
• analysts
• endUsers

And your product has these roles:

• Administrator User
• Digital.ai Analytics Service User
• End User

The Platform bridges the two. Once this mapping is in place, users receive product roles automatically based on their IdP group membership. If Doug belongs to the allAdmins group in Microsoft Entra ID (formerly Azure AD), he's assigned the Administrator User role in the product.

tip

For Entra ID, use the group's object ID rather than its name, because the object ID is the value Entra ID passes to OIDC applications like the Platform.

Set Up Group Mapping

1. Create matching user groups. The Platform doesn't create groups automatically. For every IdP group you want to map, create a group whose name exactly matches the group name, or the object ID for Entra ID, and select Sync with IdP. See User Groups.
2. Create a group mapper. One mapper passes every group from your IdP and places users in the matching Platform groups. See Create a Group Mapper.
3. Optionally, create role mappers. These assign Platform roles, not product roles, based on IdP group membership — useful when certain non-administrators need to author analytics dashboards, for example. Without them, users receive the account-user role. See Create a Role Mapper.
4. Reference the group names in your product's roles. This last step happens in the product, and each product guide covers it.

Next Steps

With the Platform prepared, continue with the guide for your product:

Product	Guide
Release	How to Integrate Release with the Platform
Agility	How to Integrate Agility with the Platform
Deploy	How to Integrate Deploy with the Platform

If you have questions or run into issues, contact Customer Support.