DriveWorks Pro 23

Single Sign-On

Single Sign-On

Single Sign-On (SSO) is an authentication method that allows one account manager to sign users in to multiple independent software systems.

SSO allows users to maintain a single login and use it to login to different software tools. Administrators of different software tools, like DriveWorks, can register their applications with the SSO account manager that will be responsible for handling the login. Users can log in to DriveWorks by logging into their standard Windows Active Directory account, for example Microsoft Entra ID, acting as the SSO agent, will authenticate the user's login and validate the user for DriveWorks.

Currently Supported Integrations:

• Microsoft Entra ID

  See What is single sign-on in Microsoft Entra ID? for more information.

How To: Configure Microsoft Entra ID For SSO

SSO for Microsoft Entra ID is configured in the DriveWorks Pro Server Web Application, available on the machine running DriveWorks Pro Server.

After opening the Pro Server Web Application, select Single Sign-On.

Single Sign-On is configured in three stages:

1. Group Login
2. Microsoft Entra ID Configuration
3. Mapping Users in the Credential Tables
   • DriveWorks Users (left frame)
   • Microsoft Entra ID Accounts (right frame)

Group Login

Login to the DriveWorks Group that you wish to map to Microsoft Entra ID. This will need to be an Administrator user for the selected DriveWorks Group.

If you are already logged in to the Group, with an Administrator user, you will navigate straight to the SSO page.

Microsoft Entra ID Configuration

The information in this section specifies the Microsoft Entra Tenant/Client with which DriveWorks will connect for SSO authentication.

The following credentials are required to integrate with your Microsoft Entra ID.

These credentials are obtained when configuring Microsoft Entra ID during App Registration.

• Tenant ID - The global unique identifier (GUID) for the Microsoft Entra ID you are integrating with. This is sometimes referred to as the Directory ID.
• Client ID - The global unique identifier (GUID) for the application within your Microsoft Entra ID instance. This is sometimes referred to as the Application ID.
• Client Secret - Your client secret is a secret string defined in your Microsoft Entra ID instance that this application uses to prove its identity when requesting tokens for the Microsoft Entra ID.

NOTE: If you require help obtaining these values, you will need to consult with your IT department or the entity that manages your Microsoft Entra ID instance.

Once you have obtained these values, press Configure at the top of the SSO page. Enter the values and press Save.

If you need to clear these settings, you can press Configure, then Delete.

Credential Tables

The table on the left hand side shows the DriveWorks users for the DriveWorks Group selected in the Group Login section.

Selecting a DriveWorks user will then populate the Microsoft Entra ID Table on the right hand side, allowing you to map the DriveWorks user to one or more AD users.

Select the checkbox(s) required and then press Save. You can select multiple mappings to batch save.

Alternatively, selecting Cancel will cancel all changes.

Green rows indicate newly added user mappings, while red rows indicate user mappings to be removed.

Amber rows indicate a mapping conflict, specifically that an Entra ID is being mapped to more than one DriveWorks user. You cannot Save until the conflicts are resolved.

The Play/Pause button controls whether the connection to the Microsoft Entra ID client is active or paused. The button will display a pause icon when it is active. Click the pause icon to pause the connection. Click the play icon to resume the connection.

Microsoft Entra ID Configuration

In order for DriveWorks to connect to Microsoft Entra ID with the client information provided, you will need to ensure that the following permissions are set in the API Permissions section of the Microsoft Entra ID application to which you are connecting:

• Microsoft Graph
  • Delegated
    • openid
    • profile
    • User.Read
  • Application
    • User
      • User.Read.All

        This Allows DriveWorks to read user profiles without a signed in user. This is required in the Pro Server Configuration Tool Directory Synchronization area. Granting this requires the consent of the Microsoft Entra ID administrator.

Logging In To DriveWorks with SSO

When logging into a Group that has SSO credentials configured, the login popup window will appear differently.

The user will now be offered an option to log in with Azure Active Directory (which is Microsoft Entra ID) or use a DriveWorks User Name and Password.

Microsoft Entra ID Configuration

The following steps are required to configure an Microsoft Entra ID for use with the DriveWorks Single Sign-On feature.

Create An App Registration

From the Azure Portal home page, select Microsoft Entra ID then App Registrations.

