Configure single sign-on in Control Hub with Shibboleth (2024)

From the customer view in https://admin.webex.com, go to Management > Organization Settings, and then scroll to Authentication, and then toggle on the Single sign-on setting to start the setup wizard.

Choose the certificate type for your organization:

• Self-signed by Cisco—We recommend this choice. Let us sign the certificate so you only need to renew it once every five years.
• Signed by a public certificate authority—More secure but you'll need to frequently update the metadata (unless your IdP vendor supports trust anchors).

Trust anchors are public keys that act as an authority to verify a digital signature's certificate. For more information, refer to your IdP documentation.

Download the metadata file.

The Webex metadata filename is idb-meta-<org-ID>-SP.xml.

Go to the directory /opt/shibboleth-idp/conf to access the example files.

Decide which authorization method to use—for example, LDAP bind to Active Directory.

Edit the handler.xml file as follows:

 <!-- Username/password login handler --> <ph:LoginHandler xsi:type="ph:UsernamePassword" jaasConfigurationLocation="file:///opt/shibboleth-idp/conf/login.config"> <ph:AuthenticationMethod>urn:oasis:names:tc:SAML:2.0:ac:classes:PasswordProtectedTransport</ph:AuthenticationMethod> </ph:LoginHandler>

<ph:LoginHandler xsi:type="ph:RemoteUser"> <ph:AuthenticationMethod>urn:oasis:names:tc:SAML:2.0:ac:classes:unspecified</ph:AuthenticationMethod> </ph:LoginHandler>

Fill up the details of your Active Directory to allow for the authentication. Provide the configuration to the file login.config.

ShibUserPassAuth { edu.vt.middleware.ldap.jaas.LdapLoginModule required ldapUrl="ldap://ad0a.cisco.net:389" ssl="false" tls="false" baseDn="cn=Users,dc=cisco,dc=net" subtreeSearch="true" userFilter="sAMAccountName={0}" bindDn="cn=Administrator,cn=Users,dc=cisco,dc=net" bindCredential="ThePassword";};

Add the file that you downloaded from the Webex SP to the directory /opt/shibboleth-idp/metadata.

Edit the relying-party.xml file; after the DefaultRelyingParty tag, add the details of the SAML assertion for Webex.

 <rp:RelyingParty id="https://idbroker.webex.com/ea7c1420-711d-4916-95f8-22de53230d1e" provider="https://shib9a.cisco.net/idp/shibboleth" defaultSigningCredentialRef="IdPCredential"> <rp:ProfileConfiguration xsi:type="saml:SAML2SSOProfile" includeAttributeStatement="true" assertionLifetime="PT5M" assertionProxyCount="0" signResponses="never" signAssertions="always" encryptAssertions="conditional" encryptNameIds="never" includeConditionsNotBefore="true"/> </rp:RelyingParty>

Inside the metadata:MetadataProvider tag, add the location of the file:

 <metadata:MetadataProvider id="ShibbolethMetadata" xsi:type="metadata:ChainingMetadataProvider"> <metadata:MetadataProvider id="IdPMD" xsi:type="metadata:FilesystemMetadataProvider" metadataFile="/opt/shibboleth-idp/metadata/idp-metadata.xml" maxRefreshDelay="P1D" /> <!-- Cisco UCXN Configuration --> <metadata:MetadataProvider xsi:type="FilesystemMetadataProvider" xmlns="urn:mace:shibboleth:2.0:metadata" id="ucxn9a" metadataFile="/opt/shibboleth-idp/metadata/ucxn9a-single-agreement.xml" /> <!-- Cisco CUCM Configuration --> <metadata:MetadataProvider xsi:type="FilesystemMetadataProvider" xmlns="urn:mace:shibboleth:2.0:metadata" id="cucm9a" metadataFile="/opt/shibboleth-idp/metadata/cucm9a.cisco.net-single-agreement.xml" />  <!-- Cisco CI Configuration  <metadata:MetadataProvider xsi:type="FilesystemMetadataProvider" xmlns="urn:mace:shibboleth:2.0:metadata" id="CI" metadataFile="/opt/shibboleth-idp/metadata/idb-meta-ea7c1420-711d-4916-95f8-22de53230d1e-SP.xml" /> </metadata:MetadataProvider>

