You are viewing a plain text version of this content. The canonical link for it is here.
Posted to oak-commits@jackrabbit.apache.org by an...@apache.org on 2023/05/16 16:15:58 UTC
[jackrabbit-oak] branch trunk updated: OAK-10245 : Document OAK-10173
This is an automated email from the ASF dual-hosted git repository.
angela pushed a commit to branch trunk
in repository https://gitbox.apache.org/repos/asf/jackrabbit-oak.git
The following commit(s) were added to refs/heads/trunk by this push:
new 1b07fcb454 OAK-10245 : Document OAK-10173
1b07fcb454 is described below
commit 1b07fcb454e1dab5275800c8778a6532436a6bf6
Author: angela <an...@adobe.com>
AuthorDate: Tue May 16 18:15:48 2023 +0200
OAK-10245 : Document OAK-10173
---
.../markdown/security/authentication/default.md | 10 ++--
oak-doc/src/site/markdown/security/user/default.md | 59 +++++++++++++---------
.../src/site/markdown/security/user/differences.md | 9 ++--
3 files changed, 44 insertions(+), 34 deletions(-)
diff --git a/oak-doc/src/site/markdown/security/authentication/default.md b/oak-doc/src/site/markdown/security/authentication/default.md
index 771d2ee2e6..44535fd05f 100644
--- a/oak-doc/src/site/markdown/security/authentication/default.md
+++ b/oak-doc/src/site/markdown/security/authentication/default.md
@@ -158,7 +158,7 @@ With Oak 1.0 impersonation is implemented as follows:
along with the current `AuthInfo` object.
3. these `ImpersonationCredentials` are passed to `Repository.login`
-Whether or not impersonation succeeds consequently both depends on the authentication
+If impersonation succeeds consequently both depends on the authentication
setup and on some implementation specific validation that make sure the
editing session is allowed to impersonate the user identified by the credentials
passed to the impersonate call.
@@ -170,23 +170,23 @@ with `ImpersonationCredentials` and applies the following logic:
as long as the user is still valid (i.e. exists and has not been disabled).
- **Regular Impersonation**: Impersonation another user will only succeed if
the impersonated user is valid (i.e. exists and is not disabled) _and_ the
- the user associated with the editing session is allowed to impersonate this
+ user associated with the editing session is allowed to impersonate this
user. The latter depends on the [User Management](../user.html) implementation
- specifically on the return value of `User.getImpersonation().allows(Subject subject)`.
+ specifically on the return value of `User.getImpersonation().allows(Subject subject)`. See [User Management : The Default Implementation](../user/default.html) for details.
##### ImpersonationCredentials
Since the implementation of `Session.impersonate` no longer uses `SimpleCredentials`
to transport the original `Subject` but rather performs the login with dedicated
[ImpersonationCredentials], impersonation is no longer restricted to `SimpleCredentials`
-being passed to `Session#impersonate` call. Instead the specified credentials are
+being passed to `Session#impersonate` call. Instead, the specified credentials are
passed to a new instance of `ImpersonationCredentials` delegating the evaluation
and validation of the specified `Credentials` to the configured login module(s).
This modification will not affect applications that used JCR API to impersonate
a given session. Note however that applications relying on the Jackrabbit
implementation and manually creating `SimpleCredentials` with a
-`SecurityConstants.IMPERSONATOR_ATTRIBUTE`, would need to be refactor after
+`SecurityConstants.IMPERSONATOR_ATTRIBUTE`, would need to be refactored after
migration to Oak.
##### Impersonation with Custom Authentication Setup
diff --git a/oak-doc/src/site/markdown/security/user/default.md b/oak-doc/src/site/markdown/security/user/default.md
index 14deb362db..108f625d66 100644
--- a/oak-doc/src/site/markdown/security/user/default.md
+++ b/oak-doc/src/site/markdown/security/user/default.md
@@ -25,7 +25,7 @@ content repository. In contrast to Jackrabbit 2.x, which by default used a singl
dedicated workspace for user/group data, this data will as of Oak 1.0 be stored
separately for each JCR workspace.
-Consequently the `UserManager` associated with the editing sessions, performs
+Consequently, the `UserManager` associated with the editing sessions, performs
all actions with this editing session. This corresponds to the behavior as defined
the alternative implementation present with Jackrabbit 2.x ((see Jackrabbit 2.x `UserPerWorkspaceUserManager`).
@@ -139,16 +139,24 @@ import. Other differences compared to Jackrabbit 2.x:
Since Oak 1.1.0 the default user management and authentication implementation
provides password expiry and initial password change.
-By default these features are disabled. See section [Password Expiry and Force Initial Password Change](expiry.html)
+By default, these features are disabled. See section [Password Expiry and Force Initial Password Change](expiry.html)
for details.
#### Password History
Since Oak 1.3.3 the default user management implementation provides password
-history support. By default this feature is disabled.
+history support. By default, this feature is disabled.
See section [Password History](history.html) for details.
+#### Impersonation
+The default implementation of the [Impersonation] interface comes with the following limitations and features:
+
+- only user principals can be granted impersonation
+- every user can impersonate itself
+- the admin user always can impersonate all users (and therefore cannot be granted impersonation)
+- the [Configuration](#configuration) allows to define a list of user or group principals that can impersonate all users (since Oak 1.54.0, see [OAK-10173])
+
<a name="representation"></a>
### Representation in the Repository
@@ -234,27 +242,27 @@ as of OAK 1.0:
#### Configuration Parameters supported by the default implementation
-| Parameter | Type | Default |
-|-------------------------------------|---------|----------------------------------------------|
-| `PARAM_ADMIN_ID` | String | "admin" |
-| `PARAM_OMIT_ADMIN_PW` | boolean | false |
-| `PARAM_ANONYMOUS_ID` | String | "anonymous" (nullable) |
-| `PARAM_USER_PATH` | String | "/rep:security/rep:authorizables/rep:users" |
-| `PARAM_GROUP_PATH` | String | "/rep:security/rep:authorizables/rep:groups" |
-| `PARAM_DEFAULT_DEPTH` | int | 2 |
-| `PARAM_PASSWORD_HASH_ALGORITHM` | String | "SHA-256" |
-| `PARAM_PASSWORD_HASH_ITERATIONS` | int | 1000 |
-| `PARAM_PASSWORD_SALT_SIZE` | int | 8 |
-| `PARAM_AUTHORIZABLE_NODE_NAME` | AuthorizableNodeName | AuthorizableNodeName#DEFAULT |
-| `PARAM_AUTHORIZABLE_ACTION_PROVIDER`| AuthorizableActionProvider | DefaultAuthorizableActionProvider |
-| `PARAM_SUPPORT_AUTOSAVE` | boolean | false |
-| `PARAM_IMPORT_BEHAVIOR` | String ("abort", "ignore", "besteffort") | "ignore" |
-| `PARAM_PASSWORD_MAX_AGE` | int | 0 |
-| `PARAM_PASSWORD_INITIAL_CHANGE` | boolean | false |
-| `PARAM_PASSWORD_HISTORY_SIZE` | int (upper limit: 1000) | 0 |
-| `PARAM_CACHE_EXPIRATION` | long | 0 |
-| `PARAM_ENABLE_RFC7613_USERCASE_MAPPED_PROFILE`| boolean | false |
-| | | |
+| Parameter | Type | Default | Description |
+|-------------------------------------|---------|----------------------------------------------|-------------|
+| `PARAM_ADMIN_ID` | String | "admin" ||
+| `PARAM_OMIT_ADMIN_PW` | boolean | false ||
+| `PARAM_ANONYMOUS_ID` | String | "anonymous" (nullable) ||
+| `PARAM_USER_PATH` | String | "/rep:security/rep:authorizables/rep:users" ||
+| `PARAM_GROUP_PATH` | String | "/rep:security/rep:authorizables/rep:groups" ||
+| `PARAM_DEFAULT_DEPTH` | int | 2 ||
+| `PARAM_PASSWORD_HASH_ALGORITHM` | String | "SHA-256" ||
+| `PARAM_PASSWORD_HASH_ITERATIONS` | int | 1000 ||
+| `PARAM_PASSWORD_SALT_SIZE` | int | 8 ||
+| `PARAM_AUTHORIZABLE_NODE_NAME` | AuthorizableNodeName | AuthorizableNodeName#DEFAULT ||
+| `PARAM_AUTHORIZABLE_ACTION_PROVIDER`| AuthorizableActionProvider | DefaultAuthorizableActionProvider ||
+| `PARAM_SUPPORT_AUTOSAVE` | boolean | false ||
+| `PARAM_IMPORT_BEHAVIOR` | String ("abort", "ignore", "besteffort") | "ignore" ||
+| `PARAM_PASSWORD_MAX_AGE` | int | 0 ||
+| `PARAM_PASSWORD_INITIAL_CHANGE` | boolean | false ||
+| `PARAM_PASSWORD_HISTORY_SIZE` | int (upper limit: 1000) | 0 ||
+| `PARAM_CACHE_EXPIRATION` | long | 0 | Number of milliseconds until the internal [principal cache](../principal/cache.html) expires. If not set or equal/lower than zero no cache is created/evaluated. |
+| `PARAM_ENABLE_RFC7613_USERCASE_MAPPED_PROFILE`| boolean | false ||
+| `PARAM_IMPERSONATOR_PRINCIPAL_NAMES` | String | {} | List of users who can impersonate and groups whose members can impersonate any user (since Oak 1.54.0, [OAK-10173]). |
The following configuration parameters present with the default implementation in Jackrabbit 2.x are no longer supported and will be ignored:
@@ -328,3 +336,6 @@ implementation.
[UserAuthenticationFactory]: /oak/docs/apidocs/org/apache/jackrabbit/oak/spi/security/user/UserAuthenticationFactory.html
[Authentication]: /oak/docs/apidocs/org/apache/jackrabbit/oak/spi/security/authentication/Authentication.html
[OAK-6072]: https://issues.apache.org/jira/browse/OAK-6072
+[OAK-10173]: https://issues.apache.org/jira/browse/OAK-10173
+[Impersonation]: /oak/docs/apidocs/org/apache/jackrabbit/api/security/user/Impersonation.html
+
diff --git a/oak-doc/src/site/markdown/security/user/differences.md b/oak-doc/src/site/markdown/security/user/differences.md
index 5a5a90c988..a5b7a5cc79 100644
--- a/oak-doc/src/site/markdown/security/user/differences.md
+++ b/oak-doc/src/site/markdown/security/user/differences.md
@@ -67,11 +67,9 @@ invalid transient modifications.
The user query is expected to work as in Jackrabbit 2.x with the following notable
bug fixes:
-* `QueryBuilder#setScope(String groupID, boolean declaredOnly)` now also works properly
- for the everyone group (see [OAK-949])
-* `QueryBuilder#impersonates(String principalName)` works properly for the admin
- principal which are specially treated in the implementation of the `Impersonation`
- interface (see [OAK-1183]).
+* `QueryBuilder#setScope(String groupID, boolean declaredOnly)` now also works properly for the `everyone` group (see [OAK-949])
+* `QueryBuilder#impersonates(String principalName)` works properly for the admin principal which are specially treated in the implementation of the `Impersonation` interface (see [OAK-1183]).
+* `QueryBuilder#impersonates(String principalName)` respects the `PARAM_IMPERSONATOR_PRINCIPAL_NAMES` configuration option (see [OAK-10173])
#### Additional Functionality
@@ -133,4 +131,5 @@ in Jackrabbit 2.x are no longer supported and will be ignored:
[OAK-949]: https://issues.apache.org/jira/browse/OAK-949
[OAK-1183]: https://issues.apache.org/jira/browse/OAK-1183
+[OAK-10173]: https://issues.apache.org/jira/browse/OAK-10173
[everyone]: /oak/docs/apidocs/org/apache/jackrabbit/oak/spi/security/principal/EveryonePrincipal.html