The following web access management and federation solutions were tested for Cisco Webex organizations with Webex Teams users. The documents linked below walk you through how to integrate that specific identity provider (IdP) with Webex Teams and your Webex organization managed through Cisco Webex Control Hub.


If you don't see your IdP listed below, use the high-level steps in the "SSO Setup" tab in this article.

The preceding guides cover SSO integration for Webex services that are managed in Cisco Webex Control Hub (https://admin.webex.com). If you're looking for SSO integration for a classic Webex site (managed in Site Administration), use the Configure Single Sign-On for Cisco Webex Site article instead.

Single sign-on (SSO) enables users to sign in to Cisco Webex Teams securely by authenticating to your organizations common identity provider (IdP). The Cisco Webex Teams app uses the Cisco Webex service to communicate with the Cisco Webex Platform Identity Service. The identity service authenticates with your identity provider (IdP).

You start configuration in Cisco Webex Control Hub. This section captures high-level, generic steps for integrating a third-party IdP.

For SSO and Cisco Webex Control Hub, IdPs must conform to the SAML 2.0 specification. In addition, IdPs must be configured in the following manner:
  • Set the NameID Format attribute to urn:oasis:names:tc:SAML:2.0:nameid-format:transient

  • Configure a claim on the IdP to include the uid attribute name with a value that is mapped to the attribute that is chosen in Cisco Directory Connector or the user attribute that matches the one that is chosen in the Cisco Webex identity service. (This attribute could be E-mail-Addresses or User-Principal-Name, for example.) See the custom attribute information in https://www.cisco.com/go/hybrid-services-directory for guidance.

  • Use a supported browser: we recommend the latest version of Mozilla Firefox or Google Chrome.

  • Disable any popup blockers in your browser.


The configuration guides show a specific example for SSO integration but do not provide exhaustive configuration for all possibilities. For example, the integration steps for nameid-format urn:oasis:names:tc:SAML:2.0:nameid-format:transient are documented. Other formats such as urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified or urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress will work for SSO integration but are outside the scope of our documentation.

You must establish a SAML agreement between the Cisco Webex Platform Identity Service and your IdP.

You need two files to achieve a successful SAML agreement.

This is an example of a PingFederate metadata file with metadata from the IdP.

Metadata file from the identity service.

The following is what you expect to see in the metadata file from the identity service.

  • EntityID—This is used to identify the SAML agreement in the IdP configuration

  • There is no requirement for a signed AuthN request or any sign assertions, it complies with what the IdP requests in the metadata file.

  • A signed metadata file for the IdP to verify that the metadata belongs to the identity service.

1

From the customer view in https://admin.webex.com, go to Settings, scroll to Authentication and click Modify.

2

Click Integrate a 3rd-party identity provider. (Advanced) and then click Getting Started.

3

Click Download Metadata File and click Next.

4

Cisco Webex Platform Identity service validates the metadata file from the IdP.

There are two possible ways to validate the metadata from the Customer IdP:

  • Customer IdP provides a signature in the metadata that is signed by a Public Root CA.

  • Customer IdP provides a self-signed private CA or doesn’t provide a signature for their metadata. This option is less secure.

5

Test the SSO Connection before you enable it.

6

If the test succeeds, then enable Single Sign On.

If you run into problems with your SSO integration, use the requirements and procedure in this section to troubleshoot the SAML Flow between your IdP and the Cisco Webex service.

  • Use the SAML trace addon for Firefox or Chrome.

  • To troubleshoot, use the web browser where you installed the SAML trace debug tool and go to the Cisco Webex Teams web app at https://teams.webex.com.

The following is the flow of messages between the Cisco Webex Teams app, Cisco Webex service, Cisco Webex Platform Identity Service and the Identity provider (IdP).

  1. Go to https://admin.webex.com and, with SSO enabled, the app prompts for an email address.
  2. The client sends a GET request to the OAuth authorization server for a token. The request is redirected to the identity service to the SSO or username and password flow. The URL for the authentication server is returned.
  3. Cisco Webex Teams requests a SAML assertion from the IdP using a SAML HTTP POST.
  4. The authentication for the app happens between the operating system web resources and the IdP.
  5. The Cisco Webex Teams app sends an HTTP Post back to the identity service and includes the attributes provided by the IdP and agreed in the initial agreement.
  6. SAML Assertion from IdP to Webex.
  7. The identity service receives an authorization code that is replaced with an OAuth access and refresh token. This token is used to access resources on behalf of the user.
1

Go to https://admin.webex.com and, with SSO enabled, the app prompts for an email address.

The app sends the information to the Cisco Webex service and the service verifies the email address.

2

The client sends a GET request to the OAuth authorization server for a token. The request is redirected to the identity service to the SSO or username and password flow. The URL for the authentication server is returned.

You can see the GET request in the trace file.

In the parameters section the service looks for an OAuth code, email of the user who sent the request, and other OAuth details such as ClientID, redirectURI and Scope.

3

Cisco Webex Teams requests a SAML assertion from the IdP using a SAML HTTP POST.

When SSO is enabled, the authentication engine in the identity service redirects to the IdP URL for SSO. The IdP URL provided when the metadata was exchanged.

Check in the trace tool for a SAML POST message. You see an HTTP POST message to the IdP requested by the IdPbroker.

The RelayState parameter shows the correct reply from the IdP.

Review the decode version of the SAML request, there is no mandate AuthN and the destination of the answer should go to the destination URL of the IdP. Ensure that the nameid-format is correctly configured in the IdP under the correct entityID (SPNameQualifier)

The IdP nameid-format is specified and the name of the agreement configured when the SAML agreement was created.

4

The authentication for the app happens between the operating system web resources and the IdP.

Depending on your IdP and the authentication mechanisms configured in the IdP, different flows are started from the IdP.

5

The Cisco Webex Teams app sends an HTTP Post back to the identity service and includes the attributes provided by the IdP and agreed in the initial agreement.

When authentication is successful, Cisco Webex Teams sends the information in a SAML POST message to the identity service.

The RelayState is the same as the previous HTTP POST message where the app tells the IdP which EntityID is requesting the assertion.

6

SAML Assertion from IdP to Webex.

7

The identity service receives an authorization code that is replaced with an OAuth access and refresh token. This token is used to access resources on behalf of the user.

After the identity service validates the answer from the IdP, they issue an OAuth token that allows Cisco Webex Teams access to the different Cisco Webex cloud services.