Configuring Microsoft Azure AD for Single Sign-On


Configuring Microsoft Azure AD for Single Sign-On

The following instructions detail how to set up Microsoft Azure Active Directory (AD) as the IdP for ZPA.

Prerequisites

Ensure that you have the following:

  • A premium Azure subscription
  • An existing Azure AD
  • A ZPA account with an administrator role that allows you to add an IdP Configuration

Configuring Azure AD for SSO

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

To configure Azure AD as the IdP for ZPA user 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, then click on the Zscaler Private Access (ZPA) application.
    See image.
  4. Click Add.
    See image.

You are redirected to the Zscaler Private Access (ZPA) application's Quick start page.

  1. Click Single sign-on.
    See image.
  2. Under Single Sign-on Mode, select SAML-based Sign-on from the drop-down menu.
    See image.
  3. Under Zscaler Private Access (ZPA) Domain and URLs, for Sign on URL, enter the following Service Provider (SP) SSO URL:
https://samlsp.private.zscaler.com/auth/sso
  1. For Identifier, enter the following SP Entity ID:
https://samlsp.private.zscaler.com/auth/metadata

See image.

  1. Under SAML Signing Certificate, click the Metadata XML hyperlink to download the Azure metadata file.

See image.

  1. Click Save.
  2. In order for Azure AD users to authenticate through ZPA, you must assign Azure AD users to the ZPA application. In the application, click Users and Groups then Add user.
    See image.
  3. Search for the user you want to assign to the ZPA application.
  4. Select the checkbox next to the user name, then click Select.
    See image.
  5. In the Add Assignment panel, click Assign.
    See image.
  6. Go to the ZPA Admin Portal and complete the IdP configuration for user SSO.

To configure Azure AD as the IdP for ZPA 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, then click on the Zscaler Private Access Administrator application.
    See image.
  4. Click Add.
    See image.

You are redirected to the Zscaler Private Access Administrator application's Quick start page.

  1. Click Single sign-on.
    See image.
  2. Under Single Sign-on Mode, select SAML-based Sign-on from the drop-down menu.
    See image.
  3. Under Zscaler Private Access (ZPA) Domain and URLs, for Identifier, enter the following Service Provider (SP) Entity ID:
https://adminsamlsp.private.zscaler.com/auth/metadata
  1. For Reply URL, enter the following SP SSO URL:
https://adminsamlsp.private.zscaler.com/auth/sso

See image.

  1. Under SAML Signing Certificate, click the Metadata XML hyperlink to download the Azure metadata file.

See image.

  1. Click Save.
  2. In order for Azure AD users to authenticate through ZPA, you must assign Azure AD users to the ZPA application. In the application, click Users and Groups then Add user.
    See image.
  3. Search for the user you want to assign to the ZPA application.
  4. Select the checkbox next to the user name, then click Select.
    See image.
  5. In the Add Assignment panel, click Assign.
    See image.
  6. Go to the ZPA Admin Portal and complete the IdP configuration for admin SSO.

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

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.

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

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

Enterprise applications page with New application 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

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

Add app panel within the Microsoft Azure Portal

Add app panel within the Microsoft Azure Portal

Single sign-on panel within the Microsoft Azure Portal

Single sign-on panel within the Microsoft Azure Portal

Single sign-on panel within the Microsoft Azure Portal

Single sign-on panel within the Microsoft Azure Portal

Single sign-on panel with ZPA Domain and URLs within the Microsoft Azure Portal

Single sign-on panel with ZPA Domain and URLs within the Microsoft Azure Portal

Single sign-on panel with SAML Signing Certificate information within the Microsoft Azure Portal

Single sign-on panel with SAML Signing Certificate information within the Microsoft Azure Portal

Users and groups > Add User panel 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 > Users and groups panel within the Microsoft Azure Portal

Add Assignment 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