icon-unified.svg
Experience Center

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 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 Internet & SaaS 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.

      A screenshot of the Configured permissions page in Microsoft Entra ID

      Close
    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

  • 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 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 Admin Portal, go to Policies > Common Configuration > Out-of-band CASB > 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 Directory (tenant) 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.
      11. In the 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 Policies > Data Protection > Common Resources > MIP Labels.
      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 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

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

      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.

        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 in the original formatting.

      5. Save the file in the JSON format.
      Close

      1. Copy and paste the public certificate from the Create Private Key JSON File section into a text editor and save it as a CER file.

      2. 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.

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

      4. Upload the public certificate CER file and click Add.
      Close
    Close

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

    • Microsoft APIMicrosoft PermissionAssociated Zscaler Actions
      Microsoft GraphMail.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 PermissionAssociated Zscaler Actions
      Azure Storageuser_impersonation
      • Discover Storage Account
      • Scanning
      Windows Azure Service Managementuser_impersonation
      • Discover Storage Account
      • Scanning
      Close

    • Microsoft APIMicrosoft PermissionAssociated Zscaler Actions
      Microsoft GraphInformationProtectionPolicy.Read.AllScanning
      Microsoft Information Protection Sync ServiceUnifiedPolicy.Tenant.ReadScanning
      Microsoft Rights Management ServicesContent.DelegatedWriterApply MIP Labels to File
      Content.WriterApply MIP Labels to File
      Content.SuperUserScanning
      Content.DelegatedReaderScanning
      Close

    • Microsoft APIMicrosoft PermissionAssociated Zscaler Actions
      Office 365 Management APIsActivityFeed.ReadScanning
      Microsoft GraphPeople.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 PermissionAssociated Zscaler Actions
      Office 365 Management APIsActivityFeed.ReadScanning
      Microsoft GraphPeople.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 PermissionAssociated Zscaler Actions
      Office 365 Management APIsActivityFeed.ReadScanning
      Microsoft GraphTeamMember.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 Google ApplicationsAuthorizing a Custom Zscaler Connector for Microsoft ApplicationsAbout SaaS Application TenantsAdding SaaS Application TenantsSaaS Application Validation Error CodesAdding Object Types for ServiceNow Tenants