jackrabbit-oak-issues mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From "angela (JIRA)" <j...@apache.org>
Subject [jira] [Comment Edited] (OAK-791) UserManagement: Document changes wrt Jackrabbit 2
Date Thu, 03 Oct 2013 14:50:42 GMT

    [ https://issues.apache.org/jira/browse/OAK-791?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=13713475#comment-13713475
] 

angela edited comment on OAK-791 at 10/3/13 2:50 PM:
-----------------------------------------------------

h4. 1. Characteristics of the Default Implementation

The default user management implementation present with OAK always stores user/group information
in the workspace associated with the editing Session (see jr2 UserPerWorkspaceUserManager).
The implementation of a user mgt variant corresponding to Jackrabbit's default
UserManagerImpl is blocked by missing workspace handling (see OAK-118).

The current user manager has the following characteristics that differ from the corresponding
Jackrabbit implementation:

h5. General

- Changes made to the user management API are always transient and require Session#save()
to be persisted.
- In case of a failure Session#refresh is no longer called in order to prevent reverting other
changes unrelated to the user mgt operation. Consequently it's the responsibility of the API
consumer to specifically revert pending or invalid transient modifications.
- The implementation is no longer built on top of the JCR API but instead directly acts on
Tree and PropertyState defined by the OAK API. This move allows to make use of the user management
API within the OAK layer (aka SPI).

h5. User/Group creation

- The rep:password property is no longer defined to be mandatory. Therefore a new user might
be created without specifying a password. Note however, that User#changePassword does not
allow to remove the password property.
- UserManager#createGroup(Principal) will no longer generate a groupID in case the principal
name collides with an existing user or group ID. This has been considered redundant as the
Jackrabbit API in the mean time added UserManager#createGroup(String groupID).
- Since OAK is designed to scale with flat hierarchies the former configuration options 'autoExpandTree'
and 'autoExpandSize' are no longer supported.

h5. Handling of the Authorizable ID

- As of OAK the node type definition of rep:Authorizable defines a new property rep:authorizableId
which is intended to store the ID of a user or group.
- The default implementation comes with a dedicated property index for rep:authorizableId
which asserts the uniqueness of that ID.
- Authorizable#getID returns the string value contained in rep:authorizableID and for backwards
compatibility falls back on the node name in case the ID property is missing.
- The name of the authorizable node is generated based on a configurable implementation of
the 'AuthorizableNodeName' interface (see configuration section below). By  default it uses
the ID as name hint and includes a conversion to a valid JCR node name.

h5. Equals and HashCode for Authorizables

The implementation of Object#equals() and Object#hashCode() for user and groups slightly differs
from Jackrabbit 2.x. It no longer relies on the sameness of the underlaying JCR node but only
compares IDs and the user manager instance.

h5. The 'everyone' Group

As in Jackrabbit 2.x the OAK implementation contains special handling for the optional group
corresponding to the {{EveryonePrincipal}} which always contains all {{Authorizable}}s as
member. As of OAK this fact is consistently reflected in all group membership related methods.

_TODO: OAK-949 (query)_

h5. Autosave behavior

Due to the nature of the UserManager (see above) we decided to drop the auto-save behavior
in the default implementation present with OAK. Consequently,

- UserManager#autoSave(boolean) throws UnsupportedRepositoryOperationException
- UserManager#isAutoSave() always returns false

h5. XML Import

As of OAK 1.0 user and group nodes can be imported both with Session and Workspace import.
The difference compare to Jackrabbit are listed below:

