Microsoft Entra ID as a User Directory via Microsoft Graph API

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

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 January 2023. 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 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 Entra ID must contain the users that are to access PrivX.
  • You will need access to your Azure Portal with sufficient permissions for registering new Entra-ID apps.
  • You will need access to the PrivX GUI as a privx-admin.

Integration Steps

The high-level workflow for allowing Entra ID users to log into PrivX involves:

  1. Registering PrivX as an application in Entra ID.
  2. Configuring the Entra ID in PrivX.

These steps are described in more detail in the following sections.

Registering PrivX in Entra ID

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

  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 Microsoft Entra ID→App registrations, then click New registration.

  3. Provide the required information regarding the PrivX app.

    After providing the PrivX-app data, click Register.

    The Redirect URIs must contain a Web address with the format https://privx.example.com/auth/api/v1/oidc-cb (replace privx.example.com with the address of your PrivX server.)

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.

  3. Finally, give the PrivX app sufficient roles in your subscription. Go to 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 Entra ID Users to PrivX

Configure PrivX to import users from Entra ID, and to authenticate Entra-ID 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 Entra-ID Directory ID.
    • Application ID: The Application ID of your PrivX app.
    • Authentication Key: The value of the key for your PrivX app.
    • Issuer: OIDC Issuer URL, typically of the syntax (Replace <Directory ID> with your Entra ID's Directory ID):
      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 Entra-ID login.
    • Group Names: Optional, if specified, only users from the specified groups are added.

    Due to Microsoft Graph API limitations, if the Entra ID group names containing the desired PrivX users are not specified, resolving groups for all directory users may take a long time. Therefore, specifying the group names is strongly recommended, especially for large Entra ID directories with many users.

  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.

User's groups are automatically created as user tags in PrivX. This allows you to use tags for role mapping. Note if Group Names are specified, only matched groups are created as user tags.

Verifying Integration

You may verify integration by testing login with one of the Entra ID users:

  1. Log out from PrivX (if logged in). Navigate to the PrivX login page.
  2. Click the login button for your Entra ID. In this example, Microsoft Login.
  3. Sign in with your Entra ID 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 33 are: principal, mail, name, cn, givenName, sn, usageLocation, mailNickname, city, companyName, onPremisesSAMAccountName, onPremisesUserPrincipalName, onPremisesDistinguishedName, country, department, officeLocation, jobTitle, preferredLanguage, employeeId, mailNickname, employeeType, state

To map Entra custom attributes, use the extension_appid_attributename syntax, where appid is the app registration id for aad-extensions-app without hyphens.

How to define custom Entra attributes

For example, to use a custom attribute as the PrivX username:

extension_fc663c026ce54704801615f04e66e1b1_customAttribute1=principal

Was this page helpful?

On this page