SSO integration

Import certificate for Secured LDAP

If you use LDAP, you must import the server certificate that is published by your LDAP provider into the Java Virtual Machine (JVM). If you do not provide the certificate, the following error is displayed in the logs: javax.naming.CommunicationException: simple bind failed

To import your LDAP provider server certificate into JVM:

1. Use the following keytool command of embedded Java Developement Kit (JDK) to trust the certificate in JVM:

cd /opt/processmining/jdk/linux/ibm-openjdk-semeru/bin
./keytool -import -keystore ../lib/security/cacerts -trustcacerts -alias "LdapCert" -file <PATH TO YOUR FILE>.pem

2. Restart the PMWeb module.

Examples

ldap: {
    url: "ldaps://ldapsrv.mycompany.com:636", 
    type: "basic" 
    searchBase : "" 
    filter:"", 
    secure: true, 
    domain: "MYDOMAIN", 
    backupurl: "",
    domainexclude: [],
    adminpassword: "",
    testmode: false
  },

ldap: {
    url: "ldaps://ldap.intranet.group.eu:636", 
    type: "standard" 
    searchBase : "uid={USERNAME},ou=people,dc=group,dc=eu" 
    filter:"uid", 
    secure: true, 
    domain: "", 
    backupurl: "",
    domainexclude: [],
    adminpassword: "",
    testmode: false
  },

 ldap: {
    url: "ldaps://myserver.company.com:636" 
    type: "query" 
    searchBase: "ou=myorganization,o=company.com"
    filter: "mail", 
    secure: true, 
    domain: "", 
    backupurl: "",
    domainexclude: [],
    adminpassword: "",
    testmode: false
  },

Activate SAML2 security

When you introduce changes to the processmining.conf file, make sure you do it correctly. For more information, see the Configuration file editing guidelines section.

To enable SAML2, do the following steps:

1. Edit the profile section in <PM_HOME>/etc/processmining.conf

2. Replace sso_none with sso_saml as shown:

     profiles: [
     "sso_saml", # sso_none | sso_saml
     ]
   

3. Edit the authentication section in:

   <PM_HOME>/etc/processmining.conf:
   authentication: {
     mode: "saml",  # ldap | basic | saml
   }
   

Minimal configuration

To configure SAML2, you need the metadata (url ir xml file) from the IdP configuration. You can download the Identity provider metadata automatically from the application by using an URI or copying the xml file into a directory in the server. You must get the following data from the application to the IdP configuration:

• Provider ID
• Assertion consumer service URL
• Service provider SSO URL

The default values are:

• {sp.base.url}/saml2/service-provider-metadata/processmining
• {sp.base.url}/login/saml2/sso/processmining
• {sp.base.url}/login/saml2/sso/processmining

where sp.base.url is your application url.

You can use the following configuration to define idp.metadata and sp.base.url:

    saml: {
     idp.metadata : "https://my-idp-host/v1.0/saml/federations/saml20ip/metadata", 
     sp.base.url: "https://my-pm-hostname.com"
    }

The property idp.metadata can be filled with an URI, an absolute path, or a file name. If it is a file name, it is located on /<PM_HOME>/etc/saml/.

IdP configuration example using IBM Security Verify

Advanced configuration

You need to get the identity provider signing certificate from Idp.

The application provides the following data to the IdP:

• Single logout url
• Service provider signer certificate

Use the following configuration to define the data:

  saml: {
   
    idp.metadata : "federation_metadata.xml",
    
    # idp Signing Certificate
    idp.signing.certificate: "cic_certificate.cer"
    
   sp.signer.certificate: "_.mydomain.company.com.pem"
   sp.signer.privateKey: "star_mycompany.key"
    
   sp.base.url: "https://my-pm-hostname.com"
    
  }

Use provisioning

By default, the auto-provisioning is enabled. The user provisioning is automatically created if a user does not exist in the IBM Process Mining database.

IdP must send the following user properties to the application:

• Email
• Given name
• Surname

You must configure a mapping between the name of the attributes that are present in the SAML2 request and the name that the IBM Process Mining application expects.

You can do the configuration in the provisioning section as shown in the following example:

    provisioning : {
    attributes : {
    email : "EmailAddress",
    firstName : "FirstName",
    lastName : "LastName",
    groups : "groups"
    },
    groupMapping: {
    owner : "",
    administrator : ""
    }
    }

• You can obtain the user groups from IdP and map it to IBM Process Mining groups.
• You can add one user each to the Administration group and the Owner group. However, if a user does not belong to a group, then IBM Process Mining gives only the basic user permission with the read-only access to that user.
• You must configure a mapping between the name of the attributes that are present in the SAML2 request and the name that the IBM Process Mining application expects.

Use the following configuration for user provisioning:

    policy : {
  	autoActivate: true,  # if new sign-up accounts are activated without administrator review
  	selfProvisioning : true # if new user are created into databese
  },
  provisioning : {
  	attributes : {
  		email : "EmailAddress",
  		firstName : "FirstName", #http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name
  		lastName : "LastName",  #http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname
		groups : "groups"
  	},
  	groupMapping: {
  		owner : "pm-owner-grp",
  		administrator : "pm-admin-grp"
  	}
  }

where pm-owner-grp and pm-admin-grp are the group defined on IdP side

Log checks after startup

You get the following logs after startup:

 2023/05/18 09:17:44.531 +0000 INFO  c.i.c.auth.saml.SAMLSecurityConfig.filterChain (200) - ******************************************************
 2023/05/18 09:17:44.532 +0000 INFO  c.i.c.auth.saml.SAMLSecurityConfig.filterChain (201) - ********* Initializing SAML Security Context *********
 2023/05/18 09:17:45.871 +0000 INFO  c.i.c.auth.saml.SAMLSecurityConfig.relyingPartyRegistrations (99) - idp.metadata https://ibm-pm-dev01-gb.verify.ibm.com/v1.0/saml/federations/saml20ip/metadata
 2023/05/18 09:17:45.872 +0000 INFO  c.i.c.auth.saml.SAMLSecurityConfig.relyingPartyRegistrations (116) - Get metadata from uri
 2023/05/18 09:17:45.872 +0000 INFO  c.i.c.auth.saml.SAMLSecurityConfig.relyingPartyRegistrations (126) - entityId https://tst-rel-pkg.automationcloud.ibm.com/saml2/service-provider-metadata/processmining
 2023/05/18 09:17:45.872 +0000 INFO  c.i.c.auth.saml.SAMLSecurityConfig.relyingPartyRegistrations (135) - assertionConsumerServiceLocation https://tst-rel-pkg.automationcloud.ibm.com/login/saml2/sso/processmining
 2023/05/18 09:17:45.875 +0000 INFO  c.i.c.auth.saml.SAMLSecurityConfig.getLogOutCredential (181) - Logout with signer
 2023/05/18 09:17:45.875 +0000 INFO  c.i.c.auth.saml.SAMLSecurityConfig.getLogOutCredential (182) - Certificates  _.automationcloud.ibm.com.pem, PrivateKey star_automationcloud.key
 2023/05/18 09:17:45.876 +0000 INFO  c.i.c.auth.saml.SAMLSecurityConfig.getCertificateCredential (258) - Loading credential _.automationcloud.ibm.com.pem
 2023/05/18 09:17:45.877 +0000 INFO  c.i.c.auth.saml.SAMLSecurityConfig.getCertificateCredential (258) - Loading credential cic_certificate.cer