icon-unified.svg
Experience Center

Configuration Guide for Microsoft Azure AD

This guide provides information on how to set up Microsoft Azure Active Directory (AD) as an IdP for Private Applications.

Prerequisites

Ensure that you have the following:

  • A premium Azure AD subscription, or an Azure AD subscription that has used less than 10 gallery Single Sign-On (SSO) applications with the license.
  • An existing directory in Azure AD.
  • A Private Applications account with an administrator role that allows you to add an IdP Configuration.

Configuring Azure AD for SSO

To configure Azure AD as the IdP for a Private Applications user and admin SSO:

  1. Log in to the Azure portal and go to Azure Active Directory > Enterprise applications from the left navigation pane.
  2. Click New application.
  3. Under Add from the gallery, search for "Zscaler Private Access". Choose one of the following:
    • For Private Applications user SSO in the IdP configuration, click the Zscaler Private Access (ZPA) application.
    • For Private Applications admin SSO in the IdP configuration, click the Zscaler Private Access Administrator application.

The following images in this procedure use the Zscaler Private Access (ZPA) application as an example.

  1. Click Add.

You are redirected to the Zscaler application's Overview page.

  1. Click Single sign-on, then SAML.

The Set up Single Sign-on with SAML - Preview page appears.

  1. For Basic SAML Configuration, click Edit and complete the following fields:
    1. For Identifier (Entity ID) enter the Service Provider Entity ID that is provided for you when you configured a new IdP configuration in the Admin Portal. This ID is specific to your IdP.
    2. For Reply URL (Assertion Customer Service URL) enter the Service Provider URL that is provided for you when you configured a new IdP configuration. This URL is specific to your IdP.

    3. For Sign on URL, perform the following:

    4. Click Save.

After saving, you will be prompted to test the configuration. Do not test the configuration at this time.

  1. Leave User Attributes & Claims as default and skip to the next step.
  2. Under SAML Signing Certificate, for Federation Metadata XML, click the Download link to obtain the metadata file. You will need to upload this IdP metadata information to the Admin Portal later in order to complete the configuration.

  1. Leave Set up Zscaler Private Access (for Private Applications user SSO) or Set up Zscaler Private Access Administrator (for Private Applications admin SSO) as default, and skip to the next step.

Do not test the configuration at this time.

  1. In order for Azure AD users to authenticate through Private Applications, you must assign these users to the Private Applications application. In the application, click Users and Groups then Add user.
  2. Search for the user you want to assign to the Private Applications application.
  3. Select the checkbox next to the user name, then click Select.
  4. In the Add Assignment panel, click Assign.
  5. If you are configuring the Azure AD for user SSO and want to use SCIM, proceed to the SCIM Configuration Guide for Microsoft Azure AD.
  6. If you are configuring the Azure AD for user SSO, proceed to the Using Roles for Group Mapping procedure below, then complete the IdP configuration. If you are configuring the Azure AD for admin SSO, you can go directly to the Admin Portal to complete the IdP configuration.

Using Roles for Group Mapping

The following procedure applies to IdP configurations for Private Applications user SSO only.

If all of the following criteria are met, then group mapping is not required:

  • User-friendly group names are only sent to Azure AD using Azure AD Connect. For example, groups from an on-premise active directory show up in Azure AD when Azure AD Connect syncs the group information.
  • AD Connect is on version 1.2.7.0 or greater.

