SSO Field Guide

Introduction

Integrating single sign-on (SSO) with Zoom offers administrators user management and security options that can simplify account management. Once configured, users authenticate using their company credentials against your company’s identity provider instead of using alternative authentication methods like Google or Facebook integrations, or a direct username and password with Zoom.

This document provides a comprehensive overview of SSO configurations and settings within Zoom, in addition to troubleshooting and security information.

SSO Integrations

SSO Requires a Vanity URL to get started

An account must have an approved vanity URL before configuring SSO. Once the Vanity URL is approved, Zoom administrators can access the SSO configuration page through the advanced options submenu on the web portal. Refer to our support article on Vanity URLs for more information.

Zoom SSO works with any SAML 2.0 identity provider

Zoom can integrate with any identity provider that supports Security Assertion Markup Language (SAML) 2.0 authentication. Although there are many documented integration walkthroughs, some identity providers do not provide documentation for integrating with Zoom. Accounts that cannot locate configuration instructions are encouraged to reach out to their identity provider for more information.

Zoom administrators can manage user profile information and licensing through SAML response mapping or SCIM integrations

Administrators can manage user profile information and licensing through SAML response mapping or System for Cross-Domain Identity Management (SCIM) Application Programming Interface (API) requests, depending on the features available from the identity provider. Both user management methods offer near-equal functionality for profile information mapping and licensing management, but some SCIM mappings require manual configuration.

For a comprehensive list of SCIM capabilities, refer to our SCIM API documentation.

Zoom administrators can manage user account status through SCIM, but not SAML

Because SCIM allows identity providers to communicate directly with Zoom at any time, user accounts can be activated, deactivated, created, or deleted through SCIM integrations automatically. For example, if a user’s account in Active Directory is disabled, or if they are unassigned the application, SCIM can send an automatic deactivation request for the user’s account within Zoom. This feature is dependent on the capabilities of the identity provider’s SCIM application and functionality may vary by provider.

Limited identity providers offer SCIM for Zoom

Many identity providers do not have a SCIM integration built for Zoom as a part of their services. Accounts using an identity provider that does not support SCIM with Zoom must use SAML response mapping for automated user management.

SCIM requires an associated domain to automatically provision users

Accounts that use SCIM to manage and provision users for SSO must associate the email domain with Zoom. Failure to associate the domain will result in user provisioning failures. Refer to our support article on Associated Domains for more information on the process.

The following SSO integrations are documented

On-premises Active Directory can use the AD Sync Tool instead of SCIM

Accounts that want to automate user provisioning through SCIM but do not have a cloud-based identity provider can use the Active Directory (AD) Sync Tool application developed by Zoom for managing their users. This application runs on Oracle JDK 8 and simulates SCIM provisioning by managing users through API commands. See our support article on the AD Sync Tool for more information.

Identity providers can even authenticate meeting participants that don't have a Zoom account

Accounts that want to require users to authenticate their identity but do not wish to provide Zoom accounts can configure an external authentication profile with their identity provider. When enabled for a meeting, users who attempt to join must authenticate their login credentials against your identity provider to gain access. This is a common configuration for schools that do not provide accounts to all students but require authentication to join classes. Refer to our support article on configuring external authentication for more information.

Changing the identity provider requires re-configuring SSO within Zoom

Accounts that are changing identity providers must redo their SSO configuration within Zoom. This includes updating all fields within the configuration page to match their new identity provider. Accounts are encouraged to confirm that SAML response mappings will not change with the new identity provider.

No additional configurations or changes should be required, assuming there are no further changes.

Customers with sub-accounts can configure SSO from the master or sub-account

Customers with sub-accounts have two options for configuring SSO:

1. All users authenticate using the master account’s Vanity URL and are automatically logged into the sub-account through advanced SAML mapping (some mapping limitations apply); or

2. Each sub-account has a unique Vanity URL and independent SSO configuration, used exclusively by members of that sub-account

