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 md...@apache.org on 2014/05/07 18:33:32 UTC
svn commit: r1593063 - in /jackrabbit/oak/branches/1.0: ./ oak-doc/
oak-doc/src/site/markdown/security/
oak-doc/src/site/markdown/security/authentication/
oak-doc/src/site/markdown/security/user/
Author: mduerig
Date: Wed May 7 16:33:31 2014
New Revision: 1593063
URL: http://svn.apache.org/r1593063
Log:
OAK-301: Document Oak
Merged r1593048
Added:
jackrabbit/oak/branches/1.0/oak-doc/src/site/markdown/security/authentication/usersync.md
- copied unchanged from r1593048, jackrabbit/oak/trunk/oak-doc/src/site/markdown/security/authentication/usersync.md
jackrabbit/oak/branches/1.0/oak-doc/src/site/markdown/security/user/authorizableaction.md
- copied unchanged from r1593048, jackrabbit/oak/trunk/oak-doc/src/site/markdown/security/user/authorizableaction.md
Modified:
jackrabbit/oak/branches/1.0/ (props changed)
jackrabbit/oak/branches/1.0/oak-doc/ (props changed)
jackrabbit/oak/branches/1.0/oak-doc/src/site/markdown/security/authentication.md
jackrabbit/oak/branches/1.0/oak-doc/src/site/markdown/security/authentication/differences.md
jackrabbit/oak/branches/1.0/oak-doc/src/site/markdown/security/authentication/externalloginmodule.md
jackrabbit/oak/branches/1.0/oak-doc/src/site/markdown/security/authentication/identitymanagement.md
jackrabbit/oak/branches/1.0/oak-doc/src/site/markdown/security/authentication/tokenmanagement.md
jackrabbit/oak/branches/1.0/oak-doc/src/site/markdown/security/overview.md
jackrabbit/oak/branches/1.0/oak-doc/src/site/markdown/security/user.md
Propchange: jackrabbit/oak/branches/1.0/
------------------------------------------------------------------------------
Merged /jackrabbit/oak/trunk:r1593048
Propchange: jackrabbit/oak/branches/1.0/oak-doc/
------------------------------------------------------------------------------
Merged /jackrabbit/oak/trunk/oak-doc:r1593048
Modified: jackrabbit/oak/branches/1.0/oak-doc/src/site/markdown/security/authentication.md
URL: http://svn.apache.org/viewvc/jackrabbit/oak/branches/1.0/oak-doc/src/site/markdown/security/authentication.md?rev=1593063&r1=1593062&r2=1593063&view=diff
==============================================================================
--- jackrabbit/oak/branches/1.0/oak-doc/src/site/markdown/security/authentication.md (original)
+++ jackrabbit/oak/branches/1.0/oak-doc/src/site/markdown/security/authentication.md Wed May 7 16:33:31 2014
@@ -30,7 +30,7 @@ The following section is copied and adap
The authentication process within the `LoginModule` proceeds in two distinct phases,
login and commit phase:
-__A. Login Phase__
+_Phase 1: Login_
1. In the first phase, the `LoginModule`'s `login` method gets invoked by the `LoginContext`'s `login` method.
2. The `login` method for the `LoginModule` then performs the actual authentication (prompt for and verify a
@@ -40,7 +40,7 @@ __A. Login Phase__
retry the authentication or introduce delays. The responsibility of such tasks belongs to the application.
If the application attempts to retry the authentication, the `LoginModule`'s `login` method will be called again.
-__B. Commit Phase__
+_Phase 2: Commit_
1. In the second phase, if the `LoginContext`'s overall authentication succeeded (the relevant REQUIRED, REQUISITE,
SUFFICIENT and OPTIONAL LoginModules succeeded), then the `commit` method for the `LoginModule` gets invoked.
@@ -60,102 +60,171 @@ flags indicating how to treat their beha
JAAS defines the following module flags:
(The following section is copied and adapted from the javadoc of [javax.security.auth.login.Configuration])
-**Required**
-: The LoginModule is required to succeed.
- If it succeeds or fails, authentication still continues to proceed down the LoginModule list.
-
-**Requisite**
-: The LoginModule is required to succeed.
- If it succeeds, authentication continues down the LoginModule list.
- If it fails, control immediately returns to the application (authentication does not proceed down the LoginModule
- list).
-
-**Sufficient**
-: The LoginModule is not required to succeed.
- If it does succeed, control immediately returns to the application (authentication does not proceed down the
- LoginModule list).
- If it fails, authentication continues down the LoginModule list.
-
-**Optional**
-: The LoginModule is not required to succeed.
- If it succeeds or fails, authentication still continues to proceed down the LoginModule list.
+- **Required**: The LoginModule is required to succeed. If it succeeds or fails,
+ authentication still continues to proceed down the LoginModule list.
+- **Requisite**: The LoginModule is required to succeed. If it succeeds, authentication
+ continues down the LoginModule list. If it fails, control immediately returns
+ to the application (authentication does not proceed down the LoginModule list).
+- **Sufficient**: The LoginModule is not required to succeed. If it does succeed,
+ control immediately returns to the application (authentication does not proceed
+ down the LoginModule list). If it fails, authentication continues down the LoginModule list.
+- **Optional**: The LoginModule is not required to succeed. If it succeeds or
+ fails, authentication still continues to proceed down the LoginModule list.
The overall authentication succeeds **only** if **all** Required and Requisite LoginModules succeed. If a Sufficient
LoginModule is configured and succeeds, then only the Required and Requisite LoginModules prior to that Sufficient
LoginModule need to have succeeded for the overall authentication to succeed. If no Required or Requisite LoginModules
are configured for an application, then at least one Sufficient or Optional LoginModule must succeed.
-### JCR and Oak Authentication
+### JCR Authentication
Within the scope of JCR `Repository.login` is used to authenticate a given user.
This method either takes a `Credentials` argument if the validation is performed
by the repository itself or `null` in case the user has be pre-authenticated by
an external system.
+Furthermore JCR defines two types of `Credentials` implementations:
+
+- [javax.jcr.GuestCredentials]: used to obtain a "guest", "public" or "anonymous" session.
+- [javax.jcr.SimpleCredentials]: used to login a user with a userId and password.
+
+
+### Oak Authentication
+
#### Differences wrt Jackrabbit 2.x
-see the corresponding [documentation](authentication/differences.html).
+See section [differences](authentication/differences.html) for complete list of
+differences wrt authentication between Jackrabbit 2.x and Oak.
#### Guest Login
-_todo_
+The proper way to obtain an guest session as of Oak is as specified by JSR 283:
-#### Logins with Credentials
+ String wspName = null;
+ Session anonymous = repository.login(new GuestCredentials(), wspName);
-_todo_
+As of Oak 1.0 `Repository#login()` and `Repository#login(null, wspName)` is no
+longer treated as guest login. This behavior of Jackrabbit-core is violating the
+specification, which defines that null-login should be used for those cases where
+the authentication process is handled outside of the repository (see [Pre-Authentication](authentication/preauthentication.html)).
-#### Impersonation
+Similarly, any special treatment that Jackrabbit core applied for the guest (anonymous)
+user has been omitted altogether from the default [LoginModuleImpl]. In the default
+setup the built-in anonymous user will be created without any password. Therefore
+explicitly uid/pw login using the anonymous userId will no longer work. This behavior
+is now consistent with the default login of any other user which doesn't have a
+password set.
-_todo_
+##### Guest Login Module
-#### Pre Authenticated Logins
+The aim of the [GuestLoginModule] implementation is to provide backwards compatibility
+with Jackrabbit 2.x with respect to the guest (anonymous) login: the `GuestLoginModule`
+can be added as _optional_ entry to the chain of login modules in the JAAS (or
+corresponding OSGi) configuration.
-Oak provides two different mechanisms to create pre-authentication that doesn't
-involve the repositories internal authentication mechanism for credentials
-validation.
+Example JAAS Configuration:
-- Pre-Authentication combined with Login Module Chain
-- Pre-Authentication without Repository Involvement
+ jackrabbit.oak {
+ org.apache.jackrabbit.oak.spi.security.authentication.GuestLoginModule optional;
+ org.apache.jackrabbit.oak.security.authentication.user.LoginModuleImpl required;
+ };
-See section [Pre-Authentication Login](authentication/preauthentication.html) for
-further details and examples.
+The behavior of the `GuestLoginModule` is as follows:
+
+*Phase 1: Login*
+
+- tries to retrieve JCR credentials from the [CallbackHandler] using the [CredentialsCallback]
+- in case no credentials could be obtained it pushes a new instance of [GuestCredentials] to the shared stated
+ and **returns** `true`
+- otherwise it **returns** `false`
+
+*Phase 2: Commit*
-### Oak Login Module Implementations
+- if the phase 1 succeeded it will add the `GuestCredentials` created above and
+ `EveryonePrincipal` the `Subject` in phase 2 of the login process and **returns** `true`
+- otherwise it **returns** `false`
-#### Abstract Login Module
+#### UserId/Password Login
_todo_
-#### Default Login Module
+##### Default Login Module
-The behavior of the default login module is relatively simple, so it is explained first:
+The [LoginModuleImpl] defines a regular userId/password login and requires a
+repository setup that supports [User Management](user.html) and is designed to
+supports the following `Credentials`:
-upon login():
+- `SimpleCredentials`
+- `GuestCredentials` (see above)
+- `ImpersonationCredentials` (see below)
+
+This login module implementations behaves as follows:
+
+*Phase 1: Login*
* if a user does not exist in the repository (i.e. cannot be provided by the user manager) it **returns `false`**.
* if an authorizable with the respective userId exists but is a group or a disabled users, it **throws `LoginException`**
* if a user exists in the repository and the credentials don't match, it **throws `LoginException`**
-* if a user exists in the repository and the credentials match, it **returns `true`**
+* if a user exists in the repository and the credentials match, it **returns `true`**
* also, it adds the credentials to the shared state
- * also, it adds the login name to the shared state
+ * also, it adds the login name to the shared state
* also, it calculates the principals and adds them to the private state
* also, it adds the credentials to the private state
-upon commit():
+*Phase 2: Commit*
* if the private state contains the credentials and principals, it adds them (both) to the subject and **returns `true`**
* if the private state does not contain credentials and principals, it clears the state and **returns `false`**
-#### Token Login Module
+#### Impersonation
_todo_
-#### Guest Login Module
+#### Token Login
-_todo_
+See section [Token Authentication](authentication/tokenmanagement.html) for details
+regarding token based authentication.
+
+##### Token Login Module
+
+The `TokenLoginModule` is in charge of creating new login tokens and validate
+repository logins with `TokenCredentials`. The exact behavior of this login module is
+described in section [Token Authentication](authentication/tokenmanagement.html).
+
+
+#### Pre-Authenticated Login
+
+Oak provides two different mechanisms to create pre-authentication that doesn't
+involve the repositories internal authentication mechanism for credentials
+validation.
-#### External Login Module
+- Pre-Authentication combined with Login Module Chain
+- Pre-Authentication without Repository Involvement (aka `null` login)
+
+See section [Pre-Authentication Login](authentication/preauthentication.html) for
+further details and examples.
+
+#### External Login
+
+While the default setup in Oak is solely relying on repository functionality to
+ensure proper authentication it quite common to authenticate against different
+systems (e.g. LDAP). For those setups that wish to combine initial authentication
+against a third party system with repository functionality, Oak provides a default
+implementation with extension points:
+
+- [External Authentication](authentication/externalloginmodule.html): Summary of
+ the external authentication and details about the `ExternalLoginModule`.
+- [User and Group Synchronization](authentication/usersync.html): Details regarding
+ user and group synchronization as well as a list of configuration options provided
+ by the the default implementations present with Oak.
+- [Identity Management](authentication/identitymanagement.html): Further information regarding extenal identity management.
+- [LDAP Integration](authentication/ldap.html): How to make use of the `ExternalLoginModule`
+ with the LDAP identity provider implementation. This combination is aimed to replace
+ [com.day.crx.security.ldap.LDAPLoginModule], which relies on Jackrabbit internals
+ and will no longer work with Oak.
+
+##### External Login Module
The external login module is a base implementation that allows easy integration
of 3rd party authentication and identity systems, such as [LDAP](ldap.html). The
@@ -164,27 +233,72 @@ source and as a provider for users and g
the repository.
This login module implementation requires an valid `SyncHandler` and `IdentityProvider`
-to be present.
+to be present. The detailed behavior of the `ExternalLoginModule` is described in
+section [External Authentication](authentication/externalloginmodule.html).
-Further reading:
-- [External LoginModule and User Synchronization](authentication/externalloginmodule.html): Details regarding the login module and the associated interfaces as well as configuration of the default implementations present with Oak.
-- [LDAP Integration](authentication/ldap.html): How to make use of the `ExternalLoginModule` to authenticate against LDAP.
+### API Extension
-### Authentication related Interfaces and Extension Points in Oak
+#### Oak Authentication
-#### LoginContextProvider
+_todo_
+
+##### Abstract Login Module
_todo_
+org.apache.jackrabbit.oak.spi.security.authentication:
+
+- `LoginContextProvider`: Configurable provider of the `LoginContext` (see below)
+- `LoginContext`: Interface version of the JAAS LoginContext aimed to ease integration with non-JAAS components
+- `Authentication`: Aimed to validate credentials during the first phase of the (JAAS) login process.
+
#### Token Management
See section [token management](authentication/tokenmanagement.html) for details.
+- `TokenConfiguration`: Interface to obtain a `TokenProvider` instance.
+- `TokenProvider`: Interface to manage login tokens.
+- `TokenInfo`: Information related to a login token and token validity.
+
+#### User and Group Synchronization
+
+_todo_ [Synchronization](authentication/usersync.html)
+
#### External Identity Management
-See section [identity management](authentication/identitymanagement.html) for details.
+Oak in addition provides interfaces to ease custom implementation of the external
+authentication with optional user/group synchronization to the repository.
+
+See section [identity management](authentication/identitymanagement.html) and
+[External Login Module and User Synchronization](authentication/externalloginmodule.html) for details.
+
+
+### Configuration
+
+- [AuthenticationConfiguration]: _todo_ `getLoginContextProvider` -> configuration of the login context
+- [TokenConfiguration]: `getTokenProvider`. See section [Token Management](tokenmanagement.html) for details.
+
+#### JAAS Configuration Utilities
+There also exists a utility class that allows to obtain different
+`javax.security.auth.login.Configuration` for the most common setup [11]:
+
+- `ConfigurationUtil#getDefaultConfiguration`: default OAK configuration supporting uid/pw login configures `LoginModuleImpl` only
+
+- `ConfigurationUtil#getJackrabbit2Configuration`: backwards compatible configuration that provides the functionality covered by jackrabbit-core DefaultLoginModule, namely:
+
+ - `GuestLoginModule`: null login falls back to anonymous
+ - `TokenLoginModule`: covers token base authentication
+ - `LoginModuleImpl`: covering regular uid/pw login
+
<!-- references -->
[javax.security.auth.spi.LoginModule]: http://docs.oracle.com/javase/6/docs/api/javax/security/auth/spi/LoginModule.html
-[javax.security.auth.login.Configuration]: http://docs.oracle.com/javase/6/docs/api/javax/security/auth/login/Configuration.html
\ No newline at end of file
+[javax.security.auth.login.Configuration]: http://docs.oracle.com/javase/6/docs/api/javax/security/auth/login/Configuration.html
+[javax.jcr.GuestCredentials]: http://www.day.com/specs/javax.jcr/javadocs/jcr-2.0/javax/jcr/GuestCredentials.html
+[javax.jcr.SimpleCredentials]: http://www.day.com/specs/javax.jcr/javadocs/jcr-2.0/javax/jcr/SimpleCredentials.html
+[GuestLoginModule]: /oak/docs/apidocs/org/apache/jackrabbit/oak/spi/security/authentication/GuestLoginModule.html
+[LoginModuleImpl]: /oak/docs/apidocs/org/apache/jackrabbit/oak/security/authentication/user/LoginModuleImpl.html
+[com.day.crx.security.ldap.LDAPLoginModule]: http://dev.day.com/docs/en/crx/current/administering/ldap_authentication.html
+[AuthenticationConfiguration]: /oak/docs/apidocs/org/apache/jackrabbit/oak/spi/security/authentication/AuthenticationConfiguration.html
+[TokenConfiguration]: /oak/docs/apidocs/org/apache/jackrabbit/oak/spi/security/authentication/token/TokenConfiguration.html
\ No newline at end of file
Modified: jackrabbit/oak/branches/1.0/oak-doc/src/site/markdown/security/authentication/differences.md
URL: http://svn.apache.org/viewvc/jackrabbit/oak/branches/1.0/oak-doc/src/site/markdown/security/authentication/differences.md?rev=1593063&r1=1593062&r2=1593063&view=diff
==============================================================================
--- jackrabbit/oak/branches/1.0/oak-doc/src/site/markdown/security/authentication/differences.md (original)
+++ jackrabbit/oak/branches/1.0/oak-doc/src/site/markdown/security/authentication/differences.md Wed May 7 16:33:31 2014
@@ -16,48 +16,23 @@
-->
### Authentication : Differences wrt Jackrabbit 2.x
-#### 1. Characteristics of the Default Implementation
+#### Characteristics of the Default Implementation
##### Null Login
As of Oak 1.0 `Repository#login()` and `Repository#login(null, wspName)` is no
-longer treated as guest login. This behavior of Jackrabbit-core is violating the
-specification, which defines that null-login should be used for those cases where
-the authentication process is handled outside of the repository (-> see pre-authentication below).
-
-In order to get a full backwards compatible behavior OAK provides a specific
-`GuestLoginModule` [0] that can be added to the JAAS (or corresponding OSGI) configuration.
-
-Example JAAS Configuration:
-
- jackrabbit.oak {
- org.apache.jackrabbit.oak.spi.security.authentication.GuestLoginModule optional;
- org.apache.jackrabbit.oak.security.authentication.user.LoginModuleImpl required;
- };
-
+longer treated as guest login. In order to get backwards compatible behavior,
+Oak comes with a dedicated [GuestLoginModule] that can be added to the JAAS (or
+the corresponding OSGI) configuration.
##### Guest Login
-With respect to guest login (aka anonymous login) the OAK content repository
+With respect to guest login (aka anonymous login) the Oak content repository
out of the box contains the following modifications:
- null login != guest login
-- no anonymous login with uid/pw
-
-As explained in 1) the null login will not longer fall back to a guest login
-unless explicitly configured (-> `GuestLoginModule`).
-The proper way to obtain an guest session as of OAK is as specified by JSR 283:
-
- String wspName = null;
- Session anonymous = repository.login(new GuestCredentials(), wspName);
-
-Similarly, the special treatment that jackrabbit core applied for
-the guest (anonymous) user has been omitted altogether in OAK. In the
-default setup the anonymous user will created without any password. Therefore
-explicitly uid/pw login using the anonymous userId will no longer work.
-This behavior is now consistent with the default login of any other user
-which doesn't have a password set.
-
+- special password handling of the anonymous user has been dropped
+- the anonymous user by default doesn't have a password set
##### Pre-Authentication
@@ -70,19 +45,19 @@ for details and examples.
- Pre-Authentication without Repository Involvement: the `Subject` must be available
with the current `java.security.AccessControlContext`.
-#### 2. Impersonation
+#### Impersonation
##### Self-Impersonation (aka Cloning a Session)
As of OAK 1.0 the latest changes made to JSR 333 with respect to `Session#impersonate`
-have been adopted [3]: Any attempt to impersonate the same session (self-impersonation)
+have been adopted ([JSR_333-27]): Any attempt to impersonate the same session (self-impersonation)
will succeed as long as the user is still valid.
##### Impersonation Credentials
The OAK implementation of `Session#impersonate` no longer uses `SimpleCredentials`
to transport the original `Subject` but rather performs the login with dedicated
-`ImpersonationCredentials` [4].
+[ImpersonationCredentials].
With this change the impersonation feature no longer relies on `SimpleCredentials`
being passed to `Session#impersonate` call. Instead the specified credentials are
@@ -99,110 +74,33 @@ impersonate an existing session:
creds.setAttribute(SecurityConstants.IMPERSONATOR_ATTRIBUTE, sImpl.getSubject());
Session impersonated = sImpl.getRepository().login(jrImpCreds, sImpl.getWorkspace().getName());
-#### 3. Token based Authentication
-
-The token based authentication has been completely refactor in OAK.
-
-- Dedicated API for managing login tokens [5]
-- Pluggable configuration of the new token management API
-- Complete separation of token based authentication from regular
- uid/pw authentication into a separate `LoginModule` [6]
-
-The default implementation differs from jackrabbit as follows
-- token node is referenceable with a dedicated node type (rep:Token)
-- expiration and key properties are mandatory and protected
-- expiration time is obtained from `PARAM_TOKEN_EXPIRATION` specified in the login
-attributes and falls back to the same configuration parameter.
-
-The definition of the new built-in node type "rep:Token":
-
- [rep:Token] > mix:referenceable
- - rep:token.key (STRING) protected mandatory
- - rep:token.exp (DATE) protected mandatory
- - * (UNDEFINED) protected
- - * (UNDEFINED) multiple protected
-
-Please note the following difference with respect to Jackrabbit core:
-- the `TokenLoginModule` is responsible for creating new login tokens. Other login modules should not attempt to do so.
-- token characteristics such as expiration time only need to be configured with the `TokenLoginModule`
-- Other `LoginModule` implementations consequently no longer need to have the same config options set.
-
-
-#### 4. External Authentication
-
-While the default setup in OAK is solely relying on repository functionality to
-ensure proper authentication it quite common to authenticate against different
-systems (e.g. LDAP). For those setups that wish to combine initial authentication
-against a third party system with repository functionality, OAK provides some
-basic implementation and extension points [7] and ship an example setup for LDAP authentication.
-
-This is aimed to become the replacement for `com.day.crx.security.ldap.LDAPLoginModule` [8],
-which relies on jackrabbit internals and will no longer work with OAK.
-
-#### 5. API Extensions
-
-The OAK project introduces the following authenticated related service provider interfaces:
-
-org.apache.jackrabbit.oak.spi.security.authentication:
-
-- `LoginContextProvider`: Configurable provider of the `LoginContext` (see below)
-- `LoginContext`: Interface version of the JAAS LoginContext aimed to ease integration with non-JAAS components
-- `Authentication`: Aimed to validate credentials during the first phase of the (JAAS) login process.
-
-org.apache.jackrabbit.oak.spi.security.authentication.token:
-
-- `TokenConfiguration`: Interface to obtain a `TokenProvider` instance.
-- `TokenProvider`: Interface to manage login tokens.
-- `TokenInfo`: Information related to a login token and token validity.
-
-org.apache.jackrabbit.oak.spi.security.authentication.external:
-
-- interfaces to ease custom implementation of the external authentication with
- optional user/group synchronization to the repository (see [7]).
-
-#### 6. Configuration
-
-##### AuthenticationConfiguration [9]:
-- `getLoginContextProvider` -> configuration of the login context
-
-##### TokenConfiguration [10]:
-- `getTokenProvider`
-
-##### Utilities
-There also exists a utility class that allows to obtain different
-`javax.security.auth.login.Configuration` for the most common setup [11]:
-
-- `ConfigurationUtil#getDefaultConfiguration`: default OAK configuration supporting uid/pw login configures `LoginModuleImpl` only
-
-- `ConfigurationUtil#getJackrabbit2Configuration`: backwards compatible configuration that provides the functionality covered by jackrabbit-core DefaultLoginModule, namely:
-
- - `GuestLoginModule`: null login falls back to anonymous
- - `TokenLoginModule`: covers token base authentication
- - `LoginModuleImpl`: covering regular uid/pw login
-
-
-#### 7. References
-
-[0] http://svn.apache.org/repos/asf/jackrabbit/oak/trunk/oak-core/src/main/java/org/apache/jackrabbit/oak/spi/security/authentication/GuestLoginModule.java
-
-[1] http://svn.apache.org/repos/asf/jackrabbit/oak/trunk/oak-core/src/main/java/org/apache/jackrabbit/oak/spi/security/authentication/LoginContextProvider.java
-
-[2] http://svn.apache.org/repos/asf/jackrabbit/oak/trunk/oak-core/src/main/java/org/apache/jackrabbit/oak/spi/security/authentication/LoginContext.java
-
-[3] https://java.net/jira/browse/JSR_333-27
-
-[4] http://svn.apache.org/repos/asf/jackrabbit/oak/trunk/oak-core/src/main/java/org/apache/jackrabbit/oak/spi/security/authentication/ImpersonationCredentials.java
-
-[5] http://svn.apache.org/repos/asf/jackrabbit/oak/trunk/oak-core/src/main/java/org/apache/jackrabbit/oak/spi/security/authentication/token/
-
-[6] http://svn.apache.org/repos/asf/jackrabbit/oak/trunk/oak-core/src/main/java/org/apache/jackrabbit/oak/security/authentication/token/TokenLoginModule.java
-
-[7] http://svn.apache.org/repos/asf/jackrabbit/oak/trunk/oak-core/src/main/java/org/apache/jackrabbit/oak/spi/security/authentication/external/
-
-[8] http://dev.day.com/docs/en/crx/current/administering/ldap_authentication.html
-
-[9] http://svn.apache.org/repos/asf/jackrabbit/oak/trunk/oak-core/src/main/java/org/apache/jackrabbit/oak/spi/security/authentication/AuthenticationConfiguration.java
-
-[10] http://svn.apache.org/repos/asf/jackrabbit/oak/trunk/oak-core/src/main/java/org/apache/jackrabbit/oak/spi/security/authentication/token/TokenConfiguration.java
+#### Token based Authentication
-[11] http://svn.apache.org/repos/asf/jackrabbit/oak/trunk/oak-core/src/main/java/org/apache/jackrabbit/oak/spi/security/authentication/ConfigurationUtil.java
+The token based authentication has been completely refactor in Oak as described
+in section [Token Management](tokenmanagement.html). The default implementation
+differs from Jackrabbit as follows
+
+- token node is created with dedicated node type (rep:Token)
+- expiration and key properties are mandatory and protected properties
+- expiration time is obtained from `PARAM_TOKEN_EXPIRATION` is defined by
+ the token management API.
+
+As far as the token based authentication itself is concerned the Oak implementation
+contains the following changes compared to Jackrabbit 2.x:
+
+- token based authentication is completely separated from regular uid/pw authentication.
+- the dedicated [TokenLoginModule] is both responsible for creating new login tokens
+ performing the the authentication for [TokenCredentials] passed to the repository
+ login. Other login modules should not attempt to do so.
+- token characteristics such as expiration time only need to be configured with the
+ token management API; other `LoginModule` implementations no longer need to have
+ the same config options set.
+
+<!-- references -->
+
+[TokenLoginModule]: /oak/docs/apidocs/org/apache/jackrabbit/oak/security/authentication/token/TokenLoginModule.html
+[TokenCredentials]: http://svn.apache.org/repos/asf/jackrabbit/trunk/jackrabbit-api/src/main/java/org/apache/jackrabbit/api/security/authentication/token/TokenCredentials.java
+[com.day.crx.security.ldap.LDAPLoginModule]: http://dev.day.com/docs/en/crx/current/administering/ldap_authentication.html
+[GuestLoginModule]:/oak/docs/apidocs/org/apache/jackrabbit/oak/spi/security/authentication/GuestLoginModule.html
+[JSR_333-27]: https://java.net/jira/browse/JSR_333-27
+[ImpersonationCredentials]: /oak/docs/apidocs/org/apache/jackrabbit/oak/spi/security/authentication/ImpersonationCredentials.html
Modified: jackrabbit/oak/branches/1.0/oak-doc/src/site/markdown/security/authentication/externalloginmodule.md
URL: http://svn.apache.org/viewvc/jackrabbit/oak/branches/1.0/oak-doc/src/site/markdown/security/authentication/externalloginmodule.md?rev=1593063&r1=1593062&r2=1593063&view=diff
==============================================================================
--- jackrabbit/oak/branches/1.0/oak-doc/src/site/markdown/security/authentication/externalloginmodule.md (original)
+++ jackrabbit/oak/branches/1.0/oak-doc/src/site/markdown/security/authentication/externalloginmodule.md Wed May 7 16:33:31 2014
@@ -15,7 +15,7 @@
limitations under the License.
-->
-External Login Module and User Synchronization
+Authentication with the External Login Module
--------------------------------------------------------------------------------
### Overview
@@ -67,7 +67,7 @@ Note:
* users (and groups) that are synced from the 3rd party system contain a `rep:externalId` property. This allows to identify the external users and distinguish them from others.
* to reduce expensive syncing, the synced users and groups have sync timestamp `rep:lastSynced` and are considered valid for a configurable time. if they expire, they need to be validated against the 3rd party system again.
-##### Phase 1: Login
+_Phase 1: Login_
* if the user exists in the repository and is not an externally synced, **return `false`**
* if the user exists in the 3rd party system but the credentials don't match it **throws `LoginException`**
@@ -77,7 +77,7 @@ Note:
* and **returns `true`**
* if the user does not exist in the 3rd party system, checks if it needs to remove the user and then it **returns `false`**
-##### Phase 2: Commit
+_Phase 2: Commit_
* if there is no credentials in the private state, it **returns `false`**
* if there are credentials in the private state propagate the subject and **return `true`**
@@ -87,10 +87,9 @@ Note:
_todo_
-
-See [LDAP](ldap.html) for further information about the `LDAPIdentityProvider`
-implementation shipped with Oak.
-
+See [External Identity Management](identitymanagement.html) for further information
+regarding the identity management API defined by Oak. Section [LDAP](ldap.html)
+further describes the `LDAPIdentityProvider` implementation shipped with Oak.
#### User and Group Synchronization
@@ -98,27 +97,8 @@ The synchronization of users and groups
after a user is successfully authenticated against the IDP or if it's no longer
present on the IDP.
-Oak comes with a default implementation of the `SyncHandler` interface:
-[org.apache.jackrabbit.oak.spi.security.authentication.external.impl.DefaultSyncHandler].
-
-##### Configuration of the DefaultSyncHandler
-Oak provides a default synchronization handler that is configured via [DefaultSyncConfig]. The handler is configured either via OSGi or during manual [Repository Construction](../../construct.html).
-
-| Name | Property | Description |
-|-------------------------------|-------------------------------|------------------------------------------|
-| Sync Handler Name | `handler.name` | Name of this sync configuration. This is used to reference this handler by the login modules. |
-| User auto membership | `user.autoMembership` | List of groups that a synced user is added to automatically |
-| User Expiration Time | `user.expirationTime` | Duration until a synced user gets expired (eg. '1h 30m' or '1d'). |
-| User Membership Expiration | `user.membershipExpTime` | Time after which membership expires (eg. '1h 30m' or '1d'). |
-| User membership nesting depth | `user.membershipNestingDepth` | Returns the maximum depth of group nesting when membership relations are synced. A value of 0 effectively disables group membership lookup. A value of 1 only adds the direct groups of a user. This value has no effect when syncing individual groups only when syncing a users membership ancestry. |
-| User Path Prefix | `user.pathPrefix` | The path prefix used when creating new users. |
-| User property mapping | `user.propertyMapping` | List mapping definition of local properties from external ones. eg: 'profile/email=mail'.Use double quotes for fixed values. eg: 'profile/nt:primaryType="nt:unstructured" |
-| Group auto membership | `group.autoMembership` | List of groups that a synced group is added to automatically |
-| Group Expiration Time | `group.expirationTime` | Duration until a synced group expires (eg. '1h 30m' or '1d'). |
-| Group Path Prefix | `group.pathPrefix` | The path prefix used when creating new groups. |
-| Group property mapping | `group.propertyMapping` | List mapping definition of local properties from external ones. |
-| | | |
-
+See section [User Synchronization](usersync.html) for further details and a
+description of the default implementation.
### Example JAAS Configuration
@@ -128,4 +108,5 @@ used in a setup that not solely uses thi
_todo_
<!-- references -->
+
[DefaultSyncConfig]: /oak/docs/apidocs/org/apache/jackrabbit/oak/spi/security/authentication/external/impl/DefaultSyncConfig.html
Modified: jackrabbit/oak/branches/1.0/oak-doc/src/site/markdown/security/authentication/identitymanagement.md
URL: http://svn.apache.org/viewvc/jackrabbit/oak/branches/1.0/oak-doc/src/site/markdown/security/authentication/identitymanagement.md?rev=1593063&r1=1593062&r2=1593063&view=diff
==============================================================================
--- jackrabbit/oak/branches/1.0/oak-doc/src/site/markdown/security/authentication/identitymanagement.md (original)
+++ jackrabbit/oak/branches/1.0/oak-doc/src/site/markdown/security/authentication/identitymanagement.md Wed May 7 16:33:31 2014
@@ -15,7 +15,7 @@
limitations under the License.
-->
-Identity Management
+External Identity Management
--------------------------------------------------------------------------------
_todo_
Modified: jackrabbit/oak/branches/1.0/oak-doc/src/site/markdown/security/authentication/tokenmanagement.md
URL: http://svn.apache.org/viewvc/jackrabbit/oak/branches/1.0/oak-doc/src/site/markdown/security/authentication/tokenmanagement.md?rev=1593063&r1=1593062&r2=1593063&view=diff
==============================================================================
--- jackrabbit/oak/branches/1.0/oak-doc/src/site/markdown/security/authentication/tokenmanagement.md (original)
+++ jackrabbit/oak/branches/1.0/oak-doc/src/site/markdown/security/authentication/tokenmanagement.md Wed May 7 16:33:31 2014
@@ -15,16 +15,161 @@
limitations under the License.
-->
-Token Management
+Token Authentication and Token Management
--------------------------------------------------------------------------------
+### General
+
+The token based authentication has been completely refactor in Oak and has the
+following general characteristics.
+
+- Dedicated API for managing login tokens defined in the package `org.apache.jackrabbit.oak.spi.security.authentication.token`.
+- Pluggable configuration of the new token management API
+- Complete separation of token based authentication into a separate `LoginModule`.
+
+### Token Authentication
+
+As of Oak the token based authentication is handled by a dedicated [TokenLoginModule].
+It is both responsible for issueing new login tokens and validating [TokenCredentials]
+passed to the repository login.
+
+This token specific login module implementation obtains the [TokenProvider] from
+the security configuration as defined for the content repository. The token
+management implementation present with a given repository can be changed or
+extended at runtime (see section Configuration below).
+
+#### TokenLoginModule
+
+The `TokenLoginModule` itself behaves as follows:
+
+upon login()
_todo_
+upon commit()
+_todo_
+
+### Token Management API
+
+_todo_
+
+- [TokenProvider]
+- [TokenInfo]
+- [CompositeTokenProvider]
+
+
+### Default Implementation
+
+The default implementation of the token management API stores login tokens along
+with the user's home directory in the repository. Along with the hash of the
+login token separated properties defining the expiration time of the token
+as well as as additional properties associated with the login tokens. This
+additional information may be mandatory (thus validated during the login) or
+optional. The optional properties are meant to have informative value only and
+will be transferred to public attributes as exposed by the [AuthInfo] present
+with each [ContentSession].
+
+#### Token Creation
+
+_todo_
-- TokenProvider
-- TokenInfo
+#### Token Removal
+
+_todo_
+
+#### Resetting Expiration Time
+
+_todo_
+
+
+#### Token Representation in the Repository
+
+##### Content Structure
+
+The login tokens issued for a given user are all located underneath a node
+named `.tokens` that will be created by the `TokenProvider` once the first token
+is created. The default implementation creates a distinct node for each login
+token as described below
+
+ testUser {
+ "jcr:primaryType": "rep:User",
+ ...
+ ".tokens" {
+ "jcr:primaryType": "rep:Unstructured",
+ "2014-04-10T16.09.07.159+02.00" {
+ "jcr:primaryType": "rep:Token",
+ ...
+ "2014-05-07T12.08.57.683+02.00" {
+ "jcr:primaryType": "rep:Token",
+ ...
+ }
+ "2014-06-25T16.00.13.018+02.00" {
+ "jcr:primaryType": "rep:Token",
+ ...
+ }
+ }
+ }
+
+##### Token Nodes
+
+As of Oak 1.0 the login token are represented in the repository as follows:
+
+- the token node is referenceable with the dedicated node type `rep:Token` (used to be unstructured in Jackrabbit 2.x)
+- expiration and key properties are defined to be mandatory and protected
+- expiration time is obtained from `PARAM_TOKEN_EXPIRATION` specified in the
+ login attributes and falls back to the configuration parameter with the same
+ name as specified in the configuration options of the `TokenConfiguration`.
+
+The definition of the new built-in node type `rep:Token`:
+
+ [rep:Token] > mix:referenceable
+ - rep:token.key (STRING) protected mandatory
+ - rep:token.exp (DATE) protected mandatory
+ - * (UNDEFINED) protected
+ - * (UNDEFINED) multiple protected
+
+The following example illustrates the token nodes resulting from this node type
+definition:
+
+ testUser {
+ "jcr:primaryType": "rep:User",
+ ...
+ ".tokens" {
+ "2014-04-10T16.09.07.159+02.00" {
+ "jcr:primaryType": "rep:Token",
+ "jcr:uuid": "30c1f361-35a2-421a-9ebc-c781eb8a08f0",
+ "rep:token.key": "{SHA-256}afaf64dba5d862f9-1000-3e2d4e58ac16189b9f2ac95d8d5b692e61cb06db437bcd9be5c10bdf3792356a",
+ "rep:token.exp": "2014-04-11T04:09:07.159+02:00",
+ ".token.ip": "0:0:0:0:0:0:0:1%0"
+ ".token.otherMandatoryProperty": "expectedValue",
+ "referer": "http://localhost:4502/crx/explorer/login.jsp"
+ "otherInformalProperty": "somevalue"
+ },
+ "2014-05-07T12.08.57.683+02.00" {
+ "jcr:primaryType": "rep:Token",
+ "jcr:uuid": "c95c91e2-2e08-48ab-93db-6e7c8cdd6469",
+ "rep:token.key": "{SHA-256}b1d268c55abda258-1000-62e4c368972260576d37e6ba14a10f9f02897e42992624890e22c522220f7e54",
+ "rep:token.exp": "2014-05-08T00:08:57.683+02:00"
+ },
+ ...
+ }
+ }
+ }
+
+### Configuration
+
+_todo_
+
+#### Custom TokenProvider
+
+_todo_
-### Custom TokenProvider
+<!-- references -->
-_todo_
\ No newline at end of file
+[TokenLoginModule]: /oak/docs/apidocs/org/apache/jackrabbit/oak/security/authentication/token/TokenLoginModule.html
+[TokenCredentials]: http://svn.apache.org/repos/asf/jackrabbit/trunk/jackrabbit-api/src/main/java/org/apache/jackrabbit/api/security/authentication/token/TokenCredentials.java
+[AuthInfo]: /oak/docs/apidocs/org/apache/jackrabbit/oak/api/AuthInfo.html
+[ContentSession]: /oak/docs/apidocs/org/apache/jackrabbit/oak/api/ContentSession.html
+[TokenProvider]: /oak/docs/apidocs/org/apache/jackrabbit/oak/spi/security/authentication/token/TokenProvider.html
+[TokenInfo]: /oak/docs/apidocs/org/apache/jackrabbit/oak/spi/security/authentication/token/TokenInfo.html
+[CompositeTokenProvider]: /oak/docs/apidocs/org/apache/jackrabbit/oak/spi/security/authentication/token/CompositeTokenProvider.html
\ No newline at end of file
Modified: jackrabbit/oak/branches/1.0/oak-doc/src/site/markdown/security/overview.md
URL: http://svn.apache.org/viewvc/jackrabbit/oak/branches/1.0/oak-doc/src/site/markdown/security/overview.md?rev=1593063&r1=1593062&r2=1593063&view=diff
==============================================================================
--- jackrabbit/oak/branches/1.0/oak-doc/src/site/markdown/security/overview.md (original)
+++ jackrabbit/oak/branches/1.0/oak-doc/src/site/markdown/security/overview.md Wed May 7 16:33:31 2014
@@ -20,11 +20,12 @@ The Oak Security Layer
* [Authentication](authentication.html)
* [Differences wrt Jackrabbit 2.x](authentication/differences.html)
- * [External Login Module and User Synchronization](authentication/externalloginmodule.html)
+ * [Token Authentication and Token Management](authentication/tokenmanagement.html)
+ * [External Authentication](authentication/externalloginmodule.html)
+ * [User and Group Synchronization](authentication/usersync.html)
* [Identity Management](authentication/identitymanagement.html)
* [LDAP Integration](authentication/ldap.html)
* [Pre-Authentication](authentication/preauthentication.html)
- * [Token Management](authentication/tokenmanagement.html)
* [Access Control](accesscontrol.html)
* [Differences wrt Jackrabbit 2.x](accesscontrol/differences.html)
* [Permission Evaluation](permission.html)
Modified: jackrabbit/oak/branches/1.0/oak-doc/src/site/markdown/security/user.md
URL: http://svn.apache.org/viewvc/jackrabbit/oak/branches/1.0/oak-doc/src/site/markdown/security/user.md?rev=1593063&r1=1593062&r2=1593063&view=diff
==============================================================================
--- jackrabbit/oak/branches/1.0/oak-doc/src/site/markdown/security/user.md (original)
+++ jackrabbit/oak/branches/1.0/oak-doc/src/site/markdown/security/user.md Wed May 7 16:33:31 2014
@@ -18,9 +18,301 @@
User Management
--------------------------------------------------------------------------------
-_TODO_
+### 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 Jackrabbit 2.x `UserPerWorkspaceUserManager`). The implementation of a user
+management variant corresponding to Jackrabbit's default `UserManagerImpl` is
+blocked by missing workspace handling (see [OAK-118]). The current user manager
+has the following characteristics:
+
+#### General
+* 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 `Session#refresh`
+ is no longer called in order to prevent reverting other changes unrelated to
+ the user management operation. Tt'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 also allows to
+ make use of the Jackrabbit user management API within the OAK layer (aka SPI).
### Differences wrt Jackrabbit 2.x
-see the corresponding [documentation](user/differences.html).
+A summary of all changes with respect to the former implementation present with
+Jackrabbit 2.x is present in the corresponding [section](user/differences.html).
+
+#### 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.
+
+#### 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() 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.
+
+#### 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 as member. As of OAK this fact is consistently reflected in all
+group membership related methods.
+
+#### Query
+
+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]).
+
+#### 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. The difference compare to Jackrabbit 2.x 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 2.x core it used to fail immediately.
+* NEW: The `BestEffort` behavior is now also implemented for the import of impersonators (was missing in Jackrabbit /2.x).
+* NEW: Workspace Import
+
+#### Group Membership
+
+##### Behavior in Jackrabbit 2.x
+With the default configuration Jackrabbit 2.x stores the group members as
+_weak references_ in a `rep:members` multi value property in the group node.
+If the `groupMembershipSplitSize` configuration parameter is set and valid,
+the group memberships are collected in a node structure below `rep:members` instead
+of the default multi valued property. Its value determines the maximum number of
+member properties until additional intermediate nodes are inserted. Valid parameter
+values are integers > 4. The node structure is a balanced b-tree where only the
+leave nodes carry the actual values in residual properties which name is the
+principal name of the member.
+
+##### Behavior as of OAK 1.0
+As of Oak the user manager automatically chooses an appropriate storage structure
+depending on the number of group members. If the number of members is low they
+are stored as _weak references_ in a `rep:members` multi value property. This is
+similar to Jackrabbit 2.x. If the number of members is high the user manager
+will limit the size of the multi value properties and create overflow
+`rep:MemberReferences` nodes below a `rep:membersList` node to hold the extra members.
+
+##### Relevant new and modified node types
+ [rep:Group] > rep:Authorizable, rep:MemberReferences
+ + rep:members (rep:Members) = rep:Members multiple protected VERSION /* @deprecated */
+ + rep:membersList (rep:MemberReferencesList) = rep:MemberReferencesList protected COPY
+
+ [rep:MemberReferences]
+ - rep:members (WEAKREFERENCE) protected multiple < 'rep:Authorizable'
+
+ [rep:MemberReferencesList]
+ + * (rep:MemberReferences) = rep:MemberReferences protected COPY
+
+##### Example Group with few members
+*(irrelevant properties excluded)*
+
+ {
+ "jcr:primaryType": "rep:Group",
+ "rep:principalName": "contributor",
+ "rep:members": [
+ "429bbd5b-46a6-3c3d-808b-5fd4219d5c4d",
+ "ca58c408-fe06-357e-953c-2d23ffe1e096",
+ "3ebb1c04-76dd-317e-a9ee-5164182bc390",
+ "d3c827d3-4db2-30cc-9c41-0ed8117dbaff",
+ "f5777a0b-a933-3b4d-9405-613d8bc39cc7",
+ "fdd1547a-b19a-3154-90da-1eae8c2c3504",
+ "65c3084e-abfc-3719-8223-72c6cb9a3d6f"
+ ]
+ }
+
+##### Example Group with many members
+*(irrelevant properties excluded)*
+
+ {
+ "jcr:primaryType": "rep:Group",
+ "rep:principalName": "employees",
+ "rep:membersList": {
+ "jcr:primaryType": "rep:MemberReferencesList",
+ "0": {
+ "jcr:primaryType": "rep:MemberReferences",
+ "rep:members": [
+ "429bbd5b-46a6-3c3d-808b-5fd4219d5c4d",
+ "ca58c408-fe06-357e-953c-2d23ffe1e096",
+ ...
+ ]
+ },
+ ...
+ "341": {
+ "jcr:primaryType": "rep:MemberReferences",
+ "rep:members": [
+ "fdd1547a-b19a-3154-90da-1eae8c2c3504",
+ "65c3084e-abfc-3719-8223-72c6cb9a3d6f",
+ ...
+ ]
+ }
+ }
+ }
+
+*Note*: The exact threshold value that determines the storage strategy is an implementation detail and might even vary depending on the underlying persistence layer.
+
+##### Upgrading Groups from Jackrabbit 2.x to OAK content structure
+
+Upon upgrade from a Jackrabbit 2.x repository to OAK the group member lists that
+adjusted to reflect the new content structure as created by the OAK user management
+implementation; this means that the group member node structure will be changed
+by the migration process. Applications that rely on these implementation
+details of Jackrabbit 2.x user management instead of use the corresponding
+API calls will need to be modified accordingly.
+
+##### Importing Group Members
+Importing group members through the import methods in `javax.jcr.Session` or
+`javax.jcr.Workspace` is storage agnostic and supports both, property based and
+node based, strategies and is backward compatible to content exported from
+Jackrabbit 2.x. The group member lists that are modified during an import are
+internally processed using the normal user manager APIs. This implies that the
+node structure after the import might not be the same as the one represented in the input.
+
+### 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 management implementation in OAK comes with an initializer that creates the following builtin user accounts (as in Jackrabbit 2.x):
+
+#### 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).
+
+#### 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]):
+
+ Repository#login(new GuestCredentials(), wspName);
+
+### 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 Jackrabbit 2.x:
+
+* `AccessControlAction`: set up permission for new authorizables
+* `PasswordAction`: simplistic password verification upon user creation and password 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.
+
+### 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'
+
+### 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 management tasks.
+
+### Configuration
+
+The following configuration options are present with the `UserConfiguration` as of OAK 1.0:
+
+* getUserManager: Obtain a new user manager instance
+* getAuthorizableActionProvider: Obtain a new instance of the AuthorizableActionProvider (see above)
+
+#### 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_GROUP_MEMBERSHIP_SPLIT_SIZE` | int | |
+| `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_SUPPORT_AUTOSAVE` | boolean | false |
+
+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"
+
+<!-- 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