Single sign-on with SAML

Context

The user identity in organizational networks is managed by an identity provider. censhare acts as a service provider (SP) in the federation of the identity provider. The censhare-OnlineChannel is considered a service provider of its own and can be included in the federation.

Prerequisites

To set up SAML SSO for censhare in a cross-domain environment requires proper planning. Plan for the project and IT resources at censhare and the customer, and make sure that you can access the customer network. For more information, read the Plan a SAML project section carefully!

Introduction

To authenticate users who want to login to the censhare platform, SAML SSO is required if users access censhare across security domains. For example, in distributed organizations or in projects with internal and external users. censhare works as a service provider in the SAML setup. If you use an Online channel with your censhare platform, it works as a separate service provider.

Service providers and the identity provider form a so-called federation that uses the same resources to authenticate and identify users and applications. The following diagram shows a simplified flow of information between principals (users) and providers (service and identity provider):

SAML specifications with censhare

Understanding SAML

The following documentation gives you an introduction to the SAML standard and the terminology that is also used in this article. Please read before you start a SAML project:

Simple SAML tutorial for web developers

Glossary for the OASIS Security Assertion Markup Standard (SAML) version 2.0  (PDF)

Plan a SAML project

The following checklist helps you to set up a SAML project with a customer and plan for the necessary resources.

Which authentication methods are you planning to use?

censhare can be set up with SAML or Kerberos/LDAP as established SSO authentication methods. Both can be used in parallel. SAML is the only method that works across domains in the browser-based censhare Web client. OpenID is currently not supported.

Before starting the setup, check with and communicate to the customer:

• Which parallel authentication methods are required?

• As a fallback, the standard authentication method must always be enabled. This method uses the credentials stored in the censhare database and is not an SSO authentication.

• The desired authentication method is selected by adding the authentication parameter ?auth=[method] to the login URL. For example, the dedicated SAML login URL is: https://customer.censhare.com/?auth=saml.

Which resources are required for the setup?

For the SAML setup, plan with the following resources:

• A censhare development account in the customer domain. If the security policies of the customer do not allow for this, the customer must appoint a proxy person with the respective permissions.

• IT staff resources to carry out the necessary configurations.

• XSLT developer at censhare to carry out the user mapping see the Party_mapping

  section.

What do we need from the customer?

To set up SAML SSO, the customer must provide the following:

• The federation metadata XML.

• Acceptance for self-signed certificates for the SAML token exchange (see  Certificates  section).

  User mapping policies for new users (see  Party mapping  section). If new users can be created on the fly, a mapping policy is required that assigns a default role and domain to new censhare users. Roles and domains are retrieved from SAML attributes (so-called  claims).

Client delivery service configuration

The Client delivery service configuration is responsible for SSO to the censhare Server. 

The service configuration is stored in the file censhare-Server/app/services/clientdelivery/config.xml:

<client id="client">
 <sso saml-url-0="[IDENTITY_PROVIDER_URL]/adfs/ls"           
      saml-url-1="[CENSHARE_BASE_URL]/censhare5/client/SAML2/POST"
      saml-url-2="[CENSHARE_BASE_URL]/adfs/ls"
      saml-url-3="[CENSHARE_BASE_URL]/censhare5/client"
      saml-signature-method="http://www.w3.org/2001/04/xmldsig-more#rsa-sha256"
      saml-auth-request-method="POST"
      saml-sp-keystore-password="[PASSWORD]"
      saml-sp-keystore-entry="[HOSTNAME]"
      saml-sp-keystore-entry-password="[PASSWORD]"
      saml-sp-keystore-file="saml-sp-sign.jks"
      saml-idp-crt-file="saml-idp.crt"
      saml-allow-new-users="true"
      saml-ldap-mapping="false"
      kerberos-logout-url="[CENSHARE_BASE_URL]/logout" />
</client>

Create certificates

The SAML SSO requires two certificate files. The certificates files must be exchanged beforehand between the service provider (censhare) and the identity provider:

• The saml-sp-sign.jks identifies the censhare Server as a service provider.
• The saml-idp.crt stores the X.509 certificate of the identity provider.

Create the saml-sp-sign.jks

The saml-sp-sign.jks certificate file identifies the censhare server at the identity provider. This file must be stored at the Identity provider. Additionally, a metadata.xml file is required that stores the certificate and the Id of the entity at the identity provider.

Proceed as follows:

1. On the censhare server, open a terminal window.