Each configuration offers unique benefits, with the second option offering the most flexibility. Customers considering implementation of either configuration should discuss with their account team which configuration is best suited for their needs.

SSO Settings & Security

Zoom administrators can choose the optimal security and settings options for their organization when configuring an SSO integration with Zoom. This section explains these settings and their implications for an SSO integration.

Zoom supports signed login and logout SAML requests

Zoom administrators that require additional service provider authentication can configure Zoom to sign all login and logout requests to the identity provider.

Accounts that use this setting may require a certificate rotation if their identity provider does not support dynamic metadata refreshment. See our support article on certificate rotation for more information.

Zoom supports encrypted SAML assertions when authenticating

Zoom administrators can configure Zoom to support encrypted assertions when authenticating. If this setting is enabled, unencrypted assertions will be discarded. Accounts that use this setting may require SSO certificate rotation if their identity provider does not support dynamic metadata refreshment. See our support article on certificate rotation for more information.

Zoom administrators can enforce automatic logout after a defined length of time

Zoom administrators can configure Zoom to automatically log users out of active sessions after defined lengths of time, customizable from 15 minutes to 180 days. This process will set the Zoom access token to expire at the predetermined length once the token is generated. This token has no relationship to an identity provider and is unique to Zoom.

SAML response logs can be saved for troubleshooting

Zoom can save SAML response logs from authentication attempts for seven days after an authentication. These response logs can be an invaluable tool for troubleshooting configuration and user errors, in addition to SAML response mapping configurations. Review the section on troubleshooting errors with SAML response logs for more information.

Provisioning at sign-in can create accounts instantly and is the easiest provisioning option

When SSO is set to provision At Sign-In (also known as just-in-time provisioning), any authorized user within the identity provider can authenticate into Zoom. Users that do not have an existing account will have one created immediately upon sign-in.

Provisioning at sign-in can simplify Zoom rollouts to a company by allowing users to create their accounts at the time of authentication instead of requiring proactive user creation. Combined with SAML response mapping, an entire user profile and licensing is ready within seconds of a user’s first authentication.

Additionally, provisioning at sign-in can dynamically create the SSO login type for pre-existing accounts. If a user has an existing Zoom account with a username and password, an SSO login type will be created upon sign-in with this configuration.

Provisioning prior to sign-in requires pre-created accounts with an SSO login type

Provisioning users for SSO prior to sign-in requires that authenticating users have both an existing Zoom account, and that the account has an SSO login type created. This type of provisioning is often paired with SCIM provisioning due to the automated account creation process but is not exclusive to it. Zoom users that consolidate into the company account through associated domains or a direct invite are not likely to have the SSO login type.

Zoom Administrators can confirm whether an account has an SSO login type by viewing the user account on the User Management page within the web portal and looking for the “SSO” icon underneath the user’s email.

If the icon is present, the user is provisioned for SSO; if the icon is missing, the user will not be able to sign in via SSO while pre-provisioning is enabled until it is added. A Zoom administrator can add this login type by adding users in bulk via a CSV file and selecting the “SSO User” option or have the user authenticate while Provision at Sign-in is enabled.

A domain must be associated and managed to enforce SSO authentication

Zoom administrators can enforce SSO authentication only if the email domain is associated and managed within Zoom. When this is enabled, all users authenticating using your company domain(s) will be automatically redirected to your identity provider’s authentication page, regardless of platform.

Once the domain is approved and managed, a Zoom administrator can enforce SSO authentication through your account’s security page under Sign-in Methods. Refer to our support article on Associated Domains for more information on associating and managing a domain.

Specified users can be exempt from enforced SSO authentication

Zoom administrators can exclude specific users from enforced SSO authentication. Excluding specific users (such as an admin account) may be useful if an SSO configuration breaks and an account administrator needs non-SSO access to the Zoom account. Admins that are exempt can sign into admin.zoom.us at any time in the event of an account lockout or broken SSO configuration (user must have the standard admin role). If a Zoom admin cannot access the account, they must contact Zoom Support for assistance.

