DriveWorks Pro 22

SSO Credentials

SSO Credentials

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. Active Directory, acting as the SSO agent, will authenticate the user's login and validate the user for DriveWorks.

Currently Supported Integrations:

• Microsoft Azure Active Directory

How To: Configure Azure Active Directory For SSO

What is single sign-on in Azure Active Directory?

SSO for Active Directory (AD) is configured in the DriveWorks Pro Server Configuration utility, available in the DriveWorks folder in the Windows Start menu on the computer running DriveWorks Server. After opening the Pro Server Configuration utility, select the SSO Credentials option in the menu on the left.

This dialog is divided into three different sections:

• Group Login
• Active Directory Configuration
• Credential Tables
  • DriveWorks Users (left frame)
  • Active Directory Users (right frame)

Group Login

This section is used to select the DriveWorks Group to integrate with SSO.

Use the dropdown to select the required DriveWorks Group that you wish to map to Active Directory. Then enter Administrator credentials (username and password) for the selected DriveWorks Group.

A refresh button is available to update the list of available groups.

Press ‘Login’ to access the Group.

Active Directory Configuration

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

The following credentials are required to integrate with your Active Directory.

These credentials are obtained when configuring Azure Active Directory during App Registration.

• Tenant ID – The global unique identifier (GUID) for the Active Directory 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 active directory instance. This is sometimes referred to as the Application ID.
• Client Secret – Your client secret is a secret string defined in your Active Directory instance that this application uses to prove its identity when requesting tokens for the Active Directory.

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

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

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

The Play/Pause button controls whether the connection to the Active Directory 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.

Azure Configuration

In order for DriveWorks to connect to Active Directory with the client information provided, you will need to ensure that the following permissions are set in the API Permissions section of the Azure Active Directory 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 Active Directory 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 or DriveWorks User Name and Password.

Active Directory Configuration

The following steps are required to configure an Azure Active Directory for use with the DriveWorks Single Sign On feature.

Create An App Registration

From the Azure Portal home page, select Active Directory 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 Azure AD 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 Active Directory 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 Azure Configuration (above) are set in the API Permissions section of the Azure Active Directory 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?

• Active Directory credentials are cached in Windows. If you need to change active directory 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.