2. Enter the required properties: 

   openssl req -x509 -newkey rsa:2048
     -keyout customer-private-key.pem
     -out customer-cert.pem
     -days 3650 -nodes

   BASH

3. Convert to PKCS12: 

   openssl pkcs12 -export -name www.customer.com
     -in customer-cert.pem
     -inkey customer-private-key.pem
     -out keystore.p12

   BASH

4. Enter a password and confirm: 

   keytool -importkeystore
     -destkeystore customer-cert.jks
     -srckeystore keystore.p12
     -srcstoretype pkcs12
     -alias www.customer.com

   BASH

5. Verify the result: 

   keytool -list -v -J-Duser.language=en
     -keystore customer-cert.jks

   BASH

6. Generate the X.509 certificate: 

   cat customer-cert.pem 
   -----BEGIN CERTIFICATE----- 
   MIIDcTCCAlmgAwIBAgIEYoOwOTANBgkqhkiG9w0BAQsFADBpMQswCQYDVQQGEwJD 
   ... 
   kmE7NsILVfimN+IU8f/HS9yw9D35 
   -----END CERTIFICATE-----

   BASH
   

   Copy the certificate to your clipboard. You need it to configure the metdata.xml in the following step.

7. Create a metadata.xml file. This file must be stored at the identity provider. Open the file and enter the configuration as follows:

   <md:EntityDescriptor xmlns:md="urn:oasis:names:tc:SAML:2.0:metadata" 
                        entityID="[CENSHARE_BASE_URL]">   
    <md:SPSSODescriptor protocolSupportEnumeration="urn:oasis:names:tc:SAML:2.0:protocol 
                        urn:oasis:names:tc:SAML:1.1:protocol 
                        urn:oasis:names:tc:SAML:1.0:protocol">     
     <md:KeyDescriptor>       
      <ds:KeyInfo xmlns:ds="http://www.w3.org/2000/09/xmldsig#">         
       <ds:X509Data>           
        <ds:X509Certificate>               
         MIIDcTCCAlmgAwIBAgIEYoOwOTANBgkqhkiG9w0BAQsFADBpMQswCQYDVQQGEwJD                    
         ...               
         kmE7NsILVfimN+IU8f/HS9yw9D35           
       </ds:X509Certificate>         
      </ds:X509Data>       
     </ds:KeyInfo>     
    </md:KeyDescriptor>     
    <md:AssertionConsumerService 
         Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST" 
         Location="[CENSHARE_BASE_URL]/SAML2/POST" 
         index="1"/>   
    </md:SPSSODescriptor> 
   </md:EntityDescriptor>

   CODE
   Notes:

   (1)  Replace the [CENSHARE_BASE_URL] part in the attributes md:EntityDescriptor@entityID  and  md:AssertionConsumerService@Location with the URL of your censhare server, for example, https://your-company.com/censhare5/client.

   (2) Paste the X.509 certificate in the <ds:X509Certificate/> node.

   (3)  The URL in the md:AssertionConsumerService@Location attribute is used for HTTP-POST binding. The identity provider sends its authentication reply to this endpoint. In ADFS implementations, the path must be identical to the URL configured in the saml-url-3 attribute of the client delivery service configuration and must not contain the /SAML2/POST extension.

   (4)  censhare accepts all paths for POST. However, the path should be identical in the manual metadata export and clientdelivery service configuration.

8. Copy the keystore file to the censhare server: 

   cp customer-cert.jks censhare-Server/app/config/saml-sp-sign.jks

   BASH

Alternatively, you can use the KeyStore Explorer to generate the certificate.

Create the saml-idp.crt

To create the saml-idp.crt file, copy the X.509 certificate (the content of the  node) from XML metadata file you receive from the identity provider to the censhare-Server/app/config/saml-idp.crt file.

Party mapping

To identify a censhare user who tries to authenticate with a SAML request, a party mapping is required. The mapping is stored in censhare in a Transformation asset.

Without additional LDAP mapping

To use SAML without additional LDAP mapping, the saml-ldap-mapping attribute in the  Client delivery service  must be set to "false".

Create an Transformation asset with the resource key censhare:saml-sso-party-mapping. The XSLT file of this asset stores the user information in the node:

<xsl:stylesheet version="2.0"
                xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
                xmlns:xs="http://www.w3.org/2001/XMLSchema"
                xmlns:saml="urn:oasis:names:tc:SAML:2.0:assertion"
                exclude-result-prefixes="#all" >
