Single sign-on with SAML - SysAdmin

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

For more information, see the anchor [LINK:prepare]

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

Remarks:

(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

For more information, see this Oracle

. Install the extension on your server in the /Java/JavaVirtualMachines//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:

For more information, see this Simple SAML tutorial for web developers

For more information, see this Glossary for the OASIS Security Assertion Markup Standard (SAML) version 2.0

Plan a SAML project

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

Which authentication methods are you planning to use?

censhare can be setup 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

  For more information, see the anchor [LINK:party_mapping]

  section).

  
  

What do we need from the customer?

To setup SAML SSO, the customer must provide the following:

• The federation metadata XML.

• Acceptance for self-signed certificates for the SAML token exchange (see

  For more information, see the anchor [LINK:certificates]

  section).

  
  

  User mapping policies for new users (see

  For more information, see the anchor [LINK: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).

  
  

Setup - key steps

1. 
   

   For more information, see the anchor [LINK:servlet]

   
   

2. 
   

   For more information, see the anchor [LINK:certificates]

   
   

3. 
   

   For more information, see the anchor [LINK:party_mapping]

   
   

4. 
   

   For more information, see the anchor [LINK:logout]

   
   

5. 
   

   For more information, see the anchor [LINK:system_asset]

   
   

Client delivery service configuration

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

Remarks:

(1) Add a 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

For more information see this article [LINK:2904624]

.

(2) In each node, add and configure an 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.

Certificates

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

1. The

   For more information, see the anchor [LINK:saml-sp]

    identifies the censhare Server as a service provider.

   
   

2. The

   For more information, see the anchor [LINK:saml-idp]

    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. The file contains XML metadata with the censhare specific URLs and the X.509 certificate. See the following example:

                                                                              MIIDcTCCAlmgAwIBAgIEYoOwOTANBgkqhkiG9w0BAQsFADBpMQswCQYDVQQGEwJD                           SDEPMA0GA1UECBMGWnVyaWNoMQ8wDQYDVQQHEwZadXJpY2gxETAPBgNVBAoTCGNl                             bnNoYXJlMREwDwYDVQQLEwhjZW5zaGFyZTESMBAGA1UEAxMJQXhlbCBSb3NlMB4X                       DTE3MDMyMzA5MzYzMloXDTI3MDMyMTA5MzYzMlowaTELMAkGA1UEBhMCQ0gxDzAN                      BgNVBAgTBlp1cmljaDEPMA0GA1UEBxMGWnVyaWNoMREwDwYDVQQKEwhjZW5zaGFy                      ZTERMA8GA1UECxMIY2Vuc2hhcmUxEjAQBgNVBAMTCUF4ZWwgUm9zZTCCASIwDQYJ                      KoZIhvcNAQEBBQADggEPADCCAQoCggEBAIh1dXPZ8vXLEI36/IFWe9OI589lm24i                      +Pon1Ld0oFhTERwDxO9D4j0aq4kg6MChrj88vqVmBidm5WiOtRK24O3YrDM/2rBS                      nuK4+q/E1s1GNZQoxHziJDbAbBLLlCxCYfyHb+qS1y6PfahQ/0QcQi7O4NF4tWC9                      75dAmgXP5jnBrS0RglccSKVc3yC/7UfoREFvH2bV2Igmh8X82yTM79C27pHQXU9E                      X8MRiOHuzyBL4/l254un4KAXf5YmYGnS9H3t7OM3s9BLDqWmtWeAhn9+RnnfWUcU                      ift677vzPAxCVUVxwx+OLgPse7kfGj44FBsw54Ek/qwB20e/1+uPtq0CAwEAAaMh                      MB8wHQYDVR0OBBYEFC17V/a+tueVie3Dmm0NqiL9xmSyMA0GCSqGSIb3DQEBCwUA                      A4IBAQAExKlZnSO1iwxrajqV6Qzxg5kdm5fc/+Sz78HBJ1rCzdfRwsAQnqsx8mrP                      obKBoG6RtuEf0FqCStib8xwq6smSvtudqkrGAuY5chjN0L19pw8FM69Uk3t+GxWZ                      lJ04N3NLH/SinPfeXtL27tva0VcTLxYGYOyjcErLwIh5VnST/SpbOL4UTZTUHul2                      plrO3LMV582msyiFVo1s01Ec0v8il2aUuDpHPQBgHRt03qfdd5skrQNu0m6Xngcn                      OKlOTGzd6W6PA9cYf/LKNhA0vD5wZI9jT3oG6fnX0saISuokcF85QODT4W2qCDBY                      kmE7NsILVfimN+IU8f/HS9yw9D35                                                            

Remarks:

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

For more information, see the anchor [LINK:servlet]

and must not contain the /SAML2/POST extension.

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

Generate the X.509 certificate

To generate the certificate to place in the node, 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

3. Convert to PKCS12:

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

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

5. Verify the result:

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

6. Generate the X.509 certificate:

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

7. Copy the certificate and paste it in the metadata XML file.

8. Copy the keystore file to the censhare server:

   $ 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

Note: To use SAML without additional LDAP mapping, the saml-ldap-mapping attribute in the

For more information, see the anchor [LINK:servlet]

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:

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

Note: To use SAML with additional LDAP mapping, the saml-ldap-mapping attribute in the

For more information, see the anchor [LINK:servlet]

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

  For more information, see the anchor [LINK:without_LDAP]

  .

  
  

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:

     http://sso-test.censhare.com/adfs/services/trust                            [USER_EMAIL]                 ... 

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

For more information, see the anchor [LINK:servlet]

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

   For more information, see the anchor [LINK:alternative_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).

Note: 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.

Tip: 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.