The authentication methods that can be configured for Process Services are:

• The Identity Service
• OAuth 2
• LDAP and Active Directory
• Kerberos and Active Directory

Identity Service

Process Services can be configured to authenticate using the Identity Service.

Note: Starting from Alfresco Process Services 24.1, basic authentication is no longer supported when activiti.identity-service.enabled is set to true, as part of replacing Keycloak adapter with Spring security. This includes access to the REST APIs, for which you will first need to obtain a token from Identity Services.

The Identity Service allows you to configure user authentication between a supported LDAP provider or SAML identity provider and the Identity Service for Single Sign On (SSO) capabilities.

The Identity Service needs to be deployed and configured with an identity provider before being set up with other Alfresco products.

Once the Identity Service has been deployed, you will need to configure Process Services to authenticate with it.

Note: Please refer to the supported platforms page to see which parts of Process Services are compatible with the Identity Service.

Note: Process Services requires an email address as the user name when logging into the Identity Service.

Properties

Use this information to configure Process Services to authenticate via Identity Service.

Configure the activiti-identity-service.properties file using the below properties:

Note: A full list of possible properties is also available.

Renamed properties

Starting from Alfresco Process Services 24.1, as part of replacing the Keycloak adapter with Spring security, the properties prefix changed from keycloak.* to activiti.identity-service.*. The new property names are:

• activiti.identity-service.enabled=false
• activiti.identity-service.realm=alfresco
• activiti.identity-service.auth-server-url=http://localhost:8180/auth
• activiti.identity-service.resource=alfresco
• activiti.identity-service.principal-attribute=email
• activiti.identity-service.credentials.secret=
• alfresco.content.sso.enabled=${activiti.identity-service.enabled}
• alfresco.content.sso.client_id=${activiti.identity-service.resource}
• alfresco.content.sso.client_secret=${activiti.identity-service.credentials.secret}
• alfresco.content.sso.realm=${activiti.identity-service.realm}
• alfresco.content.sso.auth_uri=${activiti.identity-service.auth-server-url}/realms/${alfresco.content.sso.realm}/protocol/openid-connect/auth
• alfresco.content.sso.token_uri=${activiti.identity-service.auth-server-url}/realms/${alfresco.content.sso.realm}/protocol/openid-connect/token

New properties

Here is a list of new properties in Alfresco Process Service 24.1:

• activiti.identity-service.retry.maxAttempts=20
• activiti.identity-service.retry.delay=10000

Removed properties

Starting from Process Services 24.1, as part of replacing the Keycloak adapter with Spring security, the following unused keycloak.* properties have been removed:

• keycloak.ssl-required=none
• keycloak.confidential-port=8443
• keycloak.public-client=true
• keycloak.always-refresh-token=true
• keycloak.autodetect-bearer-only=true
• keycloak.token-store=session
• keycloak.enable-basic-auth=true

OAuth 2

To use the OAuth 2 client for authenticating login to the APS web application, you first need to configure it using the information obtained by the OAuth 2 authorization server.

The following entries show the properties you need to edit in activiti-app.properties and how you might set them for a typical configuration.

Code copied to clipboard.
security.oauth2.authentication.enabled=true
security.oauth2.client.clientId=<client_id>
security.oauth2.client.clientSecret=<secret_key>
security.oauth2.client.userAuthorizationUri=https://github.com/login/oauth/authorize
security.oauth2.client.tokenName=oauth_token
security.oauth2.client.accessTokenUri=https://github.com/login/oauth/access_token
security.oauth2.client.userInfoUri=https://api.github.com/user

Note: The user name used for Process Services application login should also exist on the external authentication server. Note also that the Process Services user name is an email address.

LDAP and Active Directory

It’s possible to hook up a centralized user data store with Process Services. Any server supporting the LDAP protocol can be used. Special configuration options and logic has been included to work with Active Directory (AD) systems too.

