ADFS Setup (SAML Authentication) Version 1.6 Corresponding Software Version Celonis 4.3 This document is copyright of the Celonis SE. Distribution or reproduction are only permitted by written approval of the Celonis SE. Usage only permitted, if a valid software license is available.
TABLE OF CONTENTS REVISION HISTORY... 3 INTRODUCTION... 4 ABOUT THIS GUIDE... 4 TARGET AUDIENCE... 4 LIST OF ABBREVIATIONS... 5 SETUP CONFIGURATION FILE VALUES... 6 SETUP YOUR CERTIFICATES... 8 RETRIEVE SAML META DATA FROM YOUR IDENTITY PROVIDER... 9 GENERATE SAML META DATA FROM THE CELONIS SERVER... 9 REGISTER THE CELONIS SERVICE AS A RELIABLE PARTY IN YOUR ADFS... 10 CONFIGURE ADDITIONAL USER ACCOUNT PARAMETERS... 13 TROUBLESHOOTING... 17 REFERENCES... 18 2018 Celonis SE ADFS SETUP (SAML AUTHENTICATION) 2
REVISION HISTORY VERSION NUMBER VERSION DATE SUMMARY OF REVISIONS MADE 1.0 JUN 01, 2016 Initial version 1.01 NOV 20, 2017 Updated metadata URL to retrieve SAML meta data file 1.02 NOV 30, 2017 Add Troubleshooting section, Update layout 1.6 JAN 31, 2018 Update to Celonis 4.3 2018 Celonis SE ADFS SETUP (SAML AUTHENTICATION) 3
INTRODUCTION ABOUT THIS GUIDE Celonis is a powerful software for retrieving, visualizing and analyzing real as-is business processes from transactional data based on event information. It provides users with the possibility to create and share comprehensive process analyses giving them full transparency about the business processes at hand. This guide describes the Active Directory Federation Service (ADFS) setup utilizing SAML to provide users with a Single Sign-On (SSO) access to Celonis. If you set up ADFS from scratch, make sure to install ADFS Version 2.0, as older ADFS Versions do not yet have SAML support built in. Please check REFERENCES for further details on the ADFS deployment. TARGET AUDIENCE This guide is meant to be consulted by the following target audiences: System Administrators Technical Staff 2018 Celonis SE ADFS SETUP (SAML AUTHENTICATION) 4
LIST OF ABBREVIATIONS ABBREVIATION AD ADFS HTTPS JKS SAML SSO EXPLANATION Active Directory Active Directory Federation Service Hypertext Transfer Protocol Secure Java Key Store Security Assertion Markup Language Single Sign-On 2018 Celonis SE ADFS SETUP (SAML AUTHENTICATION) 5
SETUP CONFIGURATION FILE VALUES Setup SAML for Celonis by adding the following lines to the config-custom.properties file, which is located in the Celonis installation directory. The following configuration options are available when using SAML with Celonis (see Table 1): # SAML Configuration # ------------------ # To enable SAML based authentication, set active to true saml.active=true # The SAML claim attribute which contains a list of groups of the authenticated user saml.claims.groups=http://schemas.xmlsoap.org/claims/group # The SAML claim attribute which contains the first name of the user saml.claims.firstname=http://schemas.xmlsoap.org/ws/2005/05/identity/claims/give nname # The SAML claim attribute which contains the last name of the user saml.claims.lastname=http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surna me # The SAML claim attribute which contains the email address of the user saml.claims.emailaddress=http://schemas.xmlsoap.org/ws/2005/05/identity/claims/e mailaddress # Set to true to automatically create all groups the user is mapped to saml.groups.autocreate=false # Set to true to automatically assign all groups the user is mapped to. # When using autocreate, this is automatically set to true saml.groups.autoassign=false # Set to true to automatically create users when they log in saml.users.autocreate=false # Enter a group name which is required for users to be able to log in (and be created). # Note that all group names are Case Sensitive saml.users.requiredgroup=testgroup # Key store settings for SAML saml.keystore.path=e:/work/saml-example/samlkeystore.jks saml.keystore.password=<somepw> # The name of the key in the keystore to be used for encryption and signing saml.keystore.keyname=<somekey> saml.keystore.keypassword=<somepw> # SAML Entity configuration saml.entityid=de:celonis:pm:samldemo 2018 Celonis SE ADFS SETUP (SAML AUTHENTICATION) 6
# SAML Metadata Configuration. Right now, Celonis only supports static metadata configuration. saml.metadatapath=e:/work/saml-example/federationmetadata.xml # If saml is running behind a proxy, activate the following setting: saml.url.proxied=false # and set the following settings accordingly # one of http or https saml.url.scheme=https # the name of the saml server public address saml.url.servername=<celonis-url> # the port of the saml server public address saml.url.serverport=443 # the URL of the server server.url=https://<celonis-url>:443 Table 1: SAML configuration parameters in the config-custom.properties file. The options which are mandatory and should be customized in any case are the key store attributes, the meta data path, the entity ID, the server name, the server port and the server URL. The entity ID is used to identify the Celonis Service to the ADFS Server. The federation meta data file can be retrieved from your ADFS Server and describes the service endpoint (containing the certificates used for encryption and signature). Please note, that Celonis only supports local meta data, no HTTP based meta data retrieval is implemented. The given SAML entity ID is only a sample ID. We recommend choosing a SAML entity ID according to your cooperation guidelines. 2018 Celonis SE ADFS SETUP (SAML AUTHENTICATION) 7
SETUP YOUR CERTIFICATES Please note, it is highly recommended to use the supplied keytool located in <installdir>/jre/bin/keytool. When using SAML, you need to generate certificate for your server. This certificate can either come from your enterprise certification authority, or, for testing, you can use a self-signed certificate. Please note, that this certificate is used to establish the mutual trust between your ADFS and the Celonis application server. It is different from the certificate used for HTTPS. For the application to be able to access these certificates, both the private key and the public key must be available in a Java Key Store (JKS). To generate a self-signed certificate, use the following command to create an RSA key (see Table 2): keytool -genkeypair -alias somekey -keyalg RSA -keysize 2048 -keypass somepw -keystore samlkeystore.jks Table 2: Generate a self-signed certificate using keytool. To import an existing certificate provided by a certification authority (e.g. in PFX format) use the following command (see Table 3): keytool -importkeystore -srckeystore key.p12 -srcstoretype PKCS12 -srcstorepass password -alias somekey -destkeystore samlkeystore.jks -destalias somekey -destkeypass somepw Table 3: Import an existing certificate using keytool. The values printed in BOLD have to be updated in the config-custom.properties file. The keytool command must be executed with sufficient access rights to write the resulting keystore file (e.g. administrative privileges). For further details on the keytool commands please see REFERENCES. Figure 1 illustrates a sample output of the keytool usage as presented in this guide. Figure 1: Example output of the keytool to generate a key pair (private and public key). 2018 Celonis SE ADFS SETUP (SAML AUTHENTICATION) 8
RETRIEVE SAML META DATA FROM YOUR IDENTITY PROVIDER In the next step and before finishing the setup, we need to retrieve the SAML meta data from the Identity Provider (ADFS). To retrieve SAML meta data from the Identity Provider, use the following URL in a browser: https://myserver.domain.com/federationmetadata/2007-06/federationmetadata.xml, where myserver.domain.com is the ADFS server. In our example, ADFS is installed on https://testdc.test.celonis.corp/federationmetadata/2007-06/federationmetadata.xml This file should be stored on the Celonis Server and the configuration pointed to it. When all paths are set correctly in the configuration, start the Celonis server. Note that the SAML setup requires additional steps. Next the SAML meta data file from the Celonis server must be generated and published in your ADFS to establish the mutual trust. Please note, the Celonis server must have SSL enabled for SAML to work correctly. GENERATE SAML META DATA FROM THE CELONIS SERVER Start the Celonis server. Monitor the log for exceptions. If the server starts up correctly, you should be able to open the following URL https://localhost/saml/metadata, which will provide you with the server s SAML meta data file of the Celonis Service. If you can t open this URL, please check that the paths are all set correctly in the configuration file, check the log for errors and the troubleshooting section. For testing SSL, you can also deactivate SAML from the configuration. In case of a correct setup, a file celonis_saml_metadata.xml will be downloaded by the browser. This file contains the certificates of your Celonis Service, your entity ID and some additional information. This file now must be published and registered in your ADFS. 2018 Celonis SE ADFS SETUP (SAML AUTHENTICATION) 9
REGISTER THE CELONIS SERVICE AS A RELIABLE PARTY IN YOUR ADFS To register the Celonis Service as a relying party, open the ADFS 2.0 Management Console and click Add Relying Party Trust from the action list on the right side (see Figure 2). Figure 2: ADFS 2.0 Management Console. Start the wizard Add Relying Party Trust (see Figure 3). Figure 3: Start the wizard to add a relying party trust. 2018 Celonis SE ADFS SETUP (SAML AUTHENTICATION) 10
Choose Import data about the relying party from a file and upload the SAML meta data file generated earlier by the Celonis Service (see Figure 4). Figure 4: Upload the SAML meta data file created by the Celonis Service. Name your service appropriately (see Figure 5). 2018 Celonis SE ADFS SETUP (SAML AUTHENTICATION) 11
Figure 5: Determine an appropriate name for the Celonis Service. Choose who you want to give access to the Celonis Service (the relying party). By default, everybody who can successfully authenticate will get access to the Celonis Service (see selected option in Figure 6). Review and finish the wizard. Figure 6: Determine access to the Celonis Service. 2018 Celonis SE ADFS SETUP (SAML AUTHENTICATION) 12
CONFIGURE ADDITIONAL USER ACCOUNT PARAMETERS You can configure additional attributes which will be auto-populated for the user account in Celonis, when automated user account creation is enabled (option: saml.user.autocreate). The following configuration provided in this guide will synchronize all AD groups of the user, as well as first name, last name and email address. Click Add Rule and add a rule providing the Name ID as well as additional information (see Figure 7). Figure 7: Add a new rule to synchronize additional AD attributes of users. 2018 Celonis SE ADFS SETUP (SAML AUTHENTICATION) 13
Select the claim rule template Send LDAP Attribute as Claims (see Figure 8). Figure 8: Select the claim rule template to synchronize LDAP attributes. Name the claim rule appropriately. In this example we choose the name NameID (see Figure 9). Figure 9: Name the claim rule appropriately. 2018 Celonis SE ADFS SETUP (SAML AUTHENTICATION) 14
Add the following LDAP attributes and map them to the outgoing claim types (see Figure 10): SAM- Account-Name, Token-Groups, Given-Name, Surname, E-Mail-Addresses Figure 10: Add the LDAP attributes for the outgoing claim type. The claim rule has been set up (see Figure 11). Figure 11: Successful set up of the claim rule. 2018 Celonis SE ADFS SETUP (SAML AUTHENTICATION) 15
The Celonis Service is set up as a relying party and it should be able to access the service with SSO (see Figure 12). Figure 12: Summary screen of the established relying party trust. Make sure the secure hash algorithm is set to SHA-256. Test your setup Restart the Celonis Service. Open the Celonis Service in the web browser. 2018 Celonis SE ADFS SETUP (SAML AUTHENTICATION) 16
TROUBLESHOOTING You have configured SAML and the Celonis Service reports the HTTP error code 500. Check the Celonis Server logs. In case any of the following error messages is present, it is very likely that the keystore and keystore entry parameters are invalid: org.opensaml.common.samlruntimeexception: Can't obtain SP signing key KeyStoreCredentialResolver - Unable to retrieve keystore entry for entityid (keystore alias): <keyentryname> KeyStoreCredentialResolver - Check for invalid keystore entityid/alias entry password Validate if the keystore password, keystore entry name and password in the configuration file are written correctly. We recommend to only use alphanumeric values, hence avoid the use of special characters such as - and & for these parameter values. 2018 Celonis SE ADFS SETUP (SAML AUTHENTICATION) 17
REFERENCES ADFS deployment Java keytool 2018 Celonis SE ADFS SETUP (SAML AUTHENTICATION) 18