Skip to main content
Skip table of contents

Single sign-on with SAML - SysAdmin

The SAML protocol is a standard authentication method to authenticate users across security domains. In SAML environments, the censhare Server and the Online channel are added as service providers and authenticate users through an identity provider.

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


Version

SAML 2.0

Implementation


For more information, see this Shibboleth library / OpenSAML 3


Authentication request

GET (HTTP 302) or POST

Service provider initiated SSO

supported

Identity provider initiated SSO

supported (1)

Encryption

  • incoming assertions decrypted automatically (2)
  • outgoing encryption requests currently not used

Artifact resolution

not supported

Alternative authentication methods
(SAML / standard)

supported (see Login with alternative method )


Maximum time difference between
censhare Server and Identity Provider

20 seconds (3)

Notes:

(1)  Requires the same configuration as for SP initiated SSO. No additional setup required on censhare side otherwise. May require additional configuration of the identity provider.

(2)  For encrypted responses from the identity provider, the JVM extension Unlimited Strength Java(TM) Cryptography Extension Policy Files is required. You can download the extension from  Oracle. Install the extension on your server in the  /Java/JavaVirtualMachines/<jdk-version>/Contents/Home/jre/lib/security/  directory.

(3)  Cannot be changed. This is due to security reasons, to avoid that an older attack is repeated.

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:

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>

Notes:

(1)  Add a  <client/>  node for each branding URL. The  id  attribute value refers to the last part of the URL part. For example, use "client" for the default URL "censhare5/client". For more information, see  Branding.

(2)  In each  <client/>  node, add and configure an  <sso/>  element. For more information, see the table below.

(3)  When you use  auth-request-method=POST, the HTML form that is transmitted is visible for a very short moment. The content of the form is rendered in the Velocity template  app/services/clientdelivery/saml-post.vm. The Velocity template is derived from the OpenSAML default template, which is based on the auto-submit form of the browser. You can customize this template if necessary.


Attribute

Description

saml-url-0

The URL of the identity provider.

saml-url-1

The entry point for the SAML response. This must match the Location value in the provided metadata specifications. The default path is SAML2/POST

saml-url-2

The logout URL of the identity provider.

saml-url-3

The URL of the service provider (i.e. the URL to access censhare) as specified in the provided metadata.

saml-signature-method

Default: http://www.w3.org/2001/04/xmldsig-more#rsa-sha256

auth-request-method

The HTTP method to send the SAML authentication request to the identity provider. Default: GET(HTTP-302 redirect), if required, set to POST.

saml-sp-keystore-password

Password to open the service provider certificate file configured in the saml-sp-keystore-file attribute.

saml-sp-keystore-entry

The entry id of the saml-sp-keystore-file.

saml-sp-keystore-entry-password

The password for the saml-sp-keystore-entry.

saml-sp-keystore-file

The name of the certificate file of the censhare Server as a service provider in the censhare-Server/app/config/ directory.

saml-idp-crt-file

The name of the certificate file of the identity provider in the censhare-Server/app/config/ directory.

saml-allow-new-users

Allows the creation of new SAML users. Default: true.

saml-ldap-mapping

If "true", SAML assertions are mapped to an LDAP resource. To use an LDAP resource, the  Party mapping  must be configured accordingly. Default is "false".

kerberos-logout-url

Default: https://localhost.censhare.com:9443/logout

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:

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: 

    BASH
    openssl req -x509 -newkey rsa:2048
      -keyout customer-private-key.pem
      -out customer-cert.pem
      -days 3650 -nodes
  3. Convert to PKCS12: 

    BASH
    openssl pkcs12 -export -name www.customer.com
      -in customer-cert.pem
      -inkey customer-private-key.pem
      -out keystore.p12
  4. Enter a password and confirm: 

    BASH
    keytool -importkeystore
      -destkeystore customer-cert.jks
      -srckeystore keystore.p12
      -srcstoretype pkcs12
      -alias www.customer.com
  5. Verify the result: 

    BASH
    keytool -list -v -J-Duser.language=en
      -keystore customer-cert.jks
  6. Generate the X.509 certificate: 

    BASH
    cat customer-cert.pem 
    -----BEGIN CERTIFICATE----- 
    MIIDcTCCAlmgAwIBAgIEYoOwOTANBgkqhkiG9w0BAQsFADBpMQswCQYDVQQGEwJD 
    ... 
    kmE7NsILVfimN+IU8f/HS9yw9D35 
    -----END CERTIFICATE-----
  7. Copy the certificate.

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

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

    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.

  9. Copy the keystore file to the censhare server: 

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

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:

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


Notes:

(1) Input is processed like a master data import. To test your setup, you can export/import user data in the Master data/Users table.

(2) If you use censhare 2019.2.5, censhare 2019.3.2, censhare 2020.1 or any higher version, the synchronization of party attributes and roles is specified in the sync_extern attribute. If set to "0", nothing is synchronized. If set to "1", only attributes are synchronized. If set to "2", attributes and roles are synchronized. If you upgrade from older versions and want to keep roles that were configured manually, you must set sync_extern=0 or sync_extern=1. Otherwise, the manually configured r

(3) Existing users are authenticated with the party@login attribute. No new user with the same login is created nor updated.

(4) The party@main_role and party/party_role@role attributes must be identical.

(5) The party@main_domain and party/party_role@domain attributes must be identical.

(6) The party@main_ domain2 and the party/party_role@domain2 attributes must be identical.

(7) The party@sync_extern attribute is irrelevant. There is no syncing back to the identity provider.

(8) The party@parent_partyrel attribute synchronization is currently not implemented. Therefore, group attributes cannot be synchronized.

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:

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

Notes:

(1) The ADFS query parameter requires at least censhare 2019.2.5, censhare 2019.3.2, censhare 2020.1 or any higher version.

(2) Currently, POST  cannot be used for logout. In ADFS systems, you must add an additional logout endpoint manually.

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.

JavaScript errors detected

Please note, these errors can depend on your browser setup.

If this problem persists, please contact our support.