From a high-level overview, the external Identity Management (IDM) integration works as follows:

• Periodically, all user and group information is synchronized asynchronously. This means that all data for users (name, email address, group membership and so on) is copied to the Process Services database. This is done to improve performance and to efficiently store more user data that doesn’t belong to the IDM system.

• If the user logs in to Process Services, the authentication request is passed to the IDM system. On successful authentication there, the user data corresponding to that user is fetched from the Process Services database and used for the various requests. Note that no passwords are saved in the database when using an external IDM.

Note that the LDAP sync only needs to be activated and configured on one node in the cluster (but it works when activated on multiple nodes, but this will of course lead to higher traffic for both the LDAP system and the database).

The configuration of the external IDM authentication/synchronization is done in the same way as the regular properties. There is a properties file named activiti-ldap.properties in the WEB-INF/classes/META-INF/ folder in the WAR file. The values in a file with the same name on the classpath have precedence over the default values in the former file.

In addition, in the same folder, the example-activiti-ldap-for-ad.properties file contains an example configuration for an Active Directory system.

Server connection

The following code snippet shows the properties involved in configuring a connection to an LDAP server (Active Directory is similar). These are the typical parameters used when connecting with an LDAP server. Advanced parameters are commented out in the example below:

Code copied to clipboard.
# The URL to connect to the LDAP server
ldap.authentication.java.naming.provider.url=ldap://localhost:10389

# The default principal to use (only used for LDAP sync)
ldap.synchronization.java.naming.security.principal=uid=admin,ou=system

# The password for the default principal (only used for LDAP sync)
ldap.synchronization.java.naming.security.credentials=secret

# The authentication mechanism to use for synchronization
#ldap.synchronization.java.naming.security.authentication=simple

# LDAPS truststore configuration properties
#ldap.authentication.truststore.path=
#ldap.authentication.truststore.passphrase=
#ldap.authentication.truststore.type=
# Set to 'ssl' to enable truststore configuration via subsystem's properties
#ldap.authentication.java.naming.security.protocol=ssl

# The LDAP context factory to use
#ldap.authentication.java.naming.factory.initial=com.sun.jndi.ldap.LdapCtxFactory

# Requests timeout, in miliseconds, use 0 for none (default)
#ldap.authentication.java.naming.read.timeout=0

# See http://docs.oracle.com/javase/jndi/tutorial/ldap/referral/jndi.html
#ldap.synchronization.java.naming.referral=follow

It is possible to configure connection pooling for the LDAP/AD connections. This is an advanced feature and is only needed when creating a connection to the IDM system has an impact on system performance.

The connection pooling is implemented using the Spring-LDAP framework. Below are all the properties that it is possible to configure. These follow the semantics of the properties possible for Spring-LDAP and are described here.

Code copied to clipboard.
# -----------------------
# LDAP CONNECTION POOLING
# -----------------------

# Options=
# nothing filled in: no connection pooling
# 'jdk': use the default jdk pooling mechanism
# 'spring': use the spring ldap connection pooling facilities. These can be configured further below
#ldap.synchronization.pooling.type=spring

# Following settings follow the semantics of org.springframework.ldap.pool.factory.PoolingContextSource
#ldap.synchronization.pooling.minIdle=0
#ldap.synchronization.pooling.maxIdle=8
#ldap.synchronization.pooling.maxActive=0
#ldap.synchronization.pooling.maxTotal=-1
#ldap.synchronization.pooling.maxWait=-1
# Options for exhausted action: fail | block | grow
#ldap.synchronization.pooling.whenExhaustedAction=block
#ldap.synchronization.pooling.testOnBorrow=false
#ldap.synchronization.pooling.testOnReturn=false
#ldap.synchronization.pooling.testWhileIdle=false
#ldap.synchronization.pooling.timeBetweenEvictionRunsMillis=-1
#ldap.synchronization.pooling.minEvictableIdleTimeMillis=1800000
#ldap.synchronization.pooling.numTestsPerEvictionRun=3

