inteligr8/alfresco-keycloak
1
0
Fork 0
mirror of https://github.com/bmlong137/alfresco-keycloak.git synced 2025-05-12 21:24:43 +00:00
Code Issues Packages Projects Releases Wiki Activity

WIP documentation

Browse Source
This commit is contained in:
AFaust 2021-04-12 20:59:20 +02:00
parent 4a2f4a5f67
commit cdf9520bd0
4 changed files with 95 additions and 3 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

1
docs/Reference-Repository-Extension.md Normal file
View File

@ -0,0 +1 @@
TBD

13
docs/Reference-Repository-Subsystem.md
View File

@ -1,4 +1,4 @@
# Keycloak Repository Subsystem
# Repository Subsystem Reference
The Keycloak authentication subsystem is enabled by putting a single instance of it in the authentication chain property, e.g. by specifying
@ -152,3 +152,14 @@ The following technical role mapping configuration properties are supported by t
| --- | ---: | --- |
| `hiddenMappedRoles.list.csv` | (too long) | Comma-separated list of Alfresco authority names which should not be exposed even if the names have been mapped from Keycloak roles |
### Technical - Session Caches
In order to support Keycloak back-channel logout / session invalidation, the Repository subsystem uses custom Alfresco caches to map HTTP and SSO session IDs. Additionally, a custom cache is used to map Keycloak access tokens for authentication tickets that have been established by simple user + password authentication in order to refresh them when necessary / possible, and map the relevant roles from the token into the users authorisation context on each subsequent request. The caches added by the addon can be configured just like any other cache in Alfresco. The names / configuration key prefixes for these caches are:
- `cache.acosix-keycloak.ssoToSessionCache`
- `cache.acosix-keycloak.sessionToSsoCache`
- `cache.acosix-keycloak.principalToSessionCache`
- `cache.acosix-keycloak.sessionToPrincipalCache`
- `cache.acosix-keycloak.ticketTokenCache`
By default, all caches have been configured to use a `maxItems` value of `10000`, and are set to be distributed in case either Alfresco Enterprise or the aldica addon is used to enable distributed caching.

80
docs/Reference-Share.md Normal file
View File

@ -0,0 +1,80 @@
# Share Reference
## Keycloak Configuration
By installing the addon on the Repository tier and allowing user + password logins to be supported, Alfresco Share will automatically and transparently authenticate users against Keycloak when a login occurs via the default login form. Installing the addon on the Share tier enables extended support for single sign-on (SSO) authentication directly on the Share tier. When installed, support for Keycloak SSO authentication is pre-enabled by the default configuration bundled with the addon, and only requires the enablement of `external-auth` on the `alfresco` remote connector to be effectively activated. Adding an additional `Keycloak` configuration section in the `share-config-custom.xml` file allows to complement / modify the default configuration. The section is split into two primary sub-elements - the `keycloak-auth-config`, which handles configuration specific to features implemented as part of this addon, and `keycloak-adapter-config`, which handles configuration relating to the Keycloak adapter library used to integrate with the Keycloak server. The general structure of the Keycloak configuration section is demonstrated with the following XML snippet:
```xml
<config evaluator="string-compare" condition="Keycloak">
<keycloak-auth-config>
<!-- options -->
</keycloak-auth-config>
<keycloak-adapter-config>
<!-- options -->
</keycloak-adapter-config>
</config>
```
The configuration options for the `keycloak-adapter-config` sub-element are [documented separately](./Reference-Adapter.md) as they are nearly identical / consistent across both Repository and Share layers of the addon. The following lists the configuration elements that are supported for the `keycloak-auth-config`. All options are simply specified as elements with plain text context.
| Property | Default Value | Description |
| --- | ---: | --- |
| `enable-sso-filter` | `true` | Flag determining whether the SSO authentication handling logic is enabled - only if this is enabled (and `external-auth` configured for the main `alfresco` remote connector) will any of the functionality of the Share addon work. |
| `enhance-login-form` | `true` | Flag determining whether an additional "Log in via SSO" button is to be included in the Share login form |
| `force-keycloak-sso` | `false` | Flag determining whether SSO authentication should be forced, meaning users are automatically redirected for authentication to Keycloak and the login form is only accessible by using a direct URL access bypass |
| `body-buffer-limit` | `10485760` | Size limit for request bodies that can be cached / stored if a request needs to be redirected to Keycloak for SSO authentication - requests larger than this limit will fail and require that the client first authenticate in a simple request, and use either authentication tickets or HTTP session cookies to perform the payload request re-using the established authentication |
| `session-mapper-limit` | `10000` | Size limit (in number of sessions) of the in-memory mapper of HTTP and SSO session IDs in order to allow back-channel logout requests to be properly handled. As HTTP sessions are not replicated in default Alfresco Share, the session mapper only handles local sessions for an individual Share node. |
| `ignore-default-filter` | `true` | Flag determining whether the default SSO filter should be ignored / skipped when `enable-sso-filter` is enabled, in order to avoid functionality conflicts, e.g. via redundant handling of `Authorization` HTTP headers. |
| `perform-token-exchange` | `true` | Flag determining whether RFC 8693 OAuth 2.0 Token Exchange is to be performed to delegate user authentication to the Repository-tier. |
| `alfresco-resource-name` | `alfresco` | Technical name of the client configured for the Repository-tier - this value is used to perform the RFC 8693 OAuth 2.0 Token Exchange and **must** be identical to the corresponding value configured in the Repository subsystem for Keycloak.. |
## Remote Configuration
Similar to Alfresco's out-of-the-box SSO mechanisms for Share, the use of Keycloak for SSO requires that the Remote endpoint configuration be changed to use the `/alfresco/wcs` endpoint instead of the default `/alfresco/s` endpoint. Additionally, a special connector must be used to properly use the access token to authenticate against the Alfresco Repository, and the `external-auth` flag set to `true`. This can all be done by adding a section like the following:
```xml
<config evaluator="string-compare" condition="Remote">
<remote>
<connector>
<id>alfrescoCookie</id>
<name>Alfresco Connector</name>
<description>Connects to an Alfresco instance using cookie-based authentication and awareness of Keycloak access tokens</description>
<class>de.acosix.alfresco.keycloak.share.remote.AccessTokenAwareSlingshotAlfrescoConnector</class>
</connector>
<endpoint>
<id>alfresco</id>
<name>Alfresco - user access</name>
<description>Access to Alfresco Repository WebScripts that require user authentication</description>
<connector-id>alfrescoCookie</connector-id>
<endpoint-url>http://localhost:8080/alfresco/wcs</endpoint-url>
<identity>user</identity>
<external-auth>true</external-auth>
</endpoint>
<endpoint>
<id>alfresco-feed</id>
<name>Alfresco Feed</name>
<description>Alfresco Feed - supports basic HTTP authentication via the EndPointProxyServlet</description>
<connector-id>alfrescoCookie</connector-id>
<endpoint-url>http://localhost:8080/alfresco/wcs</endpoint-url>
<basic-auth>true</basic-auth>
<identity>user</identity>
<external-auth>true</external-auth>
</endpoint>
<endpoint>
<id>alfresco-api</id>
<parent-id>alfresco</parent-id>
<name>Alfresco Public API - user access</name>
<description>Access to Alfresco Repository Public API that require user authentication. This makes use of the authentication
that is provided by parent 'alfresco' endpoint.
</description>
<connector-id>alfrescoCookie</connector-id>
<endpoint-url>http://localhost:8080/alfresco/api</endpoint-url>
<identity>user</identity>
<external-auth>true</external-auth>
</endpoint>
</remote>
</config>
```