To configure group mapping in Azure AD, you must customize the role claim type in the SAML response token in order to push groups to Private Applications. To learn more about configuring role claims, see the Microsoft product documentation.

  • You must add a role for each group you've created. If possible, ensure that the role name and group name are the same.

    To add a role in the Private Applications application:

    1. Go to the Microsoft Graph Explorer.
    2. Sign in using your Azure credentials to run the Graph Explorer against your tenant.
    3. Under Authentication, click modify permissions.

    The Modify Permissions window appears.

    1. Select the following permissions from the list, then click Modify Permissions:
      • Directory.AccessAsUser.All
      • Directory.Read.All
      • Directory.ReadWrite.All

    1. Choose beta for the version.
    2. Enter the following query to retrieve the list of servicePrincipals from your tenant:
    https://graph.microsoft.com/beta/servicePrincipals
    1. Click Run Query.
    2. Under Response Preview, search for the following service principal.
    "appDisplayName": "Zscaler Private Access (ZPA)"

    Following is a part of the response preview for the ZPA application. Its id is highlighted in green.

    {
         "id": "c7195233-3226-4121-b436-b8e755bab66c",
         "deletedDateTime": null,
         "accountEnabled": true,
         "addIns": [],
         "appDisplayName": "Zscaler Private Access (ZPA)",
    1. Use the id to enter the following query:
    https://graph.microsoft.com/beta/servicePrincipals/<"id" of Private Applications application>

    In this example, it's https://graph.microsoft.com/beta/servicePrincipals/c7195233-3226-4121-b436-b8e755bab66c.

    1. Click Run Query.

    You will get a response preview similar to the following. The appRoles property is highlighted in green.

    {
        "@odata.context": "https://graph.microsoft.com/beta/$metadata#servicePrincipals/$entity",
        "id": "c7195233-3226-4121-b436-b8e755bab66c",
        "deletedDateTime": null,
        "accountEnabled": true,
        "addIns": [],
        "appDisplayName": "Zscaler Private Access (ZPA)",
        "appId": "6a59ce75-7dd0-4033-a651-8053a9884f88",
        "appOwnerOrganizationId": "6f7ada54-20ef-4a88-810b-a1c4179e8da9",
        "appRoleAssignmentRequired": false,
        "appRoles": [
            {
                "allowedMemberTypes": [
                    "User"
                ],
                "description": "msiam_access",
                "displayName": "msiam_access",
                "id": "8866de6e-6d1e-4990-b534-2927284b7c14",
                "isEnabled": true,
                "origin": "Application",
                "value": null
            }
        ],
    1. Copy the entire appRoles property and paste it in the Request Body.
    2. Add roles in the same JSON format. Each role must:
      • Be in the same format as the msiam_access role
      • Have a unique id (e.g., "id": "82811e87-6f98-4510-95e5-9cbe849acfad"). You can use a Globally Unique Identifier (GUID) generator.
      • Have ServicePrincipal as the origin (e.g., "origin": "ServicePrincipal")
      • Have a unique value (e.g., "value": "Engineer")

    In the following request body example, the Engineer and Quality_Assurance roles are being added:

    {    "appRoles": [
            {
                "allowedMemberTypes": [
                    "User"
                ],
                "description": "msiam_access",
                "displayName": "msiam_access",
                "id": "8866de6e-6d1e-4990-b534-2927284b7c14",
                "isEnabled": true,
                "origin": "Application",
                "value": null
            },
            {
                "allowedMemberTypes": [
                    "User"
                ],
                "description": "Engineer",
                "displayName": "Engineer",
                "id": "8866de6e-6d1e-4990-b534-2927284b7c15",
                "isEnabled": true,
                "origin": "ServicePrincipal",
                "value": "Engineer"
            },
            {
                "allowedMemberTypes": [
                    "User"
                ],
                "description": "Quality_Assurance",
                "displayName": "Quality_Assurance",
                "id": "8866de6e-6d1e-4990-b534-2927284b7c16",
                "isEnabled": true,
                "origin": "ServicePrincipal",
                "value": "Quality_Assurance"
            }
        ],
    }
    1. Choose PATCH.
    2. Click Run Query. If your request body patched successfully, you'll see a success status code.
    3. To see if the roles were added, under History on the left navigation pane, choose the query with the "id" of the ZPA application. In this example, it's https://graph.microsoft.com/beta/servicePrincipals/c7195233-3226-4121-b436-b8e755bab66c.
    4. Under Response Preview, scroll down to the appRoles property, and you'll see the added roles. In this example, within the section highlighted in green, the added roles are Quality_ Assurance and Engineer:
    {
        "@odata.context": "https://graph.microsoft.com/beta/$metadata#servicePrincipals/$entity",
        "id": "c7195233-3226-4121-b436-b8e755bab66c",
        "deletedDateTime": null,
        "accountEnabled": true,
        "addIns": [],
        "appDisplayName": "Zscaler Private Access (ZPA)",
        "appId": "6a59ce75-7dd0-4033-a651-8053a9884f88",
        "appOwnerOrganizationId": "6f7ada54-20ef-4a88-810b-a1c4179e8da9",
        "appRoleAssignmentRequired": false,
        "appRoles": [
            {
                "allowedMemberTypes": [
                    "User"
                ],
                "description": "msiam_access",
                "displayName": "msiam_access",
                "id": "8866de6e-6d1e-4990-b534-2927284b7c14",
                "isEnabled": true,
                "origin": "Application",
                "value": null
            },
            {
                "allowedMemberTypes": [
                    "User"
                ],
                "description": "Quality_Assurance",
                "displayName": "Quality_Assurance",
                "id": "8866de6e-6d1e-4990-b534-2927284b7c16",
                "isEnabled": true,
                "origin": "ServicePrincipal",
                "value": "Quality_Assurance"
            },
            {
                "allowedMemberTypes": [
                    "User"
                ],
                "description": "Engineer",
                "displayName": "Engineer",
                "id": "8866de6e-6d1e-4990-b534-2927284b7c15",
                "isEnabled": true,
                "origin": "ServicePrincipal",
                "value": "Engineer"
            }
        ],
        "displayName": "Zscaler Private Access (ZPA)",
        "errorUrl": null,
        "homepage": "https://samlsp.private.zscaler.com/auth/sso?metadata=zscalerprivateaccess|ISV9.2|primary|z",
        "keyCredentials": [

    You need the roles you added in order to complete step f of the Assigning Roles to Groups procedure below.

    Close

  • Assign roles to the groups in the Private Applications application. Each group must be paired with its own role (i.e., 1:1 mapping ratio between groups and roles).

    To assign a role to a group:

    1. Log in to the Azure portal and go to Azure Active Directory > Enterprise applications from the left navigation pane.
    2. Click All applications, then click the Zscaler Private Access (ZPA) application you added for the Adding Roles in the Private Applications Application procedure above.
    3. Click Users and groups, then click Add user.
    4. In the Add Assignment panel that appears, select Users and groups.
    5. Select the group you want to assign a role to (e.g., the Engineer group), then click Select.
    6. Click Select Role, then choose the role you added for the Adding Roles in the Private Applications Application above (e.g., the Engineer role).
    7. Click Select.
    8. In the Add Assignment panel, click Assign.

    Repeat this procedure for each role you added for the Adding Roles in the Private Applications Application procedure above.

    Close

  • You must import the memberOf attribute to Private Applications. Ensure that you have already added the attribute in Azure.

    To import the memberOf attribute to Private Applications:

    1. In the Admin Portal, go to Administration > Identity > Private Access > IDP Configuration.
    2. In the IdP Configuration page, expand the user SSO configuration for Azure AD.
    3. Click Import SAML Attributes.

    IdP Configuration page with Import SAML Attributes link

    If Private Applications was correctly configured, the link redirects you to the SSO login page.

    1. Sign in using your Azure AD credentials. The Private Applications authentication service automatically imports the memberOf attribute.

    Import SAML Attributes page in ZPA Admin Portal

    1. Click Save.
    Close

After configuring your IdP, be sure to verify the configuration.

If you are verifying your Private Applications admin SSO configuration, you can also go to myapps.microsoft.com. From your Dashboard, click on the Private Applications app to initiate admin SSO.

Related Articles
Configuration Guide for Gemalto SafeNet Authentication ManagerConfiguration Guide for Microsoft ADFS 2.0 and 3.0Configuration Guide for Microsoft Azure ADConfiguration Guide for OktaConfiguration Guide for OneloginConfiguration Guide for Ping Identity PingOne