In the Data Connector section, specify where to retrieve attributes about your users.

Active Directory, with an id of MyLDAP.

<resolver:DataConnector id="MyLDAP" xsi:type="dc:LDAPDirectory" ldapURL="ldap://ad0a.cisco.net:389" baseDN="cn=Users,dc=cisco,dc=net" principal="Administrator@cisco.net" principalCredential="ThePassword"> <dc:FilterTemplate> <![CDATA[ (sAMAccountName=$requestContext.principalName) ]]> </dc:FilterTemplate> </resolver:DataConnector>

In the Attribute definition section, keep what is already in the configuration for transientID.

Add the extra attribute that the SP is expecting, and define what it maps to in the attribute source.

<resolver:AttributeDefinition id="mail-attr" xsi:type="ad:Simple" sourceAttributeID="mail"> <resolver:Dependency ref="MyLDAP" /> <resolver:AttributeEncoder xsi:type="enc:SAML2String" name="uid" /> </resolver:AttributeDefinition>

Define which attribute to provide to each SP agreement in the attribute-filter.xml file.

Provide the uid attribute to Webex that maps to the email address of the user.

Release the attribute uid to the SP agreement with Webex.

<!-- Release the attributes to cisco CI Cloud --> <afp:AttributeFilterPolicy id="ReleaseToCI"> <afp:PolicyRequirementRule xsi:type="basic:AttributeRequesterString" value="https://idbroker.webex.com/ea7c1420-711d-4916-95f8-22de53230d1e" /> <afp:AttributeRule attributeID="transientId"> <afp:PermitValueRule xsi:type="basic:ANY"/> </afp:AttributeRule> <afp:AttributeRule attributeID="mail-attr"> <afp:PermitValueRule xsi:type="basic:ANY" /> </afp:AttributeRule> </afp:AttributeFilterPolicy>

The rule that you created in attribute-resolver.xml should have a policy to release the mail-attr attribute to the EntityID that matches Webex.

Download the metadata file from the Shibboleth server in /opt/shibboleth-idp/metadata. The filename is idp-metadata.xml.

Choose one:

• Return to the Control Hub – certificate selection page in your browser, and then click Next.
• If Control Hub is no longer open in the browser tab, from the customer view in https://admin.webex.com, go to Management > Organization Settings, scroll to Authentication, and then choose Actions > Import Metadata.

On the Import IdP Metadata page, either drag and drop the IdP metadata file onto the page or use the file browser option to locate and upload the metadata file. Click Next.

You should use the More secure option, if you can. This is only possible if your IdP used a public CA to sign its metadata.

In all other cases, you must use the Less secure option. This includes if the metadata is not signed, self-signed, or signed by a private CA.

Okta does not sign the metadata, so you must choose Less secure for an Okta SSO integration.

Select Test SSO setup, and when a new browser tab opens, authenticate with the IdP by signing in.

If you receive an authentication error there may be a problem with the credentials. Check the username and password and try again. A Webex App error usually means an issue with the SSO setup. In this case, walk through the steps again, especially the steps where you copy and paste the Control Hub metadata into the IdP setup.

To see the SSO sign-in experience directly, you can also click Copy URL to clipboard from this screen and paste it in a private browser window. From there, you can walk through signing in with SSO. This step stops false positives because of an access token that might be in an existing session from you being signed in.

Return to the Control Hub browser tab.

• If the test was successful, select Successful test. Turn on SSO and click Next.
• If the test was unsuccessful, select Unsuccessful test. Turn off SSO and click Next.

The SSO configuration does not take effect in your organization unless you choose first radio button and activate SSO.