SAML Configuration Example: Microsoft Azure Active Directory


SAML Configuration Example: Microsoft Azure Active Directory

This example illustrates how to configure Microsoft Azure Active Directory (AD) as the IdP for the Zscaler service. Refer to the Azure documentation for additional information about the steps in the Azure portal.

Prerequisites

Ensure that you have the following before you start configuring Azure AD as the IdP:

Configuring SAML Single Sign-On (SSO) with Azure

To configure Azure AD as the IdP for the Zscaler service, sign in to the Azure portal, and do the following tasks:

Using Roles for Group Mapping

To configure group mapping in Azure, you must customize the role claim type in the SAML response token to push groups to Zscaler.

To add the Zscaler cloud application:

  1. In the Azure portal, on the left navigation pane, click Azure Active Directory.
    See image.
  2. Click Enterprise applications.
    See image.
  3. Click New application.
    See image.
  4. Click All in the Categories window.
    See image.
  5. Search for "Zscaler" under Add from the gallery. All the Zscaler cloud applications will appear below.
    See image.
  6. Click the Zscaler application with your cloud name. Your cloud name depends on the URL you use to log in to the Zscaler service. For example, if you log in to https://admin.zscalerbeta.net, then your cloud name is Zscaler Beta.
    See image.
  7. Click Add.
    See image.

Azure Active Directory.png 

Enterprise applications new.png

New application.png

Click All.png

Search Zscaler new.png

Zscaler Beta.png

Zscaler Beta Add.png

To configure SAML SSO in Azure:

  1. In the Azure portal, on the left navigation pane, click Azure Active Directory.
    See image.
  2. Click Enterprise applications.
    See image.
  3. Click All applications.
    See image.
  4. Click the Zscaler cloud application you added in A. Adding the Zscaler Cloud Application. In this example, it's Zscaler Beta.
    See image.
  5. Click Single sign-on.
    See image.
  6. For Mode, choose SAML-based Sign-on
    See image.
  7. Under Zscaler Beta Domain and URLs, do the following, and click Save.
    See image.
    • Sign on URL: Enter the Zscaler SSO URL in the following format. 
https://login.<Zscaler cloud>/sfc_sso

The <Zscaler cloud> depends on the URL you use to log in to the Zscaler service. For example, if you log in to https://admin.zscalerbeta.net, then the Zscaler SSO URL is https://login.zscalerbeta.net/sfc_sso.

  • Show advanced URL settings: Select to show more settings.
    • Identifier: Enter "<Zscaler cloud>.net". The <Zscaler cloud> depends on the URL you use to log in to the Zscaler service. For example, if you log in to https://admin.zscalerbeta.net, then the identifier is zscalerbeta.net.
    • Reply URL: Leave this field blank.
    • Relay State: Leave this field blank.
  1. Scroll down to the bottom of the Single sign-on page, and click Configure Zscaler.
    See image.
  2. In the Configure sign-on page, scroll down until you see the SAML Single Sign-On Service URL field. Copy the URL. You need it for step 4 of C. Configuring SAML SSO in the Zscaler Admin Portal.
    See image.
  3. Click SAML Signing Certificate - Base64 encoded to download the Azure signing certificate. You need the certificate for step 4 of C. Configuring SAML SSO in the Zscaler Admin Portal.
    See image.
  4. Navigate to the downloaded certificate, and ensure the following.
    See image.
    • The certificate file name has a .pem extension. (For example, rename it to Azure.pem.) The Zscaler service accepts certificates with the .pem extension only.
    • The file name contains one dot (".") only.

Azure Active Directory.png

Enterprise applications new.png

All applications.png

Click Zscaler Beta.png

Single sign-on.png

SAML-based Sign-on.png

Signle sign-on page.png

Click Configure Zscaler Beta.png

SAML single sign-on service URL copied.png

 SAML Signing Certifcate - Base64 Encoded.png

Azure.pem png.png 

To configure SAML in the Zscaler admin portal:

  1. In the Zscaler admin portal, go to Administration > Authentication > Authentication Settings.
  2. Under Authentication Type, choose SAML.
    See image.
  3. Click Configure SAML.
    See image.
  4. In the Edit SAML window, do the following, and click Save.
    See image.
    • SAML Portal URL: Paste the Azure SAML Single Sign-On Service URL you copied in step 9 of B. Configuring SAML SSO in Azure.
    • Login Name Attribute: Enter "NameID".
    • Public SSL Certificate: Click Upload, and upload the the Azure SAML signing certificate you downloaded in step 10 of B. Configuring SAML SSO in Azure.
    • Enable SAML Auto-Provisioning: Enable.
    • User Display Name Attribute: Enter "displayName" if you want to enable SAML auto-provisioning for displayName attributes.
    • Group Name Attribute: Enter "memberOf" if you want to enable SAML auto-provisioning for memberOf attributes.
    • Department Name Attribute: Enter "department" if you want to enable SAML auto-provisioning for department attributes.

