Skip to main content
Version: v41

Microsoft Entra ID as a User Directory via Microsoft Graph API

This document provides instructions for adding Microsoft Entra ID users to PrivX. By following this guide, you can enable Entra ID users to log into PrivX and grant them access just like regular Active Directory users.

Disclaimer​

This document contains general guidance for configuring third-party products from Microsoft. Its instructions were verified with the Microsoft Azure version current as of January 2023 and may require adjustments for other versions.

SSH Communications Security Corporation makes no warranties regarding the accuracy, reliability, or continued relevance of these instructions, and does not offer support for third-party products.

For accurate setup and usage, refer to the official Microsoft documentation or contact Microsoft support. You are responsible for defining your final production setup for Microsoft products.

Prerequisites​

Before the Entra ID integration, check the following:

  • Your Entra ID contains the users that are to access PrivX.
  • You have access to your Azure Portal with sufficient permissions for registering new Entra ID apps.
  • You have 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 detailed in the following sections.

Registering PrivX in Entra ID​

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

  1. Log into the 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, and click New registration.

  3. Provide the required information about the PrivX app, then click Register:

    info

    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 your PrivX server address).

    You should now be able to see the details of your app. Make note of the Application ID and the Directory ID, which are later required for PrivX configuration:

  4. Next, create an authentication key for the PrivX app by selecting Certificates & Secrets, then New Client Secret.

    1. Enter the details for your key, then click Save.
    2. Copy the key Value, which is later required for PrivX configuration.

  5. 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

    Remember to also grant admin consent.

  6. 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.

    1. Provide the Reader role to your PrivX app.

    1. Click Review + assign.

After completing these steps, the PrivX app should be set up.

Adding Entra ID Users to PrivX​

To make PrivX recognize the Entra ID users and allow them to authenticate via Microsoft login, you must configure it to import the Entra ID users:

  1. Access the PrivX GUI.

  2. Go to Administration→Directories and click Add Directory.

    Add a directory of type Microsoft Graph, providing the following required settings:

    • Microsoft Graph Settings:
      • Tenant ID: Entra ID Directory ID.
      • Application ID: PrivX app application ID.
      • Authentication Key: Key value of your PrivX app.
    • OpenID Connect Settings:
      • Issuer: OIDC Issuer URL, typically following the syntax https://sts.windows.net/<Directory_ID>/ (replace <Directory_ID> with your Entra ID Directory ID).
      • Client ID: PrivX app application ID (typically the same used in the Application ID field).
      • 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 Filter
      • Group Names (optional): If specified, only users from the listed groups are added to PrivX.

    info

    Due to limitations in the Microsoft Graph API, resolving groups for all Entra ID users can be slow if specific group names are not defined. To improve performance – especially in large directories – it is strongly recommended to specify the group names containing the users you want to import into PrivX.

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

    It can take a while for PrivX to fetch and display the directory status. It should display one or more users after that.

info

User's groups are automatically created as user tags in PrivX. This allows you to use tags for role mapping.

Note that 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) and navigate to the login page.

  2. Click the login button for your Entra ID — for example, Microsoft Login.

  3. Sign in with your Entra ID credentials.

  4. After a successful login, you should be granted access to PrivX. 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:

Since PrivX 36, the supported source fields are:

  • principal
  • mail
  • name
  • cn
  • givenName
  • sn
  • usageLocation
  • mailNickname
  • city
  • companyName
  • onPremisesSAMAccountName
  • onPremisesUserPrincipalName
  • onPremisesDistinguishedName
  • onPremisesSecurityIdentifier
  • country
  • department
  • officeLocation
  • jobTitle
  • preferredLanguage
  • employeeId
  • mailNickname
  • employeeType
  • state
  • objectSID

To map Entra custom attributes, use the extension_{appid}_attributename syntax, where {appid} is the app registration ID for aad-extensions-app (without hyphens). See How to define custom Entra attributes for more information.

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

extension_fc663c026ce54704801615f04e66e1b1_customAttribute1=principal