SAML2 authentication

You can configure the SAML2 (Security Assertion Markup Language) authentication only in a single tenant environment. Secure IBM Process Mining with https by installing NGINX and the related configuration.

Verify that the value of the property is engine.defaults.signup.groupid.

Check that that value corresponds to the ID of your tenant. This value is visible in the Admin Console.

Activating SAML2 security

Warning: 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"
    }
Tip: 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

sso SAML2 Configuration 1

sso SAML2 Configuration 2

sso SAML2 Configuration 3

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. 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 : ""
      }
    }
Note: You can obtain the user groups from IdP and map it to IBM Process Mining groups.
Note: 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).
Note: 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

SSO SAML2 Configuration 3

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