adfs setup (saml authentication)

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


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


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


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


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


# 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.


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


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.

https://myserver.domain.com/FederationMetadata/2007-06/FederationMetadata.xml

https://testdc.test.celonis.corp/FederationMetadata/2007-06/FederationMetadata.xml

https://testdc.test.celonis.corp/FederationMetadata/2007-06/FederationMetadata.xml

https://localhost/saml/metadata


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.


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


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.


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.


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.


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.


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.


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.


REFERENCES

• ADFS deployment

• Java keytool

https://docs.microsoft.com/en-us/windows-server/identity/ad-fs/deployment/windows-server-2012-ad-fs-deployment-guide

https://docs.oracle.com/javase/8/docs/technotes/tools/unix/keytool.html

adfs setup (saml authentication)

Documents