The following guide explains how to configure OAuth 2.0 authorization for Internet & SaaS API using Microsoft Entra ID (formerly Azure Active Directory).

Microsoft Entra ID is an identity provider (IdP) that you can use for authentication and authorization. Using OAuth 2.0 with Client Credentials flow in Microsoft Entra ID permits a web client to use its own credentials, instead of impersonating a user. To manage authorization and consent in Microsoft Entra ID, you need to configure both the client and the resource server as applications. Based on this implementation, there is a separate application registration for each of the clients and the resource server (Intenet & SaaS API).

OAuth 2.0 authorization is currently supported only for Internet & SaaS API.

Prerequisites

Ensure that the following prerequisites are met before you start configuring Microsoft Entra ID as your OAuth 2.0 service for Internet & SaaS API:

• You have a subscription to Microsoft Entra ID.
• You have an application (i.e., API Client) that needs to send API requests to the Internet & SaaS API.
• You have configured the necessary API Roles in the Admin Portal and assigned appropriate API permissions.

Configuring Microsoft Entra ID

For each API Role configured in the Admin Portal, you need to complete the following steps to set up OAuth 2.0 authorization using Microsoft Entra ID.

• 1. Register the Internet & SaaS API client application.

  This section covers how to register your Internet & SaaS API client application in Microsoft Entra ID and configure the client credentials.

  • a. Register the app.

    To complete the client application registration process:

    1. Sign in to Microsoft Entra admin center.
    2. Go to Identity > Applications > App registrations.

    3. Click New Registration.

       See image.

       

       Close

       The Register an application window opens.

    4. In the Register an application window:
       • Name: Enter a name for the application that is representative of the Internet & SaaS API Role used (e.g., ZIA API Client Super Admin).
       • Supported account types: Ensure that this option is set to the Accounts in this organizational directory only (<tenant> only - Single tenant) value.

    5. Click Register.

       See image.

       

       Close

       The application is registered and the application's Overview page is displayed. Copy the Application (client) ID value from the Overview page and save it for later use.

       See image.

       

       Close

    Close
  • b. Configure client credentials.

    To configure the credentials for your API client application:

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

       See image.

       

       Close

       The Add a client secret pane opens.

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

       See image.

       

       Close

    3. Click Add.

       The client secret value is generated and displayed.

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

       See image.

       

       Close

    Close

  Close
• 2. Configure the Internet & SaaS API service to expose a web API.

  This section covers how to register the Internet & SaaS API service in Microsoft Entra ID and configure the app to expose a web API that is accessible by the client app.

  • a. Register the app.

    To complete the application registration process:

    1. In the Microsoft Entra admin center, go to Identity > Applications > App registrations.

    2. Click New Registration.

       See image.

       

       Close

       The Register an application window opens.

    3. In the Register an application window:

       • Name: Enter a name for the Internet & SaaS API service, e.g., ZIA API Web Service.
       • Supported account types: Ensure that this option is set to the Accounts in this organizational directory only (<tenant> only - Single tenant) value.

       See image.

       

       Close

    4. Click Register.

       The application is registered and displayed.

    Close
  • b. Add a scope.

    To configure the Internet & SaaS API app to expose a web API:

    1. Click Expose an API on the left-side navigation of the app.
    2. Click Add next to the Application ID URI and then click Save with the default value that is provided. Copy the Application ID URI and save it for later use.

    3. Click Add a scope under Scopes defined by this API.

       See image.

       

       Close

       The Add a Scope pane opens.

    4. In the Add a Scope pane:

       • Scope name: Enter a relevant scope name (e.g., ZIA API Client <ZIA API Role>).

       • Who can consent?: Choose which users can consent to this scope based on your business requirements and organization policies.

         If you are configuring this for testing purposes, make sure this option is restricted to Admins only.

       • Admin consent display name: Enter a consent name that must be displayed on the consent screen when admins consent to this scope.
       • Admin consent description: Enter a detailed description that must be displayed when tenant admins expand a scope on the consent screen.
       • User consent display name: Enter a consent name that must be displayed on the consent screen when users consent to this scope.
       • User consent description: Enter a detailed description that must be displayed when users expand a scope on the consent screen.
       • State: Ensure that the scope is enabled.

       See image.

       

       Close

    5. Click Add scope.

    6. To authorize the client application, click Add a client application under Authorized client applications.

       See image.

       

       Close

    7. In the Client ID field, enter the Application (client) ID from Step 1 > a, and select the required scope under Authorized scopes.

       See image.

       

       Close

    8. Click Add Application.

    Close
  • c. Define an app role.

    To declare a role for the Internet & SaaS API app (can be assigned to the client app for accessing the API):

    1. Click App roles on the left-side navigation and then click Create app role.

       See image.

       

       Close

       The Create app role pane opens.

    2. In the Create app role pane:

       • Display name: Enter a display name for the app role.
       • Allowed member types: Select Applications for this option.

       • Value: Enter a value in the format supported by the Zscaler service, <Zscaler Cloud Name>::<Org ID>::<API Role>, where:

         • <Zscaler Cloud Name> represents the name of the cloud on which your organization is provisioned.
         • <Org ID> is an identifier assigned to your organization by Zscaler. You can obtain this value from the Company Profile page within the Admin Portal.
         • <API Role> represents the API Role configured on the Role Management page within the Admin Portal.

         For example, zscalerbeta.net::272378::sampleRole.

       • Description: Enter a description of the app role.
       • Do you want to enable this app role?: Enable this checkbox.

       See image.

       

       Close

    3. Click Apply.
    4. After the app role is created, go to the Manifest page from the left-side navigation and ensure that the app role you configured appears in the appRoles field within the JSON fields.

    Close

  Close
