SAML & SCIM Configuration Example: Microsoft Azure Active Directory


SAML & SCIM Configuration Example: Microsoft Azure Active Directory

This article 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 your IdP:

Configuring SAML Single Sign-On (SSO) and SCIM Provisioning in Azure

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

Zscaler recommends you use SCIM for provisioning. When using SCIM-based provisioning, Zscaler strongly recommends you disable SAML auto-provisioning. 

To use SAML without SCIM, follow the preceding steps with the exception of steps 4 and 5.

Using Roles for Group Mapping

If you are using SCIM for provisioning and have SAML auto-provisioning disabled, the following steps do not apply. If you have enabled SAML auto-provisioning, you need to take additional steps for group mapping. To configure this in Azure, you must customize the role claim type in the SAML response token to push groups to Zscaler. If you decide to use SAML and SCIM for provisioning, ensure that the role name and group name are identical.To configure group mapping in Azure, you must customize the role claim type in the SAML response token to push groups to Zscaler. To do this:

Zscaler does not recommend using SCIM Provisioning and SAML Auto-Provisioning in parallel. If you decide to use both these provisioning methods, ensure that the role name and group name are identical.

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 1. Add 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, complete 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: Enter the Sign on URL. In this example, it's https://login. zscalerbeta.net/sfc_sso.
    • 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 d of 3. Configure 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 d of 3. Configure 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 only accepts certificates with the .pem extension.
    • 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

Screenshot of the SAML configuration on the Azure single sign-on page.

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 Settings.
  2. Select SAML as the Authentication Type and click Configure SAML. The Configure SAML window appears.
    See image.
  3. In this window, complete the following:
    • SAML Portal URL: Paste the Azure SAML Single Sign-On Service URL you copied in step i of 2. Configure SAML SSO in Azure.
    • Login Name Attribute: Enter "NameID".
    • Public SSL Certificate: Click Upload, and upload the Azure SAML signing certificate you downloaded in step j of 2. Configure SAML SSO in Azure.
    • Enable SAML Auto-Provisioning:  Zscaler recommends you leave this disabled and instead Enable SCIM-Based Provisioning.
      If you want to use SAML for provisioning, Enable SAML Auto-Provisioning and complete the below fields: 
      • 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.
        See image.

        SAML auto-provisioning can only be enabled for the 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 your changes.

Screenshot showing the configure SAML option highlighted

 Screenshot showing the options needed for using SAML as an IdP

To configure SCIM provisioning in the Zscaler Admin Portal:

  1. In the Zscaler Admin Portal go to Administration > Authentication Settings.
  2. Select SAML as the Authentication Type and click Configure SAML. The Configure SAML window appears.
    See image.
  3. In this window, click Enable SCIM-Based Provisioning.  Zscaler recommends you disable SAML Auto-Provisioning when SCIM-Based Provisioning is enabled.
    See image.
  4. Copy the Base URL. This is used when configuring the app in the Azure portal in step g of 5. Configure SCIM Provisioning in Azure
    See image. 
  5. Copy the Bearer Token. This is used when configuring the app in the Azure portal in step h of 5. Configure SCIM Provisioning in Azure. The bearer token is a unique alphanumeric string that is used to authenticate SCIM requests from Azure.
    See image.
  6. (Optional) Click Generate Token if you need to generate a new token for security reasons. If you do this and have already completed the configuration you need to update the Secret Token field in Azure. For details, see step h of 5. Configure SCIM Provisioning in Azure.
    See image.
  7. Click Save and activate your changes.

Screenshot showing the configure SAML option highlighted

Screenshot showing the Enable SCIM-Based Provisioning option highlighted

Screenshot showing the Base URL option highlighted

Screenshot of the SCIM settings, with Bearer Token circled

Screenshot with the Generate Token option highlighted

To configure SCIM provisioning 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 1. Add the Zscaler Cloud Application. In this example, it's Zscaler Beta.
  5. Click Provisioning in the left navigation pane. 
    See image.
  6. Select Automatic as the Provisioning Mode
    See image.
  7. In the Tenant URL field, enter the Base URL you copied in step d in 4. Configure SCIM Provisioning in the Zscaler Admin Portal
    See image.
  8. In the Secret Token field, enter the Bearer Token you copied in step e in 4. Configure SCIM Provisioning in the Zscaler Admin Portal
    See image.
  9. Click Test Connection and Azure Active Directory will attempt to connect to the SCIM endpoint. When the connection is successful, you will see a green check mark.
    See image.
    If the attempt fails, error information is displayed. Resolve any errors before moving forward.
  10. After a successful connection, click Save to save your credentials. 
    See image.
  11. Set the Provisioning Status to On
    See image.
  12. (Optional) Set the Scope to Sync only assigned users and groups. Zscaler recommends you use this setting. For details on how to assign users, see 6. Assign Users to the Zscaler Cloud Application
    See image.
  13. Click Save again to start the Azure AD provisioning service.
     

Azure Active Directory.png

Enterprise applications new.png

All applications.png

Screenshot showing the Provisioning option highlighted

Screenshot showing the Provisioning Mode set to Automatic

Screenshot showing the Secret Token highlighted

Screenshot showing the results of a successful connection

Screenshot showing the Save option highlighted

Screenshot showing the Provisioning Status set to On

Screenshot showing the Sync only assigned users and groups

Screenshot of the Tenant URL field

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 1. Add 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 

When your configuration is complete, 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.

To test the SCIM configuration, in the Zscaler Admin Portal, navigate to Administration > User Management. You should see a complete list of the users and groups added to your user database.

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 roles you added for step j of 2. 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. 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 1. Add 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 1. Add 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 roles 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