This article describes how to set up, develop and test SAML-SSO authentication with the legacy tech stack for developers and QA.
Introduction
The development setup uses an ADFS as Identity Provider (IdP). You can use the existing QA installation for your purposes, or setup a local instance.
Personal account registration
User accounts and service configuration are maintained by development department only. Please ask one of the admins Axel Rose or Sergii Sinelnychenko to register accounts for you. The username is always in the subdomain dev.censhare.com and must be fully specified on login.
Use existing QA installation
Use this URL to force censhare Web to use SAML authentication: https://qa-dev.censhare.com:9443/censhare5/client/?auth=saml
Use this URL for the IdP-initiated login: https://de-nue-dev-dc.dev.censhare.com/adfs/ls/idpinitiatedsignon/
The username is qa@dev.censhare.com, the password is stored in Team Password Manager.
The configuration is stored in gitlab repo.
Setup local development instance
Step 1 - Get remote certificate
To get the certificate, download the XML metadata file from the IdP with the following command:
curl -k https://de-nue-dev-dc.dev.censhare.com/federationmetadata/2007-06/federationmetadata.xml -o metadata.xml
Open the downloaded XML and extract the X.509 certificate from it. Use the XPath expression /EntityDescriptor/ds:Signature/KeyInfo/X509Data/X509Certificate to get the value of the respective node.
Save the result to censhare-Custom/censhare-Server/app/config/samp-idp.crt. You can compare it with existing values for qa-dev at https://git.censhare.com/ar/saml-customer-configs/-/blob/master/qa-dev/target/config/saml-idp.crt).
Step 2 - Create local certificate
For convenience, the steps are combined into a reusable Shell script. To create the local certificate, download and run the script locally on your server.
As a result, you get a Java Keystore file saml-sp-sign.js. Install this file into the censhare-Custom/censhare-Server/app/config/ directory.
Step 3 - Configure server
The default values from censhare-Server/app/services/clientdelivery/config.xml work out of the box for most cases. Just make sure the attribute saml-url-0 points to our development test IdP https://de-nue-dev-dc.dev.censhare.com/adfs/ls.
All values are documented in this article. For further configuration options, see the Configuration options section below.
The mapping from SAML users to a censhare party requires a mapping XSLT. The mapping is stored in an asset. Proceed as follows:
- Create the asset manually with the resource key
censhare+saml-sso-party-mapping.xsl. - Copy the XSLT file, or use qa-dev example as reference from https://git.censhare.com/ar/saml-customer-configs/-/blob/master/qa-dev/target/mapping/censhare+saml-sso-party-mapping.xsl.
Step 4 - Register at IdP
To register at the IdP, you need privileged access. This is not open to non-admin users. Ask one of the admins Axel Rose or Sergii Sinelnychenko for assistance.
You are required to supply a metadata.xml file. Please use this XML file as template and fill it with the certificate produced in localhost-cert.pem in step 2.
Configuration options
- Encryption - will be enabled on IdP side
- Allow creation of new users - in
clientdelivery/config.xml - Sync modus of party attributes - setup in Admin-Client/Masterdata/Party
IdP Access
This is implementated is via ADFS at de-nue-dev-dc.censhare.com. You can access the IdP from your computer via the Microsoft Remote Access.app. The credentials are stored at Team Password Manager.
Troubleshooting
General hints
- Check network traffic from your browser console, debugging of SAML traffic is easyly done with Chrome browser plugins. For example: SAML Chrome Panel.
- Good example data and tools are available online at samltool site.
- Use the following command line tool to check validity of certificates:
openssl s_client -showcerts -connect de-nue-dev-dc.dev.censhare.com:443
Last Updated: 9th of March 2020