inteligr8/auth-activiti-app-ext
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

updated docs

Browse Source
This commit is contained in:
Brian Long
2025-05-07 08:50:25 -04:00
parent d631cc5f12
commit c38c1d28df
1 changed files with 32 additions and 22 deletions
Download Patch File Download Diff File Expand all files Collapse all files

54
README.md
View File

@@ -1,6 +1,6 @@
# Auth Extension for APS (Activiti App) # Auth Extension for APS (Activiti App)
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. 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: APS delivers SSO capability and that is about it. It has a few shortcomings:
@@ -9,6 +9,8 @@ APS delivers SSO capability and that is about it. It has a few shortcomings:
This extension aims to resolve those issues. 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](https://git.inteligr8.com/inteligr8/auth-activiti-app-ext/src/branch/develop-v1.4.x/) for details specific to it.
## Installation ## 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: 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:
@@ -35,11 +37,11 @@ This extension requires the [`multiext-activiti-app-ext`](https://git.inteligr8.
## Support Matrix ## Support Matrix
| Auth Activiti App Extension | Activiti App | | Activiti App Extension | Activiti App |
| --------------------------- | --------------- | | --------------------------------------- | --------------- |
| v1.0 - v1.2 | v1.11.x | | `keycloak-activiti-app-ext` v1.0 - v1.2 | v1.11.x |
| v1.3 | v1.11.x - v2.x | | `keycloak-activiti-app-ext` v1.3 | v1.11.x - v2.x |
| v2.0+ | v24.x+ | | `auth-activiti-app-ext` v2.0+ | v24.x+ |
## Configuration ## Configuration
@@ -47,6 +49,13 @@ The library is highly configurable. You configure it with properties specified
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`. 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 ### 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. 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.
@@ -61,8 +70,6 @@ The following properties provide the core functionality of this extension. That
| Property | Default | Description | | 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 by this extension. |
| `auth-ext.tenant` | | A preselected tenant for all operations in this extension. Only required if there are multiple tenants. |
| `auth-ext.sync.user.createMissing` | `true` | If the user is authenticated, the user may be created in APS. | | `auth-ext.sync.user.createMissing` | `true` | If the user is authenticated, the user may be created in APS. |
| `auth-ext.sync.user.requireGroup` | | 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.requireGroup` | | 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.user.clearNewUserGroups` | `true` | This is only applicable when `createMissing` is `true`. All default APS groups will be deleted from the new user record. |
@@ -78,29 +85,32 @@ The following properties provide the core functionality of this extension. That
| `auth-ext.sync.group.exclude.patterns` | | A comma delimited set of regular expression patterns on what authorities to exclude. This is processed before `translate` processing. A blank value excludes nothing. If anything is specified and `include` is empty, then only matches will be excluded. If both are specified, `exclude` overrules `include` matches. | | `auth-ext.sync.group.exclude.patterns` | | A comma delimited set of regular expression patterns on what authorities to exclude. This is processed before `translate` processing. A blank value excludes nothing. If anything is specified and `include` is empty, then only matches will be excluded. If both are specified, `exclude` overrules `include` matches. |
| `auth-ext.sync.group.capabilities.patterns` | `Superusers` | A comma delimited set of regular expression patterns on what authorities to associate with APS Capabilities instead of APS Organizations (default). | | `auth-ext.sync.group.capabilities.patterns` | `Superusers` | A comma delimited set of regular expression patterns on what authorities to associate with APS Capabilities instead of APS Organizations (default). |
### Authentication Data Fixers ### Authentication Data Fixers
#### Administrator Password Fixer #### Administrator Password Fixer
| Property | Default | Description | 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.
| ----------------------------------------- | ------------------------ | ----------- |
| `auth-ext.reset.admin.username` | `admin@app.activiti.com` | | Property | Default |
| `auth-ext.reset.admin.password` | | If set, the user's password will be set to this value on startup; otherwise this fixer is skipped. | | --------------------------------- | ------------------------ |
| `auth-ext.reset.admin.username` | `admin@app.activiti.com` |
| `auth-ext.reset.admin.password` | |
#### Administrator Members Fixer #### Administrator Members Fixer
| Property | Default | Description | 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.
| ----------------------------------------- | ------------------------ | ----------- |
| `auth-ext.default.admins.users` | | A comma delimited list of user emails; fixer is skipped if empty. | | Property | Default | Description |
| `auth-ext.group.admins.name` | `Superusers` | The APS Group (Capability or Organization) to add the specified users to. | | ------------------------------------ | ------------ | ----------- |
| `auth-ext.group.admins.externalId` | | If specified, this APS Group will be considered before the specified `name` field. | | `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. |
| `auth-ext.group.admins.externalId` | | If specified, the external APS Group will take precedence over the internal APS Group; if both exist. |
#### Administrator Group Fixer #### 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 | | Property | Default | Description |
| ----------------------------------------- | ------------------------ | ----------- | | ----------------------------------------- | ------------------------ | ----------- |
| `auth-ext.group.admins.validate` | `false` | If `true`, the specified APS Group will be granted all capabilities. | | `auth-ext.group.admins.validate` | `false` |
| `auth-ext.group.admins.name` | `Superusers` | The APS Group (Capability or Organization) to add the specified users to. | | `auth-ext.group.admins.name` | `Superusers` | The APS Capability Group of which to grant all capabilities. |
| `auth-ext.group.admins.externalId` | | If specified, this APS Group will be considered before the specified `name` field. |