Azure AD as a User Directory via Microsoft Graph API

This document provides instructions for adding users from Azure Active Directory (Azure AD) as PrivX users. By following these instructions, you can allow users from your Azure AD to log into PrivX. Such users may then be granted access similarly to regular AD users.

This version of the instructions is suitable for Azure environments without LDAPS. For Azure environments that support LDAPS, consider checking Microsoft Azure AD as a user directory via LDAPS instead.

Disclaimers

This document includes instructions regarding third-party products by Microsoft. These instructions are provided for general guidance only.

Documentation involving third-party products include configuring applications in Microsoft Azure. The instructions in this manual were verified against the Microsoft Azure version that was current in March 2022. These instructions will need to be adapted when using other versions of Microsoft Azure.

SSH Communications Security Corporation does not make any warranties as to the accuracy, reliability, or usefulness of these instructions, or guarantee that the content related to third-party products is up to date.

SSH Communications Security Corporation does not provide any warranties regarding third-party products, such as Microsoft Azure, nor provide any support or other services for third- party products.

For instructions about setting up and operating Microsoft Azure products, we always recommend that you consult the official Microsoft documentation intended for the specific version(s) of Microsoft products in your use and/or directly contact Microsoft representatives or support.

It is always your responsibility to define the final production setup for the Microsoft products that you use.

Prerequisites

Check and ensure the following before performing integration:

• Your Azure AD must contain the users that are to access PrivX.
• You will need access to your Azure Portal with sufficient permissions for registering new apps.
• You will need access to PrivX as a privx-admin.

Integration Steps

The high-level workflow for allowing Azure AD users to log into PrivX involves:

1. Registering PrivX as an application in Azure.
2. Configuring the Azure AD in PrivX.
   These steps are described in more detail in the following sections.

Registering PrivX in Azure

Azure AD users use Microsoft login for authenticating to PrivX. To enable this functionality, you must first register PrivX as an app in Azure:

1. Log into Azure Portal at https://portal.azure.com/
   Ensure you are logged into the correct directory.

2. To create a new app, navigate to Azure Active Directory→App registrations, then click New Registration.

3. Provide the required information regarding the PrivX app.

After providing the PrivX-app data, click Register.

You should now see the details of your app. Make note of the Application ID and the Directory ID, which are later required for configuring PrivX.

1. Next, create an authentication key for the PrivX app. To do this, click Certificates & Secrets, then click New Client Secret.
   Enter the details for your key, then click Save.
   Copy the Value of the key, which is later required for PrivX configuration.

2. Provide the PrivX app with sufficient permissions for reading user and group data. To do this, click API permissions, then click Add a permission. The PrivX app will require at least the following Microsoft Graph permissions:

• Application:
  • GroupMember.Read.All
  • User.Read.All

Also Grant admin consent.

1. Finally, give the PrivX app sufficient roles in your subscription. Go to All services→Subscriptions and select your subscription. Then under Access control (IAM), click Add and select Add Role Assignment.

Provide the Reader role to your PrivX app.

Click Review + assign. The PrivX app is now set up.

Adding Azure AD users to PrivX

Configure PrivX to import users from Azure AD, and to authenticate Azure-AD users using Microsoft login:

1. Access the PrivX GUI.
2. On the Administration→Directories page, click Add Directory.
   Add a directory of type Microsoft Graph. Provide the rest of the required settings:

• Tenant ID: Your Azure Directory ID.

• Application ID: The Application ID of your PrivX app.

• Authentication key: The value of the key for your PrivX app.

• Issuer: OpenID Connect Issuer URL, typically of the syntax (Replace with the Directory ID of your Azure AD):
  https://sts.windows.net/<Directory ID>/

• Client ID: Application ID of your PrivX app, typically the same you would enter into Application ID.

• Client secret: The value of the key for your PrivX app, typically the same you would enter into Authentication key.

• Login button title: Optional, title for the button used for Azure AD login.

• Group names: Optional: if specified, only users from the specified groups are added.

1. Click Save to apply your changes. You should verify the directory back on the Administration→Directories page.

Note that it will take a while for PrivX to fetch and display the directory status. You should ensure that the directory status displays one or more users.

Verifying Integration

You may verify integration by testing login with one of the Azure AD users:

1. Log out from PrivX (if logged in). Navigate to the PrivX login page.
2. Click the login button for your Azure AD. In this example, Microsoft Login.
3. Sign in with your Azure AD credentials.
   After successful sign in you will be logged into the PrivX GUI. Integration is now complete.

Attribute mapping for Graph directory

To modify the user attributes for your Graph directory users, you can edit the "Attribute Mapping" field within your Graph directory settings:

Supported source fields since PrivX 31 are principal, mail, name, cn, givenname, sn, usage_location, mailnickname, city, companyname, onpremisessamaccountname, onpremisesuserprincipalname, onpremisesdistinguishedname, country, department