How to Integrate Deploy with the Platform

This guide provides step-by-step instructions for integrating Digital.ai Deploy with the Digital.ai Platform.

The Platform uses your existing single sign-on (SSO) infrastructure to securely authenticate users in Deploy using the same corporate credentials they already use. Acting as a bridge between your identity provider (IdP) and Deploy, the Platform grants access to Deploy based on user data from your IdP, eliminating the need for unique credentials in Deploy. This integration also allows you to map user groups in your IdP to specific roles in Deploy.

note

This guide assumes that you have already installed Deploy and configured one or more roles. If you have not yet done so, see the Deploy documentation

The following diagram summarizes the workflow required to complete this integration:

Before You Start

Complete the setup described in Prepare the Platform for a Product Integration. That topic covers administrator access, connecting your identity provider, mapping user attributes, and mapping IdP groups to Platform user groups — the work that's the same for every Digital.ai product. This guide picks up from there: it registers Deploy as an application in the Platform, then covers the Deploy-side configuration.

Deploy determines a user's permissions from the Platform user groups that user belongs to, so complete the group mapping step as well. See Map User Groups to Product Roles.

note

Digital.ai Deploy has no direct support for SAML. However, you can integrate Deploy as an OIDC client with the Digital.ai Platform Identity Service, and in turn connect that Identity Service to your SAML-compliant IdP.

Step 1: Connect Deploy to the Platform

In this step, you'll learn how to establish a connection between the Platform and your Deploy instance for user management and login purposes. This step does not cover setting up the Cloud Connector or Data Collector.

Add Deploy as an Application

First, you need to define your Deploy instance as an application in the Platform. This lets you download a configuration file whose values you apply to your Deploy server so Deploy understands the configurations you've made in the Platform.

The steps below are the Deploy version of the registration wizard. For what each wizard page does, the full list of application types, how mappers work, and how to get the client ID and secret again later, see Manage Applications.

1. In the left navigation, click Applications.

2. Click Applications.

3. Click Create application.

4. In Select application, choose Deploy.

5. In Instance name, enter a descriptive name for this instance.

6. Choose whether this is a production or non-production instance.

7. Enter the URL for your Deploy instance, in the following format:

   <deploy url>/oidc-login

8. On the Advanced configuration page, click Next.

9. On the Mappers page, click Next.

10. On the Get client ID & secret page, click Download to download the Deploy configuration file. Copy and save this information — you need it when you configure the OIDC Authentication plugin in Configure JVM Sites.

11. Click Complete.

A summary of the application and instance details appears at the end. It includes the Deploy configuration file, so you can return here if you need those values again.

Configure JVM Sites

Deploy is a Java-based application, meaning it runs inside a Java Virtual Machine (JVM). The JVM provides the runtime environment that executes the Deploy server's application code, which is what lets Deploy run on Linux, Windows, or macOS without modification.

The OIDC Authentication plugin is a Java-based component that runs inside the Deploy server's JVM. Configuring it allows secure communication between Deploy and the Identity Service.

Do the following on the Digital.ai Deploy server to integrate Deploy as an OIDC client with the Digital.ai Identity Service.

1. Install and enable the OIDC Authentication plugin, then change the Default configuration property to OIDC in the XL_DEPLOY_SERVER_HOME/centralConfiguration/deploy-server.yaml file.

2. To configure the OIDC Authentication plugin, add the following YAML code snippet to the XL_DEPLOY_SERVER_HOME/centralConfiguration/deploy-oidc.yaml file.

   deploy.security:
     auth:
       providers:
        oidc:
         loginMethodDescription:
         clientId: "<Your client ID>"
         clientSecret: "<Your client secret>"
         issuer: "<Enter the Open ID Provider Issuer>" # for example "https://identity.staging.digital.ai/auth/realms/demoaccount"
         redirectUri: "<deploy url>/login/external-login"
         postLogoutRedirectUri: "<deploy url>/login/external-login"
         rolesClaimName: "realm_access.roles"
         userNameClaimName: "preferred_username"
         emailClaim: "email"
         fullNameClaim: "name"

   note

   This configuration automatically fetches the required configuration from the discovery endpoint.

Add the Admin User in Deploy

Sign in to Deploy and add the local admin user.

1. Sign in to Deploy as an administrator.
2. Create a role named Admin and add the Platform admin user to that role.
3. Assign admin permissions to the Admin role you created.

Restart the Deploy Server

Restart the Deploy server and navigate to the appropriate instance URL. If you set a default IdP earlier, you're automatically redirected to the Platform authentication and seamlessly signed in to Deploy. If not, use the SSO login button to sign in to Deploy as your SSO user.

Configure Roles in Deploy

For this last step, you must update your roles in Deploy so they sync with the Platform user groups you created earlier.

In Deploy, go to Settings > Users and permissions > Roles and edit any of the roles. In Principals, add the Platform user group name that corresponds to this role. Repeat this for all roles that you want to inherit group assignments. You may optionally want to create new roles for this purpose, depending on how your workflow is configured.

For example, edit the role called Administrator User, and add allAdmins as a Principal for the role.

Next Steps

At this point you have successfully connected Deploy with the Platform. From here, you can move on to any of the following tasks (and more that aren't listed here):

• Inform your users that they can begin accessing Deploy with their corporate SSO credentials.
  • You may also want to instruct them to stop using their old application-specific login credentials entirely to avoid any confusion caused by using multiple user accounts.
• Begin configuring Analytics dashboards. For more information, see Creating Dashboards.