• 3. Configure the client to access the web API.

  To configure the client app's permissions to the Internet & SaaS API app:

  1. In the Microsoft Entra admin center, go to Identity > Applications > App registrations.

  2. Select the Internet & SaaS API client app configured in Step 1.

     The Overview page of the app is displayed.

  3. Click API permissions on the left-side navigation and then click Add a permission under Configured permissions.

     The Request API permissions pane opens.

  4. In the Request API permissions pane:

     1. Navigate to the My APIs tab and then click the Internet & SaaS API app that you configured in Step 2.

        See image.

        

        Close

     2. Choose the Application permissions as the type of permission required by the client application.

     3. Under Select permissions, select the API Role that was created in Step.2c.

        See image.

        

        Close

     4. Click Add permissions.

  If you are testing the configurations, enable the Grant admin consent for <tenant> option under the Configured permissions section and click Yes when prompted.

  Close
• 4. Collect information for Zscaler OAuth 2.0 server configuration.

  To collect information from Microsoft Entra ID used to configure the OAuth 2.0 authorization server in the Admin Portal:

  1. In the Microsoft Entra admin center, go to Identity > Applications > App registrations.
  2. Select the Internet & SaaS API app configured in Step 2.

  3. Click the Endpoints tab on the Overview page.

     See image.

     

     Close

     The Endpoints pane opens.

  4. In the Endpoints pane:

     • Copy the OAuth 2.0 token endpoint (v2) URL. The typical format is https://login.microsoftonline.com/<Application ID>/oauth2/v2.0/token.
     • Copy the URL displayed in the OpenID Connect metadata document field and open the link in a new browser window. Locate the jwks_uri parameter in the metadata displayed and copy its value. The typical format is https://login.microsoftonline.com/<Application ID>/discovery/v2.0/keys.

     See image.

     

     Close

     These values are required for configuring the OAuth 2.0 authorization server in the Admin Portal, as explained in the subsequent section.

  Close

Validating Configurations and Retrieving an Access Token

After completing the necessary configurations in Microsoft Entra ID, you can validate the authorization server configuration and retrieve an access token.

• 1. Validate authorization server configuration.

  To validate your authorization server configuration:

  1. Log in to the Admin Portal.
  2. Go to Administration > API Configuration > Legacy API > Internet & SaaS API.

  3. Click the OAuth 2.0 Authorization Servers tab and then click Add Authorization Server.

     The Add Authorization Server window opens.

  4. In the Add Authorization Server window, fill out the following information that is necessary for validating your authorization server configuration:

     • Name: Enter a name for your authorization server configuration (e.g., Microsoft Entra ID). The name can only contain alphanumeric characters without spaces and cannot exceed 64 characters.
     • OAuth 2.0 JWKS Location: Enter the JSON Web Key Set (JWKS) endpoint value obtained through the jwks_uri parameter in Configuring Microsoft Entra ID. The JWKS endpoint returns the public key set of the authorization server that is used by Zscaler to cryptographically verify the authenticity of the JWT in API requests.

     See image.

     

     Close

     Click Validate to verify that the JWKS endpoint is configured correctly. If validation is successful, a Save button appears.

  5. After successful validation, click Save.

  Close
• 2. Retrieve an access token.

  To retrieve an access token from the authorization server by using the credentials saved in the previous steps:

  1. Create a JSON file with the following fields:

     grant_type = client_credentials
     client_id = <Application (client) ID from Step 1.a>
     client_secret = <Client secret value from Step 1.b>
     scope = <Application ID URI from Step 2.b, appended with "/.default". For example, api://fe2f6a75-199e-48a5-b9ef-a7357ab78c53/.default>

  2. Send a POST request to the OAuth 2.0 token endpoint (v2) URL from Step 4, with the JSON payload in the request body.

     The API response should contain the access token (JWT). This access token must be sent in the API calls made to the Internet & SaaS API service. The access token can be presented in the request Authorization header using the bearer authentication scheme along with the token expiration time.

  Close