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 the embedded Java Development 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.

User provisioning for LDAP

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

You can also make mappings between your organization user groups and groups in IBM Process Mining in the Administration page inside the IBM Process Mining application. For more information, see Managing groups - Details. If there are no changes made in the Administration page, then group mappings from this configuration file are used.

The following table contains descriptions of properties that are used in user provisioning:

IBM Process Mining obtains the following user properties from the LDAP server:

• Email
• First name
• Last name

Configure the mapping and the corresponding property in the directory after each of the user properties.

 provisioning : {
  	attributes : {
  		username: "emailAddress" # sAMAccountName for ADFS, emailAddress for Ibm
  		email : "EmailAddress",
  		firstName : "givenname"
  		lastName : "sn", 
  		groups : "memberOf"
  	},
  	groupMapping: {
  		owner : "",
  		administrator : "myCompanyGroup"
  	}
  }

You can obtain the user groups from LDAP and map it to IBM Process Mining groups.

You can add one user each to the Administration group and the Owner group (Analytics user). However, if a user does not belong to a group, then IBM Process Mining can only grant the basic user permission with the read-only access (Business User).

The group can be obtained in two ways:

• From a Person object attribute (that is, memberOf) - The property groupFilter must be empty
• From a link relationship between a "group" object (that is, the attribute uniqueMember of an groupOfUniqueNames object) - The property groupFilter must be populated - The uniqueMember attribute must be the user's DN

Examples

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

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

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

Activate SAML2 security

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

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"
    
  }

User provisioning for SAML2

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.

You can also make mappings between your organization user groups and groups in IBM Process Mining in the Administration page inside the IBM Process Mining application. For more information, see Managing groups - Details. If there are no changes that are made in the Administration page, then group mappings from this configuration file are used.

IdP must send the following user properties to the application:

• Email
• Given name
• Surname

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 (Analytics user). However, if a user does not belong to a group, then IBM Process Mining can only grant the basic user permission with the read-only access (Business User).

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 that is defined on the 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