To enable a user exception, navigate to the account security page on the web portal under advanced options, locate the list of enforced domains, and add an exception through the edit list.

Mobile and desktop clients can be configured to require users to use SSO authentication

Zoom clients can be preconfigured to automate SSO functionality, including automatic login, automatic logout, SSO-only authentication on the device, and more through Group Policy, mobile device management (MDM) services, and mass deployment clients.

For a complete list of configuration possibilities, refer to our configuration options for Group Policy, iOS, Android, Mac and Windows.

Office 365 users can automatically sign in to the Zoom for Outlook add-in using SSO credentials

Customers that use Office 365 can automatically sign their users into the Zoom for Outlook add-in using SSO credentials. This can be paired with a custom add-in manifest that pre-populates the account’s vanity URL, creating a seamless authentication experience for users. This feature uses the user’s SSO session token if it is active, or will prompt for a new authentication with your identity provider if no active session is found.

A Zoom admin can enable this setting on the account's security page under the advanced menu.

SAML Response Mapping

SAML attributes are categories of data defined by SAML values, and are used to pass information from the identity provider to a service provider like Zoom. Mapping attributes and values is essential for automating user profile information and managing user licenses.

SAML response mapping is broken into two halves: basic and advanced. Basic mapping is used to map basic profile information, including name, phone number, department, etc. Advanced mapping is used to manage dynamic license assignments, assigning user groups, user roles, and more.

This section covers the fundamentals of SAML response mapping, basic and advanced SAML response mapping, and highlights unique conditions required for some features.

Fundamentals: SAML Attributes and Values

Most identity providers pass basic profile information using plain attribute names and values. For example, an employee’s department may come through SAML with an attribute of department and a value of Human Resources. The following table demonstrates the relationship between attributes and values when passing information on a user.

By correctly assigning a SAML attribute to a response mapping, user information can be automatically applied to a user profile to simplify the account creation and management process.

Basic Mapping: Profile Information

SAML Basic Information Mapping is used to apply profile information like first name, last name, department, phone number, cost center, and location from a directory to a user’s profile. Many of these categories are self-explanatory and can be easily configured; however, some categories require explanation for proper configuration to prevent unanticipated consequences or application errors. The following section highlights unique mapping options and configuration settings for basic mapping. Refer to our Basic SAML Mapping article for a complete list of supported attributes.

Default license type only applies to brand new users

The default license type option will apply the designated license to all brand new users that are provisioned within the account through SAML. This does not apply to users that are authenticating for a second time, users that have consolidated into the account from a previous account, users that are provisioned through SCIM, or users that have been manually invited.

For information on updating user licenses with authentication, refer to the license configuration under Advanced SAML Mapping.

A default license type of None will not allow new users to authenticate unless advanced mapping is configured to assign a license

Zoom users must have an assigned license type (Basic, Licensed, or On-Prem) to login to the Zoom service. If a default license type of None is selected, new users cannot sign in or create a new account unless they will receive a license through Advanced SAML Mapping.

Most basic mappings will re-apply on login, unless otherwise specified

Most basic SAML mappings will update every time a user signs in by default, except for first name, last name, display name, and phone number. By default, these four mappings will only apply the first time a user authenticates and will not re-apply again, even if updated by a user or admin. Zoom administrators can change this behavior by enabling the option for Update at each SSO login on the SAML response mapping page.

Phone number mappings should include a country code and area code if outside the United States

Phone numbers mapped through SAML should include the user’s country code and area code in the SAML assertion when possible. Zoom will assume a country code of +1 if not defined by default.

Accounts that do not retain country codes within their directory can edit their SAML assertions within their identity provider to automatically include these if necessary.

Each user can have up to three phone numbers and one fax number mapped to their profile

