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

Update WIP docs with latest config changes

Browse Source
This commit is contained in:
AFaust 2021-10-19 12:00:27 +02:00
parent cdf9520bd0
commit 1cb1e571ac
2 changed files with 19 additions and 15 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

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

@ -50,6 +50,7 @@ The following technical authentication configuration properties are supported by
| `enabled` | `true` | Flag determining whether the default property mapping is enabled - mapping of properties for person nodes is technically extensible, and in some cases, the default handling may need to be disabled | | `enabled` | `true` | Flag determining whether the default property mapping is enabled - mapping of properties for person nodes is technically extensible, and in some cases, the default handling may need to be disabled |
| `mapNull` | `true` | Flag determining whether `null` values in specific fields of a token should still be mapped to the corresponding person property - if disabled, mapping of person properties will not remove previously mapped values from Alfresco person nodes if the value has been removed without replacement in Keycloak | | `mapNull` | `true` | Flag determining whether `null` values in specific fields of a token should still be mapped to the corresponding person property - if disabled, mapping of person properties will not remove previously mapped values from Alfresco person nodes if the value has been removed without replacement in Keycloak |
| `mapGivenName` | `true` | Flag determining whether the `givenName` token attribute should be mapped as `cm:firstName` | | `mapGivenName` | `true` | Flag determining whether the `givenName` token attribute should be mapped as `cm:firstName` |
| `mapMiddleName` | `true` | Flag determining whether the `middleName` token attribute should be mapped as `cm:middleName` |
| `mapFamilyName` | `true` | Flag determining whether the `familyName` token attribute should be mapped as `cm:lastName` | | `mapFamilyName` | `true` | Flag determining whether the `familyName` token attribute should be mapped as `cm:lastName` |
| `mapEmail` | `true` | Flag determining whether the `email` token attribute should be mapped as `cm:email` | | `mapEmail` | `true` | Flag determining whether the `email` token attribute should be mapped as `cm:email` |
| `mapPhoneNumber` | `true` | Flag determining whether the `phoneNumber` token attribute should be mapped | | `mapPhoneNumber` | `true` | Flag determining whether the `phoneNumber` token attribute should be mapped |
@ -66,6 +67,7 @@ The following synchronisation configuration properties are supported by the subs
| `enabled` | `true` | Flag determining whether general synchronisation functionality is enabled | | `enabled` | `true` | Flag determining whether general synchronisation functionality is enabled |
| `user` | | Name of a user account to be used to perform synchronisation-related calls to Keycloak - if not set, the subsystem will use the configured adapter client credentials to use the service account of the client (service account must have been enabled / set up in Keycloak) | | `user` | | Name of a user account to be used to perform synchronisation-related calls to Keycloak - if not set, the subsystem will use the configured adapter client credentials to use the service account of the client (service account must have been enabled / set up in Keycloak) |
| `password` | | Password for the user account to be used to perform synchronisation-related calls to Keycloak| | `password` | | Password for the user account to be used to perform synchronisation-related calls to Keycloak|
| `requiredClientScopes` | | Comma-separated list of required client scopes to be requested for the Keycloak token used for authentication on Keycloak API - this may be necessary if an optional client scope has been configured to include/map the required `realm-management` client roles + audience used in Keycloak for access checking |
| `personLoadBatchSize` | `50` | Number of users to retrieve from Keycloak in a single admin API call | | `personLoadBatchSize` | `50` | Number of users to retrieve from Keycloak in a single admin API call |
| `groupLoadBatchSize` | `50` | Number of groups to retrieve from Keycloak in a single admin API call | | `groupLoadBatchSize` | `50` | Number of groups to retrieve from Keycloak in a single admin API call |
@ -123,6 +125,9 @@ The following role mapping configuration properties are supported by the subsyst
| Property | Default Value | Description | | Property | Default Value | Description |
| --- | ---: | --- | | --- | ---: | --- |
| `user` | | Name of a user account to be used to perform role-related calls to Keycloak - if not set, the subsystem will use the configured adapter client credentials to use the service account of the client (service account must have been enabled / set up in Keycloak) |
| `password` | | Password for the user account to be used to perform role-related calls to Keycloak|
| `requiredClientScopes` | | Comma-separated list of required client scopes to be requested for the Keycloak token used for authentication on Keycloak API - this may be necessary if an optional client scope has been configured to include/map the required `realm-management` client roles + audience used in Keycloak for access checking |
| `mapRoles` | `true` | Flag determining whether role mapping is enabled | | `mapRoles` | `true` | Flag determining whether role mapping is enabled |
| `mapRealmRoles` | `true` | Flag determining whether roles in the context of the Keycloak realm should be mapped | | `mapRealmRoles` | `true` | Flag determining whether roles in the context of the Keycloak realm should be mapped |
| `mapResourceRoles` | `true` | Flag determining whether roles in the context of the configured Keycloak client should be mapped | | `mapResourceRoles` | `true` | Flag determining whether roles in the context of the configured Keycloak client should be mapped |

