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

SAML & SCIM Configuration Guide for Okta

This guide illustrates how to configure and install the Zscaler Internet Access app in Okta, which enables the user to use SAML as the method of authentication and SCIM as the method of provisioning.

Zscaler and Okta are technology partners. To learn more about the Zscaler and Okta integration, see the Zscaler and Okta Deployment Guide.

Supported Features

The SAML features supported by the Zscaler and Okta integration are:

To perform SP-initiated SSO:

  1. Open your site.
  2. You are redirected to https://gateway.<Zscaler Cloud Name>.net and prompted for a User Name.
  3. Enter your User Name and click Sign in.
Close

  • Just-in-Time (JIT) Provisioning (SAML auto-provisioning)

The SCIM features supported by the Zscaler and Okta integration are:

  • Create Users
  • Update User Attributes
  • Deactivate Users
  • Group Push

Prerequisites

Ensure that you have the following before you start configuring Okta:

  • An Okta account with admin privileges
  • A SCIM provisioning subscription for Okta. Contact your Okta representative to ensure your organization has the appropriate subscription.

Configuring Okta as the IdP for the Zscaler Service

To configure an Okta SAML and SCIM integration with Zscaler:

  • Okta allows you to integrate with your existing Active Directory using the Okta AD Agent. To learn more, refer to the Okta documentation.

    Close

  • To add the Zscaler Internet Access app in the Okta administrator portal:

    1. Log in to Okta.

    2. Click the Admin button at the top of the page to enter the administrator view.

      The Dashboard is displayed.

    3. On the Dashboard, click the Menu icon.

    4. Go to Applications > Applications.

    5. On the Applications page, click Browse App Catalog.

    6. On the Browse App Integration Catalog page, enter Zscaler Internet Access in the Search field.

    7. Select Zscaler Internet Access in the list of results.

      Selecting the Zscaler Internet Access Application in the Okta Admin Portal

      Close

    8. On the Zscaler Internet Access Application page, click Add Integration. This adds the application.

    9. In the General Settings, define the following fields:

      • Application Label: Specify the display name for the service.

      • Your Zscaler Domain: Enter your cloud name. For example, zscalerbeta.net. To learn how to find your domain, see What Is My Cloud Name for ZIA?

        Make sure to enter the correct value. Using the wrong value prevents you from authenticating via SAML to Zscaler.

      • Application Visibility: Configure as desired.
      • Browser plugin auto-submit: Configure as desired.

    10. Click Next.
    11. In the Sign on methods section, select SAML 2.0.

    12. Use the drop-down menu in the memberOf field to select a condition type and then enter an expression that specifies the groups you would like to send in your SAML assertion. Zscaler recommends to set the condition to a regular expression (Regex) with the expression being .*. This means that all groups the user belongs to are sent in the SAML assertion.

    13. In the Metadata details section, click More details. Copy the Sign on URL and download the Signing Certificate. You need them when configuring Okta as the IdP in the ZIA Admin Portal.

    14. Ensure the certificate file name:

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

      By default, Windows hides extensions for known file types.

    15. Click Done.
    Close

  • To configure SAML in the ZIA Admin Portal:

    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. Click 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 Sign on URL that you copied from Okta in step 2.m.
      • Login Name Attribute, enter NameID (case sensitive).
      • IdP SAML Certificate, upload the .pem certificate that you downloaded from Okta.

      • Org-Specific Entity ID: Enable if you have more than one organization instance on the same Zscaler cloud. For example, if you have two organization instances on the same Zscaler cloud and must authenticate both instances against the same Okta account, you can't use the same entity ID for multiple apps in Okta. For this situation, you must enable this setting for both instances to generate a unique organization-specific entity ID.

        The Org-Specific Entity ID is formatted like the following example

        https://login.zscalerbeta.net/sfc_sso/3829920
      • Locations: Select the locations to map to this IdP. You can also search for a location. Any unselected locations will be 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 will be mapped to the default IdP. This field is set to Any for the default IdP, and you can't modify it. Apart from the default IdP, any additional IdPs must be mapped to at least one domain.

      Ensure the Sign SAML Request option is disabled in the ZIA Admin Portal. Okta doesn't support signed SAML responses from the service provider.

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

    3. Click Save.

    4. Go to the Default Settings tab and select SAML as the Authentication Type.

    5. Click Save and activate the changes.

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

    Close

  • To configure SCIM in the ZIA Admin Portal:

    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 Okta (step 3).

      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.

          <Organization ID>/<IdP ID>

          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

  • After the app is installed, you need to configure it in the Okta administrator portal:

    1. In Okta, go to the Provisioning tab and click Configure API Integration.

    2. Select Enable API Integration.
    3. Enter the following information:

      • Zscaler ID: Enter the Organization ID and IdP ID of the Base URL in the following format:

        <Organization ID>/<IdP ID>

        For example, if your Base URL is https://scim.zscalerbeta.net/1234567/098/scim, enter 1234567/098.

      • API Token: Enter the Bearer Token you copied in step 4.d.

    4. Click Test API Credentials. If the test fails, verify that your bearer token is correct.
    5. Click Save.
    6. Select To App in the left-side navigation.
    7. Select Edit.

    8. Enable these checkboxes:

      • Create Users: When a user is created and is assigned Zscaler Internet Access, the user is automatically provisioned on the Zscaler service with SCIM.
      • Update User Attributes: If a user’s attributes are changed in Okta, the attributes are also updated in the Zscaler service. This is done with a SCIM API call.
      • Deactivate Users: If a user account is deleted or deactivated in Okta or has Zscaler Internet Access unassigned, the user is also deactivated in the Zscaler service.

    9. Click Save.
    Close

  • To assign people or groups to the app:

    1. In Okta, go to the Assignments tab.
    2. From the Assign drop-down menu, select Assign to People or Assign to Groups.
    3. Click Assign next to the people or groups you want to assign Zscaler Internet Access to. When you assign a group to Zscaler Internet Access, all users in that group are automatically assigned to the application.
    4. Click Done.

    At this point, Okta takes several minutes to sync the user database with the Zscaler service. The service accepts provisioning requests at the rate of 5 requests per second. To calculate your approximate sync time in seconds, divide your total number of users by 5 and then add 4% of your total users to accommodate for network drops and errors.

    For example, if you have 3,000 users:

    • 3,000/5 = 600
    • 0.04*3,000 = 120
    • 600+120 = 720

    This means the expected time for this database sync is 720 seconds or 12 minutes.

    Close

  • To provision groups:

    1. In Okta, go to Dashboard > Tasks to track the progress of your provisioning. If any errors have occurred, you can see them here. If you have multiple apps, you can filter by Zscaler Internet Access to see the relevant errors.

      Many errors happen because users and groups are still in the queue to be synced to the Zscaler service with SCIM provisioning. These types of errors are resolved when provisioning is complete. Before you take any further action, make sure you have calculated your approximate sync time and allowed it to sufficiently elapse.

    2. Click on the errors and a new page that lists all errors related to Zscaler Internet Access appears. To see details on the errors, click the expand icon.

    3. Select all errors by selecting the checkbox in the top left corner and click Retry Selected.

      This triggers another round of synchronization for the failed tasks. The same rate-limit applies to resynchronization of failed tasks. For example, if you have 300 failed tasks, it would take a little more than one minute to resynchronize. You might have to repeat this step multiple times if you continue to see failed tasks.

      Do not move to the next step until the entire database is synced. Failure to do so might result in unrecoverable errors.

    4. To sync the group information with the Zscaler service, go to the Push Groups tab.
    5. Click Push Groups > Find groups by name.
    6. Search and select the groups to sync with the Zscaler service, making sure to select Push group memberships immediately.
    7. Click Save to only add a single group or Save & Add Another if you want to push multiple groups.
    8. Click Close.
    9. On the Push Groups page, verify that all of your groups have been added.
    Close

  • To configure the Zscaler Authentication Exemptions list and enable users access to Okta:

    1. In the ZIA Admin Portal, go to Administration > Advanced Settings.
    2. In the Authentication Exemptions section, enter the required Okta domains in Exempted URLs. To learn more, refer to the Okta documentation.
    3. Click Save and activate the change.

    If you are using PAC files, enter the required Okta domains in the PAC file exemption list. Otherwise, the authentication fails.

         	If (shExpMatch(host, "*.okta.com", "*.oktacdn.com"))
                                        	return "DIRECT";

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

    Close

Testing the SAML and SCIM Configuration

This testing method only applies if you're forwarding traffic using PAC files, GRE tunnels, or IPSec tunnels, and you've enabled Enforce Authentication for the location or sub-location.

To test the SAML configuration:

  1. If you're already logged in to the Zscaler service, browse to https://login.<Zscaler Cloud Name>.net/zscaler.portal, and click Logout. Replace <Zscaler Cloud Name> with your Zscaler cloud name. To learn how you can find your cloud name, see What Is My Cloud Name for ZIA?
  2. Ensure that your traffic is being forwarded to the Zscaler service and then browse to a website.
  3. When prompted for authentication, enter your Okta credentials.

To test the SCIM configuration, in the ZIA Admin Portal, go to Administration > User Management. You should see a complete list of the users and groups added to your user database.

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