Zoom administrators can configure up to three separate phone numbers and one fax number mapping for each user. Each phone number must be unique and cannot duplicate the value of another field.

Profile pictures must be mapped from either a publicly accessible URL or encoded with Base64

Accounts that want to map profile pictures from their directory must map the images using either a publicly-accessible URL or encode the image in Base64 when asserting.

Employee Unique ID

The Employee Unique ID changes the primary identifier Zoom uses to identify users

The Employee Unique ID is a feature Zoom offers to assist with identity management. By default, the primary identification for a Zoom user is their email address. This means that if the work email login type is [email protected], then Zoom will always identify this user by that e-mail address. This identifier is what allows integrations like SSO or Facebook and Google OAuth accounts to associate the user with the same Zoom account.

However, this identification process can be problematic if a user’s name or email changes. For example, if [email protected] has an email change to [email protected], Zoom cannot safely determine these are the same person (because the fundamental identifier is different) so Zoom will create a new account the first time [email protected] logs in.

To simplify this issue, Zoom offers the Unique Employee ID feature, which changes the primary identifier of a user from their email address to an established unique ID. This does not change a user’s Zoom username, but instead offers an alternative identifying attribute. This change allows Zoom to dynamically update a user’s email address within Zoom if:

• a new email address is accompanied by a known Unique Employee ID; and

• the affected user’s email domain is associated within Zoom

For example, if [email protected] authenticates and passes a SAML value of 12345 (their employee number) for the Employee Unique ID attribute, Zoom will now identify the user within the account by the asserted value. If John authenticates again using the email [email protected] while still passing the Employee Unique ID of 12345, Zoom will identify that [email protected] is now [email protected] and will dynamically update the user’s email within the account if the domain is associated.

Identity administrators should be positive that no two users will overlap with the same Employee Unique ID value before establishing SAML mapping for this category. If another user authenticates and passes the same value, the email will update again to the new user and can cause significant disruption to user services and experience.

The Employee Unique ID feature requires associated domains to change a user’s email

The Employee Unique ID feature cannot update a user’s email address unless the email domain is officially associated with your account profile. Refer to our support article on Associated Domains for more information.

Admins and Owners cannot update their email through the Employee Unique ID

Admin and owner emails within Zoom cannot be updated through the Employee Unique ID feature. This is intended as a security measure to prevent unauthorized access. Admins and owners must change their email through their profile page.

User emails can only be updated once per day through the Employee Unique ID

User emails can only be updated once every 24 hours through the Employee Unique ID feature. A user must wait a full calendar day from the previous update before updating their email through SSO again.

Setting the SAML attribute to <NameID> will use the asserted NameID of the user

Mapping the Employee Unique ID SAML attribute to <NameID> will automatically use the asserted NameID value of the user as their unique identifier. This can be a beneficial tool if your identity provider asserts a NameID other than a user’s email, like a User Principal Name (UPN) or similar value that does not change. Do not use this value if users’ NameIDs match their email.

Advanced Mapping: Licenses, Add-ons, and Access

The SAML Advanced Information Mapping section can dynamically apply licenses (including Zoom Phone), add-ons, and user access groups to users as they authenticate. Unlike basic mapping, advanced mapping contains many nuances that can require diligent attention when configuring, depending on the complexity of your environment. This section highlights the nuances for configuring advanced SAML mapping. Refer to our Advanced SAML Mapping article for a complete list of supported attributes.

Advanced mapping applies every time a user authenticates

Unlike basic mapping, which has optional updates for some categories, advanced mapping configurations will apply every time a user authenticates, according to the top-down order of application.

For example, if a user has a basic license and then authenticates through SSO passing a SAML attribute and value mapped to granting a full license, the user will be instantly granted the full license. If the user’s profile is then changed within the identity provider to move them back to a basic license, they will be re-assigned the basic license once they reauthenticate within Zoom.

