HomeDocumentationAPI Reference
Log In
These docs are for v17. Click to read the latest docs for v33.

Microsoft Azure AD as a User Directory via 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 SSH/RDP 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 May 2019. 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 the procedures in this document:

  • 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. Setting up Azure connectivity 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.

📘

Note

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

700

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.

794
  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 acquiring user data. To do this, click API permissions, then click Add a permission. The PrivX app will require at least the following permissions:

  • Azure Active Directory Graph
    • Directory.Read.All - Application
  • Microsoft Graph
    • Directory.Read.All - Delegated
    • Group.Read.All - Delegated
    • Group.Read.All - Application
    • User.Read.All - Delegated
1101

📘

Note

You will need to Grant admin consent for these permissions in your directory.

  1. Finally, give the PrivX app sufficient roles in your subscription. Go to All services→Subscriptions and select your subscription. Note the Subscription ID, which is later required for configuring PrivX. Then under Access control (IAM), click Add a role assignment.

Provide the Reader role to your PrivX app.

416

Click Save. 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 Azure Active Directory. Provide the rest of the required settings:
  • Subscription ID: The ID of your Azure subscription.
  • 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.
2274

📘

Note

Due to Microsoft Graph API limitations, if the Azure AD 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 Graph API directories with many users.

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