# Connection pool validation (see http://docs.spring.io/spring-ldap/docs/2.0.2.RELEASE/reference/#pooling for semantics)
# Used when any of the testXXX above are set to true
#ldap.synchronization.pooling.validation.base=
#ldap.synchronization.pooling.validation.filter=
# Search control: object, oneLevel, subTree
#ldap.synchronization.pooling.validation.searchControlsRefs=

Authentication

To enable authentication via LDAP or AD, set the following property:

Code copied to clipboard.
ldap.authentication.enabled=true

In some organizations, a case insensitive log in is allowed with the LDAP ID. By default, this is disabled. To enable, set following property to false.

Code copied to clipboard.
ldap.authentication.casesensitive=false

Next, set the following property to specify the user ID pattern for an authenticating LDAP user:

Code copied to clipboard.
ldap.authentication.dnPattern=uid={0},ou=users,dc=alfresco,dc=com

However, if the users are in structured folders (organizational units for example), a direct pattern cannot be used. In this case, leave the property either empty or comment it out. Now, a query will be performed using the ldap.synchronization.personQuery (see below) with the ldap.synchronization.userIdAttributeName to find the user and their distinguished (DN) name. That DN will then be used to sign in.

When using Active Directory, two additional properties need to be set:

Code copied to clipboard.
ldap.authentication.active-directory.enabled=true
ldap.authentication.active-directory.domain=alfresco.com

The first property enables Active Directory support and the second property is the domain of the user ID (that is, userId@domain) to sign in using Active Directory.

If the domain does not match with the rootDn, it is possible to set is explicitly:

Code copied to clipboard.
ldap.authentication.active-directory.rootDn=DC=somethingElse,DC=com

And also the filter that is used (which defaults to a userPrincipalName comparison) can be changed:

Code copied to clipboard.
ldap.authentication.active-directory.searchFilter=(&(objectClass=user)(userPrincipalName={0}))

The following property can be set to true to allow for basic authentication to be used as a fallback for LDAP authentication. This allows for system or service users to be utilized for certain actions, such as making specific REST API calls:

Code copied to clipboard.
ldap.allow.database.authenticaion.fallback=true

Synchronization

The synchronization component will periodically query the IDM system and change the user and group database. There are two synchronization modes: full and differential.

Full synchronization queries all data from the IDM and checks every user, group, and membership to be valid. The resource usage is heavier than the differential synchronization in this type of synchronization and therefore, it is usually only triggered on the very first sync when Process Services starts up and is configured to use an external IDM. This is so that all users and groups are available in the database.

Full synchronization

The frequency in which it runs is set using a cron expression:

Code copied to clipboard.
ldap.synchronization.full.enabled=true
ldap.synchronization.full.cronExpression=0 0 0 * * ?

Differential synchronization is lighter, in terms of performance, as it only queries the users and groups that have changed since the last synchronization. One downside is that it cannot detect deletions of users and groups. Consequently, a full synchronization needs to run periodically (but less than a differential synchronization typically) to account for these deletions.

Code copied to clipboard.
ldap.synchronization.differential.enabled=true
ldap.synchronization.differential.cronExpression=0 0 */4 * * ?

Do note that all synchronization results are logged, both in the regular logging and in a database table named IDM_SYNC_LOG.

The synchronization logic builds on two elements:

• Queries that return the correct user/group/membership data
• A mapping of LDAP attributes to attributes used within the Process Services system

There are a lot of properties to configure, so do base your configuration on one of the two files in the META-INF folder, as these contain default values. You only need to add the specific properties to your custom configuration file if the default values are not appropriate.

Generic synchronization settings

These are settings that are generic or shared between user and group objects. For each property, an example setting of a regular LDAP system (that is, ApacheDS) and Active Directory is shown.

User synchronization settings

You can configure which users should be made administrators in the system. Delimit multiple entries with a ; (semi-colon) as commas can’t be used.