Advanced mapping allows multiple SAML attributes and values per category

Unlike basic mapping, which allows only one SAML attribute per category, advanced mapping can support multiple attributes and values for each category. This allows for significant flexibility when managing user licensing and access through security groups within your identity provider as seen in the following configuration.

Advanced mapping applies licenses from the top-down when multiple attributes are asserted

If a user passes multiple SAML attributes or values that are configured for advanced SAML mapping, Zoom will map the licenses from the top-down. See the following example:

According to the above configuration, if a user were to pass an attribute for both global_users and marketing, because marketing is the highest in the configuration, this attribute will be applied to the user, and the remaining applicable attributes will be ignored.

Alternatively, if the configuration was set with global_users as the highest, as seen in the following screenshot, if a user’s assertion contained global_users, marketing, human resources, and IT, because global_users is the highest priority, only a basic license will be asserted.

Zoom administrators can adjust the order of application when editing the mapping values using the ↑↓ arrows within the editor.

Webinar and Large Meeting mappings can share a common value to apply both add-ons

To simplify the application process, Zoom administrators can configure the same SAML attribute and value twice to apply both webinar and large meeting add-ons to the users, as seen in the following image with the global_users value. These add-ons can also be independently configured if desired, as shown with the webinar_only and large_meeting_only values.

Users can be added to multiple User Groups using one SAML value

Zoom Administrators can configure User Group mapping to add a user to multiple groups with one SAML value.

The first user group added will be set as the user’s Primary Group and will determine the user’s default settings unless an underlying group has a setting locked. For more information on User Groups refer to our support article.

Specified users and User Groups can be exempt from specific SAML mappings

Every option under Advanced SAML Mapping can be configured to exempt specific users and User Groups from mapping behavior. This can be beneficial for preventing VIP users from service disruption due to a potential change in licensing.

Auto Mapping automatically assigns users to a User, Channel, or IM group named after their asserted SAML value if the value is not previously mapped to a group

Auto Mapping can be used to automatically assign users to a User Group, Channel, and IM Group named after their asserted SAML value. Unlike other advanced mapping components, which can be configured to assign a user to any group based on the SAML value, Auto Mapping always assigns a user to a group based on the exact SAML value. If the group previously did not exist, it will be automatically created.

For example, if Auto Mapping is set to map a user into the groups based on their department, if their department value is not already defined for the User Group, Channel, or IM Group, users will be automatically assigned into a group that matches their department name, as shown in the following table:

Zoom supports up to five custom SAML attributes

Zoom administrators can configure up to five custom SAML attributes for adding user data to their Zoom profile under the advanced user management page. After adding the custom fields, Zoom Administrators can configure the mapping on the SAML Response Mapping page.

Mapping users to a sub-account will only apply a meeting license and add-ons

Mapping a user to a sub-account will only apply a user’s meeting license and add-ons like Webinar and Large Meetings to the sub-account. User Groups, IM Groups, User Roles, etc., will not apply and must be configured within the sub-account.

Customers that require more flexibility for SAML response mapping with sub-accounts will require a unique Vanity URL and new SSO configuration within the sub-account.

Troubleshooting SSO

Using SAML Response Logs to Troubleshoot

Saved SAML response logs can be an invaluable tool for troubleshooting configuration and user errors, in addition to SAML response mapping configurations. If your SSO configuration is set to save SAML response logs, they can be accessed through the SAML Response Log tab available within the SSO configuration page in Advanced Settings. To view SAML response logs, click View Details next to an authentication attempt.

Most authentications will display in the response logs

Most failed or unsuccessful authentication attempts will display on the response logs page. If an authentication attempt does not display, it is most likely Zoom did not receive a SAML assertion from your identity provider, or saving SAML response logs is disabled.

Response logs can tell you if your configuration is incorrect or your certificate is outdated

