Setting up the Azure AD Integration

Overview

If your organization is using Azure Active Directory (Azure AD) or Office 365, you can connect your Automation Suite organization directly to your Azure AD tenant to see existing user accounts in your UiPath® environment.

The Azure AD integration allows you to continue leveraging local user model, if you want, while bootstrapping your organization with the additional benefits of using Azure AD. For more information about the differences, see Authority over accounts and groups.

If you have decided to use Azure AD for your organization, follow the instructions on this page to set up the integration.

Tip: The Azure AD integration is designed such that activating it and rolling it out can happen gradually, with no disruption in production for your existing users.

Prerequisites

To set up the Azure AD integration, you need:

• admin permissions in both Automation Suite and Azure AD (if you don't have admin permissions in Azure, collaborate with an Azure administrator to complete the setup process);
• an organization administrator UiPath account that uses the same email address as an Azure AD user; the Azure AD user does not require admin permissions in Azure;
• UiPath Studio and Assistant version 2020.10.3 or later;
• UiPath Studio and Assistant to use the recommended deployment .
• if you previously used local user accounts , make sure that all your Azure AD users have the email address in the Mail field; having the email address in the User Principle Name (UPN) field alone is not enough. The Azure AD integration links directory user accounts with the local user accounts if the email addresses match. This allows users to retain permissions when they transition from signing in with their local user account to the Azure AD directory user account.

Note: UiPath obeys the OIDC protocol for its integration with Azure Active Directory. However, the integration does not support usage of application custom keys through claiming an appid query parameter in a dedicated URL, as described in Microsoft's access tokens documentation.

Configuring Azure for the integration

Your organization requires an app registration in your Azure AD tenant and some configuration so that it can view your AD members to establish account identity. The app registration details are also required to later connect your organization to your Azure AD tenant.

Permissions: You must be an administrator in Azure to perform the tasks in this section. The following Azure administrator roles have the required privileges: Global Administrator, Cloud Application Administrator, or Application Administrator.

There are two ways to set up your Azure tenant for the integration:

• Follow the instructions below to manually configure an app registration for the integration.
• Use the UiPath Azure AD scripts that we created for this task, which are available on GitHub: The configAzureADconnection.ps1 script performs all the actions described in this section and returns the app registration details. Then you can run the testAzureADappRegistration.ps1 script to make sure the app registration was successful.

To manually configure your Azure tenant, do the following in Azure Portal:

1. Create an app registration for your organization.
   During registration, select Accounts in this organizational directory only and set the Redirect URI to https://{yourDomain}/identity_/signin-oidc.

   Note: If you already have a registered application for your organization, there is no need to create a new one, but make sure that it is set up as described above.
2. Open the application's Overview page, copy the Application (client) ID and Directory (tenant) ID, and save them for later use:
   
   

   

   
   
3. Go to the Authentication page of your app:
   1. Under Redirect URIs, click Add URI to add a new entry.
   2. Add https://{yourDomain}/portal_/testconnection to the Redirect URIs list.
   3. At the bottom, select the ID tokens checkbox.
   4. Click Save.
   
   

   

   
   
4. Go to the Token configuration page.
5. Select Add Optional Claim.
6. Under Token type, select ID.
7. Select the checkboxes for family_name,given_name, and upn to add them as optional claims:
   
   

   

   
   
8. Go to the API permissions page.
9. Click Add permission and add the following delegated permissions from the Microsoft Graph category:
   • OpenId permissions - email, openid, offline_access, profile;
   • Group member permissions - GroupMember.Read.All;
   • User permissions - User.Read, User.ReadBasic.All, User.Read.All (requires administrative consent).
   
   

   

   
   

   Permission	What it allows you to do	What we do with it
   email, openid, profile, offline_access, User.Read	Allows AAD to issue a user token to the system application	Allow users to log into the system using an AAD login. This permits us to keep our user object updated, ensuring consistency of these attributes.
   User.ReadBasic.All	Reads basic properties of all users in the directory that the logged in user is allowed to see	When a user assigns permissions to other users in the directory to their resources, they are able to search these users. The functionality for access management/authorization are in the system user experience.
   User.Read.All (requires admin consent)	Reads all user properties in the directory that the logged in user is allowed to see	Your administrator may want to import these additional user properties to configure permissions or display custom information inside the system services. For Automation Hub, customers looking to obtain the full set of attributes from AAD, it is necessary to grant the User.Read.All permission to the app.
   GroupMember.Read.All	Reads the group memberships of all the users that the signed in user has access to	If your organization is using groups to manage permissions in the system, then the platform needs to be able to list all the groups and discover the members of a group; that allows both management and enforcement of group assigned permissions.

   To learn more about UiPath's access with these permissions, see our Encryption documentation.

10. Select the Grant admin consent checkbox.
    Note: The administrator consents on behalf of all users in the tenant active directory. This allows the application to access the data of all users, without users being prompted to consent.

    For more information about permissions and consent, see the Azure AD documentation.
11. Go to the Certificates & secrets page.
12. Create a new client secret.
    Note: The created client secret is not permanent. You must update the client secret after its validity period.
13. Copy the client secret Value and save it for later use
    
    

    

    
    
14. Share the Directory (tenant) ID, Application (client) ID, and Client Secret values with the organization administrator so that they can proceed with the configuration.

Deploying the Integration to Automation Suite

After Azure setup is complete, you can prepare for the integration, activate it, and then clean up old accounts.

The process is broken down in stages so that there is no disruption for your users.

Permissions: You must be an organization administrator in Automation Suite to perform the tasks in this section.

Clean up Inactive Users

When you connect Automation Suite to Azure AD by activating the integration, accounts with matching email addresses are linked so that the Azure AD account benefits from the same permissions as the matching UiPath account.

Important: For account linking to work properly, make sure that all your Azure AD users have the email address added in the Mail field in Azure; having the email address in the User Principle Name (UPN) field alone is not enough.

If your organization practices email recycling, meaning that an email address that was used in the past could be assigned to a new user in the future, this could lead to a risk of elevated access.

Note: If inactive email addresses are not reused in your organization, you can skip this step.

More information...

Let's say you once had and employee whose email address was [e-mail] and this employee had a UiPath account where he was an organization administrator, but has since left the company and the email address was deactivated, but the user was not removed from Automation Suite. \n When a new employee who is also named John Doe joins your company, he receives the same [e-mail] email address. In such a case, when accounts are liked for the Automation Suite integration with Azure AD, John Doe inherits organization administrator privileges.

To prevent such situations, make sure you remove all users who are no longer active from Automation Suite before proceeding to the next step.

Activate the Azure AD Integration

Before you begin

• Make sure that Azure configuration is complete, as described above.
• Obtain the Directory (tenant) ID,Application (client) ID, and Client Secret values for the Automation Suite app registration in Azure from your Azure administrator.

To activate the Azure AD integration, do the following in Automation Suite:

1. Log in to your organization as an organization administrator.
2. Go to Admin, make sure that the organization is selected at the top of the left pane, and then click Security.
3. Click Configure SSO and then, in the panel that opens, click Azure Active Directory.
   
   

   

   
   
4. Fill in the fields with the information received from your Azure administrator.
5. Select the checkbox.

   This is required because after you save your changes, matching accounts are automatically linked.

6. Click Test Connection.
7. When prompted, sign in with your Azure AD account.

   A successful sign in indicates that the integration has been configured correctly. In case it fails, ask your Azure administrator to check that Azure is correctly configured and then try again.

8. Click Save.

   The integration is now active for your organization.

9. Go to Admin > organization > Settings and copy the URL for your organization.
10. Sign out.
11. Navigate to the URL for your organization (https://{baseURL}/orgID/) and sign in using your Azure AD account by clicking Continue with Enterprise SSO.

Now you can work with the users and groups in the linked Azure AD tenant. You can find Azure AD users and groups using search, for example to add a user to an Automation Suite group.

Note: Directory accounts and groups are not listed in either the Users or Groups pages under Admin > organization > Accounts & Groups, you can only find them through search.

What changes for my users after the integration is active?

Users can immediately sign in using their existing Azure AD account and benefit from the same permissions they had on their UiPath account.

If you have not removed their UiPath user accounts, users can also continue to sign in with their UiPath account, both methods work.

To use their Azure AD account, they must navigate to your organization-specific Automation Suite URL, which is of the form https://{baseURL}/myOrganization/, or select Enterprise SSO on the main login page.

Another change users might notice is that if they are already signed in to their Azure AD accounts from using another application, they are automatically signed in when they navigate to this URL.

What roles does each account have?

Azure AD account: When a user signs in with their Azure AD account, they immediately benefit from all the roles they had on their UiPath account, plus any roles assigned within UiPath to the Azure AD account or to the Azure AD groups to which they belong. These roles can come from the Azure AD user or the Azure AD group being included in Automation Suite groups, or from other services such as Orchestrator where roles were assigned to the Azure AD user or Azure AD group.

UiPath account: With the Azure AD integration active, for UiPath accounts it depends:

• If the user hasn't signed in at least once with their Azure AD account, they have only the roles of the UiPath account.
• If they have previously signed in with the Azure AD account at least once, the UiPath account also has any roles that the Azure AD user has within UiPath, either explicitly assigned, or inherited from Automation Suite group memberships. The UiPath account does not benefit from any of the roles assigned to Azure AD groups that the Azure AD account is in.

Do I need to re-apply permissions for the Azure AD accounts?

No. Because matching accounts are automatically linked, their existing permissions apply when logged in with the Azure AD account as well. However, if you decide to discontinue use of UiPath accounts, make sure the appropriate permissions have been set for users and groups from Azure AD beforehand.

Test the Azure AD Integration

To check that the integration is running from Automation Suite, sign in as an organization administrator with an Azure AD account and try to search for Azure AD users and groups on any related page, such as the Edit Group panel in Automation Suite (Admin > organization > Accounts and Groups > Groups > Edit).

• If you can search for users and groups that originate in Azure AD, it means the integration is running. You can tell the type of user or group by its icon.

  Note: Users and groups from Azure AD are not listed in the Users page or the Groups page, they are only available through search.

• If you encounter an error while trying to search for users, as shown in the example below, this indicates that there is something wrong with the configuration in Azure. Reach out to your Azure administrator and ask them to check that Azure is set up as described above in Configuring Azure for the Integration.

  Tip: Ask your Azure administrator to confirm that they selected the Grant admin consent checkbox during Azure configuration. This is a common cause why the integration fails.

Completing the Transition to Azure AD

After the integration is active, we recommend that you follow the instructions in this section to ensure that user creation an group assignations are handed off to Azure AD. This way you can build on top of your existing identity and access management infrastructure for easier governance and access management control over the resources of your Automation Suite organization.

Configure Groups for Permissions and Robots (Optional)

You can do this to ensure that the Azure administrator can also onboard new users with the same permissions and robot configuration for Automation Suite and other services that you had set up prior to the integration. They can do this by adding any new users to an Azure AD group if the group has the required roles already assigned in Automation Suite.

You can map your existing user groups from Automation Suite to new or existing groups in Azure AD. You can do this in several ways, depending on how you use groups in Azure AD:

• If users with the same roles in Automation Suite are already in the same groups in Azure AD, the organization administrator can add these Azure AD groups to the Automation Suite user groups that these users were in. This ensures that users keep the same permissions and robot setup.
• Otherwise, the Azure administrator can create new groups in Azure AD to match the ones in Automation Suite and add the same users that are in the Automation Suite user groups. Then the organization administrator can add the new Azure AD groups to the existing user groups to ensure the same users have the same roles.

In either case, make sure you check for any roles that were assigned to accounts. If possible, eliminate the explicit role assignments by adding these users to groups that have the roles that were explicitly assigned.

Example: Let's say the Administrators group in Automation Suite includes the users Roger, Tom, and Jerry. These same users are also in a group in Azure AD called admins. The organization administrator can add the admins group to the Administrators group in Automation Suite . This way, Roger, Tom, and Jerry, as members of the admins Azure AD group, all benefit from the roles of the Administrators group.

Because admins is now part of the Administrators group, when you need to onboard a new administrator, the Azure administrator can add the new user to the admins group in Azure, thus granting them administration permissions in Automation Suite without having to make any changes in Automation Suite.

Changes to Azure AD group assignments apply in Automation Suite when the user logs in with their Azure AD account, or if already logged in, within an hour.

Migrate Existing Users

Initial sign in: For the permissions assigned to Azure AD users and groups to apply, users must sign in at least one time. We recommend that, after the integration is running, you communicate to all your users to sign out of their UiPath account and sign in again with their Azure AD account. They can sign in with their Azure Ad account by:

• navigating to the organization-specific URL, in which case the sign in type is already selected;

  Note: The URL must include the organization ID and end in a forward slash, such as https://{baseURL}/orgID/.

• by selecting Enterprise SSO on the main login page.

  Note: Make sure you provide your organization-specific URL for Automation Suite to all your users. Only organization administrators can see this information in Automation Suite.

Migrated users benefit from the union of the permissions that were directly assigned to them and the ones from their Azure AD groups.

Configuring Studio and Assistant for users: To set up these products to connect with Azure AD accounts:

1. In Assistant, open Preferences and select the Orchestrator Connection tab.
2. Click Sign Out.
3. For the connection type, select Service URL.
4. In the Service URL field, add the organization-specific URL
   Note: The URL must include the organization ID and end in a forward slash, such as https://{baseURL}/orgID/. Otherwise the connection fails saying that the user does not belong to any organization.
5. Sign back in with the Azure AD account.

Important: Permissions from Azure AD groups don't influence the automations from classic folders or the robots that are connected using the machine key. To operate under group-based permissions, configure the automations in modern folders and use the Service URL option to connect to UiPath Assistant or Studio.

Discontinue Use of Local Accounts (Optional)

Although optional, we recommend that you do this to maximize the core compliance and efficiency benefits of the complete integration between Automation Suite and Azure AD.

After all users have been migrated, you can remove the users which are based on personal local accounts from the Users tab, so that your users won't be able to sign in using their UiPath accounts anymore. You can find these accounts based on their user icons.

You can also clean up individual permissions in the UiPath services, such as the Orchestrator service, and remove individual users from Automation Suite groups so that permissions rely exclusively on Azure AD group membership.

Best Practices

Here are a few useful pointers for advanced features you can leverage now that you have the Azure AD integration set up.

Restrict Access to Automation Suite

Because the integration with Azure AD is performed at the level of the Azure tenant, by default all Azure AD users can access the Automation Suite organization. The first time an Azure AD user signs in to Automation Suite, they are automatically included in the Automation Suite group Everyone, which grants them the User organization-level role.

If you want to only allow certain users to access your Automation Suite organization, you can activate user assignment for the Automation Suite app registration in Azure. This way, users need to be explicitly assigned to the app (Automation Suite) to be able to access it. For instructions, see this article in the Azure AD documentation.

Restrict Access to Trusted Networks or Devices

If you want to only allow your users to access Automation Suite from a trusted network or a trusted device, you can use the Azure AD Conditional Access feature.

Governance for Automation Suite Groups in Azure AD

If you have created groups in Azure AD for easy Automation Suite onboarding directly from Azure AD, as described in Configure groups for permissions and robots, you can use the advanced security options of Privileged Identity Management (PIM) for these groups to govern access requests for Automation Suite groups.