Note: No trimming of spaces will be applied and the property value must be an exact string match to the user DN value not an LDAP/AD query string.

Code copied to clipboard.
ldap.synchronization.tenantAdminDn=uid=joram,ou=users,dc=alfresco,dc=com;uid=tijs,ou=users,dc=alfresco,dc=com

When using multi-tenancy, the administrator of all tenants can be configured as follows. Similar rules for delimiting apply as above.

Note: The property value must be an exact string match to the user DN value not an LDAP/AD query string.

Code copied to clipboard.
ldap.synchronization.tenantManagerDn=uid=joram,ou=users,dc=alfresco,dc=com

It’s important to set at least 1 user with admin rights. Otherwise no user will be able to sign into the system and administer it.

Group synchronization settings

Add users to an LDAP group

Active Directory sets a limit on the number of attributes stored in a group that are retrievable in a single query. To overcome this, you can use incremental retrieval of data. This involves limiting the number of attribute values in a single query. To reduce the number of times the query is required to contact the server, set the number of values requested as close, as possible, to the maximum.

Process Services provides the capability to configure the number of group members retrieved per query subject to the limitations imposed by Active Directory. Follow these steps to enable this:

1. Open the <InstallLocation>/tomcat/webapps/activiti-app/WEB-INF/classes/META-INF/activiti-app/activiti-ldap.properties file.

2. Set the following property to true.

   Code copied to clipboard.
    ldap.synchronization.groupMemberRangeEnabled=true
   

3. Set the maximum number of members to retrieve in a single query.

   Code copied to clipboard.
    ldap.synchronization.groupMemberRangeSize=1500
   

   Note: This value should not exceed the limit set by Active Directory. If this is greater than the Active Directoy limit, no members are returned. See https://msdn.microsoft.com/en-us/library/ms676302(v=vs.85).aspx for information related to the maximum number of values returned in a single query in Active Directory. For further information regarding the behavior of the range attribute see https://msdn.microsoft.com/en-us/library/ms676302(v=vs.85).aspx.

Note: If you set the enablement property to true, the default value for ldap.synchronization.groupMemberRangeSize is set to 1000.

Paging

It is possible to use paging when connecting to an LDAP server (some even mandate this).

To enable paging when fetching users or groups, set following properties:

Code copied to clipboard.
ldap.synchronization.paging.enabled=true
ldap.synchronization.paging.size=500

By default, paging is disabled.

Batch insert

It is possible to tweak the batch size when doing an LDAP sync.

The insert batch size limits the amount of data being inserted in one transaction (for example, 100 users per transactions are inserted).By default, this is 5. The query batch size is used when data is fetched from the Process Services database (for example, fetching users to check for deletions when doing a full sync).

Code copied to clipboard.
ldap.synchronization.db.insert.batch.size=100
ldap.synchronization.db.query.batch.size=100

Kerberos and Active Directory

Process Services support for Kerberos SSO allows customers with existing Kerberos AD infrastructure to quickly and easily set up Windows-based SSO for their users’ access. It’s established as a security standard in many organizations and does not require additional infrastructure. It allows users secure access to the Process Services app (activiti-app) without explicit login through a web browser.

You must first set up accounts for use on a Microsoft Active Directory domain controller. It is important to identify each of the servers in your cluster that will be running the Process Services (activiti-app.war) web application. These instructions also apply to simple non-clustered installations, where a single activiti-app.war runs on a single host.

These instructions use the following naming conventions for the example server, server1.alfresco.org:

• <host> is the server host name (without domain name suffix). For example, server1.
• <hostnetbios> is the resolved value of the cifs.serverName property if the server is part of the Active Directory domain (typically the host name with the letter ‘A’ appended) or the host name otherwise (without domain name suffix). For example, server1A.
• <domain> is the DNS domain. For example, alfresco.org.
• <domainnetbios> is the Windows domain NetBIOS name. For example, alfresco.
• <REALM> is t he DNS domain in upper case. For example, ALFRESCO.ORG.

