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

Integrating with Microsoft Cloud App Security

This article provides configuration steps and examples for integrating Zscaler and Microsoft Cloud App Security (MCAS) (i.e., Microsoft Defender for Cloud Apps).

With MCAS, you can sanction or unsanction applications for use in your organization. When you integrate MCAS and Zscaler, Zscaler syncs unsanctioned application URLs to a custom URL category called MS Defender Unsanctioned Apps. The integration enables you to discover unsanctioned applications and automatically update the custom URL category based on your organization’s web transaction logs streaming from ZIA through the Nanolog Streaming Service (NSS) to MCAS.

Zscaler and Microsoft are technology partners. To learn more about the Zscaler and MCAS integration, see the Zscaler and Microsoft Defender for Cloud Applications Deployment Guide.

Integrating with MCAS using OAuth 2.0-Based Authentication

The integration supports secure OAuth 2.0-based authentication. In contrast to token-based authentication in which a key is generated based on the user’s security context, the OAuth 2.0 method grants access based on the application’s context. Permissions are set at the application level and not inherited by the user, whose roles and permissions in Azure can change over time. To learn more about accessing MCAS with application context, refer to the Microsoft documentation.

To integrate with MCAS using OAuth 2.0-based authentication:

  • To access MCAS with application context, create an application in Microsoft Entra ID (previously Microsoft Active Directory) and assign it with the permissions required to access MCAS. In creating the application, you generate the values of the parameters (e.g., client ID, client secret, etc.) required for OAuth 2.0-based authentication. You later provide the values when configuring the integration on the Partner Integrations page in the ZIA Admin Portal.

    To create an application:

    • To register an application:

      1. Log in to Microsoft Azure.
      2. Under Azure services, go to Microsoft Entra ID.

      3. In the left-side navigation, go to App Registrations and then click New registration.

        The Register an application window appears.

      4. In the Register an application window:

        • Name: Enter a name for the application.
        • Supported account types: Ensure that this option is set to Accounts in this organizational directory only (<tenant> only - Single tenant).

      5. Click Register.

        The application is registered, and its Overview page is displayed.

      6. On the application’s Overview page, copy the Application (client) ID and Directory (tenant) ID values and save them for later use.

      Close

    • To add a client secret to the application:

      1. On the left side-navigation of the application, go to Certificates & secrets and then click New client secret.

        The Add a client secret pane appears.

      2. In the Add a client secret pane:

        • Description: Add a description.
        • Expiration: Add an expiration.

      3. Click Add.

        The client secret value is generated and displayed.

      4. Copy the generated secret value immediately and save it for later use.

        The client secret value is displayed only once and cannot be retrieved after you navigate away from the page.

      Close

    • To add the required MCAS permissions to the application:

      1. In the left side-navigation of the application, go to API Permissions and click Add a permission.

        The Request API permissions pane appears.

      2. In the Request API permissions pane, click the APIs my organization uses tab and then enter Microsoft Cloud App Security in the search bar.

      3. Copy the Application (client) ID value for MCAS and save it for later use.

        This value is used for the Scope parameter when configuring the partner integration in the ZIA Admin Portal.

      4. Select Microsoft Cloud App Security in the search results and then select Application permissions.

      5. Select the discovery.manage permission, which is required to upload data and generate block scripts.

      6. Click Add permissions.

      7. Click Grant admin consent for <Tenant> under the Configured permissions section and then click Yes when prompted.

      Close
    Close

  • After creating the application, use the generated values (e.g., client ID, client secret, etc.) to configure the integration on the Partner Integrations page in the ZIA Admin Portal. This step of the integration also requires:

    • An active NSS web log subscription or trial
    • A healthy NSS web server enabled
    • An MCAS NSS feed configured for the enabled NSS web server

    After you complete and validate the configuration on the Partner Integrations page, the OAuth 2.0-based authentication parameters are pushed to the MCAS NSS feed configuration (in the backend only). The feed configuration is pushed to the Zscaler Central Authority (CA). The Zscaler CA then pushes the feed configuration to NSS.

    To configure an MCAS partner integration:

    1. Log in to the ZIA Admin Portal.
    2. Go to Administration > Partner Integrations.
    3. On the Microsoft Cloud App Security tab:
      1. Under Microsoft Cloud App Security (MCAS) Authentication Setup, configure the following parameters and then click Test:
        • Client ID: Enter the Application (client) ID for the application that you created in Azure (e.g., 97b9XXXX-beXX-48XX-b5XX-8792cdXXXXXX).
        • Client Secret: Enter the application’s client secret value that you generated in Azure. Ensure that you provide the client secret value, not the client secret ID.
        • Scope: Enter the scope (i.e., the resource identifier) for the MCAS API, appended with the /.default suffix. Microsoft currently defines the scope for MCAS as 05a65629-4c1b-48c1-a78b-804c4abdd4af, so enter 05a65629-4c1b-48c1-a78b-804c4abdd4af/.default in this field. To ensure you have the current scope for MCAS, refer to the Microsoft documentation.
        • Authentication URL: Enter the authentication URL with your Directory (tenant) ID in Azure: https://login.microsoftonline.com/<Tenant ID>/oauth2/v2.0/token. For example: https://login.microsoftonline.com/9fe3XXXX-d6XX-46XX-a9XX-d8907dXXXXXX/oauth2/v2.0/token

        • API URL: Enter the API URL for your tenant (e.g., https://safemarch.us3.portal.cloudappsecurity.com). To find your API URL, refer to the Microsoft documentation.

          Zscaler verifies if the configuration is valid. If the configuration is valid, the integration proceeds to the next step and Zscaler attempts to sync your unsanctioned Cloud App URLs. If the configuration is not valid, the reason for the failure appears on the page. In the following image, the API URL is not valid.

          The invalid configuration and the reason for the failure is also logged in the audit logs (Administration > Audit Logs).

          To clear the existing configuration, click Clear Config and then OK when prompted.

          Clearing the configuration stops the syncing of unsanctioned Cloud App URLs from MCAS to your MS Defender Unsanctioned Apps URL category. This existing category is not removed by this action, as it might be in use as part of your configured policies.

      2. Under NSS Subscription, ensure that you have:
    4. Under Unsanctioned Cloud App URLs Sync, note that after your MCAS integration is configured, the first unsanctioned Cloud App URL sync occurs within two hours. Syncs to this custom URL category occur every two hours after the initial sync.

    After your integration is configured, this page updates automatically, showing the number of URLs that are successfully synced. If you exceed the maximum custom category limit that is set for your organization, then the sync fails. To learn more, see the Troubleshooting section of this article.

    Close

  • After you configure the MCAS partner integration in the ZIA Admin Portal, you configure and enable automatic log uploads from NSS to MCAS. This involves adding a data source for NSS in the MCAS (i.e., Microsoft Defender) portal, and from your NSS VM, starting the NSS service in OAuth 2.0 mode.

    To configure and enable automatic log uploads:

      1. In the MCAS portal, go to Settings and then click Cloud Apps.

      2. Under Cloud Discovery, click Automatic log upload.

      3. On the Data sources tab, click Add data source.

      4. On the Add Data Source page:

        • Name: Enter NSS.
        • Source: Select Zscaler QRadar LEEF.
        • Receiver type: Select Syslog - UDP.

        You must configure the fields as documented in the Microsoft documentation, otherwise NSS and MCAS cannot communicate.

      5. Click Add.
      Close

    • The NSS gets the logs from the Zscaler Nanolog, converts the logs per the MCAS NSS feed output format (i.e., LEEF), and sends the logs for uploading to MCAS.

      To start the NSS service in OAuth 2.0 mode:

      1. Log in to the NSS VM for your platform (i.e., VMware vSphere, Amazon Web Services, or Azure).

      2. Run the following command:

        sudo nss configure-mcas2

        The command sudo nss configure-mcas used for token-based integrations does not work for OAuth 2.0-based integrations.

      3. Restart the NSS service by running the following command:

        sudo nss restart
      Close
    Close

  • To verify your MCAS partner integration:

    1. In the ZIA Admin Portal, go to Administration > URL Categories.

    2. After the initial URL sync, verify that the User-Defined category called MS Defender Unsanctioned Apps is shown in the table on the page.

    To verify automatic log uploads:

    1. In the MCAS portal, go to the Automatic log upload page (Settings > Cloud Apps > Cloud Discovery).

    2. On the Data sources tab, make sure that the NSS data source you set up for Zscaler is receiving data.

    To verify the connection with MCAS, run the following cURL command, replacing the authentication parameters in red with the values from your configuration:

    curl -X POST 
"https://login.microsoftonline.com/<Tenant ID>/oauth2/token" -d 
"resource=<Scope>" -d 
"client_id=<Client ID>" -d 
"client_secret=<Client Secret Value>" -d 
"grant_type=client_credentials" -H 
"Content-Type: application/x-www-form-urlencoded"

    The value of resource (e.g., 05a65629-4c1b-48c1-a78b-804c4abdd4af) is also used in the Scope parameter when configuring the partner integration in the ZIA Admin Portal.

    The following example of a valid connection shows the bearer token and its expiration in the output.

    Close
    • You must assign the MS Defender Unsanctioned Apps URL category to a URL filtering rule to block the traffic to those destinations. Zscaler recommends that SSL inspection is enabled for that category in case some sanctioned applications are uniquely identified by a full URL rather than just a domain name. To learn more, see Configuring the URL Filtering Policy and Configuring SSL Inspection Policy.
    • If the unsanctioned Cloud App URL sync to your custom URL category is not occurring every two hours, contact Zscaler Support.
    • If you encounter an MCAS authentication validation error on a valid and verified configuration, make sure that you have at least one application categorized as unsanctioned within the MCAS portal. To learn more, refer to the Microsoft documentation.
    Close

Support for Existing Token-Based Integrations

If you have an existing MCAS partner integration using token-based authentication, your integration remains supported for backward compatibility. On the Partner Integrations page in the ZIA Admin Portal, you see the Select Authentication Method setting with the Token option enabled.

You cannot make any configuration changes to your existing integration or create a new token-based integration. Zscaler recommends converting your existing integration to the OAuth 2.0-based authentication method for improved security. After you convert your integration, the token method is no longer available as an option.

If you do not have an existing integration using token-based authentication, the token method is not available as an option in the portal at all.

Related Articles
About Partner IntegrationsIntegrating with Microsoft Cloud App SecurityManaging SD-WAN Partner KeysIntegrating with Microsoft Azure Virtual WANIntegrating with CrowdStrikeViewing the CrowdStrike Endpoint Hits ReportIntegrating with Microsoft Defender for EndpointViewing the Microsoft Defender Endpoint Hits Report