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

Authorizing a Custom Zscaler Connector for Microsoft Applications

The Zscaler service supports custom, client-side connector onboarding for access to the following Microsoft applications: Exchange, Microsoft Information Protection (MIP) Labels, OneDrive, SharePoint, Microsoft Azure Blob Storage, and Teams. With this functionality, instead of requiring full administrator credentials, the Zscaler service can use a minimum set of credentials to access your Microsoft applications.

When you create a custom connector for a Microsoft application, you must provide the Client ID, Client Secret, and Tenant ID in the ZIA Admin Portal so that the Zscaler service can access the application.

To create a custom connector for a Microsoft application:

  • This section covers how to register your ZIA API client application in Microsoft Entra ID and configure the client credentials.

      1. Sign in to Azure portal.
      2. In the Azure Services section, click App registrations.
        The App registrations page is displayed.
      3. Click New registration.

      The Register an application window opens.

      1. In the Register an application window:

        • Name: Enter a name for the application that is representative of the Zscaler connection you are creating (e.g., Zscaler OneDrive Connector).
        • Supported account types: Ensure that this option is set to the Accounts in any organizational directory (Any Microsoft Entra ID tenant - Multitenant) value.
        • Redirect URI (optional): Select Web as the platform, then provide the URL of the Zscaler account (e.g., https://admin.zscalertwo.net/). Save the URL for later use.

      2. Click Register.

      The application is registered and the application's Overview page is displayed. Copy the Application (client) ID and Directory (tenant) ID values from the Overview page and save them for later use.

      Close

      1. Go to Certificates & secrets in the left-side navigation of the app and then click New client secret on the Client secrets tab.

      The Add a client secret pane opens.

      1. In the Add a client secret pane:
        • Description: Provide information about the client's secret.
        • Expires: Select the appropriate expiration time from the drop-down menu.

      1. Click Add.

      The client secret value is generated and displayed.

      1. Copy the 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
    Close

  • You must assign specific API permissions for each Microsoft connector you create for the Zscaler service.

    1. Go to API permissions in the left-side navigation and then click Add a permission under Configured permissions.
      The Request API permissions pane is displayed.
    2. On the Microsoft APIs tab, click an API to assign permissions (i.e., Microsoft Graph). To learn more, see the complete list of API permissions.
    3. Click Application permissions.
    4. In the Select permissions list, select each necessary permission for the connector.
    5. Click Add permissions.

      The permissions appear in the Configured permissions list on the API permissions page.

      Configured permissions page with annotation around People.Read.All permission

      Close
    6. If admin consent is required (such as SharePoint permissions), select Grant admin consent.
    7. In the Grant admin consent confirmation window, select Yes.
    Close

  • If you are setting up a custom connector for Microsoft Azure Blob Storage, you must add additional role assignments in Azure to ensure that the Zscaler service can properly access the application.

    1. Go to Azure Services > Enterprise Applications.

    2. Copy the Tenant ID and the Application name matching the ID from when you created the custom connector and client secret.

    3. Go back to the Azure portal home page, then go to Subscriptions and select your subscription.

    4. Go to Access Control (IAM) > Role Assignments > Add > Add role assignment.

    5. Search Storage Contributor. Select Storage Blob Data Contributor and Storage Account Contributor and then click Next. You must do this separately for each role.

    6. Click Select members and add the application as a member to Storage Blob Data Contributor and Storage Account Contributor, then select Review + assign.

    Close

  • If you are adding SharePoint as a SaaS Application tenant to ZIA, you need to create a private key JSON file and upload your public certificate to Azure.

      1. Open the terminal on your computer.

      2. Execute the following script:

        Keytool -genkey -alias selfsigned -keyalg RSA -keypass <keypassword> -storepass <keystorepass> -keystore Keystore.pfx -keysize 2048 -validity 1461

      3. Enter your custom information and press Enter.

      4. Execute the following script:

        Keytool -export -keystore keystore.pfx -alias selfsigned -file ketstore.cer

      5. Enter the source keystone password that you set in the first script.

        You will have two files ready: keystore.pfx and keystore.cer.

      Close

      1. In the Azure portal, go to App registrations and click on the client connector you created. In the left-side navigation, go to Manage > Certificates & secrets.

      2. Click the Certificates tab and then click Upload certificate.

      3. In the Description field, enter a description for the certificate.
      4. Upload the public certificate CER file and click Add.
      Close
      1. Go to your certificate uploaded on the Azure portal. For help viewing this, refer to the Microsoft documentation.

      2. Enter and run the following command on the PFX file to obtain the public certificate where <certname> is the name of the certificate in the previous step. The command asks for your source keystore password which you set in a previous step:

        openssl pkcs12 -in <certname>.pfx

      3. Enter and run the following command to obtain your decrypted private key:

        openssl pkcs12 -in <certname>.pfx -nocerts -nodes -out

      4. Create a new file with the following format and paste in the private key and certificate:

        {“private_key”: ”<Private Key>”,
   “public_cert”: ”<Certificate>”
}

        Format the private key and certificate as one line between the parentheses. Enter \n for every line break from the original formatting. See the following example:

        { "private_key":"-----BEGIN PRIVATE KEY-----\nXXXXXXXXXXXXXXXXXX\nXXXXXXXXXXXXXXXXXX\nXXXXXXXXXXXXXXXXXX\n-----END PRIVATE KEY-----\n",
"public_cert":"-----BEGIN CERTIFICATE-----\nXXXXXXXXXXXXXXXXXX\nXXXXXXXXXXXXXXXXXX\nXXXXXXXXXXXXXXXXXX\n-----END CERTIFICATE-----\n" 
}
      5. Save the file in the JSON format.
      Close
    Close

  • To authorize a custom connector, you must first manually update the Azure login URL to grant permissions for the application on the tenant. After that, you must provide the Client ID, Client Secret, and Tenant ID in the ZIA Admin Portal so that the Zscaler service can access the application. You can create custom connectors for Microsoft SaaS application tenants or for MIP accounts.

      1. In the ZIA Admin Portal, go to Administration > SaaS Application Tenants.
      2. Click Add SaaS Application Tenant.
        The Add SaaS Application Tenant page is displayed.
      3. Under Choose the SaaS Application Provider, select a Microsoft SaaS application.
      4. In the Tenant Name field, provide a name.
      5. Copy the following URL and paste it in a separate browser tab: https://login.microsoftonline.com/common/adminconsent?<client_id>&state=administration/add-casb-tenants&<redirect_uri>.
      6. In the URL, replace the client_id parameter with the Application (client) ID that you copied earlier, and replace the redirect_uri with the Redirect URI that you copied earlier.
      7. Press Enter on your keyboard.
        A Microsoft window appears listing the permissions requested by the Zscaler service.
      8. Click Accept.
        You return to the Add SaaS Application Tenant page.
      9. In the Authorize the SaaS Application section, select Custom for the SaaS Connector.

      10. Enter the values for the Client ID, Client Secret, and Tenant ID that you copied earlier, then click Authorize.

        If you're onboarding SharePoint, also upload the JSON file you created and formatted in the previous section.

      11. In the ZIA Admin Portal, click Save and activate the change.

      After adding the tenants, you can configure the Data at Rest Scanning DLP policy, Malware Detection policy, and Scan Configuration. You can also view reports and data for the tenants in the SaaS Security Report, Insights, and Logs.

      Close

      1. Go to Administration > Labels and Tags.
      2. In the Microsoft Information Protection (MIP) Labels tab, click Add MIP Account.

      The Add MIP Account window appears.

      1. Copy the following URL and paste it in a separate browser tab: https://login.microsoftonline.com/common/adminconsent?client_id=<client_id>&state=administration/mip-labels&redirect_uri=<redirect_uri>.
      2. In the URL, replace the client_id parameter with the Application (client) ID that you copied earlier, and replace the redirect_uri with the Redirect URI that you copied earlier.
      3. Press Enter on your keyboard.
        A Microsoft window appears listing the permissions requested by the Zscaler service.
      4. Click Accept.
      5. Return to the Add MIP Account window.
      6. Select Custom for the SaaS Connector.
      7. Enter the values for the Client ID, Client Secret, and Tenant ID that you copied earlier, then click Validate.

      The Add MIP Account window reappears, displaying the next window for account details.

      1. In the Add MIP Account window, under Account Name, enter a name you want to associate with the Microsoft account. It must be unique.
      2. Click Save and activate the change.

      The MIP account is added to the ZIA Admin Portal. The MIP Account displays a status of Validation Successful if the account is authorized. It displays a status of Validation Failed if the account is not authorized. If the status on the MIP account is Validation Failed, you can try the authorization process again by clicking Reauthorize on the Edit MIP Account window.

      1. Change the Label Retrieval field for the MIP account.
      Close
    Close

When creating custom connectors, provide the following application-specific API permissions to ensure that the Zscaler service has the access it needs.

  • In the following API tables, you need to select a different application from the Request API permissions page for each row of the Microsoft API column. For example, Azure requires selecting the same user_impersonation permission for both Azure Storage and Windows Azure Service Management.

    • Microsoft APIMicrosoft PermissionsAssociated Zscaler Actions
      Microsoft Graph APIsMail.ReadWriteApply Email Tag Label
      MailboxSettings.ReadScanning
      Directory.Read.AllScanning
      User.Read.AllScanning
      Mail.SendQuarantine
      Organization.Read.AllScanning
      AuditLog.Read.AllScanning
      Member.Read.HiddenScanning
      Reports.Read.AllScanning
      Close

    • Microsoft APIMicrosoft PermissionsAssociated Zscaler Actions
      Azure Storage APIuser_impersonation
      • Discover Storage Account
      • Scanning
      Windows Azure Service Management APIuser_impersonation
      • Discover Storage Account
      • Scanning
      Close

    • Microsoft APIMicrosoft PermissionsAssociated Zscaler Actions
      Microsoft Graph APIInformationProtectionPolicy.Read.AllScanning
      Microsoft Information Protection Sync Service APIUnifiedPolicy.Tenant.ReadScanning
      Microsoft Rights Management Services APIsContent.DelegatedWriterApply MIP Labels to File
      Content.WriterApply MIP Labels to File
      Content.SuperUserScanning
      Content.DelegatedReaderScanning
      Close

    • Microsoft APIMicrosoft PermissionsAssociated Zscaler Actions
      Office 365 Management APIActivityFeed.ReadScanning
      Microsoft GraphPeople.Read.AllScanning
      Group.Read.AllScanning
      Sites.Manage.AllScanning and Quarantine
      Sites.ReadWrite.All
      • Remove Sharing
      • Restore Quarantined File
      • Remove External Collaborators
      • Remove External Collaborators and Shareable Link
      • Remove Public Shareable Link
      • Remove Internal Shareable Link
      • Quarantine
      • Quarantine to User Root Folder
      • Remove File
      Files.ReadWrite.All
      • Scanning and Quarantine
      • Quarantine to User Root Folder
      Directory.Read.AllScanning
      GroupMember.Read.AllScanning
      Organization.Read.AllScanning
      AuditLog.Read.AllScanning
      Application.Read.AllScanning
      Reports.Read.AllScanning
      Close

    • Microsoft APIMicrosoft PermissionsAssociated Zscaler Actions
      SharePoint APISites.Read.AllScanning
      Office 365 Management APIActivityFeed.ReadScanning
      Microsoft Graph APIsPeople.Read.AllScanning
      Group.Read.AllScanning
      Sites.Manage.AllScanning
      Sites.ReadWrite.All
      • Remove Sharing
      • Restore Quarantined File
      • Remove External Collaborators
      • Remove External Collaborators and Shareable Link
      • Remove Public Shareable Link
      • Remove Internal Shareable Link
      • Quarantine
      • Quarantine to User Root Folder
      • Remove File
      Files.ReadWrite.All
      • Scanning and Quarantine
      • Quarantine to User Root Folder
      Directory.Read.AllScanning
      GroupMember.Read.AllScanning
      Organization.Read.AllScanning
      AuditLog.Read.AllScanning
      Application.Read.AllScanning
      Reports.Read.AllScanning
      Close

    • Microsoft APIMicrosoft PermissionsAssociated Zscaler Actions
      Office 365 Management APIsActivityFeed.ReadScanning
      Microsoft Graph APIsTeamMember.Read.AllScanning
      Chat.UpdatePolicyViolation.AllBlock Message
      TeamsAppInstallation.ReadForUser.AllScanning
      TeamsAppInstallation.ReadWriteSelfForUser.AllNotify User (ZscalerWorkflow Automation)
      TeamsAppInstallation.ReadWriteAndConsentForTeam.AllNotify User (ZscalerWorkflow Automation)
      Sites.SelectedScanning
      TeamsActivity.Read.AllScanning
      TeamsAppInstallation.ReadForChat.AllScanning
      ChannelSettings.Read.AllScanning
      Channel.ReadBasic.AllScanning
      People.Read.AllScanning
      Group.Read.AllScanning
      Sites.Read.AllScanning
      Sites.ReadWrite.All
      • Remove Sharing
      • Restore Quarantined File
      • Remove External Collaborators
      • Remove External Collaborators and Shareable Link
      • Remove Public Shareable Link
      • Remove Internal Shareable Link
      • Quarantine
      • Quarantine to User Root Folder
      • Remove File
      ChatMessage.Read.AllScanning
      Directory.Read.AllScanning
      User.Read.AllScanning
      ChannelMember.Read.AllScanning
      GroupMember.Read.AllScanning
      Files.Read.AllScanning
      Team.ReadBasic.AllScanning
      Chat.Read.AllScanning
      ChannelMessage.Read.AllScanning
      ChannelMessage.UpdatePolicyViolation.All
      Organization.Read.AllScanning
      AuditLog.Read.AllScanning
      Chat.ReadBasic.AllScanning
      Application.Read.AllScanning
      ChatMember.Read.AllScanning
      TeamsAppInstallation.ReadForTeam.AllNotify User (ZscalerWorkflow Automation)
      Reports.Read.AllScanning
      Close
    Close
Related Articles
Authorizing a Custom Zscaler Connector for Microsoft ApplicationsAuthorizing a Custom Zscaler Connector for Google ApplicationsAbout SaaS Application TenantsAdding SaaS Application TenantsSaaS Application Validation Error CodesAdding Object Types for ServiceNow Tenants