- Importing an authorizable to another tree than the configured user/group node will only
failed upon save (-> see UserValidator during the Root#commit). With Jackrabbit core it
used to fail immediately.
- NEW: The BestEffort behavior is now also implemented for the import of impersonators (was
missing in JR).
- NEW: Workspace Import

h5. Group Membership

_TODO_ (see OAK-482)

h4. 2. Builtin Users

The setup of builtin user and group accounts is triggered by the configured WorkspaceInitializer
associated with the user management configuration (see Configuration section below).
The default user mgt implementation in OAK comes with an initializer that creates the following
builtin user accounts (as in JR2):

h5. Administrator user 

The admin user is always being created. The ID of this user is retrieved from the user configuration
parameter PARAM_ADMIN_ID, which defaults to "admin". 
As of OAK 1.0 however the administrator user might be created without initial password forcing
the application to set the password upon start (see PARAM_OMIT_ADMIN_PW configuration parameter).

h5. Anonymous user

In contrast to Jackrabbit 2.x the anonymous (or guest) user is optional. Creation will be
skipped if the value of the PARAM_ANONYMOUS_ID configuration parameter is null or empty. 
Note, that the anonymous user will always be created without specifying a password in order
to prevent login with SimpleCredentials. 
The proper way to obtain a guest session is (see also OAK-793):

{code}
   Repository#login(new GuestCredentials(), wspName);
{code}

h4. 3. Authorizable Actions

The former internal interface AuthorizableAction has been slightly adjusted to match OAK requirements
and is now part of the public OAK SPI interfaces. In contrast to Jackrabbit-core the AuthorizableAction(s)
now operate directly on the OAK API which eases the handling of implementation specific tasks
such as writing protected items.

The example implementations of the AuthorizableAction interface present with OAK match the
implementations available with JR2:
- AccessControlAction: set up permission for new authorizables
- PasswordAction: simplistic password verification upon user creation and pw modification
- PasswordChangeAction: verifies that the new password is different from the old one
- ClearMembershipAction: clear group membership upon removal of an authorizable.

As in jackrabbit core the actions are executed with the editing session and the target operation
will fail if any of the configured actions fails (e.g. due to insufficient permissions by
the editing OAK ContentSession).

In order to match the OAK repository configuration setup and additional interface AuthorizableActionProvider
has been introduced. See section Configuration below.

h4. 4. Node Type Definitions

The built-in node types related to user management tasks have been modified as follows:

{code}
[rep:Authorizable] > mix:referenceable, nt:hierarchyNode
  abstract
  + * (nt:base) = nt:unstructured VERSION
  - rep:principalName  (STRING) protected mandatory
  - rep:authorizableId (STRING) protected /* @since oak 1.0 */
  - * (UNDEFINED)
  - * (UNDEFINED) multiple

[rep:Members]
  orderable
  + * (rep:Members) = rep:Members protected multiple /* FIXME: SNS definition */
  - * (WEAKREFERENCE) protected < 'rep:Authorizable' /* FIXME: OAK-482 */
{code}

h4. 5. API Extensions

The OAK project introduces the following user management related public
interfaces and classes:

org.apache.jackrabbit.oak.spi.security.user:

- AuthorizableNodeName: Defines the generation of the authorizable node names in case the
user management implementation stores user information in the repository.
- AuthorizableType: Ease handling with the different authorizable types.
- UserConstants: Constants (NOTE: OAK names/paths)

org.apache.jackrabbit.oak.spi.security.user.action:

- AuthorizableAction (see above)
- AuthorizableActionProvider (see above)

org.apache.jackrabbit.oak.spi.security.user.util:

- PasswordUtil: utilities for password generation. This utility corresponds to the internal
jackrabbit utility. As of OAK it also supports Password-Based Key Derivation Function 2 (PBKDF2)
function for password generation.
- UserUtil: utilities related to general user mgt tasks.

h4. 6. Configuration

* User Configuration []
** getUserManager: Obtain a new user manager instance
** getAuthorizableActionProvider: Obtain a new instance of the AuthorizableActionProvider
(see 3)

* Configuration Parameters supported by the default implementation
** PARAM_ADMIN_ID: String, default: "admin"
** PARAM_OMIT_ADMIN_PW: boolean, default: false
** PARAM_ANONYMOUS_ID: String, default: "anonymous", nullable
** PARAM_USER_PATH: String, default: "/rep:security/rep:authorizables/rep:users" 
** PARAM_GROUP_PATH: String, default: "/rep:security/rep:authorizables/rep:groups", 
** PARAM_DEFAULT_DEPTH: int, default: 2
** PARAM_GROUP_MEMBERSHIP_SPLIT_SIZE: int, default: -
** PARAM_PASSWORD_HASH_ALGORITHM: String, default: "SHA-256"
** PARAM_PASSWORD_HASH_ITERATIONS: int, default: 1000
** PARAM_PASSWORD_SALT_SIZE: int, default: 8
** PARAM_AUTHORIZABLE_NODE_NAME: AuthorizableNodeName, default: AuthorizableNodeName#DEFAULT

The following configuration parameters present with the default implementation in Jackrabbit
2.x are no longer supported and will be ignored:
* "compatibleJR16"
* "autoExpandTree"
* "autoExpandSize"


h4. 7 References

_TODO_


was (Author: anchela):
h4. 1. Characteristics of the Default Implementation

The default user management implementation present with OAK always stores user/group information
in the workspace associated with the editing Session (see jr2 UserPerWorkspaceUserManager).
The implementation of a user mgt variant corresponding to Jackrabbit's default
UserManagerImpl is blocked by missing workspace handling (see OAK-118).

The current user manager has the following characteristics that differ from the corresponding
Jackrabbit implementation:

h5. General

- Changes made to the user management API are always transient and require Session#save()
to be persisted.
- In case of a failure Session#refresh is no longer called in order to prevent reverting other
changes unrelated to the user mgt operation. Consequently it's the responsibility of the API
consumer to specifically revert pending or invalid transient modifications.
- The implementation is no longer built on top of the JCR API but instead directly acts on
Tree and PropertyState defined by the OAK API. This move allows to make use of the user management
API within the OAK layer (aka SPI).

h5. User/Group creation

- The rep:password property is no longer defined to be mandatory. Therefore a new user might
be created without specifying a password. Note however, that User#changePassword does not
allow to remove the password property.
- UserManager#createGroup(Principal) will no longer generate a groupID in case the principal
name collides with an existing user or group ID. This has been considered redundant as the
Jackrabbit API in the mean time added UserManager#createGroup(String groupID).
- Since OAK is designed to scale with flat hierarchies the former configuration options 'autoExpandTree'
and 'autoExpandSize' are no longer supported.

h5. Handling of the Authorizable ID

- As of OAK the node type definition of rep:Authorizable defines a new property rep:authorizableId
which is intended to store the ID of a user or group.
- The default implementation comes with a dedicated property index for rep:authorizableId
which asserts the uniqueness of that ID.
- Authorizable#getID returns the string value contained in rep:authorizableID and for backwards
compatibility falls back on the node name in case the ID property is missing.
- The name of the authorizable node is generated based on a configurable implementation of
the 'AuthorizableNodeName' interface (see configuration section below). By  default it uses
the ID as name hint and includes a conversion to a valid JCR node name.

h5. Equals and HashCode for Authorizables

The implementation of Object#equals() and Object#hashCode() for user and groups slightly differs
from Jackrabbit 2.x. It no longer relies on the sameness of the underlaying JCR node but only
compares IDs and the user manager instance.

h5. The 'everyone' Group

As in Jackrabbit 2.x the OAK implementation contains special handling for the optional group
corresponding to the {{EveryonePrincipal}} which always contains all {{Authorizable}}s as
member. As of OAK this fact is consistently reflected in all group membership related methods.

_TODO: OAK-949 (query)_

h5. Autosave behavior

Due to the nature of the UserManager (see above) we decided to drop the auto-save behavior
in the default implementation present with OAK. Consequently,

- UserManager#autoSave(boolean) throws UnsupportedRepositoryOperationException
- UserManager#isAutoSave() always returns false

h5. XML Import

As of OAK 1.0 user and group nodes can be imported both with Session and Workspace import.
The difference compare to Jackrabbit are listed below:

- Importing an authorizable to another tree than the configured user/group node will only
failed upon save (-> see UserValidator during the Root#commit). With Jackrabbit core it
used to fail immediately.
- NEW: The BestEffort behavior is now also implemented for the import of impersonators (was
missing in JR).
- NEW: Workspace Import

h5. Group Membership

_TODO_ (see OAK-482)

h4. 2. Builtin Users

The setup of builtin user and group accounts is triggered by the configured WorkspaceInitializer
associated with the user management configuration (see Configuration section below).
The default user mgt implementation in OAK comes with an initializer that creates the following
builtin user accounts (as in JR2):

h5. Administrator user 

The admin user is always being created. The ID of this user is retrieved from the user configuration
parameter PARAM_ADMIN_ID, which defaults to "admin". 
As of OAK 1.0 however the administrator user might be created without initial password forcing
the application to set the password upon start (see PARAM_OMIT_ADMIN_PW configuration parameter).

h5. Anonymous user

In contrast to Jackrabbit 2.x the anonymous (or guest) user is optional. Creation will be
skipped if the value of the PARAM_ANONYMOUS_ID configuration parameter is null or empty. 
Note, that the anonymous user will always be created without specifying a password in order
to prevent login with SimpleCredentials. 
The proper way to obtain a guest session is (see also OAK-793):

{code}
   Repository#login(new GuestCredentials(), wspName);
{code}

h4. 3. Authorizable Actions

The former internal interface AuthorizableAction has been slightly adjusted to match OAK requirements
and is now part of the public OAK SPI interfaces. In contrast to Jackrabbit-core the AuthorizableAction(s)
now operate directly on the OAK API which eases the handling of implementation specific tasks
such as writing protected items.

The example implementations of the AuthorizableAction interface present with OAK match the
implementations available with JR2:
- AccessControlAction: set up permission for new authorizables
- PasswordAction: simplistic password verification upon user creation and pw modification
- ClearMembershipAction: clear group membership upon removal of an authorizable.

As in jackrabbit core the actions are executed with the editing session and the target operation
will fail if any of the configured actions fails (e.g. due to insufficient permissions by
the editing OAK ContentSession).

In order to match the OAK repository configuration setup and additional interface AuthorizableActionProvider
has been introduced. See section Configuration below.

h4. 4. Node Type Definitions

The built-in node types related to user management tasks have been modified as follows:

{code}
[rep:Authorizable] > mix:referenceable, nt:hierarchyNode
  abstract
  + * (nt:base) = nt:unstructured VERSION
  - rep:principalName  (STRING) protected mandatory
  - rep:authorizableId (STRING) protected /* @since oak 1.0 */
  - * (UNDEFINED)
  - * (UNDEFINED) multiple

[rep:Members]
  orderable
  + * (rep:Members) = rep:Members protected multiple /* FIXME: SNS definition */
  - * (WEAKREFERENCE) protected < 'rep:Authorizable' /* FIXME: OAK-482 */
{code}

h4. 5. API Extensions

The OAK project introduces the following user management related public
interfaces and classes:

org.apache.jackrabbit.oak.spi.security.user:

- AuthorizableNodeName: Defines the generation of the authorizable node names in case the
user management implementation stores user information in the repository.
- AuthorizableType: Ease handling with the different authorizable types.
- UserConstants: Constants (NOTE: OAK names/paths)

org.apache.jackrabbit.oak.spi.security.user.action:

- AuthorizableAction (see above)
- AuthorizableActionProvider (see above)

org.apache.jackrabbit.oak.spi.security.user.util:

- PasswordUtil: utilities for password generation. This utility corresponds to the internal
jackrabbit utility. As of OAK it also supports Password-Based Key Derivation Function 2 (PBKDF2)
function for password generation.
- UserUtil: utilities related to general user mgt tasks.

h4. 6. Configuration

* User Configuration []
** getUserManager: Obtain a new user manager instance
** getAuthorizableActionProvider: Obtain a new instance of the AuthorizableActionProvider
(see 3)

* Configuration Parameters supported by the default implementation
** PARAM_ADMIN_ID: String, default: "admin"
** PARAM_OMIT_ADMIN_PW: boolean, default: false
** PARAM_ANONYMOUS_ID: String, default: "anonymous", nullable
** PARAM_USER_PATH: String, default: "/rep:security/rep:authorizables/rep:users" 
** PARAM_GROUP_PATH: String, default: "/rep:security/rep:authorizables/rep:groups", 
** PARAM_DEFAULT_DEPTH: int, default: 2
** PARAM_GROUP_MEMBERSHIP_SPLIT_SIZE: int, default: -
** PARAM_PASSWORD_HASH_ALGORITHM: String, default: "SHA-256"
** PARAM_PASSWORD_HASH_ITERATIONS: int, default: 1000
** PARAM_PASSWORD_SALT_SIZE: int, default: 8
** PARAM_AUTHORIZABLE_NODE_NAME: AuthorizableNodeName, default: AuthorizableNodeName#DEFAULT

The following configuration parameters present with the default implementation in Jackrabbit
2.x are no longer supported and will be ignored:
* "compatibleJR16"
* "autoExpandTree"
* "autoExpandSize"


h4. 7 References

_TODO_

> UserManagement: Document changes wrt Jackrabbit 2
> -------------------------------------------------
>
>                 Key: OAK-791
>                 URL: https://issues.apache.org/jira/browse/OAK-791
>             Project: Jackrabbit Oak
>          Issue Type: Sub-task
>          Components: jcr
>            Reporter: angela
>            Assignee: angela
>




--
This message was sent by Atlassian JIRA
(v6.1#6144)

Mime
View raw message