Cisco Spark Single Sign-On with Shibboleth

Document created by Cisco Documentation Team on Jun 28, 2016Last modified by Cisco Documentation Team on Aug 18, 2017
Version 8Show Document
  • View in full screen mode
 

Single Sign-On and Cisco Spark

Single sign-on (SSO) is a session or user authentication process that permits a user to provide credentials to access one or more applications. The process authenticates users for all the applications that they are given rights to. It eliminates further prompts when users switch applications during a particular session.

The Security Assertion Markup Language (SAML 2.0) Federation Protocol is used to provide SSO authentication between the Cisco Collaboration Cloud platform and your identity provider (IdP).

Profiles

The Cisco Spark platform only supports the web browser SSO profile. In the web browser SSO profile, the Cisco Spark platform supports the following bindings:

 
  • SP initiated POST->POST binding 


     

  • SP initiated REDIRECT->POST binding

      


 
      

NameID Format

The SAML 2.0 Protocol supports a number of NameID formats for the purpose of communicating about a specific user. The Cisco Collaboration Cloud platform supports the following NameID formats.

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

In the metadata that you load from your IdP, the first entry is configured for use in the Cisco Spark Platform.

SingleLogout

The Cisco Collaboration Cloud supports the single logout profile. In the Cisco Spark or WebEx Meeting app, a user can sign out of the application, which will use the SAML single log out protocol to end the session and confirm that sign out with your IdP. Ensure your IdP is configured for SingleLogout.

Integrate Cisco Spark with Shibboleth for Single Sign-On

Follow the tasks in this article to configure Single Sign-On (SSO) integration between Cisco Spark services and a deployment that uses Shibboleth 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.

  

The integration steps refer to Shibboleth 2.4.5 in CentOS 7 with Tomcat 7 as the web server.

Before You Begin 
For SSO and Cisco Spark services, IdPs must conform to the SAML 2.0 specification. In addition, IdPs must be configured in the following manner:
  •       

    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

               

          
  

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.

Configure Authorization in Shibboleth Files

 

After you install Shibboleth, you are provided configuration files with examples.

  
       
1    Go to the directory /opt/shibboleth-idp/conf to access the example files.
2    Decide which authorization method to use—for example, LDAP bind to Active Directory.
3    Edit the handler.xml file as follows:  

Uncomment

  
 

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

  
  

Comment

  
 

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

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

Example: 
 

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";
};

  
  

Configure Shibboleth Service Provider Components for SAML Assertion

      
1    Add the file that you downloaded from CI to the directory /opt/shibboleth-idp/metadata.
2    Edit the relying-party.xml file; after the DefaultRelyingParty tag, add the details of the SAML assertion for Cisco Spark.  
 

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

  
  

For id, you must use the EntityID value from the Cisco Spark metadata file. Replace the ID of the example with the EntityID of your organization.

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

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

    </metadata:MetadataProvider>

  
  

The SP metadata comes from a file in the Shibboleth file system, in the location where you uploaded the metadata for your Cisco Spark organization.

  

Configure the Assertion Attributes

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

Example: 

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>

  
  
2    In the Attribute definition section, keep what is already in the configuration for transientID.
3    Add the extra attribute that the SP is expecting, and define what it maps to in the attribute source.

Example: Map the attribute mail (email address attribute in Active Directory) to uid (UserID in Cisco Spark).
 

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

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

Provide trhe uid attribute to Cisco Spark that maps to the email address of the user.

  

Example: 

Release the attribute uid to the SP agreement with Cisco Spark.

  
 

<!--  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 Cisco Spark.

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

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.
 

Attachments

    Outcomes