adfs setup (saml authentication)
TRANSCRIPT
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.
Version 1.8
Corresponding Software Version
Celonis 4.5
ADFS Setup
(SAML Authentication)
© 2019 Celonis SE ADFS SETUP (SAML AUTHENTICATION) 2
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
© 2019 Celonis SE ADFS SETUP (SAML AUTHENTICATION) 3
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
1.8 APR 18, 2019 Revision & Update for Celonis 4.5
© 2019 Celonis SE ADFS SETUP (SAML AUTHENTICATION) 4
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
© 2019 Celonis SE ADFS SETUP (SAML AUTHENTICATION) 5
LIST OF ABBREVIATIONS
ABBREVIATION EXPLANATION
AD Active Directory
ADFS Active Directory Federation Service
HTTPS Hypertext Transfer Protocol Secure
JKS Java Key Store
SAML Security Assertion Markup Language
SSO Single Sign-On
© 2019 Celonis SE ADFS SETUP (SAML AUTHENTICATION) 6
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/givenname # The SAML claim attribute which contains the last name of the user saml.claims.lastName=http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname # The SAML claim attribute which contains the email address of the user saml.claims.emailAddress=http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress # 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
© 2019 Celonis SE ADFS SETUP (SAML AUTHENTICATION) 7
# 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 end-
point (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.
© 2019 Celonis SE ADFS SETUP (SAML AUTHENTICATION) 8
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).
© 2019 Celonis SE ADFS SETUP (SAML AUTHENTICATION) 9
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.
© 2019 Celonis SE ADFS SETUP (SAML AUTHENTICATION) 10
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.
© 2019 Celonis SE ADFS SETUP (SAML AUTHENTICATION) 11
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).
© 2019 Celonis SE ADFS SETUP (SAML AUTHENTICATION) 12
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.
© 2019 Celonis SE ADFS SETUP (SAML AUTHENTICATION) 13
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.
© 2019 Celonis SE ADFS SETUP (SAML AUTHENTICATION) 14
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.
© 2019 Celonis SE ADFS SETUP (SAML AUTHENTICATION) 15
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.
© 2019 Celonis SE ADFS SETUP (SAML AUTHENTICATION) 16
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.
© 2019 Celonis SE ADFS SETUP (SAML AUTHENTICATION) 17
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.
© 2019 Celonis SE ADFS SETUP (SAML AUTHENTICATION) 18
REFERENCES
• ADFS deployment
• Java keytool