Cisco Spark Single Sign-On with Active Directory Federation Services 2.0 and 3.0

Document created by Cisco Documentation Team on Jun 24, 2016Last modified by Cisco Documentation Team on Aug 30, 2017
Version 37Show Document
  • View in full screen mode
 

Integrate Cisco Spark with Active Directory Federation Services

   

You can configure Single Sign On (SSO) integration between Cisco Spark Servers and a deployment that uses Active Directory Federation Services (AD FS) as an identity provider (IdP).

  

Set up this integration for users of Cisco Spark message, meet, and call. If your WebEx Meeting Center is integrated in Cisco Spark Control Hub, WebEx Meeting Center inherits the user management. If you can't access WebEx in this way, you must do a separate integration to enable SSO for Cisco WebEx.

Download the Cisco Spark Metadata to your Local System

       
1    From the customer view in https://admin.ciscospark.com, go to Settings, and then scroll to Authentication.
2    Click Modify, click Integrate a 3rd-party identity provider. (Advanced), and then click Get Started.
3    Download the metadata file.  

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

  
4    Keep your Cisco Spark Control Hub session open in your browser.

Install Cisco Spark Metadata in Active Directory Federation Services

Before You Begin

  • Cisco Spark supports Active Directory Federation Services (AD FS) 2.x and 3.x.

     

    Windows 2008 R2 only includes AD FS 1.0, you must install AD FS 2.x from Microsoft.

     

  • For SSO and Cisco Spark services, identity providers (IdPs) must conform to the following SAML 2.0 specifications:
    • Configure the IdP to use Forms Based authentication.

       

    • Set the NameID Format attribute to one of the following:
      • 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 mapped to the user's email address in the SAML Assertion.

         

      • urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified

         

        Configure a claim on the IdP to include the uid attribute name with a value mapped to the user's email address in the SAML Assertion.

         

      • urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress

         

           
1    Sign in to the AD FS server with administrator permissions.
2    Open the AD FS Management console and browse to Trust Relationships > Relying Party Trusts.
3    Select Add Relying Party Trust.
4    From the Add Relying Party Trust Wizard window, select Start.
5    In the Select Data Source step, select Import data about the relying party from a file, browse to the Cisco Spark Metadata file that you downloaded, and select Next.
6    In the Specify Display Name step, create a display name for this relying party trust such as “Cisco Spark” and select Next.
7    In the Choose Issuance Authorization Rules step, select Permit all users to access this relying party, and select Next.
8    In the Ready to Add Trust step, select Next and finish adding the relying trust to AD FS.

Create Claim Rules to Allow Authentication from Cisco Spark

                 
1    In the main AD FS pane, select the trust relationship that you created, and then select Edit Claim Rules.
2    On the Issuance Transform Rules tab, select Add Rule.
3    In the Choose Rule Type step, select Send LDAP Attributes as Claims, and then select Next.  


  
  1. Enter a Claim Rule Name.
  2. Select Active Directory as the Attribute Store.
  3. Map the E-mail-Addresses LDAP attribute to the uid outgoing claim type.  

    This rule tells AD FS which fields to map to Cisco Spark to identify a user. Spell the outgoing claim types exactly as shown.

      
4    Save your changes.
5    Select Add Rule again.
6    Select Send Claims Using a Custom Rule, and then select Next.  

This rule provides AD FS with the “spname qualifier” attribute that Cisco Spark does not otherwise provide.

  
7    Open your text editor and copy the following content.  

c:[Type == "http://schemas.microsoft.com/ws/2008/06/identity/claims/windowsaccountname"] => issue(Type = "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/nameidentifier", Issuer = c.Issuer, OriginalIssuer = c.OriginalIssuer, Value = c.Value, ValueType = c.ValueType, Properties["http://schemas.xmlsoap.org/ws/2005/05/identity/claimproperties/format"] = "urn:oasis:names:tc:SAML:2.0:nameid-format:transient", Properties["http://schemas.xmlsoap.org/ws/2005/05/identity/claimproperties/namequalifier"] = "URL1", Properties["http://schemas.xmlsoap.org/ws/2005/05/identity/claimproperties/spnamequalifier"] = "URL2");

  

Replace URL1 and URL2 in the text as follows:

  
  • URL1 is the entityID from the AD FS metadata file that you downloaded.

    For example, the following is a sample of what you see: <EntityDescriptor xmlns="urn:oasis:names:tc:SAML:2.0:metadata" entityID="http://ad0a.identitylab20.ciscolabs.com/adfs/services/trust" ID="_55515dde-8147-4183-8a85-b704d26b5dba">

    Copy just the entityID from the AD FS metadata file and paste it in the text file to replace URL1

  • URL2 is on the first line in the Cisco Spark metadata file that you downloaded.

    For example, the following is a sample of what you see: <EntityDescriptor xmlns="urn:oasis:names:tc:SAML:2.0:metadata" entityID=" https://idbroker.webex.com/35a15b0a-0eg1-4029-9f63-a8c54df5df59"> 

    Copy just the entityID from the Cisco Spark metadata file and paste it in the text file to replace URL2.