29
docs/Simple-Configuration.md
View File

@ -1,6 +1,6 @@
# Getting Started (Simple Configuration) # Getting Started (Simple Configuration)
This section provides the most basic configuration required to use this addon in combination with a Keycloak server (Keycloak version 11.0.2 used as a reference). This section provides the most basic configuration required to use this addon in combination with a Keycloak server (Keycloak version 15.0.2 used as a reference).
## Keycloak ## Keycloak
@ -34,32 +34,31 @@ Two clients must be created for the Alfresco Repository and Share. The following
- "Client Scopes" => "Setup" => "Default Client Scopes" - "Client Scopes" => "Setup" => "Default Client Scopes"
- `email` and `profile` (on the client for Alfresco Repository, if mapping of person from access / identity tokens should be supported) - `email` and `profile` (on the client for Alfresco Repository, if mapping of person from access / identity tokens should be supported)
- `roles` (on the client for Alfresco Repository, if mapping of authorities from Keycloak roles should be supported) - `roles` (on the client for Alfresco Repository, if mapping of authorities from Keycloak roles should be supported)
- "Mappers" => "Add Builtin" `groups` (on the client for Alfresco Repository, if mapping of authorities from Keycloak gropus should be supported) - "Mappers" => "Add Builtin" `groups` (on the client for Alfresco Repository, if mapping of authorities from Keycloak groups should be supported)
- "Service Account Roles" (on the client for Alfresco Repository, if active user / group synchronisation *or* the service/web script to expose roles for use e.g. in permission mangement should be supported) - "Service Account Roles" (on the client for Alfresco Repository, if active user / group synchronisation *or* the service/web script to expose roles for use e.g. in permission mangement should be supported)
- Assign client roles `query-groups`, `query-users`, `view-users` and `view-clients` on the client `realm-management` - Assign client roles `query-groups`, `query-users`, `view-users` and `view-clients` on the client `realm-management`
- Assign client roles `view-profile` and `manage-account` on the client `account`
If the RFC 8693 OAuth 2.0 Token Exchange functionality is to be used for delegation of user authentication from Share to the Repository, an authorisation policy needs to be defined on the pre-existing client `realm-management`. The necessary elements can all be configured in the "Authorization" tab in the configuration of that client. The following elements must be created (if not pre-existing) and/or associated with one another. If the RFC 8693 OAuth 2.0 Token Exchange functionality is to be used for delegation of user authentication from Share to the Repository, an authorisation policy needs to be defined on the pre-existing client `realm-management`. The necessary elements can all be configured in the "Authorization" tab in the configuration of that client. The following elements must be created (if not pre-existing) and/or associated with one another.
- "Authorization Scopes" `token-exchange` - "Authorization Scopes" `token-exchange`
- "Resources" `client.resource.&lt;idOfRepositoryClient&gt;` - "Resources" `client.resource.<idOfRepositoryClient>`
- "Type" `Client` - "Type" `Client`
- "Scopes" `view`, `map-roles-client-scope`, `configure`, `map-roles`, `manage`, `token-exchange`, `map-roles-composite` (`token-exchange` is required for the feature, the others are typically created by default when an optional Keycloak feature for simplified authorisation management is used - if these do not exist, they can be manually created in "Authorization Scopes") - "Scopes" `view`, `map-roles-client-scope`, `configure`, `map-roles`, `manage`, `token-exchange`, `map-roles-composite` (`token-exchange` is required for the feature, the others are typically created by default when an optional Keycloak feature for simplified authorisation management is used - if these do not exist, they can be manually created in "Authorization Scopes")
- "Permissions" - "Permissions"
- `view.permission.client.&lt;idOfRepositoryClient&gt;` - `view.permission.client.<idOfRepositoryClient>`
- `map-roles-client-scope.permission.client.&lt;idOfRepositoryClient&gt;` - `map-roles-client-scope.permission.client.<idOfRepositoryClient>`
- `configure.permission.client.&lt;idOfRepositoryClient&gt;` - `configure.permission.client.<idOfRepositoryClient>`
- `map-roles.permission.client.&lt;idOfRepositoryClient&gt;` - `map-roles.permission.client.<idOfRepositoryClient>`
- `manage.permission.client.&lt;idOfRepositoryClient&gt;` - `manage.permission.client.<idOfRepositoryClient>`
- `token-exchange.permission.client.&lt;idOfRepositoryClient&gt;` - `token-exchange.permission.client.<idOfRepositoryClient>`
- `map-roles-composite.permission.client.&lt;idOfRepositoryClient&gt;` - `map-roles-composite.permission.client.<idOfRepositoryClient>`
- "Policies" `&lt;idOfRepositoryClient&gt;-token-exchange` - "Policies" `<idOfRepositoryClient>-token-exchange`
- "Logic" `Positive` - "Logic" `Positive`
- "Clients" `&lt;idOfShareClient&gt;` - "Clients" `<idOfShareClient>`
### Roles / Groups ### Roles / Groups
Unless disabled, the Repository module of this addon can synchronise users / groups, and map groups or roles from the access / identity token as authorities of the user. In the default configuration of the module, all users and groups are synchronised, all roles defined as realm-level roles will be mapped as `ROLE_KEYCLOAK_&lt;realm&gt;_&lt;role&gt;`, and all client roles of the Alfresco Repository client are mapped as `ROLE_KEYCLOAK_&lt;realm&gt;_&lt;idOfRepositoryClient&gt;_&lt;role&gt;. The following special cases are handled by default with regards to Alfresco Repository client roles (all of these roles do not exist by default and must be created if they are to be used): Unless disabled, the Repository module of this addon can synchronise users / groups, and map groups or roles from the access / identity token as authorities of the user. In the default configuration of the module, all users and groups are synchronised, all roles defined as realm-level roles will be mapped as `ROLE_KEYCLOAK_<realm>_<role>`, and all client roles of the Alfresco Repository client are mapped as `ROLE_KEYCLOAK_<realm>_<idOfRepositoryClient>_<role>`. The following special cases are handled by default with regards to Alfresco Repository client roles (all of these roles do not exist by default and must be created if they are to be used):
- `admin` mapped as `ROLE_ADMINISTRATOR` - `admin` mapped as `ROLE_ADMINISTRATOR`
- `guest` mapped as `ROLE_GUEST` - `guest` mapped as `ROLE_GUEST`
@ -102,7 +101,7 @@ The following core configuration properties can be set (more extensive list in t
| `...directAuthHost` | | Alternative base URL for the Keycloak server (excluding path) to be used for calls from Alfresco to Keycloak - useful e.g. in scenarios where the regular `auth-server-url` can not be resolved by the Alfresco Repository host or round-trips via a public gateway / proxy should be avoided | | `...directAuthHost` | | Alternative base URL for the Keycloak server (excluding path) to be used for calls from Alfresco to Keycloak - useful e.g. in scenarios where the regular `auth-server-url` can not be resolved by the Alfresco Repository host or round-trips via a public gateway / proxy should be avoided |
| `...realm` | `alfresco` | Technical name of the Keycloak realm | | `...realm` | `alfresco` | Technical name of the Keycloak realm |
| `...resource` | `alfresco` | Technical name of the client set up for the Alfresco Repository in the realm | | `...resource` | `alfresco` | Technical name of the client set up for the Alfresco Repository in the realm |
| `...keycloak.adapter.credentials.secret` | | Shared secret for validation of authorisation codes / access tokens | | `...credentials.secret` | | Shared secret for validation of authorisation codes / access tokens |
| `...verify-token-audience` | `true` | Flag enabling validation of the audience specified in an access token - must be disabled if Share or any other application which authenticates users via Keycloak is not delegating user authentication using RFC 8693 OAuth 2.0 Token Exchange | | `...verify-token-audience` | `true` | Flag enabling validation of the audience specified in an access token - must be disabled if Share or any other application which authenticates users via Keycloak is not delegating user authentication using RFC 8693 OAuth 2.0 Token Exchange |
## Alfresco Share ## Alfresco Share