This library was originally created to expand the functionality of Keycloak integration within the Alfresco Process Services (APS) application. It has expanded to support general OAuth, closing gaps that remain in the implementation provided by Alfresco. This is useless for the open source Activiti product.

APS delivers SSO capability and that is about it. It has a few shortcomings:

The user must already exist in APS, which means they must be sync'd in from LDAP.
The user roles are for their session only and not synchronized with APS Organizations. This prevents the user from being included in task candidate group assignments and other group features.

This extension aims to resolve those issues.

The older version of this extension was specific to Keycloak and was named keycloak-activiti-app-ext. See the develop-v1.4.x branch for details specific to it.

Installation

The installation is simple. Just include the JAR in the classpath of your APS application. This is best done by not chaning the activiti-app.war file, but instead including it within the classpath using your web container configuration. For Apache Tomcat, you would add or modify the following context file: conf/Catalina/localhost/activiti-app.xml. Its related contents would be:

<Context>
        <Resources>
                <PostResources base="${catalina.base}/ext" className="org.apache.catalina.webresources.DirResourceSet" webAppMount="/WEB-INF/lib" readOnly="true" />
        </Resources>
</Context>

Notice the use of PostResources instead of PreResources. This library needs to be loaded after the web application. This is the best way to load any other extensions or customization to the Activiti App, including JavaDelegate implementations. If you use the -security switch, you will need to give this path permissions in the catalina.policy file:

grant codeBase "file:${catalina.base}/ext/-" {
	permission java.security.AllPermissions
}

Dependencies

This extension requires the multiext-activiti-app-ext. Without it, APS will fail to startup. It is very small and requires no additional configuration.

Support Matrix

Activiti App Extension	Activiti App
`keycloak-activiti-app-ext` v1.0 - v1.2	v1.11.x
`keycloak-activiti-app-ext` v1.3 - v1.4	v1.11.x - v2.x
`auth-activiti-app-ext` v2.0+	v24.x+

Configuration

The library is highly configurable. You configure it with properties specified in the activiti-app.properties file, which exists somewhere in the root of the classpath. That is typically in the lib folder. Or you could specify these options with -D switches on startup of the web container. The properties to configure are enumerated in the table below.

This will only work if OAuth is being used. That would be the case if activiti.identity-service.enabled or security.oauth2.authentication.enabled is true.

The following properties are used across the functionalities of this extension.

Property	Default	Description
`auth-ext.externalId`	`oauth`	This will serve as the external ID for users and as the prefix for the external ID of groups created or searched by this extension. Anything without an external ID is considered internal. So mismatched external IDs are never considered for anything by this extension.
`auth-ext.tenant`		A preselected tenant for all operations in this extension. Only required if there are multiple tenants.

OAuth Authentication/Authorization

The following properties were added to increase the configurability of the built-in OAuth capabilities of APS. The default in this extension adds the microprofile-jwt scope, which is key to providing groups/roles/entitlements.

Property	Default
`auth-ext.oauth.scopes`	`openid`, `profile`, `email`, `microprofile-jwt`

OAuth Synchronization

The following properties provide the core functionality of this extension. That is role synchronization.

Property	Default	Description
`auth-ext.sync.user.createMissing`	`true`	If the user is authenticated, the user may be created in APS.
`auth-ext.sync.user.requireOidcGroup`		This is only applicable when `createMissing` is `true`. If this is unset or the OAuth Authorization Server gives the user the specified group/role, then the user record will be created in APS.
`auth-ext.sync.user.clearNewUserGroups`	`true`	This is only applicable when `createMissing` is `true`. All default APS groups will be deleted from the new user record.
`auth-ext.sync.group.createMissing`	`true`	If a filtered and translated OIDC group has no corresponding APS group, a group will be created in APS. See `auth-ext.sync.group.capabilities.patterns` for whether that group will be an APS Organization or APS Capability.
`auth-ext.sync.group.additions`	`true`	If the user isn't in an APS group but OAuth claims the OIDC group, then add them to it.
`auth-ext.sync.group.removals`	`true`	If the user is in APS group but OAuth claims no OIDC group, then remove them from it.
`auth-ext.sync.group.internal`	`false`	When considering groups for creation or user membership, include internal groups. Internal groups are ones without an `externalId`.
`auth-ext.sync.group.internal.externalize`	`false`	This is only applicable when `internal` is `true`. If an internal group is encountered during the operation of this extension, make it external with the current `externalId`.
`auth-ext.sync.group.tenantize`	`false`	If a group without a tenant is encountered during the operation of this extension, make it part of the selected tenant.
`auth-ext.sync.group.include.patterns`		A comma delimited set of regular expression patterns on what OIDC groups to include. This is processed before `translate` processing. A blank value matches everything. If anything is specified, then only matches could possibly be included. Any matches of the `exclude` property patterns always override though.
`auth-ext.sync.group.exclude.patterns`		A comma delimited set of regular expression patterns on what OIDC groups to exclude. This is processed before `translate` processing. A blank value matches nothing (includes all that pass the `include` constraint). If anything is specified and `include` is empty, then all non-matches are included. If both are specified, `exclude` matches override `include` matches.
`auth-ext.sync.group.translate.patterns`		A comma delimited set of regular expression patterns for the translation (reformatting) of OIDC groups to APS groups. This list corresponds to the `replacements` property and must have the same number of commas.
`auth-ext.sync.group.translate.replacements`		A comma delimited set of regular expression replacement strings for the translation (reformatting) of OIDC groups to APS groups. This list corresponds to the `patterns` property and must have the same number of commas.
`auth-ext.sync.group.capability.patterns`	`Superusers`	A comma delimited set of regular expression patterns on what translated OIDC groups to associate with APS Capability Groups instead of APS Organization Groups (default). This is processed after `translate` processing.

Authentication Data Fixers

Administrator Password Fixer

This fixer does not execute unless the auth-ext.reset.admin.password property is explicitly set. It is meant to be set for a single run to fix scenarios when a non-OAuth administrator cannot access the system. This is useful when your OAuth configuration isn't working and you need to reset your non-OAuth administrator's password.

Property	Default
`auth-ext.reset.admin.username`	`admin@app.activiti.com`
`auth-ext.reset.admin.password`

Administrator Members Fixer

This fixer does not execute unless the auth-ext.default.admin-users property is explicitly set. It is meant to be set for a single run to add both non-OAuth and OAuth users to an administrator group. This is useful when OAuth is misconfigured and all administrators lose their administrator rights.

Property	Default	Description
`auth-ext.default.admins.users`		A comma delimited list of user emails.
`auth-ext.group.admins.name`	`Superusers`	The APS Group (Capability or Organization) for the specified users to be members.

Administrator Group Fixer

This fixer does not execute unless the auth-ext.group.admins.validate property is set to true. It is meant to be set for a single run to correct the specified group for administration access. This is useful if you accidentally delete the administrative APS Capability Group, typically called Administrator or Superusers.

Property	Default	Description
`auth-ext.group.admins.validate`	`false`
`auth-ext.group.admins.name`	`Superusers`	The APS Capability Group of which to grant all capabilities.