Tom Greene – Paragon Development Systems, Inc.
Neil Cashell – Novell Technical Services
This goal of this document is to show how Novell Access Manager can be used to single sign on to Cisco's WebEx collaboration cloud using the SAML2 protocol. Although we will be referencing SAML authentication requests and responses, and assertion specifics, details on the SAML protocol is outside the scope of this document. An outline of the configuration steps required on both the Novell Access Manager Identity server and WebEx server will be covered. We will also cover some basic troubleshooting in a separate section where we look at available tools and log files for troubleshooting SAML, as well as sample entries showing successful communications.
Before attempting this integration, you should:
Configuring Cisco WebEx to integrate with Novell Access Manager 3.1
The Cisco WebEx server is simply a SAML2 Service Provider (SP). It's goal is to
- redirect authentication requests to the SAML2 Identity Server (Novell Access Manager's IDP server) in an SP initiated SSO model
In order to be able to do this, the Cisco WebEx server must know the type of SAML Authentication request required to authenticate to the IDP server, and what URLs to send it to on the IDP server. In the screenshot below (figure 1), the following options must be enabled and populated:
- Federation Protocol: Defines the Federation protocol that will be used to communicate between the SP (Cisco WebEx) and the IDP server (Novell). Options include WS-Fed but we will use SAML2 in this example.
- SSO Profile: WebEx supports both the SP initiated and IDP initiated SSO form. In our case, we selected the SP initiated SSO option, without signing the authentication request. It is possible to sign the authentication request – if this is the case, the issuer of the signing certificate must simply be imported into the NIDP truststore of the Novell Identity Server.
- WebEx SAML Issuer (SP ID): This is the unique identifier for your SAML2 SP and will be included in the Issuer header of the SAML2 Authentication requests from WebEx. This information will also be part of the SP metadata imported into the IDP server.
- Issuer for SAML (IDP ID): This is the IDP server metadata URL and must match the <Issuer> tag of the SAML2 Authentication Response sent by the IDP server to the SP. It must be set to the Novell IDP server SAML2 metadata URL (/nidp/saml2/metadata).
- You can export the SAML metadata WebEx SP configuration file: This can be used to export the SP metadata. This exported metadata is then used on the Novell IDP server when building the trust relationship. Note that this metadata must be manually changed before doing so – see section XXXX for more details
- Customer SSO Service Login URL: This defines the URL on the IDP server where the Cisco WebEx server will redirect the SAML authentication request to. When the user selects to authenticate to Cisco WebEx, Cisco WebEx will generate an Authentication request to be sent to this URL specified here. In our case, it will be the Novell Access Manager login URL.
- NAMEID Format: Defines the NameIdentifier format requested in the SAML2 Authentication Request. The IDP server must be capable of responding with this NameID format. In our case, we use the default unspecified format.
- AuthnContextClassRef: Defines the type of authentication we want to execute at the IDP server. The Authentication Request will include this authentication type, and the Identity server must satisfy that authentication type when authenticating the users.
- Default WebEx target page URL: This defines the default URL that the WebEx server will redirect users to after the SAML assertion is consumed and the user SSO process finishes successfully. Leaving it blank redirects the user to the default WebEx page.
- Customer SSO error URL: This defines the URL that users will be redirected to if an error in the SSO process occurs.
- Single logout URL: Defines the logout URL on the Identity Server that users will be redirected to when logging out of the WebEx application. It will always be the /nidp/saml2/slo URL when dealing with Novell's Identity Server.
- Auto Account creation/Auto Account update: Defines whether an account is created or updated on the WebEx SAML2 SP based on the assertion sent by the SAML2 Identity Server.
- process the SAML assertion generated by the IDP server
When the user has successfully authenticated to the SAML IDP server, an assertion is generated by that IDP server and sent to the WebEx service provider via the browser. The assertion generated by the IDP server is signed and the signature must be validated by the WebEx server. In order to validate the signature, the WebEx configuration must import the correct signing certificate (available from the NIDP-signing keystore on Access Manager). In figure 1, you will see the site certificate manager link in the upper left. Select that and import the Identity Server signing certificate.
Configuring Novell Access Manager 3.1 to integrate with Cisco WebEx
Establish trust relationship between Novell Access Manager SAML2 Identity Server and the Cisco WebEx SAML2 Service Provider.
At the Novell Access Manager Admin Console, select the IDP configuration and go to the SAML2 TAB. Under Trusted provider, create a new SAML2 Service Provider. At the prompt, give this new SAML2 SP a logical name (WebEx below) and point to the WebEx SAML2 metadata that was exported from the WebEx SSO configuration page defined in figure 1.
NOTE: When exporting the metadata from WebEx and importing it into Access Manager, the certificate validation process would fail. Although the certificate is only required when Authentication requests from the WebEx SP are signed (and they were not), the exported metadata did not contain the proper certificate. Instead of including the server certificate in the metadata, the certificate referenced was the trusted root certificate.
To overcome the issue, and allow to future authentication requests to be signed, we modified the exported metadata to include the server certificate instead of the trusted root. We then exported the server certificates trusted root and imported into it into the NIDP truststore on Access Manager.
After importing the metadata successfully, make sure the Service provider is displayed as shown below in Figure 2.
Click to view.
Figure 2: WebEx SAML2 SP created on Novell Access Manager Administration Console
- Configure the Identity Server to send required response to the WebEx SP
The WebEx SP requires the NameIdentifier format to be unspecified, and that it include as a value the username. In order to be able to send the username in the NameIdentifier header, one must define an attribute set with that username first.
By selecting the Identity Servers -> Shared Settings field in the Administration Console, one can create a new attribute set (called WebEx below in Figure 3) and include a list of attributes that may need to be sent to the WebEx SP from the IDP server. In our example, we included 4 LDAP attributes (cn, mail, givenName and sn) as examples. The only requirements are that the cn and mail be sent.
Click to view.
Figure 3: Attribute set configuration with attributes required by SP
Once the Attribute Set is defined and applied to the IDP server, the SAML configuration can leverage any of these attributes to send them with the assertion. By selecting the WebEx SAML2 SP configuration in the Admin Console again, the Administrator can go to the Attributes TAB and select the newly created WebEx attribute set from the drop down menu as shown in Figure 4. The LDAP attributes should be mapped to remote attribute names expected by WebEx SAML SP (uid, firstname, lastname and email in our example below).
Click to view.
Figure 4: Mapping Local Attributes to Remote Attributes.
By moving these attributes to the 'Send with Authentication' field (figure 5), the IDP will include an AttributeStatement for each of these attributes, along with their corresponding values.
Click to view.
Figure 5: Defining Attributes to send in Assertion.
More importantly, the Authentication response must be configured to send the 'unspecified' NameIdentifier format, with the authenticates users LDAP CN (requirement for WebEx SSO). In Figure 6 below, we make sure that the 'unspecified' NameIdentifier format is enabled, and that it is the default format used in the response. It's value must also be set to include the username of the user that will be used to SSO to the WebEx SP.
The binding used must always be set to POST. WebEx does not support the Artifact based binding.
Click to view.
Figure 6: Configuring the Authentication response attributes that will be sent from the IDP server to the WebEx SP
As an aside, it is possible to configure the IDP initiated SSO between the Novell Identity Server and the WebEx SP. The 'Intersite Transfer Service' configuration TAB can be used to define the SP ID and target URL as shown in Figure 7.
In this scenario, the users do not have to browse to the WebEx SP first and then select to authenticate at the Novell IDP server ... they can simply hit the base URL of the Novell IDP server with the following query, authenticate successfully at the IDP server and the user is redirected to the WebEx server where the SSO will take place: https://youridp.yourdomain.com/nidp/saml2/idpsend?id=WebEx
Click to view.
Figure 7: IDP initiated SSO setup using Intersite Transfer Service
The WebEx SP, based on the configuration in Figure 1, generates an Authentication request to the Novell IDP server with an authentication type of PasswordProtectedTransport.
The Novell Identity Server works with authentication contracts by default, and not authentication types. A mapping must be configured between the incoming authentication type (as shown in Figure 8), and the corresponding contract that must be executed to login the user. If no mapping exists, the default Authentication contract (also shown in Figure 8) is executed.
Selecting the IDP server configuration -> Local -> Defaults TAB, there is an option where the Administrator can map authentication types to contracts. The PasswordProtectedType (authentication over a secure channel) was mapped to the secure Name/Password Form contract, so that when the incoming Authentication request was processed, the IDP server simply executed the Secure Name/password form contract and presented the user with the login page. If the WebEx was configured for the Password type as opposed to PasswordProtecedTransport, we would map the password type to Name/Password form contract (authentication over an insecure channel) – although this is not recommended as credentials are passed in clear text.
Click to view.
Figure 8: Mapping Authentication types sent by SAML2 SP to authentication contracts understood by the Novell IDP server
Verifying SAML SSO between Novell Identity server and Cisco WebEx
The testing of the setup simply involves bringing up a browser and accessing your WebEx server, or application. Assuming that the setup is successful, the WebEx server should allow you to sign on via your newly created trust relationship with the Novell Identity server. In our example, the option to Sign in to Novell's Identity Server is done by clicking the 'Host Log In' button on the main WebEx page as shown in Figure 9.
Click to view.
Figure 9 – Signing in to WebEx via Novell Identity server
Selecting the option to login, the WebEx server will generate the SAML authentication request to the Novell IDP server with the appropriate settings. This request is sent via the browser to the single sign on URL defined on the WebEx server and is encoded. It also includes a RelayState parameter that includes the URL the user was trying to access initially. This user will eventually be redirected back to this RelayState URL after successful authentication.
Figure 10 - Authentication request sent by WebEx SP server to Novell IDP server
<samlp:AuthnRequest xmlns:samlp="urn:oasis:names:tc:SAML:2.0:protocol"ID="s2af73ec1bf438040c88f427ee82d9f1a43d55ae07" Version="2.0" IssueInstant="2011-08-18T15:33:23Z">
<samlp:NameIDPolicy xmlns:samlp="urn:oasis:names:tc:SAML:2.0:protocol" Format="urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified" AllowCreate="true"></samlp:NameIDPolicy></samlp:AuthnRequest<samlp:RequestedAuthnContext Comparison="exact"><saml:AuthnContextClassRef>urn:oasis:names:tc:SAML:2.0:ac:classes:PasswordProtectedTransport</saml:AuthnContextClassRef></samlp:RequestedAuthnContext></samlp:AuthnRequest>
Assuming that the Novell IDP server is capable of validating the source of this Authentication request (based on finding a matching trusted provider in it's SAML trusted provider configuration), the user will be prompted to login to the Novell Identity server (Figure 11). In our example, we have a simple non customized login page asking the user for name and password. This may be modified to ask for other credential details.
After the user submits the credentials, the Identity server will validate them against the back end user store. It will also retrieve the users LDAP CN based on the attribute set defined for our SAML Authentication response. Assuming the IDP server has all it needs, it will generate the SAML authentication response to the WebEx SP server and single sign on the user. The resulting page will display the authenticated user (pds2 in our case) as logged in on the WebEx main page as shown in Figure 12.
Click to view.
Figure 12 – Successful single sign on to WebEx showing the admin username
The SAML assertion sent to the WebEx SP Assertion Consumer service includes the following details:
<samlp:Response xmlns:samlp="urn:oasis:names:tc:SAML:2.0:protocol" xmlns:saml="urn:oasis:names:tc:SAML:2.0:assertion" Destination="https://yourcompany.webex.com/dispatcher/SAML2AuthService?siteurl=yourcompany" ID="idrdSMbMXUCGl2LrjAJtwVbWG08H0" IssueInstant="2011-08-18T15:34:06Z" Version="2.0">
<saml:Assertion ID="ideLWtTf2CmFXuNlbAlDtqFSgL-hE" IssueInstant="2011-08-18T15:34:06Z" Version="2.0"><saml:Issuer>https://youridp.yourdomain.com/nidp/saml2/metadata</saml:Issuer>
: Signature and certificate details
<saml:Subject><saml:NameID Format="urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified" NameQualifier="https://youridp.yourdomain.com/nidp/saml2/metadata" SPNameQualifier="https://yourcompany.webex.com">youraccount</saml:NameID>
<saml:SubjectConfirmation Method="urn:oasis:names:tc:SAML:2.0:cm:bearer"><saml:SubjectConfirmationData NotOnOrAfter="2011-08-18T16:34:06Z" Recipient="https://yourcompany.webex.com/dispatcher/SAML2AuthService?siteurl=yourcompany"/></saml:SubjectConfirmation>
<saml:Conditions NotBefore="2011-08-18T15:29:06Z" NotOnOrAfter="2011-08-18T15:39:06Z"><saml:AudienceRestriction><saml:Audience>https://yourcompany.webex.com</saml:Audience></saml:AudienceRestriction></saml:Conditions><saml:AuthnStatement AuthnInstant="2011-08-18T15:34:06Z" SessionIndex="ideLWtTf2CmFXuNlbAlDtqFSgL-hE"><saml:AuthnContext><saml:AuthnContextClassRef>urn:oasis:names:tc:SAML:2.0:ac:classes:PasswordProtectedTransport</saml:AuthnContextClassRef><saml:AuthnContextDeclRef>secure/name/password/uri</saml:AuthnContextDeclRef></saml:AuthnContext></saml:AuthnStatement><saml:AttributeStatement><saml:Attribute xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" Name="uid" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:unspecified"><saml:AttributeValue xsi:type="xsd:string">**</saml:AttributeValue></saml:Attribute><saml:Attribute xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" Name="email" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:unspecified"><saml:AttributeValue xsi:type="xsd:string">**</saml:AttributeValue></saml:Attribute><saml:Attribute xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" Name="lastname" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:unspecified"><saml:AttributeValue xsi:type="xsd:string">**</saml:AttributeValue></saml:Attribute><saml:Attribute xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" Name="firstname" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:unspecified"><saml:AttributeValue xsi:type="xsd:string">**</saml:AttributeValue></saml:Attribute></saml:AttributeStatement></saml:Assertion></samlp:Response>
Under the Subject header, we can see the NameID tag with the value of the authenticated users LDAP CN (yourname in our example). This is what the WebEx server will retrieve to authenticate the user. The additional attributes are used by the WebEx SP should the user not already exist and user provisioning is enabled.
Should any part of the above setup fail and require debugging, the troubleshooting process outlined in Troubleshooting SAML assertion issues can be followed. Although it is for a different setup, the process is identical and will help pinpoint the problem area.