Configuration Guide for Microsoft Azure AD


Configuration Guide for Microsoft Azure AD

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

Prerequisites

Ensure that you have the following:

  • A premium Azure AD subscription
  • An existing directory in Azure AD
  • A ZPA 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 ZPA user and admin SSO:

  1. Log in to the Azure portal and go to Azure Active Directory > Enterprise applications from the left navigation pane.
    See image.
  2. Click New application.
    See image.
  3. Under Add from the gallery, search for "Zscaler Private Access". If you are:
    • Configuring the IdP for ZPA user SSO, click the Zscaler Private Access (ZPA) application.
    • Configuring the IdP for ZPA admin SSO, click the Zscaler Private Access Administrator application.

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

See image.

  1. Click Add.
    See image.

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

  1. Click Single sign-on, then SAML.
    See image.

The Set up Single Sign-on with SAML - Preview page that 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 ZPA 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 in ZPA Admin Portal. This URL is specific to your IdP.
    3. For Sign on URL, enter the same URL you used for the Reply URL (Assertion Customer Service URL) field in the previous step.
    4. Click Save.

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

See image.

  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 tho upload this IdP metadata information to the ZPA Admin Portal later in order to complete the configuration.

See image.

  1. Leave Set up Zscaler Internet Access (for ZPA user SSO) or Set up Zscaler Internet Access Administrator (for ZPA 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 ZPA, you must assign these users to the ZPA application. In the application, click Users and Groups then Add user.
    See image.
  2. Search for the user you want to assign to the ZPA application.
  3. Select the checkbox next to the user name, then click Select.
    See image.
  4. In the Add Assignment panel, click Assign.
    See image.
  5. 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 ZPA Admin Portal to complete the IdP configuration.

Using Roles for Group Mapping

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

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 ZPA. To learn more about configuring role claims, see the Microsoft product documentation.

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

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

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 ZPA application:

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

See image.

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

See image.

  1. Choose beta for the version.
    See image.
  2. Enter the following query to retrieve the list of servicePrincipals from your tenant:
https://graph.microsoft.com/beta/servicePrincipals
  1. Click Run Query.
    See image.
  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 ZPA application>

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

  1. Click Run Query.
    See image.

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.
    See image.
  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.
    See image.
  2. Click Run Query. If your request body patched successfully, you'll see a success status code.
    See image.
  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.
    See image.
  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.

Assign roles to the groups in the ZPA 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.
    See image.
  2. Click All applications, then click the Zscaler Private Access (ZPA) application you added for the Adding Roles in the ZPA Application procedure above.
    See image.
  3. Click Users and groups, then click Add user.
    See image.
  4. In the Add Assignment panel that appears, select Users and groups.
    See image.
  5. Select the group you want to assign a role to (e.g., the Engineer group), then click Select.
    See image.
  6. Click Select Role, then choose the role you added for the Adding Roles in the ZPA Application above (e.g., the Engineer role).
    See image.
  7. Click Select.
  8. In the Add Assignment panel, click Assign.
    See image.

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

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

To import the memberOf attribute to ZPA:

  1. In the ZPA Admin Portal, go to Administration 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 ZPA was correctly configured, the link redirects you to the SSO login page.

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

Import SAML Attributes page in ZPA Admin Portal

  1. Click Save.

Azure Active Directory > Enterprise applications menu option within Microsoft Azure Portal

Azure Active Directory > Enterprise applications menu option within Microsoft Azure Portal

Enterprise applications page with New application option within Microsoft Azure Portal

Zscaler Private Access application in gallery search results within the Microsoft Azure Portal

Add app panel within the Microsoft Azure Portal

Single sign-on panel within the Microsoft Azure Portal

Enter the Basic SAML Configuration information obtained from the ZPA Admin Portal

SAML Signing Certificate information within the Microsoft Azure Portal

Users and groups > Add User panel within the Microsoft Azure Portal

Add Assignment > Users and groups panel within the Microsoft Azure Portal

Add Assignment panel within the Microsoft Azure Portal

Sign in with Microsoft button within Microsoft Graph Explorer

API version menu within Microsoft Graph Explorer

API version menu within Microsoft Graph Explorer

Run Query button within Microsoft Graph Explorer

Request Body section within Microsoft Graph Explorer

API method menu within Microsoft Graph Explorer

Success Status Code example within Microsoft Graph Explorer

History section within Microsoft Graph Explorer

Enterprise applications > All applications within the Microsoft Azure Portal

Users and groups > Add user within the Microsoft Azure Portal

Add Assignment panel within the Microsoft Azure Portal

Add Assignment > Users and groups panel within the Microsoft Azure Portal

Add Assignment > Users and groups panel within the Microsoft Azure Portal

Add Assignment panel within the Microsoft Azure Portal

Authentication with modify permissions within the Microsoft Graph Explorer

Modify Permissions window within the Microsoft Graph Explorer