icon-zia.svg
Secure Internet and SaaS Access (ZIA)

SAML & SCIM Configuration Guide for Microsoft Entra ID

This guide illustrates how to configure Microsoft Entra ID (formerly Azure Active Directory) as the identity provider (IdP) for the Zscaler service. To learn more about the steps in the Microsoft Entra admin center, refer to the Microsoft Entra ID documentation.

Zscaler and Microsoft are technology partners. To learn more about the Zscaler and Microsoft Entra ID integration, see the Zscaler and Microsoft Entra ID Passwordless Deployment Guide.

Prerequisites

Although you can set some configurations with a free Microsoft Entra subscription, a premium subscription is highly recommended to avoid restricted functionality.

Ensure that you have the following before you start configuring Microsoft Entra ID as your IdP:

Configuring Microsoft Entra ID as the IdP for the Zscaler Service

Zscaler recommends using Security Assertion Markup Language (SAML) single sign-on (SSO) for user authentication and System for Cross-domain Identity Management (SCIM) for user provisioning.

To configure SAML SSO and SCIM provisioning with Microsoft Entra ID:

    1. Sign in to the Microsoft Entra admin center.

    2. In the left-side navigation, go to Identity > Applications > Enterprise applications.

    3. Click New application.

      The Browse Microsoft Entra Gallery page appears.

    4. On the Browse Microsoft Entra Gallery page, enter zscaler internet access in the search bar, then 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 and your application name is Zscaler Internet Access ZSBeta. This guide uses the Zscaler Internet Access ZSBeta application as an example.

    5. Click Create.

      The Microsoft Entra service displays a notification that the Zscaler cloud application was added.

    Close

    1. In the left-side navigation for the Zscaler cloud application, click Single sign-on.

    2. Select SAML.

    3. In the Basic SAML Configuration section, click Edit.

      The Basic SAML Configuration window appears.

    4. In the Basic SAML Configuration window:

      • Identifier (Entity ID): Enter the default identifier based on your added Zscaler cloud application. It's typically <Zscaler Cloud Name>. The <Zscaler 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 the identifier is zscalerbeta.net.

        If you have more than one organization instance on the same Zscaler cloud, you must use an org-specific entity ID. You can see the org-specific entity ID for your instance in the ZIA Admin Portal while adding or editing an identity provider.

        The org-specific entity ID is formatted like the following example:

        https://login.zscalerbeta.net/sfc_sso/3829920

      • Reply URL (Assertion Consumer Service URL): Enter the following Zscaler SSO URL:

        https://login.<Zscaler Cloud Name>:443/sfc_sso

        The <Zscaler 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 the Zscaler SSO URL is https://login.zscalerbeta.net/sfc_sso.

      • Sign on URL: Enter the Reply URL (Assertion Consumer Service URL). In this example, it's https://login.zscalerbeta.net:443/sfc_sso.
      • Relay State: Leave this field blank.
      • Logout URL: Leave this field blank.

    5. Click Save and exit the window.

    6. In the Attributes & Claims section, click Edit.

    7. Click Add a group claim.
    8. In the Group Claims window:

      • If the groups you are assigning exist in Microsoft Entra ID locally:

        • Select Groups assigned to the application.
        • For Source attribute, select Cloud-only group display names.

      • If the groups you are assigning are from an on-premises active directory (AD):

        • Select Groups assigned to the application.
        • For Source attribute, select sAMAccountName.

    9. Click Save.
    10. Click Add new claim.

    11. On the Manage claim page:

      • Name: Enter Department (case sensitive).
      • Source: Select Attribute.
      • Source attribute: Enter user.department (case sensitive).

    12. Click Save.

      When you are finished, check the Attribute & Claims section to ensure that you have configured the Department and groups attributes properly.

    13. In the SAML Certificates section, download Certificate (base64). You need this certificate file when you add Microsoft Entra ID as the IdP for the Zscaler service.

      Ensure that the certificate file name:

      • Has a .pem extension (e.g., rename it to Entra.pem). The Zscaler service only accepts certificates with the .pem extension.
      • Contains only one dot (".").

      By default, Windows hides extensions for known file types.

    14. In the Set up Zscaler Beta section, copy the Login URL. You need this URL when you add Microsoft Entra ID as the IdP for the Zscaler service.

      (Optional) for Seamless SSO, you must append the domain hint ?whr=contoso.com to the end of the Login URL. The URL must be similar to the following example:

      https://login.microsoftonline.com/1ab234c5-def6-789a-bcde-0f1abc23456d/saml2?whr=contoso.com
    Close
    1. Go to Administration > Authentication Settings.
    2. Click the Identity Providers tab.
    3. Click Add IdP.

    If you have an existing IdP configuration, the What do you want to do? window appears. Select Add another SAML IdP for a subset of users or locations and then Next.

    1. In the Add IdP window:

      • SAML Portal URL: Enter the Login URL that you copied from the Microsoft Entra admin center in Configure SAML SSO in the Microsoft Entra admin center.
      • Login Name Attribute: Enter NameID (case sensitive).
      • IdP SAML Certificate: Upload the .pem certificate that you downloaded from the Microsoft Entra admin center in Configure SAML SSO in the Microsoft Entra admin center.
      • Org-Specific Entity ID: If you have more than one organization instance on the same Zscaler cloud, enable this option. For example, if you have two organization instances on the same Zscaler cloud and must authenticate both instances against the same Microsoft Entra account, you can't use the same entity ID for multiple apps in the Microsoft Entra admin center. For this situation, you must enable this setting for both instances to generate a unique organization-specific entity ID.
      • Locations: Select the locations to map to this IdP. You can also search for a location. Any unselected locations are mapped to the default IdP. This field is set to Any for the default IdP, and you can't modify it.
      • Authentication Domains: Select the domains to map to this IdP. This allows the Zscaler service to display the correct IdP to authenticate an incoming user. Any unselected domains are mapped to the default IdP. For the default IdP, this field is set to Any, and you can't modify it. You must map any additional IdPs to at least one domain.

    2. (Optional) If you want to enable Sign SAML Request for additional security:

      1. After enabling Sign SAML Request:

        • Signature Algorithm: Zscaler recommends selecting SHA-2 (256-bit).
        • Request Signing SAML Certificate: Select the most recent certificate.
        • SP SAML Certificate: Click Download Certificate.

      2. In the Microsoft Entra admin center, go to the Single sign-on page in your previously configured Zscaler cloud application.

      3. In the Verification certificates (optional) section, click Edit.

      4. In the Verification certificates window:

        • Require verification certificates: Enable this option.
        • Allow requests signed with RSA-SHA1: If you selected SHA-1 (160-bit) in the ZIA Admin Portal, enable this option.
        • Upload the SP SAML Certificate you downloaded in the ZIA Admin Portal.

      5. Click Save.

      6. In the Token signing certificate section, click Edit.

      7. In the SAML Signing Certificate window:

        • Signing Option: Select Sign SAML response and assertion.
        • Signing Algorithm: Select either SHA-256 or SHA-1 depending on your selection in the ZIA Admin Portal.

      8. Click Save.

    3. (Optional) If you want to configure SAML without SCIM, in the Provisioning Options section:

      • Enable SAML Auto-Provisioning: Enable this option.
      • User Display Name Attribute: Enter displayName (case sensitive).
      • Group Name Attribute: Enter groups (case sensitive).
      • Department Name Attribute: Enter Department (case sensitive).

      Zscaler recommends using SCIM to provision users. Skip this step if you are using SCIM provisioning.

    4. Click Save and activate the changes.

    To learn more about configuring an IdP in the ZIA Admin Portal, see Adding Identity Providers.

    Close
    1. Go to Administration > Authentication Settings.
    2. Under Authentication Frequency, select how often users are required to authenticate to the Zscaler service. To learn more, see About Authentication Profile. If you select Custom, the Custom Authentication Frequency (days) field appears. In this field, specify 1 to 180 days.

    3. Under Authentication Type, select SAML.

    4. Click Save and activate the change.
    Close
    1. Go to Administration > Authentication Settings.
    2. Click the Identity Providers tab.

    3. Click the Edit icon for the identity provider (IdP) you configured for Microsoft Entra ID. To learn more, see Add Microsoft Entra ID as the IdP for the Zscaler service in the ZIA Admin Portal.

      The Edit IdP window appears.

    4. In the Edit IdP window:

      • Enable SAML Auto-Provisioning: Disable this option when enabling SCIM-based provisioning.
      • Enable SCIM Provisioning: Enable to activate SCIM-based provisioning for users on the Zscaler service. To learn more, see About SCIM. SCIM provisioning isn't supported with Active Directory or OpenLDAP user repositories. If you want to migrate from directory synchronization to SCIM provisioning, enable Disable Directory Sync & Enable SCIM Provisioning on the Authentication Profile page. After enabling SCIM provisioning, the following fields appear:

        • Base URL: Copy the Base URL for the SCIM server. You need this URL when configuring your IdP for SCIM provisioning. Okta only accepts strings with the following format. In this example it is 37146169/1605333.

          https://scim.<Zscaler Cloud>/<Organization ID>/<IdP ID>/scim

          The old SCIM Base URL marked as (Deprecated) will be removed in the future.

        • Bearer Token: Copy the bearer token. It's a unique alphanumeric string that is used by the SCIM client to make authenticated API calls to the Zscaler SCIM server. You need this token when configuring your IdP for SCIM provisioning.
        • Generate Token: Click to generate a new bearer token for security reasons. If you're generating a new bearer token for an existing SCIM configuration, ensure you update the token for your IdP.

    5. Click Save to exit the window.
    6. Click Save and activate the change.

    To learn more about configuring SCIM in the ZIA Admin Portal, see Configuring SCIM.

    Close

  • To learn more about SCIM provisioning in Microsoft Entra ID, refer to the Microsoft Entra ID documentation.

    1. In the Microsoft Entra admin center, in the left-side navigation of the Zscaler cloud application, click Provisioning.

    2. On the provisioning Overview page, click Get started.

      The Provisioning page appears.

    3. For Provisioning Mode, select Automatic.

    4. Under Admin Credentials:

      1. Tenant URL: Enter the Base URL you copied previously in Configure SCIM provisioning in the ZIA Admin Portal.
      2. Secret Token: Enter the Bearer Token you copied previously in Configure SCIM provisioning in the ZIA Admin Portal.

      3. Click Test Connection. Microsoft Entra ID connects to the SCIM endpoint. If the connection is successful, the Microsoft Entra service displays a notification that the credentials are authorized.

        If the connection fails, error information is displayed. Resolve any errors before moving forward.

    5. Click Save to save your credentials.
    6. Under Mappings:

      1. Click the groups attribute mapping link (e.g., Provision Azure Active Directory Groups). The Attribute Mapping page appears.

        Microsoft Entra ID - Provisioning Page

        Close

      2. On the Attribute Mapping page, review the attributes that are synchronized from Microsoft Entra ID to your application.

      3. Verify the group attribute mappings as listed in the following table. If needed, change them by clicking Edit on an existing attribute or by clicking Add New Mapping.

        Zscaler Attribute (Target Attribute)Microsoft Entra Attribute (Source Attribute)Match Objects Using This Attribute
        displayNamedisplayNameYes
        membersmembers
        externalIdobjectId

      4. Click Ok to save the attribute parameters.
      5. Click Save to save the attribute mapping changes.
      6. Return to the Provisioning page.
    7. Under Mappings:

      1. Click the users attribute mapping link (e.g., Provision Azure Active Directory Users). The Attribute Mapping page appears.

        Microsoft Entra ID - Provisioning Page

        Close

      2. On the Attribute Mapping page, review the attributes that are synchronized from Microsoft Entra ID to your application.

      3. Verify the users attribute mappings as listed in the following table. If needed, change them by clicking Edit on an existing attribute or by clicking Add New Mapping.

        Zscaler Attribute (Target Attribute)Microsoft Entra Attribute (Source Attribute)Match Objects Using This Attribute
        userNameuserPrincipalNameYes
        externalIdobjectId
        activeSwitch([IsSoftDeleted], , "False", "True", "True", "False")
        name.familyNamesurname
        name.givenNamegivenName
        displayNamedisplayName
        urn:ietf:params:scim:schemas:extension:enterprise:2.0:User:departmentdepartment

      4. (Optional) If you use the Workflow Automation Admin Portal, add and map additional user attributes that Workflow Automation uses.

        • The following table lists the additional user attributes to add for Workflow Automation:

          NameTypeReferenced Object Attribute

          urn:ietf:params:scim:schemas:extension:enterprise:2.0:User:manager.value

          		Referenceurn:ietf:params:scim:schemas:extension:enterprise:2.0:User
          urn:ietf:params:scim:schemas:extension:enterprise:2.0:User:employeeNumberString
          titleString
          emails[type eq "work"].valueString
          preferredLanguageString
          addresses[type eq "work"].formattedString
          addresses[type eq "work"].streetAddressString
          addresses[type eq "work"].localityString
          addresses[type eq "work"].regionString
          addresses[type eq "work"].postalCodeString
          addresses[type eq "work"].countryString
          addresses[type eq "home"].countryString
          phoneNumbers[type eq "work"].valueString
          phoneNumbers[type eq "mobile"].valueString
          phoneNumbers[type eq "fax"].valueString

          To add additional user attributes:

          1. Under the existing attribute mappings that are displayed, select the Show advanced options checkbox. The page expands to display additional information.

            Microsoft Entra ID - Attribute Mapping - Show Advanced Options checkbox selected

            Close

          2. Click the Edit attribute list link (e.g., Edit attribute list for Zscaler). The Edit Attribute List page appears, displaying the existing user attributes. An empty row appears at the bottom of the list.

            Edit Attribute List Page - Blank Row for Adding New Attribute

            Close

          3. In the empty row, add the information for an additional user attribute:

            Add the user attributes one at a time. When you begin to enter a name in the empty row, an additional empty row appears below that row. Add all the user attributes using the information that is provided in the table above.

            • Name: Enter the name of the user attribute. When you begin to enter a name, an additional blank row appears below that row.
            • Type: From the drop-down menu, select the user attribute type. Types are Binary, Boolean, DateTime, Integer, Reference, and String. The user attributes for Workflow Automation use either String or Reference as the type.
            • Referenced Object Attribute: From the drop-down menu, select the referenced object attribute for the user attribute.
          4. Click Save. A dialog window appears, asking if you are sure you want to make these changes.
          5. Click Yes. The attributes are added. You can now map these user attributes.
          Close

        • The following table lists the mapping information to use when mapping the additional user attributes you previously added:

          Mapping TypeMicrosoft Entra Attribute (Source Attribute)Zscaler Attribute (Target Attribute)Match Objects Using This AttributeApply This Mapping
          DirectjobTitletitleNoAlways
          Directmailemails[type eq "work"].valueNoAlways
          DirectpreferredLanguagepreferredLanguageNoAlways
          DirectphysicalDeliveryOfficeNameaddresses[type eq "work"].formattedNoAlways
          DirectstreetAddressaddresses[type eq "work"].streetAddressNoAlways
          Directcityaddresses[type eq "work"].localityNoAlways
          Directstateaddresses[type eq "work"].regionNoAlways
          DirectpostalCodeaddresses[type eq "work"].postalCodeNoAlways
          Directcountryaddresses[type eq "work"].countryNoAlways
          Directextension_d46aad061f2b47f497418d1ff465699b_HomeCountryaddresses[type eq "home"].countryNoAlways
          DirectmobilephoneNumbers[type eq "work"].valueNoAlways
          DirectmobilephoneNumbers[type eq "mobile"].valueNoAlways
          DirectfacsimileTelephoneNumberphoneNumbers[type eq "fax"].valueNoAlways
          DirectemployeeIdurn:ietf:params:scim:schemas:extension:enterprise:2.0:User:employeeNumberNoAlways
          Directmanagerurn:ietf:params:scim:schemas:extension:enterprise:2.0:User:manager.valueNoAlways

          To map additional user attributes:

          1. Under the existing attribute mappings that are displayed, click Add New Mapping. The Edit Attribute page appears.

            Microsoft Entra ID - Attribute Mapping - Add New Mapping Link

            Close

          2. On the Edit Attribute page:

            Add the user attribute mappings one at a time. With attribute mappings, you control how attributes are populated in a non-Microsoft SaaS application. Map all the user attributes using the information that is provided in the table above.

            • Mapping type: From the drop-down menu, select the mapping type. Mapping types are:
              • Direct: The target attribute is populated with the value of an attribute of the linked object in Microsoft Entra ID. All the user attribute mappings for Workflow Automation use Direct for this field.
              • Constant: The target attribute is populated with a specific string you specified.
              • Expression: The target attribute is populated based on the result of a script-like expression.
              • None: The target attribute is left unmodified.
            • Source attribute: From the drop-down menu, select the Microsoft Entra Attribute (source attribute) for the mapping.
            • Target attribute: From the drop-down menu, select the Zscaler attribute (target attribute) for the mapping.
            • Match objects using this attribute: From the drop-down menu, select Yes or No. If you select Yes, this mapping is used to uniquely identify users between the source and target systems. All the user attribute mappings for Workflow Automation use No for this field.
            • Apply this mapping: From the drop-down menu, select when to apply this mapping. Options are Always, Only if the attribute contains multiple values, and Only during object creation. All the user attribute mappings for Workflow Automation use Always for this field.

            Microsoft Entra ID - Edit Attribute Page

            Close

          3. Click Ok.
          4. Click Save. A dialog window appears, asking if you are sure you want to make these changes.
          5. Click Yes. The attribute mapping is added and is listed in the Attribute Mappings section of the Attribute Mapping page.
          6. Return to the Provisioning page.
          Close

    8. Under Settings:

      • Send an email notification when a failure occurs: (Optional) Select this and provide an email to receive a notification when there is a provisioning failure.
      • Prevent accidental deletion: (Optional) Selecting this option allows you to set an Accidental deletion threshold. When the option is enabled, deleting a number of groups and users over the threshold requires approval from an admin.
      • Scope: (Optional) Select Sync only assigned users and groups. Zscaler recommends enabling this setting. To learn more about assigning users, see Assign Users to the Zscaler Cloud Application.

    9. For Provisioning Status, select On.
    10. Click Save to start the Microsoft Entra provisioning service.
    11. Return to the provisioning Overview page.

    12. On the provisioning Overview page, review the current cycle status, provisioning details, and technical information for the Microsoft Entra provisioning service.

    Close

  • To configure the Zscaler Authentication Exemptions list and enable users access to Microsoft Entra ID in the ZIA Admin Portal:

    1. Go to Administration > Advanced Settings.

    2. In the Authentication Exemptions section, enter the following exceptions in Exempted URLs, and click Add Items:

      • login.windows.net
      • login.microsoftonline.com
      • .windowsazure.com
      • aadcdn.msauth.net
      • aadcdn.msftauth.net

      This option only applies to user traffic from known locations. For more information, see Exempting URLs and Cloud Apps from Authentication.

    3. Click Save and activate the change.

    If you are using PAC files, enter the following exceptions in the PAC file exemption list. Otherwise, the authentication fails.

    if (shExpMatch(host, "login.windows.net") || shExpMatch(host, "login.microsoftonline.com") || shExpMatch(host, "*.windowsazure.com"))
                                return "DIRECT";
    Close

  • For Microsoft Entra users to authenticate through the Zscaler service, you must assign Microsoft Entra users or groups to the Zscaler cloud application.

    1. In the left-side navigation of the Zscaler cloud application, click Users and groups.

    2. Click Add user/group.

      The Add Assignment window appears.

    3. In the Add Assignment window, under Users and groups, click None Selected.

      The Users and groups window appears.

    4. In the Users and groups window, select the users or groups you want to assign to the Zscaler cloud application, and click Select.

      To ensure that Microsoft Entra ID sends group memberships to Zscaler, you must assign groups to the enterprise application.

    5. In the Add Assignment window, click Assign.

    Close