8    With the updated URLs, copy the rule from your text editor (starting at "c:") and paste it in to the custom rule box on your AD FS server.  
The completed rule should look like this:


  
  
9    Select Finish to create the rule, and then exit the Edit Claim Rules window.
10    Select Relying Party Trust in the main window, and then select Properties in the right pane.
11    When the Properties window appears, browse to the Advanced tab, and then select SHA-256.
12    Select OK to save changes.
13    Browse to the following URL on the internal AD FS server to download the file: https://<AD_FS_Server>/FederationMetadata/2007-06/FederationMetadata.xml  

You may need to right click on the page and view page source to get the properly formatted XML file.

  
14    Save the file to your local machine.
What to Do Next

 

You're ready to import the AD FS metadata back in to Cisco Spark from the management portal.

  

Download and Modify Active Directory Federation Services Metadata

       
1    Browse to the following URL on the internal AD FS server: https://<AD_FS_Server>/FederationMetadata/2007-06/FederationMetadata.xml

You may need to right click on the page and view page source to get the properly formatted XML file.

2    Modify the AD FS Metadata file to remove unsupported attributes from the XML.
  • Keep only the following entries in the AD FS Metadata file:
    • <EntityDescriptor>

       

    • <IDPSSODescriptor>

       

    • <ContactPerson>

       

    All other entries can be deleted.
  • Delete all the metadata from the first ds:Signature tag up to and including SPSSODescriptor.
    The highlighted metadata is collapsed and intended as an example.


3    Do not alter anything after the IDPSSODescriptor tag.
4    Save your changes.
What to Do Next

 

You're ready to import the AD FS metadata back in to Cisco Spark from the management portal.

  

Import the IdP Metadata and Enable Single Sign-On After a Test

 

After you export the Cisco Spark metadata, configure your IdP, and download the IdP metadata to your local system, you are ready to import it into your Cisco Spark organization.

  
        
1    Go back to the browser or tab where you're signed in to the Cisco Spark Control Hub – Export Directory Metadata page, and then click Next.
2    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.

We recommend that you use require certificate signed by a certificate authority in Metadata (more secure) for service providers that use publicly signed and trusted certificates.

3    Click Next.
4    Select Test SSO Connection, and when a new browser tab opens, authenticate with the IdP by signing in.

A common cause of an authentication error is a problem with the credentials. Please check the username and password and try again.

A Cisco Spark or Webex 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 Cisco Spark metadata into the IdP setup.

5    Return to the Cisco Spark Control Hub browser tab.
  • If the test was successful, select This test was successful. Enable Single Sign-On option and click Next.
  • If the test was unsuccessful, select This test was unsuccessful. Disable Single Sign-On option and click Next.

Active Directory Federation Services Troubleshooting

AD FS Errors in Windows Logs

   

In the Windows logs, you may see an AD FS event log error code 364. The event details identify an invalid certificate. In these cases, the AD FS host is not allowed through the firewall on port 80 to validate the certificate.

  

Federation ID

The Federation ID is case-sensitive. If this is your organizational email address, enter it exactly as AD FS sends it, or Cisco Spark cannot find the matching user.

 

A custom claim rule cannot be written to normalize the LDAP attribute before it is sent.

 

Import your metadata from the ADFS server that you set up in your environment.

 

You can verify the URL if necessary by navigating to Service > Endpoints > Metadata > Type:Federation Metadata in ADFS Management.

  

Time Synchronization

   

Ensure that your AD FS server's system clock is synchronized to a reliable Internet time source that uses the Network Time Protocol (NTP). Use the following PowerShell command to skew the clock for the Cisco Spark Relying Party Trust relationship only.

  

Set-ADFSRelyingPartyTrust -TargetIdentifier "https://idbroker.webex.com/$ENTITY_ID_HEX_VALUE" -NotBeforeSkew 3

  

The hexadecimal value is unique for your environment. Please replace the value from the SP EntityDescriptor ID value in the Cisco Spark metadata file. For example:

  
 
<EntityDescriptor xmlns="urn:oasis:names:tc:SAML:2.0:metadata" entityID=" https://idbroker.webex.com/c0cb726f-a187-4ef6-b89d-46749e1abd7a">
  
  
 

Attachments

    Outcomes