Add Azure Active Directory as a directory service

This topic describes how to add Azure Active Directory (AAD) as a directory service in CyberArk Identity.

We only support managed domains for AAD as a Directory Service.

To add AAD as a directory source, you need to register an application in your Azure account with appropriate access to the Microsoft Graph API. You can then authenticate using the Azure application's Application ID, Directory ID, and Client Secret.

CyberArk recommends registering a new Azure application that is specific to its intended purpose. For example, if you are adding Azure Active Directory as a directory source in CyberArk Identity in addition to integrating Office 365 for SSO and provisioning, you would register two Azure applications - one for each task. In addition, each registered application should have the minimum set of API permissions required to perform its function.

Step 1: Register an Azure application.

  1. Log in to your Azure account as an administrator.

    https://portal.azure.com

  2. Go to App registrations, and click New registration.

  3. Enter a name for your app.

  4. Select Accounts in this organizational directory only.

  5. Click Register.

    The overview page for your registered app appears.

    Once you register an app, Azure generates an Application (client) ID that is unique for your app. You will later use this ID to add AAD as a directory source in the Identity Administration portal. If you remove the registered app in Azure, the Identity Administration portal will lose AAD user information; AAD user objects already in the Identity Administration portal will be orphaned. This means you will have to:

    • remove AAD from the Identity Administration portal and re-add it using a new Application (client) ID
    • update the members list for any roles that included AAD users
    • update application permissions for any apps assigned to individual AAD users

Step 2: Add Certificates & secrets to allow access to the resource server.

  1. Go to Certificates & secrets, then click New client secret.

  2. Enter a description and select an expiration date option, then click Add.

  3. Copy the client secret value and paste it into a text editor for later use. You can click the copy icon to the right of the row.

    The client secret value will be unavailable once you logout, so it's critical to capture the value now.

Step 3: Grant the necessary API permissions to your newly registered app.

  1. Go to API permissions, then click Add a permission.

  2. Click Microsoft Graph.

  3. Click Application permissions.

  4. Scroll down the permissions list and select the following permissions, then click Add permissions.

    • Domain.Read.All

    • Group.Read.All

    • User.Read.All

  5. Azure updates the permissions for your app; however, you still need to provide admin consent.

    Refer to Microsoft's documentation for more information on the difference between Delegated and Application permissions, as well as reference material for each permission.

  6. Click Grant admin consent for <your company>.

  7. Click Yes on the confirmation prompt.

    Since you are already logged in as an administrator, a notification Successfully granted admin consent for the requested permissions. appears at the top of the page.

  8. Return to the overview page for the registered application; you will need the information there for the following steps.

Step 4: Add the Azure Active Directory in the Identity Administration portal.

  1. Open a new browser tab and log in to the Identity Administration portal as a member of the system administrator role.

  2. Go to Settings > Users > Directory Services, then click Add Azure Active Directory.

    The Azure Active Directory Service window appears.

  3. Enter a name for the Azure Active Directory.

  4. Copy the following values from the overview page of your registered app in the Azure portal and paste them into the Azure Active Directory Service window in the Identity Administration portal.

    • Application (client) ID
    • Directory (tenant) ID

  5. Enter the client secret value you saved previously.

  6. Click Authorize.

    Your available domains appear in the table below the authorize button. Domains not indicated as Federated are considered Managed domains.

    If you add additional custom domains in AAD, you have to re-authorize AAD in the Identity Administration portal before you can query the users and groups.

  7. Below the list of domains, click Copy URL to copy the authenticated redirect URI.

  8. From the Overview page of your registered app in the Azure portal, click Add a redirect URI.

  9. Click Add a platform, then click Web.

  10. Paste the redirect URL you copied from the Identity Administration portal into the Redirect URIs field.

  11. Select ID tokens in the Implicit grant section, then click Configure.

    Your Azure Active Directory users can now log in to CyberArk Identity using their Azure Active Directory credentials. Add them to roles so you can grant permissions to applications, enforce authentication profiles, and more.

    After entering a username, users are redirected to login.microsoftonline.com for authentication, then redirected back to the User Portal after successfully completing authentication mechanisms.

    Signing out from CyberArk results in managed domain users signing out from AAD as well; however, due to third-party limitations users are not signed out of the Azure Portal (portal.azure.com).