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 2016/02/10 18:12:27 UTC
svn commit: r1729662 [3/3] - in
/jackrabbit/oak/trunk/oak-doc/src/site/markdown: ./ oak_api/ security/
security/accesscontrol/ security/authentication/ security/authorization/
security/permission/ security/principal/ security/privilege/ security/user/
Added: jackrabbit/oak/trunk/oak-doc/src/site/markdown/security/user/default.md
URL: http://svn.apache.org/viewvc/jackrabbit/oak/trunk/oak-doc/src/site/markdown/security/user/default.md?rev=1729662&view=auto
==============================================================================
--- jackrabbit/oak/trunk/oak-doc/src/site/markdown/security/user/default.md (added)
+++ jackrabbit/oak/trunk/oak-doc/src/site/markdown/security/user/default.md Wed Feb 10 17:12:26 2016
@@ -0,0 +1,311 @@
+<!--
+ Licensed to the Apache Software Foundation (ASF) under one or more
+ contributor license agreements. See the NOTICE file distributed with
+ this work for additional information regarding copyright ownership.
+ The ASF licenses this file to You under the Apache License, Version 2.0
+ (the "License"); you may not use this file except in compliance with
+ the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+-->
+
+User Management : The Default Implementation
+--------------------------------------------------------------------------------
+
+### General Notes
+
+The default user management implementation stores user/group information in the
+content repository. In contrast to Jackrabbit 2.x, which by default used a single,
+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
+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`).
+
+* The Oak implementation is build on the Oak API. This allows for double usage as
+ extension to the JCR API as well as within the Oak layer (aka SPI).
+* The `UserManager` is always associated with the same JCR workspace as the editing
+ `Session` from which the class has been obtained.
+* Changes made to the user management API are always transient and require `Session#save()` to be persisted.
+* In case of any failure during user management related write operations the API
+ consumer is in charge of specifically revert pending or invalid transient modifications
+ or calling `Session#refresh(false)`.
+
+### Differences wrt Jackrabbit 2.x
+
+A summary of all changes with respect to the former implementation present with
+Jackrabbit 2.x is present in the corresponding [section](differences.html).
+
+### Built-in Users and Special Groups
+
+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 management implementation in OAK comes with an initializer that
+creates the following builtin user accounts:
+
+#### Administrator
+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).
+
+##### 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 regular login with `SimpleCredentials`.
+The proper way to obtain a guest session is:
+
+ Repository#login(new GuestCredentials(), wspName);
+
+See section [Authentication](../authentication.html) for further information about
+guest login.
+
+#### Everyone Group
+
+The default user management implementation in Oak contains special handling for
+the optional group that represents _everyone_, which is marked by the reserved
+name [everyone] and corresponds to the `EveryonePrincipal`.
+
+This special group always contains all Authorizable as member and cannot be edited
+with user management API. As of OAK this fact is consistently reflected in all
+group membership related methods. See also [Principal Management](../principal.html).
+
+### User Management Operations
+
+#### Reading Authorizables
+
+##### 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.
+
+##### equals() and hashCode()
+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.
+
+#### Creating Authorizables
+* 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.
+
+#### Query
+
+See section [Searching Users and Groups](query.html) for details.
+
+#### Group Membership
+
+See section [Group Membership](membership.html) for details.
+
+#### 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`
+
+See also `PARAM_SUPPORT_AUTOSAVE` below; while this should not be needed if
+application code has been written against the Jackrabbit API (and thus testing if
+auto-save mode is enabled or not) this configuration option can be used as last resort.
+
+#### XML Import
+As of Oak 1.0 user and group nodes can be imported both with Session and Workspace
+import. Other differences compared to Jackrabbit 2.x:
+
+* 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 2.x core it used to fail immediately.
+* The `BestEffort` behavior is now also implemented for the import of impersonators (was missing in Jackrabbit /2.x).
+
+#### Password Expiry and Force Initial Password Change
+
+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. The corresponding configuration options
+are
+
+- `PARAM_PASSWORD_MAX_AGE`: number of days until the password expires.
+- `PARAM_PASSWORD_INITIAL_CHANGE`: boolean flag to enable this feature.
+
+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. The corresponding configuration option is
+
+- `PARAM_PASSWORD_HISTORY_SIZE`: number of changed passwords to remember.
+
+See section [Password History](history.html) for details.
+
+
+### User/Group Representation in the Repository
+
+The following block lists the built-in node types related to user management tasks:
+
+ [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:Group] > rep:Authorizable, rep:MemberReferences
+ + rep:members (rep:Members) = rep:Members multiple protected VERSION /* @deprecated */
+ + rep:membersList (rep:MemberReferencesList) = rep:MemberReferencesList protected COPY
+
+ /** @since oak 1.0 */
+ [rep:MemberReferences]
+ - rep:members (WEAKREFERENCE) protected multiple < 'rep:Authorizable'
+
+ /** @since oak 1.0 */
+ [rep:MemberReferencesList]
+ + * (rep:MemberReferences) = rep:MemberReferences protected COPY
+
+ /** @deprecated since oak 1.0 */
+ [rep:Members]
+ orderable
+ + * (rep:Members) = rep:Members protected multiple
+ - * (WEAKREFERENCE) protected < 'rep:Authorizable'
+
+<a name="validation"/>
+### Validation
+
+The consistency of this content structure is asserted by a dedicated `UserValidator`.
+The corresponding errors are all of type `Constraint` with the following codes:
+
+| Code | Message |
+|-------------------|----------------------------------------------------------|
+| 0020 | Admin user cannot be disabled |
+| 0021 | Invalid jcr:uuid for authorizable (creation) |
+| 0022 | Changing Id, principal name after creation |
+| 0023 | Invalid jcr:uuid for authorizable (mod) |
+| 0024 | Password may not be plain text |
+| 0025 | Attempt to remove id, principalname or pw |
+| 0026 | Mandatory property rep:principalName missing |
+| 0027 | The admin user cannot be removed |
+| 0028 | Attempt to create outside of configured scope |
+| 0029 | Intermediate folders not rep:AuthorizableFolder |
+| 0030 | Missing uuid for group (check for cyclic membership) |
+| 0031 | Cyclic group membership |
+| 0032 | Attempt to set password with system user |
+| 0033 | Attempt to add rep:pwd node to a system user |
+
+<a name="configuration"/>
+### Configuration
+
+The following user management specific methods are present with the [UserConfiguration]
+as of OAK 1.0:
+
+* getUserManager: Obtain a new user manager instance
+
+#### 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 |
+| | | |
+
+The following configuration parameters present with the default implementation in Jackrabbit 2.x are no longer supported and will be ignored:
+
+* `compatibleJR16`
+* `autoExpandTree`
+* `autoExpandSize`
+* `groupMembershipSplitSize`
+
+The optional `cacheExpiration` configuration option listed above is discussed in
+detail in section [Caching Results of Principal Resolution](../principal/cache.html).
+It is not related to user management s.str. but affects the implementation
+specific `PrincipalProvider` implementation exposed by `UserConfiguration.getUserPrincipalProvider`.
+
+<a name="pluggability"/>
+### Pluggability
+
+Within the default user management implementation the following parts can be
+modified or extended at runtime by providing corresponding OSGi services or passing
+appropriate configuration parameters exposing the custom implementations:
+
+- `AuthorizableActionProvider`: Defines the authorizable actions, see [Authorizable Actions](user/authorizableaction.html).
+- `AuthorizableNodeName`: Defines the generation of the authorizable node names
+ in case the user management implementation stores user information in the repository.
+ See [Authorizable Node Name Generation](user/authorizablenodename.html).
+- `UserAuthenticationFactory`: see below
+
+#### UserAuthenticationFactory : Authenticating Users
+
+Since Oak 1.1.5 the default user management implementation allows to configure
+and thus replace the default [UserAuthenticationFactory], which links the user
+management implementation with the authentication (specifically the [uid/pw-login](../authentication/default.html#user_authentication))
+as it exposes the [Authentication] implementation to be used for verification
+of the specified credentials according to details provided by a given user management
+implementation.
+
+##### Examples
+
+###### Example UserAuthenticationFactory
+
+ @Component()
+ @Service(UserAuthenticationFactory.class)
+ public class MyUserAuthenticationFactory implements UserAuthenticationFactory {
+
+ private Set<String> ids = Collections.emptySet();
+
+ public MyUserAuthenticationFactory() {}
+
+ //--------------------------------------< UserAuthenticationFactory >---
+ @Override
+ Authentication getAuthentication(@Nonnull UserConfiguration configuration, @Nonnull Root root, @Nullable String userId) {
+ final boolean canAuthenticate = (userId != null && ids.contains(userId));
+ return new Authentication() {
+ @Override
+ public boolean authenticate(@Nullable Credentials credentials) {
+ return canAuthenticate;
+ }
+ };
+ }
+
+ //------------------------------------------------< SCR Integration >---
+ @Activate
+ private void activate(Map<String, Object> properties) {
+ ids = ImmutableSet.copyOf(PropertiesUtil.toStringArray(properties.get("ids"), new String[0]));
+ }
+ }
+
+
+<!-- hidden references -->
+[everyone]: /oak/docs/apidocs/org/apache/jackrabbit/oak/spi/security/principal/EveryonePrincipal.html#NAME
+[UserConfiguration]: /oak/docs/apidocs/org/apache/jackrabbit/oak/spi/security/user/UserConfiguration.html
+[UserAuthenticationFactory]: /oak/docs/apidocs/org/apache/jackrabbit/oak/spi/security/user/UserAuthenticationFactory.html
Modified: jackrabbit/oak/trunk/oak-doc/src/site/markdown/security/user/differences.md
URL: http://svn.apache.org/viewvc/jackrabbit/oak/trunk/oak-doc/src/site/markdown/security/user/differences.md?rev=1729662&r1=1729661&r2=1729662&view=diff
==============================================================================
--- jackrabbit/oak/trunk/oak-doc/src/site/markdown/security/user/differences.md (original)
+++ jackrabbit/oak/trunk/oak-doc/src/site/markdown/security/user/differences.md Wed Feb 10 17:12:26 2016
@@ -66,7 +66,9 @@ The user query is expected to work as in
#### XML Import
-* 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 2.x core it used to fail immediately.
+* 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 2.x core it used to fail immediately.
* The `BestEffort` behavior is now also implemented for the import of impersonators (was missing in Jackrabbit /2.x).
* Oak also supports workspace import for authorizables
@@ -112,11 +114,4 @@ in Jackrabbit 2.x are no longer supporte
* "compatibleJR16"
* "autoExpandTree"
* "autoExpandSize"
-* "groupMembershipSplitSize"
-
-<!-- hidden references -->
-[OAK-118]: https://issues.apache.org/jira/browse/OAK-118
-[OAK-482]: https://issues.apache.org/jira/browse/OAK-482
-[OAK-793]: https://issues.apache.org/jira/browse/OAK-793
-[OAK-949]: https://issues.apache.org/jira/browse/OAK-949
-[OAK-1183]: https://issues.apache.org/jira/browse/OAK-1183
\ No newline at end of file
+* "groupMembershipSplitSize"
\ No newline at end of file