Testing the SAML or SCIM Configuration

This testing method only applies if you're forwarding traffic using Proxy Auto-Configuration (PAC) files, Generic Routing Encapsulation (GRE) tunnels, or IPSec tunnels, and you've enabled Enforce Authentication for the location or sub-location.

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. If you are already logged in to the Zscaler service, click Logout. Otherwise, ensure that your traffic is being forwarded to the Zscaler service.

  3. Browse to a website. You are redirected to Microsoft Entra ID and prompted to log in.

  4. Log in using your Microsoft Entra credentials, and you are automatically redirected to the original URL request.
  5. Go to ip.zscaler.com, and the status window shows the username indicating that the authentication was successful.

To test the SCIM configuration, complete the following procedures:

    1. Sign in to the Microsoft Entra admin center.
    2. In the left-side navigation, go to Applications > Enterprise applications.
    3. On the Enterprise applications page, locate the application for which you want to initiate the provision on demand.

    4. Click the application.

      The Overview page for the application appears.

    5. In the left-side navigation, click Provisioning.

      The provisioning Overview page for the application appears.

    6. Click Provision on demand.

      To learn more about provision on demand, refer to the Microsoft Entra ID documentation.

    7. In the Provision on demand page, search for a user.

      This user must have already been assigned to the cloud application. This user can be a part of the initial payload. If you select a user that is part of the initial payload, then this user is skipped over when the initial payload is provisioned because they were already provisioned on demand. To learn more, see Assigning Users to the Zscaler Cloud Application.

    8. Select the user for which you want to provision.

    9. Click Provision.

      The provision on demand process is initiated. After the process is completed, the Provision on demand page appears, displaying the results from the 5 steps that the provisioning service takes when provisioning a user. If a step is successful, a green check mark appears next to the step. If a step is not successful, then a red circle with an X appears next to the step.

    10. On the Provision on demand page, review the results.

      If there are no failures in the steps, then the provisioning configuration for your application has been properly configured. If there are failures, fix the issues that are listed and retry the provision on demand process again. Focus on the Perform action step. To understand why the failure occurred, click the View Details link located under each step.

      For failures that you cannot fix, contact either Microsoft Entra Support or Zscaler Support for assistance.

    11. Verify that the user has been added to your database in the ZIA Admin Portal. In the ZIA Admin Portal, go to Administration > User Management.
    Close

  • In the ZIA Admin Portal, go to Administration > User Management.

    After the Microsoft Entra provisioning service is successfully completed, this page displays a complete list of the users and groups added to your user database.

    Close

Troubleshooting

If any errors occur, see Troubleshooting SAML to troubleshoot browser settings and SAML error codes.

Related Articles
About Identity ProvidersAdding Identity ProvidersMigrating to a New SAML IdPAdding the Zscaler Client Connector as an IdPUnderstanding SAMLConfiguring SAMLLogging Out from Zscaler While Using SAMLTroubleshooting SAMLUnderstanding SCIMConfiguring SCIMSCIM API ExamplesActive Directory with LDAP to SCIM Provisioning Migration GuideSAML & SCIM Configuration Guide for Microsoft Entra IDSAML & SCIM Configuration Guide for OktaSAML & SCIM Configuration Guide for PingFederateSAML & SCIM Configuration Guide for PingOneSAML Configuration Guide for AD FS 3.0SAML Configuration Guide for AD FS 2.0SAML & SCIM Configuration Guide for Google AppsSAML Configuration Guide for OneLoginSAML Configuration Guide for CA Single Sign-On