Prerequisites

You must ensure that you have configured LDAP (LDAP synchronization in particular). You can use Kerberos SSO in combination with LDAP authentication and also database authentication. You can use both of these as fallback scenarios in the case that the user’s browser does not support Kerberos authentication.

Configuration steps

Kerberos SSO configuration can be divided into three parts:

• (1) Steps to configure Active Directory and are performed by an Administrator against the domain controllers
• (2) Steps to configure the machine where Process Services is hosted (for example, creating the krb5.ini file)
• (3) Steps to set configuration properties

1. Create accounts for the SSO authentication filters by repeating the following steps for each server in the cluster that will be running the activiti-app.war file.

   1. In the Active Directory Users and Computers application, choose Action > New > User, then enter the full name as HTTP and the user log in name as http.

   2. Click Next.

   3. Enter a password.

   4. Enable Password never expires and disable User must change password at next logon.

   5. Click Next.

   6. Click Finish.

   7. Right-click the new user account name, and then select Properties.

   8. Select the Account tab and enable the Do not require Kerberos preauthentication option in the Account Options section.

   9. From the command prompt, use the ktpass utility to generate key tables for this account as shown:

      Code copied to clipboard.
       ktpass -princ HTTP/<host>.<domain>@<REALM> -pass <password> -mapuser 
       <domainnetbios>\http<host> -crypto all -ptype KRB5_NT_PRINCIPAL -out 
       c:\temp\http<host>.keytab -kvno 0
      

   10. Create the Service Principal Names (SPN) for the account using the setspn utility.

       Code copied to clipboard.
       setspn -a HTTP/<host> http<host>
       setspn -a HTTP/<host>.<domain> http<host>
       

       Note: When configuring Kerberos on a cluster through a load balancer, use the proxy name as the Service Principal Names (SPN).

   11. In the Active Directory Users and Computers application, right click on the http<host> user and select Properties.

   12. Select the Delegation tab. If you cannot see the Delegation tab, do one or both of the following:

       • Check that you ran the specified setspn command correctly. Delegation is only intended to be used by service accounts, which should have registered SPNs, as opposed to a regular user account which typically does not have SPNs.
       • Raise the functional level of your domain to Windows Server 2012 R2 x64. To do this:
         • Open Active Directory Domains and Trusts.
         • In the console tree, right-click the applicable domain and then click Raise Domain Functional Level.
         • In Select an available domain functional level, click Windows Server 2012, and then click Raise.

   13. In the user Delegation tab, select the Trust this user for delegation to any service (Kerberos only) check box.

   Copy the key table files created in steps 1 and 2 to the servers they were named after. Copy the files to a protected area, such as C:\etc\ or /etc.