When SAML response logs are enabled, the identity provider’s information is asserted to Zoom to authenticate identities for each party. If an asserted setting or string of information, like the X509 certificate or issuer ID is different from Zoom’s current configuration, an error will appear advising that the information “does not match the current SSO Settings.” A Zoom administrator can update the SSO configuration to match these asserted values if they are correct to resolve the error.

Response logs tell you which SAML values and attributes are being asserted

Reviewing response logs can assist with resolving SAML response mapping configurations by verifying what attributes and values are being asserted by users as they authenticate. These can be compared to the configuration to ensure the attributes and values match.

If SAML attributes or values are missing, the information is not being asserted by the identity provider service. Users experiencing this issue are encouraged to reach out to their identity provider support services for more assistance.

Response Logs include an error code and brief explanation, if unsuccessful

If a user cannot authenticate or receives an error, the SAML response logs contain an error code and brief explanation of the error.

Most issues can be identified and resolved by using these error messages. If you cannot resolve the error, reach out to Zoom Support for additional assistance.

Web Tracking ID Errors

If a user fails SSO authentication, they will receive a WEB Tracking ID error code. These codes are not an error message related to a specific failure, but are instead a unique log ID that can be reviewed in SAML Response Mapping for identifying authentication issues.

To identify the error, if SAML response logging is enabled, navigate to the SAML Response Log tab available within the SSO configuration page in Advanced Settings. From there, enter the WEB tracking ID into the Tracking ID field and search to populate the response log

The SAML response logs should display the SAML assertion and an error code and message at the bottom of the response that can be used for additional troubleshooting.

SCIM Errors

User Not Exist or Not Belong to this Account

This error occurs when a targeted user’s email address fails to provision due to an already existing account. Zoom administrators are encouraged to reach out to the user directly and manually invite the user to the account.

You Can’t Add Paid Users

This error occurs when SCIM attempts to provision a user when there are inadequate licenses on the account. To resolve the error, the user must be provisioned as a basic user, or a license must be made available for provisioning.

Using SCIM Logs to Troubleshoot User Provisioning

Zoom provides the most recent 100 API request logs in the Zoom Marketplace. A Zoom administrator can use these logs to confirm what information is being sent and received through provisioning APIs. To access the logs, sign into the Zoom Marketplace as a Zoom administrator and click Manage. On the following page, select Call Logs under Personal App Management. From there, click an entry to expand the API logs and review the contents.

The following image shows an example of a SCIM user provisioning request, with the user’s identity and licensing attributes highlighted for reference.

Like SAML response mapping, Zoom can only apply information that is submitted from the identity provider in the provisioning request. Use these logs to confirm that user identity and licensing attributes are being submitted from the identity provider. If expected information is missing from these assertions, contact your identity provider for support.

Data Flows and Authentication

SAML Authentication

The following diagram details a user’s SAML authentication flow when initiating a single sign-on session with Zoom.

SSO Web Login Token

After a user authenticates through SAML, the user's session is built within their browser, and has

a life of two hours by default. If the user continues to actively use their Zoom web page, the session will refresh; however, if the user does not use their web page for two hours, the token will expire and the user must reauthenticate. Zoom admins can configure this active session length on the Security page under Users need to sign in again after a period of inactivity and Set period for inactivity on the web (minutes).

Client Login Token

When a user attempts to authenticate via SSO within a client, the user’s machine will open a web browser and redirect them to the identity provider’s login page. After a user authenticates, the user’s browser will receive a Zoom client launch token. Once a user clicks the “open” or “launch” button, the browser uses the URL schema combined with the launch token to open the Zoom client.

The Zoom client will use the launch token to obtain the access token and the refresh token from Zoom server. The client will use the access token for a length of two hours at a time, and upon expiration will use the refresh token to gain a new set of tokens, which are stored within the client’s local database. This refresh process is unlimited by default, and can continually cycle through tokens until a user signs out or the tokens expire. Zoom administrators can customize the session length on the SSO settings page under enforce automatic logout.