[
https://issues.apache.org/jira/browse/OAK-793?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=13710893#comment-13710893
]
angela edited comment on OAK-793 at 11/12/13 3:53 PM:
------------------------------------------------------
moved to
http://svn.apache.org/repos/asf/jackrabbit/oak/trunk/oak-doc/src/site/markdown/differences_authentication.md
was (Author: anchela):
h4. 1. Characteristics of the Default Implementation
h5. 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:
{code}
jackrabbit.oak {
org.apache.jackrabbit.oak.spi.security.authentication.GuestLoginModule
optional;
org.apache.jackrabbit.oak.security.authentication.user.LoginModuleImpl
required;
};
{code}
h5. Guest Login
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:
{code}
String wspName = null;
Session anonymous = repository.login(new GuestCredentials(), wspName);
{code}
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.
h5. Pre-Authentication in the LoginContextProvider
Like in Jackrabbit-core the repository internal authentication verification can
be skipped by calling {{Repository#login()}} or {{Repository#login(null,
wspName)}}. In this case the repository implementation expects the verification
to be performed prior to the login call.
This behavior is provided by the default implementation of the
{{LoginContextProvider}} [1] which expects a {{Subject}} to be available with
the current {{java.security.AccessControlContext}}. However, in contrast to
Jackrabbit-core the current implementation does not try to extend the
pre-authenticated subject but skips the internal verification step altogether.
Since the {{LoginContextProvider}} is a configurable with the authentication
setup OAK users also have the following options by providing a custom
{{LoginContextProvider}}:
- Disable pre-authentication by not trying to retrieve a pre-authenticated
{{Subject}}.
- Add support for extending the pre-authenticated subject by always passing
writable subjects to the {{JaasLoginContext}}
- Dropping JAAS altogether by providing a custom implementation of the
{{org.apache.jackrabbit.oak.spi.security.authentication.LoginContext}} [2]
interface.
Example how to use the pre-auth:
{code}
String userId = "test";
/**
Retrive valid principals e.g. by calling jackrabbit API
- PrincipalManager#getPrincipal and/or #getGroupMembership
or from Oak SPI
- PrincipalProvider#getPrincipals(String userId)
*/
Set<? extends Principal> principals = getPrincipals(userId);
AuthInfo authInfo = new AuthInfoImpl(userId, Collections.<String,
Object>emptyMap(), principals);
Subject subject = new Subject(true, principals,
Collections.singleton(authInfo), Collections.<Object>emptySet());
Session session;
try {
session = Subject.doAsPrivileged(subject, new
PrivilegedExceptionAction<Session>() {
@Override
public Session run() throws Exception {
return login(null, null);
}
}, null);
} catch (PrivilegedActionException e) {
throw new RepositoryException("failed to retrieve session.", e);
}
{code}
h4. 2. Impersonation
h5. 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) will succeed as long as the user is still
valid.
h5. 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].
With this change the impersonation feature no longer relies on
{{SimpleCredentials}} being passed to {{Session#impersonate}} call. Instead the
specified credentials are passed to a new instance of
{{ImpersonationCredentials}} delegating the evaluation and validation of the
specified {{Credentials}} to the configured login module(s).
This modification will not affect applications that used JCR API to impersonate
a given session. However the following example which 'manually' builds
impersonation credentials the way jackrabbit core was handling it will no
longer work to impersonate an existing session:
{code}
SessionImpl sImpl = (SessionImpl) mySession;
SimpleCredentials jrImpCreds = new SimpleCredentials("someUserId, new
char[0]);
creds.setAttribute(SecurityConstants.IMPERSONATOR_ATTRIBUTE,
sImpl.getSubject());
Session impersonated = sImpl.getRepository().login(jrImpCreds,
sImpl.getWorkspace().getName());
{code}
h4. 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":
{code}
[rep:Token] > mix:referenceable
- rep:token.key (STRING) protected mandatory
- rep:token.exp (DATE) protected mandatory
- * (UNDEFINED) protected
- * (UNDEFINED) multiple protected
{code}
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.
h4. 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.
h4. 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:
- {{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 6).
h4. 6. Configuration
* {{AuthenticationConfiguration}} [9]:
** {{getLoginContextProvider}} -> configuration of the login context
** {{getTokenProvider}} -> configuration of the token management implementation
There also exists a utility class that allows to obtain different
{{javax.security.auth.login.Configuration}} for the most common setup [10]:
* {{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
h4. 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/ConfigurationUtil.java
> Authentication: Document changes wrt. Jackrabbit
> ------------------------------------------------
>
> Key: OAK-793
> URL: https://issues.apache.org/jira/browse/OAK-793
> Project: Jackrabbit Oak
> Issue Type: Sub-task
> Components: jcr
> Reporter: angela
> Assignee: angela
> Fix For: 0.9
>
>
--
This message was sent by Atlassian JIRA
(v6.1#6144)