<xsl:output indent="yes" omit-xml-declaration="yes"/>

 <xsl:template match="saml:Assertion">
  <!--<xsl:message><DEBUG><xsl:copy-of select="/"/></DEBUG></xsl:message>-->
  <root>
    <xsl:apply-templates/>
  </root>

<xsl:template match="saml:AttributeStatement">
  <xsl:apply-templates select="saml:Attribute"/>
</xsl:template>

<xsl:template match="saml:Attribute">
  <xsl:choose>
    <xsl:when test='@Name = "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress"'>
     <party isgroup="0"
            isactive="1"
            isvisible="1"
            issystem="0"
            auth_extern="1"
            auth_standard="0"
            sync_extern="0"
            main_role="userrole"
            main_domain="root."
            main_domain2="root.">
        <xsl:attribute name="login" select="saml:AttributeValue/text()"/>
        <xsl:attribute name="name" select="saml:AttributeValue/text()"/>
        <xsl:attribute name="display_name" select="saml:AttributeValue/text()"/>
        <xsl:attribute name="email" select="saml:AttributeValue/text()"/>
        <xsl:attribute name="expiry_date" select="xs:dateTime(current-dateTime()) + xs:dayTimeDuration('P30D')"/>
        <party_role role="userrole"
                 domain="root."
                 domain2="root."
                 enabled="1"/>
      </party>
    </xsl:when>
  </xsl:choose>
</xsl:template>

<xsl:template match="text()"></xsl:template>

</xsl:stylesheet>

With additional LDAP mapping

To use SAML with additional LDAP mapping, the saml-ldap-mapping attribute in the  Client delivery service  must be set to "true".

Create two Transformation assets with the following resource keys:

• censhare:saml-ldap-search-mapping - this asset queries the LDAP server.

• censhare:saml-ldap-party-mapping - this asset maps the query result to the party master data, similar to the party mapping  without additional LDAP mapping.

For more information about the XSLT resources, please contact the censhare support.

Result

When an authentication is requested or granted, the assertion XML contains the email attribute from the mapping. For example:

<Assertion xmlns="urn:oasis:names:tc:SAML:2.0:assertion">   
 <Issuer>http://sso-test.censhare.com/adfs/services/trust</Issuer>     
  <AttributeStatement>     
   <Attribute Name="SAML_EMAIL">      
    <AttributeValue>[USER_EMAIL]</AttributeValue>     
   </Attribute>
  </AttributeStatement>    
...
</Assertion>

Logout

To log out a user, a signed logout request is sent with  GET  ( HTTP-302 redirect)  to the logout URL configured in the  saml-url-2  attribute in the  client delivery service configuration.

To keep the current SSO session alive, use a censhare logout URL. For example:

https://[CENSHARE_BASE_URL]/logout

To invalidate the current SSO session on logout, use a signout URL for the identity provider. For example, for ADFS:

https://[IDENTITY_PROVIDER_URL]/adfs/ls/?wa=wsignout1.0

System asset configuration

In the System asset, edit the system properties. In the Authentication area select the desired methods: and restart the server. select SAML and Standard.

1. For SAML SSO, select SAML.

2. Always select Standard as fallback and technical support login method (see  Login with alternative login method  section below).

   
   

3. If an alternative authentication method is required, select the respective entry from the list. SAML SSO can be combined with Kerberos, Online channel or Custom methods. Kerberos is a SSO method for single-domain environments. Online channel signs on users to both censhare applications (censhare platform and censhare Online channel). The Custom method uses LDAP (without SSO).

The methods External (via Servlet) and HTTP Basic are deprecated. Do not use them anymore!

Login with alternative login method

With an alternative authentication method, users can bypass the SAML authentication and use alternative authentication for censhare Web by accessing the login URL with the authentication parameter:

https://localhost.censhare.com:9443/censhare5/client/?auth=[kerberos|standard]

The URL parameter ?auth=standard sets the CENSHARE_SAML_STANDARD_LOGIN cookie and redirects the user to the censhare login page. To switch back to the SAML SSO, users must delete the cookie manually from their browser.

We recommend to use the standard authentication for technical support. To do this, add the respective users (generic or individual) in the censhare Admin Client and assign the necessary roles and permissions. Ensure that the technical support users access the root domain.

Result

Login requests from users are redirected to the identity provider via SAML, users are authenticated and logged in via SAML SSO to censhare.