2. On each server in the cluster that will be running the APS web application (activiti-app.war), repeat the following steps:

   1. Set up the Kerberos ini file to point to the Windows domain controller.

      The default location is %WINDIR%\\krb5.ini, where %WINDIR% is the location of your Windows directory, for example, C:\Windows\krb5.ini. If the file does not already exist (for example, if the Kerberos libraries are not installed on the target server), you must copy these over or create them from scratch. See Kerberos Help for more information on the krb5.conf file. In this example, our Windows domain controller host name is adsrv.alfresco.org.

      Code copied to clipboard.
       [libdefaults]
       default_realm = ALFRESCO.ORG
       default_tkt_enctypes = rc4-hmac
       default_tgs_enctypes = rc4-hmac
      
       [realms]
       ALFRESCO.ORG = {
          kdc = adsrv.alfresco.org
          admin_server = adsrv.alfresco.org
       }
      
       [domain_realm]
       adsrv.alfresco.org = ALFRESCO.ORG
       .adsrv.alfresco.org = ALFRESCO.ORG
      

      Note: Specify the realm in uppercase.

      The Kerberos ini file for Linux is /etc/krb5.conf.

   2. Set up the Java login configuration file.

      For JBoss, open the $JBOSS_HOME/standalone/configuration/standalone.xml file.

      In the <subsystem xmlns="urn:jboss:domain:security:1.2"> section, add the following:

      Code copied to clipboard.
       <security-domain name="alfresco" cache-type="default">  
           <authentication>  
                 <login-module code="com.sun.security.auth.module.Krb5LoginModule" flag="sufficient"/>  
           </authentication>  
       </security-domain> 
      

      Add the following security-domain sections:

      Code copied to clipboard.
       <security-domain name="AlfrescoHTTP" cache-type="default">
       	<authentication>
       			<login-module code="com.sun.security.auth.module.Krb5LoginModule" flag="required">
       			   <module-option name="debug" value="true"/>
       			   <module-option name="storeKey" value="true"/>
       			   <module-option name="useKeyTab" value="true"/>
       			   <module-option name="doNotPrompt" value="true"/>
       			   <module-option name="isInitiator" value="false"/>
       			   <module-option name="keyTab" value="C:/etc/http<host>.keytab"/>
       			   <module-option name="principal" value="HTTP/<host>.<domain>"/>
       			</login-module>
       	</authentication>
       </security-domain>
      

      For other environments, in the Java security folder (for example, C:\Alfresco\java\lib\security), create a file named java.login.config with entries as shown below.

      Code copied to clipboard.
       Alfresco {
          com.sun.security.auth.module.Krb5LoginModule sufficient;
       };
      
       AlfrescoHTTP
       {
          com.sun.security.auth.module.Krb5LoginModule required
          storeKey=true
          useKeyTab=true
          doNotPrompt=true
          keyTab="C:/etc/http<host>.keytab"
          principal="HTTP/<host>.<domain>";
       };
      
       com.sun.net.ssl.client {
          com.sun.security.auth.module.Krb5LoginModule sufficient;
       };
      
       other {
          com.sun.security.auth.module.Krb5LoginModule sufficient;
       };
      

   3. Enable the login configuration file by adding the following line to the main Java security configuration file, usually at java\lib\security\java.security.

      Code copied to clipboard.
       login.config.url.1=file:${java.home}/lib/security/java.login.config
      

   4. If the Process Services server is not part of the Active Directory domain, ensure that its clock is kept in sync with the domain controller’s, for example, by configuring the domain controller as an NTP server.

3. To complete Kerberos SSO enablement, perform the following configuration steps after completing the actions described in step 1 and step 2 above:

   Note: Use the same server as that used in part 2 of Kereberos SSO configuration to carry out these steps.

   1. Open the <InstallLocation>/tomcat/lib/activiti-ldap.properties file.

      Note: You will need to create this file if it does not already exist.

   2. Specify the configuration settings listed in the table below.

   Property name	Description
   kerberos.authentication.enabled	A switch for activating functionality for Kerberos SSO authentication. This applies to both the APS user interface and the REST API. The default value is FALSE.
   kerberos.authentication.principal	The Service Principal Name (SPN). For example, HTTP/alfresco.test.activiti.local.
   kerberos.authentication.keytab	The file system path to the key table file. For example, C:/alfresco/alfrescohttp.keytab.
   kerberos.authentication.krb5.conf	The file system path to the local server. For example, C:/Windows/krb5.ini.
   kerberos.allow.ldap.authentication.fallback	Determines whether to allow login for unsupported client browsers using LDAP credentials. The default value is FALSE.
   kerberos.allow.database.authentication.fallback	Determines whether to allow login for unsupported client browsers using database credentials. The default value is FALSE.
   kerberos.allow.samAccountName.authentication	Authentication of the user id using the short form (for example username instead of username@domain.com). The default value is FALSE.
   security.authentication.use-externalid	A setting that enables the use of Kerberos authentication. The default value is FALSE.