SAML auto-provisioning can only be enabled for displayName and department attributes. If you want to provision Group attributes, see the Using Roles for Group Mapping section below.

  1. Click Save and activate the change.

Zscaler SAML.png

Zscaler Configure SAML.png

Edit SAML new.png 

In order for Azure AD users to authenticate through the Zscaler service, you must assign Azure AD users to the Zscaler cloud application.

To assign users to the Zscaler cloud application:

  1. In the Azure portal, on the left navigation pane, click Azure Active Directory.
    See image.
  2. Click Enterprise applications.
    See image.
  3. Click All applications.
    See image.
  4. Click the Zscaler cloud application you added in A. Adding the Zscaler Cloud Application. In this example, it's Zscaler Beta.
    See image.
  5. Click Users and groups.
    See image.
  6. Click Add user in the Add Assignment window. 
    See image.
  7. Click Users and groups.
    See image.
  8. Search for the user you'd like to assign to your Zscaler cloud application (Zscaler Beta).
    See image.
  9. Select the user when the name appears, and then click Select.
    See image.
  10. Click Assign in the Add Assignment window.
    See image.

Azure Active Directory.png 

Enterprise applications new.png

All applications.png

Click Zscaler Beta.png

Users and Groups.png

Add user.png

Users and groups None Selected.png

Search name.png

Select the user.png

Click Assign.png 

The SAML configuration with Azure is done, and you can test your work on another device.

To test the SAML configuration:

  1. On the device, browse to ip.zscaler.com
  2. Click Logout if you are already logged in to the Zscaler service. Otherwise, ensure that your traffic is being forwarded to the Zscaler service.
  3. Browse to a website. You will be redirected to Azure and prompted to log in.
    See image.
  4. Log in using your Azure AD credentials, and you will automatically be redirected to the original URL request.
  5. Go to ip.zscaler.com, and the status window will show the username indicating that the authentication was successful.

If any error occurs, see SAML Troubleshooting Guidelines.

Azure Login.png 

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 Zscaler cloud 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. Choose beta for the version.
    See image.
  4. 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. Search for the service principal you want to modify under Response Preview. In this example, it's "appDisplayName": "Zscaler Beta".
     

Following is a part of the response preview for the Zscaler Beta cloud application. Note its "id" in green.