4
docs/Simple-Configuration.md
View File

@ -107,7 +107,7 @@ The following core configuration properties can be set (more extensive list in t
## Alfresco Share
The Keycloak support in Alfresco Share is configured via the standard `share-config-custom.xml` file. Just by isntalling the module into Share and its packaged module default file, support for Keycloak authentication is pre-enabled. By configuring an additional `Keycloak` configuration section in the `share-config-custom.xml`, the default configuration can be complemented / modified. Its configuration is split into two sub-elements - the `keycloak-auth-config`, which handles configuration specific to features implemented as part of this addon, and `keycloak-adapter-config`, which handles configuration relating to the Keycloak adapter library used to integrate with the Keycloak server. The latter section shares / supports identical configuration properties as the `keycloak.adapter.???` properties in the Repository subsystem.
By installing the addon on the Repository tier and allowing user + password logins to be supported, Alfresco Share will automatically and transparently authenticate users against Keycloak when a login occurs via the default login form. Installing the addon on the Share tier enables extended support for single sign-on (SSO) authentication directly on the Share tier. When installed, support for Keycloak SSO authentication is pre-enabled by the default configuration bundled with the addon, and only requires the enablement of `external-auth` on the `alfresco` remote connector to be effectively activated. Adding an additional `Keycloak` configuration section in the `share-config-custom.xml` file allows to complement / modify the default configuration. The section is split into two primary sub-elements - the `keycloak-auth-config`, which handles configuration specific to features implemented as part of this addon, and `keycloak-adapter-config`, which handles configuration relating to the Keycloak adapter library used to integrate with the Keycloak server. The latter section uses identical configuration properties as the Repository subsystem (all properties with the `keycloak.adapter.` key prefix).
The following showcases an example configuration block:
```xml
@ -140,7 +140,7 @@ The following showcases an example configuration block:
**Note**: When the `enable-sso-filter` is set to `true`, the Keycloak authentication subsystem must be enabled on the Alfresco Repository for correct operation.
Similar to Alfresco's out-of-the-box SSO mechanisms for Share, the use of Keycloak for SSO requires that the Remote endpoint configuration be changed to use the `/alfresco/wcs` endpoint instead of the default `/alfresco/s` endpoint. Additionally, a special connector must be used to properly use the access token to authenticate against the Alfresco Repository. This can all be done by adding a section like the following:
Similar to Alfresco's out-of-the-box SSO mechanisms for Share, the use of Keycloak for SSO requires that the Remote endpoint configuration be changed to use the `/alfresco/wcs` endpoint instead of the default `/alfresco/s` endpoint. Additionally, a special connector must be used to properly use the access token to authenticate against the Alfresco Repository, and the `external-auth` flag set to `true`. This can all be done by adding a section like the following:
```xml
<config evaluator="string-compare" condition="Remote">