1. Enter a Name for the App.

   The Name given to the App Registration should be something meaningful to yourself.

2. Under Supported Account Types, select the 'Accounts in any organizational directory (Any Microsoft Entra directory - Multitenant) and personal Microsoft accounts (e.g. Skype, Xbox)'.

The Optional Redirect URI field can be left empty at this stage.

Add Platforms to the App Registration Authentication Config

Each platform type that is to use SSO is required to be added.

The applicable platform types are:

• Desktop

  Used for logging into a Shared Group from all DriveWorks desktop based modules.

• Web

  Used for logging into a web based DriveWorks solution through the DriveWorks Live Integration Theme.

  See Using SSO with DriveWorks Live below.

To Add a platform

1. From the Azure Portal home page, select Microsoft Entra ID then App Registrations.
2. Select the application registered in Create An App Registration above.
3. Select Authentication from the left hand menu.
4. For Desktop Application authentication:
   5. Press Add a platform.
   6. Select Mobile and desktop applications.
   7. Leave the three URI options unchecked.
   8. When asked for a Custom redirect URI, enter http://localhost
   9. Press configure.

   For Web authentication:

   5. Press Add a platform.
   6. Select Web.
   7. When asked for a Redirect URI, enter the URL hosting the Integration Theme followed by /api/[GROUP_ALIAS]/oauth2/token

      For example:

      https://[SERVER_URL]/api/[GROUP_ALIAS]/oauth2/token

      The values entered above are case-sensitive.

   8. Scroll down the page to ‘Implicit grant and hybrid flows’ and select both ‘Access tokens’ and ‘ID token’

      

   9. Press configure.

   To allow the Integration Theme to use SSO an additional element is required to be added to the DriveWorksConfigUser.xml file.

   See Using SSO with DriveWorks Live below.

API Permissions

Ensure the permissions detailed in Microsoft Entra ID Configuration (above) are set in the API Permissions section of the Microsoft Entra ID application to which you are connecting.

Using SSO with DriveWorks Live (Integration Theme)

In order to use SSO with DriveWorks Live, you will need to use the Integration Theme. This contains a Javascript function (loginSSO) that will consume the client secret from the Group Alias.

To set your Integration Theme site to use SSO, you will need to add the following code inside the sharedGroupAlias element of the DriveWorksConfigUser.xml.

See Group Connection Settings for more information.

<identityProviders>
    <azure>
        <!-- Note: This is the same secret you add to the Pro Server Config Tool -->
        <clientSecret>InsertSecretHere</clientSecret>
    </azure>
</identityProviders>

An example of this code in place would look like this:

<connections>
    <sharedGroupAlias name="DriveWorksAlias" serverAddress="ProServerMachine" groupname="GroupName">
        <identityProviders>
            <azure>
                <!-- Note: This is the same secret you add to the Pro Server Config Tool -->
                <clientSecret>InsertSecretHere</clientSecret>
            </azure>
        </identityProviders>
    </sharedGroupAlias>
<connections>

Consuming SSO in the DriveWorks Example Sites

To use SSO to login to the DriveWorks Example Sites, the login method is required to use loginSSO.

This is done by changing the line below:

In the login.js file find the following line:

// Start session
const result = await DW_CLIENT.loginGroup(GROUP_ALIAS, userCredentials);

And change it to this:

// Start session
const result = await DW_CLIENT.loginSSO(GROUP_ALIAS);

You will only need to pass in the Group Alias into this method.

Frequently Asked Questions

Can I use DriveWorks Logins alongside SSO logins?

• Yes, the login window allows each user to decide the credentials that they wish to use each time they log in.

How can I log in with a different Windows user?

• Microsoft Entra ID credentials are cached in Windows. If you need to change Microsoft Entra ID users, you will need to remove the cache file (C:\Users\[Windows User logged in]\AppData\Local\DriveWorks\AADCache).

Does configuring the SSO in the Pro Server Configuration enable users to use SSO in all DriveWorks modules?

• Configuring SSO in the Pro Server Configuration utility will enable users to log in to every DriveWorks application, including DriveWorks Administrator, DriveWorks Live (and web sites driven by DriveWorks Live), DriveWorks Autopilot, DriveWorks User and the DriveWorks Data Management tool.