{
            "id": "7bad13ac-8ecc-4b11-8d51-c65f9fdd1ba5",
            "deletedDateTime": null,
            "accountEnabled": true,
            "addIns": [],
            "appDisplayName": "Zscaler Beta", 
  1. Use the "id" to enter the following query:
https://graph.microsoft.com/beta/servicePrincipals/<"id" of Zscaler cloud application>

In this example, it's https://graph.microsoft.com/beta/servicePrincipals/7bad13ac-8ecc-4b11-8d51-c65f9fdd1ba5.

  1. Click Run Query.
    See image.

You will get a response preview similar to the following. Note the "appRoles" property in green.

{
    "@odata.context": "https://graph.microsoft.com/beta/$metadata#servicePrincipals/$entity",
    "id": "7bad13ac-8ecc-4b11-8d51-c65f9fdd1ba5",
    "deletedDateTime": null,
    "accountEnabled": true,
    "addIns": [],
    "appDisplayName": "Zscaler Beta",
    "appId": "cd4e7583-bfe4-483d-8c22-df5a735706be",
    "appOwnerOrganizationId": "47df5bb7-e6bc-4256-afb0-dd8c8e3c1ce8",
    "appRoleAssignmentRequired": false,
    "appRoles": [
        {
            "allowedMemberTypes": [
                "User"
            ],
            "description": "msiam_access",
            "displayName": "msiam_access",
            "id": "3f66022b-0b5c-4218-a8c3-7276649869f4",
            "isEnabled": true,
            "origin": "Application",
            "value": null
        }
    ],
    "displayName": "Zscaler Beta",
    "errorUrl": null,
    "homepage": "https://login.zscalerbeta.net:443/sfc_sso?metadata=zscalerbeta|ISV9.2|primary|z",
    "keyCredentials": [
  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" for the "origin"
    • have a unique "value"

In the following example, the Engineer and Quality_Assurance roles are being added. Your request body should look similar.

{    "appRoles": [
        {
            "allowedMemberTypes": [
                "User"
            ],
            "description": "msiam_access",
            "displayName": "msiam_access",
            "id": "3f66022b-0b5c-4218-a8c3-7276649869f4",
            "isEnabled": true,
            "origin": "Application",
            "value": null
        },
        {
            "allowedMemberTypes": [
                "User"
            ],
            "description": "Engineer",
            "displayName": "Engineer",
            "id": "14ca78f1-a526-42fb-8750-47df538dbfb7",
            "isEnabled": true,
            "origin": "ServicePrincipal",
            "value": "Engineer"
        },
        {
            "allowedMemberTypes": [
                "User"
            ],
            "description": "Quality_Assurance",
            "displayName": "Quality_Assurance",
            "id": "3f66022b-0b5c-4218-a8c3-7276649869e6",
            "isEnabled": true,
            "origin": "ServicePrincipal",
            "value": "Quality_Assurance"
        }
    ],
}   
  1. Choose PATCH.
    See image.
  2. Click Run Query. If your request body patched successfully, you will see a success status code.
    See image.
  3. To see if the roles have been added, under History on the left navigation pane, choose the query with the "id" of your Zscaler cloud application. In this example, it's https://graph.microsoft.com/beta/servicePrincipals/7bad13ac-8ecc-4b11-8d51-c65f9fdd1ba5.
    See image.
  4. Under Response Preview, scroll down to the "appRoles" property, and you will see the added roles. In this example, the added roles are Quality_ Assurance and Engineer.
{
    "@odata.context": "https://graph.microsoft.com/beta/$metadata#servicePrincipals/$entity",
    "id": "7bad13ac-8ecc-4b11-8d51-c65f9fdd1ba5",
    "deletedDateTime": null,
    "accountEnabled": true,
    "addIns": [],
    "appDisplayName": "Zscaler Beta",
    "appId": "cd4e7583-bfe4-483d-8c22-df5a735706be",
    "appOwnerOrganizationId": "47df5bb7-e6bc-4256-afb0-dd8c8e3c1ce8",
    "appRoleAssignmentRequired": false,
    "appRoles": [
        {
            "allowedMemberTypes": [
                "User"
            ],
            "description": "msiam_access",
            "displayName": "msiam_access",
            "id": "3f66022b-0b5c-4218-a8c3-7276649869f4",
            "isEnabled": true,
            "origin": "Application",
            "value": null
        },
        {
            "allowedMemberTypes": [
                "User"
            ],
            "description": "Quality_Assurance",
            "displayName": "Quality_Assurance",
            "id": "3f66022b-0b5c-4218-a8c3-7276649869e6",
            "isEnabled": true,
            "origin": "ServicePrincipal",
            "value": "Quality_Assurance"
        },
        {
            "allowedMemberTypes": [
                "User"
            ],
            "description": "Engineer",
            "displayName": "Engineer",
            "id": "14ca78f1-a526-42fb-8750-47df538dbfb7",
            "isEnabled": true,
            "origin": "ServicePrincipal",
            "value": "Engineer"
        }
    ],
    "displayName": "Zscaler Beta",
    "errorUrl": null,
    "homepage": "https://login.zscalerbeta.net:443/sfc_sso?metadata=zscalerbeta|ISV9.2|primary|z",
    "keyCredentials": [

You need the role(s) you added for step 10 of B. Assigning Roles to Groups.

sign in to graph explorer.png 

Choose beta new 2.png 

Run Query.png 

Run Query 2.png  

Paste AppRoles property (updated).png 

Choose Patch 3.png 

Success Status Code.png 

Under History.png 

Assign roles to the groups in your Zscaler cloud application. Note that 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. Go to the Azure portal.
  2. In the Azure portal, on the left navigation pane, click Azure Active Directory.
    See image.
  3. Click Enterprise applications.
    See image.
  4. Click All applications.
    See image.
  5. Click your Zscaler cloud application. In this example, it's Zscaler Beta.
    See image.
  6. Click Users and groups.
    See image.
  7. Select the group you want to assign a role to. In this example, it's Engineer.
    See image.
  8. Click Edit.
    See image.
  9. Click Select Role.
    See image.
  10. Choose the role you added in A. Adding Roles in the Zscaler Cloud Application. In this example, it's Engineer.
    See image.
  11. Click Select.
    See image.
  12. Click Assign in the Edit Assignment window.
    See image.
  13. Repeat this procedure for each role you added in A. Adding Roles in the Zscaler Cloud Application.

Azure Active Directory.png 

Enterprise applications new.png

All applications.png

Click Zscaler Beta.png

Users and Groups.png

Select the group.png

Click Edit new.png

Click Select Role.png

Select Engineer Role.png

Click Select new 2.png

Click Assign new.png 

To add the memberOf attribute:

  1. In the Azure portal, on the left navigation pane, click Azure Active Directory.
    See image.
  2. Click Enterprise applications.
    See image.
  3. Click All applications.
    See image.
  4. Click your Zscaler cloud application. In this example, it's Zscaler Beta.
    See image.
  5. Click Single sign-on.
    See image.
  6. Select View and edit all other user attributes under User Attributes.  A list of SAML token attributes appears below.
    See image.
  7. Click Add attribute.
    See image.
  8. Do the following, and click Ok.
    See image.
    • Name: Enter "memberOf".
    • Value: Choose user.assignedroles.
  9. Click Save.
    See image.

When users log in to the Zscaler service, you can see their role(s) in SAML response.

<Subject>
            <NameID Format="urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress">mariah@safemarch.com</NameID>
            <SubjectConfirmation Method="urn:oasis:names:tc:SAML:2.0:cm:bearer">
                <SubjectConfirmationData InResponseTo="_7616181144097429863"
                                         NotOnOrAfter="2017-05-19T20:36:24.526Z"
                                         Recipient="https://login.zscalerbeta.net:443/sfc_sso"
                                         />
            </SubjectConfirmation>
        </Subject>
        <Conditions NotBefore="2017-05-19T20:26:24.526Z"
                    NotOnOrAfter="2017-05-19T21:26:24.526Z"
                    >
            <AudienceRestriction>
                <Audience>zscalerbeta.net</Audience>
            </AudienceRestriction>
        </Conditions>
        <AttributeStatement>
            <Attribute Name="http://schemas.microsoft.com/identity/claims/tenantid">
                <AttributeValue>9fe396c9-aec0-440d-aabd-1f5cdf35515e</AttributeValue>
            </Attribute>
            <Attribute Name="http://schemas.microsoft.com/identity/claims/objectidentifier">
                <AttributeValue>15dcd3bd-eed3-4c14-8f3d-a67c4064fcd5</AttributeValue>
            </Attribute>
            <Attribute Name="http://schemas.microsoft.com/identity/claims/displayname">
                <AttributeValue>Mariah</AttributeValue>
            </Attribute>
            <Attribute Name="http://schemas.microsoft.com/identity/claims/identityprovider">
                <AttributeValue>https://sts.windows.net/9fe396c9-aec0-440d-aabd-1f5cdf35515e/</AttributeValue>
            </Attribute>
            <Attribute Name="http://schemas.microsoft.com/claims/authnmethodsreferences">
                <AttributeValue>http://schemas.microsoft.com/ws/2008/06/identity/authenticationmethod/password</AttributeValue>
            </Attribute>
            <Attribute Name="http://schemas.microsoft.com/ws/2008/06/identity/claims/role">
                <AttributeValue>Engineer</AttributeValue>
                <AttributeValue>Quality_Assurance</AttributeValue>
            </Attribute>
            <Attribute Name="http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname">
                <AttributeValue>Mariah</AttributeValue>
            </Attribute>
            <Attribute Name="http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name">
                <AttributeValue>mariah@safemarch.com</AttributeValue>
            </Attribute>
            <Attribute Name="memberOf">
                <AttributeValue>Engineer</AttributeValue>
            </Attribute>
        </AttributeStatement>
        <AuthnStatement AuthnInstant="2017-05-19T20:31:24.182Z"
                        SessionIndex="_6466d430-b329-481d-b76e-020182922111"
                        >
            <AuthnContext>
                <AuthnContextClassRef>urn:oasis:names:tc:SAML:2.0:ac:classes:Password</AuthnContextClassRef>
            </AuthnContext>
        </AuthnStatement>
    </Assertion>
</samlp:Response>

Azure Active Directory.png

Enterprise applications new.png

All applications.png

Click Zscaler Beta.png

Single sign-on.png

Select View and edit all other user attributes.png

Add attribute.png

Add attribute information.png

Click Save.png