Propchange: jackrabbit/site/live/oak/docs/security/.DS_Store ------------------------------------------------------------------------------ svn:mime-type = application/octet-stream Modified: jackrabbit/site/live/oak/docs/security/accesscontrol.html URL: http://svn.apache.org/viewvc/jackrabbit/site/live/oak/docs/security/accesscontrol.html?rev=1730074&r1=1730073&r2=1730074&view=diff ============================================================================== --- jackrabbit/site/live/oak/docs/security/accesscontrol.html (original) +++ jackrabbit/site/live/oak/docs/security/accesscontrol.html Fri Feb 12 17:09:05 2016 @@ -1,15 +1,15 @@ - + - Jackrabbit Oak - Access Control + Jackrabbit Oak - Access Control Management @@ -213,7 +213,7 @@ + +

Jackrabbit API

The Jackrabbit API defines various access control related extensions to the JCR API in order to cover common needs such as for example:

@@ -587,323 +593,8 @@
  • JackrabbitAccessControlList
  • JackrabbitAccessControlEntry
  • -
    -
    -

    Edit Access Control

    -

    see section Using the Access Control Management API for a comprehensive list of method calls as well as examples that may be used to edit the access control content of the repository.

    -
    -

    Characteristics of the Default Implementation

    -
    -

    General

    -

    In general the authorization related code in Oak clearly separates between access control management (such as defined by the JCR and Jackrabbit API) and the internal permission evaluation (see also Permission Evaluation).

    -
    -

    Differences wrt Jackrabbit 2.x

    -

    see the corresponding documentation.

    -
    -

    Resource vs Principal Based Access Control

    -

    The default implementation present with Oak 1.0 is natively resource-based which corresponds to the way JCR defines access control. Nevertheless the principal based approach as defined by the Jackrabbit API is supported using a best-effort approach: principal-based policies are created using the Oak query API and fully respect the access rights imposed on the different policies that contain entries for a given principal. These principal-based policies can also be modified using the corresponding methods provided by the access control, except for JackrabbitAccessControlList.orderBefore.

    -

    Thus the default implementation corresponds to the default implementation present with Jackrabbit 2.x. Note however, that the former principal-base approach that stored policies per principal in a dedicated tree is no longer available.

    -
    -

    Access Control Policies

    -

    The Oak access control management exposes two types of policies that cover all use case defined by the specification and required by the default setup:

    - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    Name Policy Description
    Default ACL JackrabbitAccessControlList access control on individual nodes
    Repo-Level ACL JackrabbitAccessControlList repo-level access control for the null path
    Read Policy NamedAccessControlPolicy trees that are configured to be readable to everyone
    -
    -
    Default ACL
    -

    The default access control lists are bound to individual nodes. They may be used to grant/deny access for all operations that are in some way related to JCR items: regular read/write, access control management, versioning, locking and as of Oak 1.0 user management and writing index definitions.

    -

    These policies are designed to take effect on the complete subtree spanned by the node they are bound to. The individual access control entries are evaluated in strict order (first entries in a given list, second entries inherited from list bound to parent nodes) with one notable exception: access control entries created for non-group principals always take precedence irrespective of their inheritance status.

    -

    Further details are described in section Permissions.

    -
    -
    Repo-Level ACL
    -

    The access control lists bound to the null path can be used to grant/deny privileges associated with operations on repository-level such as namespace, node type, privilege and workspace management.

    -

    The effect of these entries is limited to the repository operations and is no inherited to any items inside the repository.

    -
    -
    Read Policy
    -

    These immutable policy has been introduced in Oak 1.0 in order to allow for opening up trees that need to be readable to all sessions irrespective of other effective policies.

    -

    By default these policies are bound to the following trees:

    - -
      - -
    • /jcr:system/rep:namespaces: stores all registered namespaces
    • - -
    • /jcr:system/jcr:nodeTypes: stores all registered node types
    • - -
    • /jcr:system/rep:privileges: stores all registered privileges
    -

    The default set can be changed or extended by setting the corresponding configuration option. However, it is important to note that many JCR API calls rely on the accessibility of the namespace, nodetype and privilege information. Removing the corresponding paths from the configuration will most probably have undesired effects.

    -
    -

    Access Control Entries

    -

    The access control entries present in a given list are subject to the following rules applied upon editing but not enforced by CommitHooks:

    - -
    -
    -

    Restrictions

    -

    Access control entries may be created by limiting their effect by adding restrictions as mentioned by JSR 283. Details about the restriction management in Oak 1.0 as well as a list of built-in restrictions and extensibility can be found in section Restriction Management.

    -
    -

    Representation in the Repository

    -

    All access control policies defined with an Oak repository are stores child of the node they are bound to. The node type definition used to represent access control content:

    - -
    -
    [rep:AccessControllable]
    -  mixin
    -  + rep:policy (rep:Policy) protected IGNORE
    -
    -[rep:RepoAccessControllable]
    -  mixin
    -  + rep:repoPolicy (rep:Policy) protected IGNORE
    -
    -[rep:Policy]
    -  abstract
    -
    -[rep:ACL] > rep:Policy
    -  orderable
    -  + * (rep:ACE) = rep:GrantACE protected IGNORE
    -
    -[rep:ACE]
    -  - rep:principalName (STRING) protected mandatory
    -  - rep:privileges (NAME) protected mandatory multiple
    -  - rep:nodePath (PATH) protected /* deprecated in favor of restrictions */
    -  - rep:glob (STRING) protected   /* deprecated in favor of restrictions */
    -  - * (UNDEFINED) protected       /* deprecated in favor of restrictions */
    -  + rep:restrictions (rep:Restrictions) = rep:Restrictions protected /* since oak 1.0 */
    -
    -[rep:GrantACE] > rep:ACE
    -
    -[rep:DenyACE] > rep:ACE
    -
    -/**
    - * @since oak 1.0
    - */
    -[rep:Restrictions]
    -  - * (UNDEFINED) protected
    -  - * (UNDEFINED) protected multiple
    -
    -
    -
    Examples
    -
    -
    Regular ACL at /content
    - -
    -
    "": {
    -    "jcr:primaryType": "rep:root",
    -    "content": {
    -        "jcr:primaryType": "oak:Unstructured",
    -        "jcr:mixinTypes": "rep:AccessControllable",
    -        "rep:policy": {
    -            "jcr:primaryType": "rep:ACL",
    -            "allow": {
    -                "jcr:primaryType": "rep:GrantACE",
    -                "rep:principalName": "jackrabbit",
    -                "rep:privileges": ["jcr:read", "rep:write"]
    -            },
    -            "deny": {
    -                "jcr:primaryType": "rep:DenyACE",
    -                "rep:principalName": "jackrabbit",
    -                "rep:privileges": ["jcr:addNodes", "rep:addProperties"],
    -                "rep:restrictions" {
    -                    "jcr:primaryType": "rep:Restrictions",
    -                    "rep:ntNames": ["nt:hierarchyNode", "nt:resource"]
    -                }
    -            }
    -        }
    -    }
    -}
    -
    -
    -
    Repo-Level Policy
    - -
    -
    "": {
    -    "jcr:primaryType": "rep:root",
    -    "jcr:mixinTypes": "rep:RepoAccessControllable",
    -    "rep:repoPolicy": {
    -        "jcr:primaryType": "rep:ACL",
    -        "allow": {
    -            "jcr:primaryType": "rep:GrantACE",
    -            "rep:principalName": "elefant",
    -            "rep:privileges": ["rep:privilegeManagement"]
    -        }
    -    }
    -}
    -
    -

    -
    -
    Validation
    -

    The consistency of this content structure is asserted by a dedicated AccessControlValidator. The corresponding errors are all of type AccessControl with the following codes:

    - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    Code Message
    0001 Generic access control violation
    0002 Access control entry node expected
    0003 Invalid policy name
    0004 Invalid policy node: Order of children is not stable
    0005 Access control policy within access control content
    0006 Isolated policy node
    0007 Isolated access control entry
    0008 ACE without principal name
    0009 ACE without privileges
    0010 ACE contains invalid privilege name
    0011 ACE uses abstract privilege
    0012 Repository level policies defined with non-root node
    0013 Duplicate ACE found in policy
    -
    -

    XML Import

    -

    As of OAK 1.0 access control content can be imported both with Session and Workspace import.

    -

    In addition the JCR XML import behavior has been extended to respect the o.a.j.oak.spi.xml.ImportBehavior flags instead of just performing a best effort import.

    -

    Currently the ImportBehavior is only used to switch between different ways of handling principals unknown to the repository. For consistency and in order to match the validation requirements as specified by AccessControlList#addAccessControlEntry the default behavior is ABORT (while in Jackrabbit 2.x the behavior always was BESTEFFORT).

    -

    The different ImportBehavior flags are implemented as follows: - ABORT: throws an AccessControlException if the principal is unknown - IGNORE: ignore the entry defining the unknown principal - BESTEFFORT: import the access control entry with an unknown principal.

    -

    In order to get the same best effort behavior as present with Jackrabbit 2.x the configuration parameters of the AuthorizationConfiguration must contain the following entry:

    - -
    -
    importBehavior = "besteffort"
    -
    -

    See also (OAK-1350))

    +

    API Extensions

    Oak defines the following interfaces extending the access control management API:

    @@ -929,7 +620,8 @@

    Restriction Management

    -

    Oak 1.0 defines a dedicated restriction management API. See Restriction Management for details and further information regarding extensibility and pluggability.

    +

    Oak 1.0 defines a dedicated restriction management API. See Restriction Management for details and further information regarding extensibility and pluggability.

    +

    Utilities

    The jcr-commons module present with Jackrabbit provide some access control related utilities that simplify the creation of new policies and entries such as for example:

    @@ -955,6 +647,10 @@ acMgr.setPolicy(path, acl); session.save();
    +

    Characteristics of the Default Implementation

    +

    The behavior of the default access control implementation is described in sections Access Control Management: The Default Implementation
    and Restriction Management.

    +

    +

    Configuration

    The configuration of the access control management implementation is handled within the AuthorizationConfiguration, which is used for all authorization related matters. This class provides the following two access control related methods:

    @@ -966,79 +662,7 @@ session.save();

    Configuration Parameters

    -

    The default implementation supports the following configuration parameters:

    - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    Parameter Type Default
    PARAM_RESTRICTION_PROVIDER RestrictionProvider RestrictionProviderImpl
    PARAM_READ_PATHS Set<String> paths to namespace, nodetype and privilege root nodes
    PARAM_IMPORT_BEHAVIOR String (“abort”, “ignore”, “besteffort”) “abort”
    -

    Differences to Jackrabbit 2.x:

    - -
    -
    -

    Pluggability

    -

    There are multiple levels for plugging access control related custom implementations:

    - -
      - -
    1. replace AuthorizationConfiguration: if you want to completely replace the way authorization is handled in the repository. In OSGi-base setup this is achieved by making the configuration implementation a service. In a non-OSGi-base setup the custom configuration must be exposed by the SecurityProvider implementation.
    2. - -
    3. extend AuthorizationConfiguration: it is planned to provide a CompositeAuthorizationConfiguration that allows to aggregate different authorization implementations (see OAK-1268).
    4. - -
    5. extend the existing implementation by providing custom restrictions (see RestrictionManagement.
    6. -
    +

    The supported configuration options of the default implementation are described in the corresponding section.

    Further Reading

    @@ -1046,7 +670,11 @@ session.save();
  • Differences wrt Jackrabbit 2.x
  • +
  • Access Control Management: The Default Implementation
  • +
  • Restriction Management
  • + +
  • Using the Access Control Management API
  • Added: jackrabbit/site/live/oak/docs/security/accesscontrol/default.html URL: http://svn.apache.org/viewvc/jackrabbit/site/live/oak/docs/security/accesscontrol/default.html?rev=1730074&view=auto ============================================================================== --- jackrabbit/site/live/oak/docs/security/accesscontrol/default.html (added) +++ jackrabbit/site/live/oak/docs/security/accesscontrol/default.html Fri Feb 12 17:09:05 2016 @@ -0,0 +1,918 @@ + + + + + + + + + Jackrabbit Oak - Access Control Management : The Default Implementation + + + + + + + + + + + + + + + + + + Fork me on GitHub + + + + + + + + + +
    + + + + + +
    +
    + +
    + + +
    + +
    +

    Access Control Management : The Default Implementation

    +
    +

    General

    +

    In general the authorization related code in Oak clearly separates between access control management (such as defined by the JCR and Jackrabbit API) and the internal permission evaluation (see also Permission Evaluation).

    +
    +

    Differences wrt Jackrabbit 2.x

    +

    see the corresponding documentation.

    +
    +

    Resource vs Principal Based Access Control

    +

    The default implementation present with Oak 1.0 is natively resource-based which corresponds to the way JCR defines access control. Nevertheless the principal based approach as defined by the Jackrabbit API is supported using a best-effort approach: principal-based policies are created using the Oak query API and fully respect the access rights imposed on the different policies that contain entries for a given principal. These principal-based policies can also be modified using the corresponding methods provided by the access control, except for JackrabbitAccessControlList.orderBefore.

    +

    Thus the default implementation corresponds to the default implementation present with Jackrabbit 2.x. Note however, that the former principal-base approach that stored policies per principal in a dedicated tree is no longer available.

    +
    +

    The Elements of Access Control Management

    +
    +

    Access Control Policies

    +

    The Oak access control management exposes two types of policies that cover all use case defined by the specification and required by the default setup:

    + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    Name Policy Description
    Default ACL JackrabbitAccessControlList access control on individual nodes
    Repo-Level ACL JackrabbitAccessControlList repo-level access control for the null path
    Read Policy NamedAccessControlPolicy trees that are configured to be readable to everyone
    +
    +
    Default ACL
    +

    The default access control lists are bound to individual nodes. They may be used to grant/deny access for all operations that are in some way related to JCR items: regular read/write, access control management, versioning, locking and as of Oak 1.0 user management and writing index definitions.

    +

    These policies are designed to take effect on the complete subtree spanned by the node they are bound to. The individual access control entries are evaluated in strict order (first entries in a given list, second entries inherited from list bound to parent nodes) with one notable exception: access control entries created for non-group principals always take precedence irrespective of their inheritance status.

    +

    Further details are described in section Permissions.

    +
    +
    Repo-Level ACL
    +

    The access control lists bound to the null path can be used to grant/deny privileges associated with operations on repository-level such as namespace, node type, privilege and workspace management.

    +

    The effect of these entries is limited to the repository operations and is no inherited to any items inside the repository.

    +
    +
    Read Policy
    +

    These immutable policy has been introduced in Oak 1.0 in order to allow for opening up trees that need to be readable to all sessions irrespective of other effective policies.

    +

    By default these policies are bound to the following trees:

    + +
      + +
    • /jcr:system/rep:namespaces: stores all registered namespaces
    • + +
    • /jcr:system/jcr:nodeTypes: stores all registered node types
    • + +
    • /jcr:system/rep:privileges: stores all registered privileges
    • +
    +

    The default set can be changed or extended by setting the corresponding configuration option. However, it is important to note that many JCR API calls rely on the accessibility of the namespace, nodetype and privilege information. Removing the corresponding paths from the configuration will most probably have undesired effects.

    +
    +

    Access Control Entries

    +

    The access control entries present in a given list are subject to the following rules applied upon editing but not enforced by CommitHooks:

    + +
      + +
    • uniqueness: a given entry may only appear onces in a list
    • + +
    • merging: if an entry exists for a given principal with the same allow-status and restrictions, the existing entry will be updated without being moved in the list.
    • + +
    • redundancy: if an new entry makes an existing entry (partially) redundant the existing entry will be updated or removed altogether.
    • +
    +
    +

    Restrictions

    +

    Access control entries may be created by limiting their effect by adding restrictions as mentioned by JSR 283. Details about the restriction management in Oak 1.0 as well as a list of built-in restrictions and extensibility can be found in section Restriction Management.

    +
    +

    Representation in the Repository

    +

    All access control policies defined with an Oak repository are stores child of the node they are bound to. The node type definition used to represent access control content:

    + +
    +
    [rep:AccessControllable]
    +  mixin
    +  + rep:policy (rep:Policy) protected IGNORE
    +
    +[rep:RepoAccessControllable]
    +  mixin
    +  + rep:repoPolicy (rep:Policy) protected IGNORE
    +
    +[rep:Policy]
    +  abstract
    +
    +[rep:ACL] > rep:Policy
    +  orderable
    +  + * (rep:ACE) = rep:GrantACE protected IGNORE
    +
    +[rep:ACE]
    +  - rep:principalName (STRING) protected mandatory
    +  - rep:privileges (NAME) protected mandatory multiple
    +  - rep:nodePath (PATH) protected /* deprecated in favor of restrictions */
    +  - rep:glob (STRING) protected   /* deprecated in favor of restrictions */
    +  - * (UNDEFINED) protected       /* deprecated in favor of restrictions */
    +  + rep:restrictions (rep:Restrictions) = rep:Restrictions protected /* since oak 1.0 */
    +
    +[rep:GrantACE] > rep:ACE
    +
    +[rep:DenyACE] > rep:ACE
    +
    +/**
    + * @since oak 1.0
    + */
    +[rep:Restrictions]
    +  - * (UNDEFINED) protected
    +  - * (UNDEFINED) protected multiple
    +
    +
    +
    +
    Examples
    +
    +
    Regular ACL at /content
    + +
    +
    "": {
    +    "jcr:primaryType": "rep:root",
    +    "content": {
    +        "jcr:primaryType": "oak:Unstructured",
    +        "jcr:mixinTypes": "rep:AccessControllable",
    +        "rep:policy": {
    +            "jcr:primaryType": "rep:ACL",
    +            "allow": {
    +                "jcr:primaryType": "rep:GrantACE",
    +                "rep:principalName": "jackrabbit",
    +                "rep:privileges": ["jcr:read", "rep:write"]
    +            },
    +            "deny": {
    +                "jcr:primaryType": "rep:DenyACE",
    +                "rep:principalName": "jackrabbit",
    +                "rep:privileges": ["jcr:addNodes", "rep:addProperties"],
    +                "rep:restrictions" {
    +                    "jcr:primaryType": "rep:Restrictions",
    +                    "rep:ntNames": ["nt:hierarchyNode", "nt:resource"]
    +                }
    +            }
    +        }
    +    }
    +}
    +
    +
    +
    Repo-Level Policy
    + +
    +
    "": {
    +    "jcr:primaryType": "rep:root",
    +    "jcr:mixinTypes": "rep:RepoAccessControllable",
    +    "rep:repoPolicy": {
    +        "jcr:primaryType": "rep:ACL",
    +        "allow": {
    +            "jcr:primaryType": "rep:GrantACE",
    +            "rep:principalName": "elefant",
    +            "rep:privileges": ["rep:privilegeManagement"]
    +        }
    +    }
    +}
    +
    +
    +

    XML Import

    +

    As of OAK 1.0 access control content can be imported both with Session and Workspace import.

    +

    In addition the JCR XML import behavior has been extended to respect the o.a.j.oak.spi.xml.ImportBehavior flags instead of just performing a best effort import.

    +

    Currently the ImportBehavior is only used to switch between different ways of handling principals unknown to the repository. For consistency and in order to match the validation requirements as specified by AccessControlList#addAccessControlEntry the default behavior is ABORT (while in Jackrabbit 2.x the behavior always was BESTEFFORT).

    +

    The different ImportBehavior flags are implemented as follows: - ABORT: throws an AccessControlException if the principal is unknown - IGNORE: ignore the entry defining the unknown principal - BESTEFFORT: import the access control entry with an unknown principal.

    +

    In order to get the same best effort behavior as present with Jackrabbit 2.x the configuration parameters of the AuthorizationConfiguration must contain the following entry:

    + +
    +
    importBehavior = "besteffort"
    +
    +

    See also (OAK-1350))

    +

    +
    +

    Validation

    +

    The consistency of this content structure is asserted by a dedicated AccessControlValidator. The corresponding errors are all of type AccessControl with the following codes:

    + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    Code Message
    0001 Generic access control violation
    0002 Access control entry node expected
    0003 Invalid policy name
    0004 Invalid policy node: Order of children is not stable
    0005 Access control policy within access control content
    0006 Isolated policy node
    0007 Isolated access control entry
    0008 ACE without principal name
    0009 ACE without privileges
    0010 ACE contains invalid privilege name
    0011 ACE uses abstract privilege
    0012 Repository level policies defined with non-root node
    0013 Duplicate ACE found in policy
    +

    +
    +

    Configuration

    +
    +

    Configuration Parameters

    +

    The default implementation supports the following configuration parameters:

    + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    Parameter Type Default
    PARAM_RESTRICTION_PROVIDER RestrictionProvider RestrictionProviderImpl
    PARAM_READ_PATHS Set<String> paths to namespace, nodetype and privilege root nodes
    PARAM_IMPORT_BEHAVIOR String (“abort”, “ignore”, “besteffort”) “abort”
    +

    Differences to Jackrabbit 2.x:

    + +
      + +
    • The “omit-default-permission” configuration option present with the Jackrabbit’s AccessControlProvider implementations is no longer supported with Oak.
    • + +
    • As of OAK no extra access control content is installed by default which renders that flag superfluous.
    • +
    +
    +
    +
    +
    + +
    + + + + \ No newline at end of file Propchange: jackrabbit/site/live/oak/docs/security/accesscontrol/default.html ------------------------------------------------------------------------------ svn:eol-style = native Modified: jackrabbit/site/live/oak/docs/security/accesscontrol/differences.html URL: http://svn.apache.org/viewvc/jackrabbit/site/live/oak/docs/security/accesscontrol/differences.html?rev=1730074&r1=1730073&r2=1730074&view=diff ============================================================================== --- jackrabbit/site/live/oak/docs/security/accesscontrol/differences.html (original) +++ jackrabbit/site/live/oak/docs/security/accesscontrol/differences.html Fri Feb 12 17:09:05 2016 @@ -1,15 +1,15 @@ - + - Jackrabbit Oak - AccessControl Management : Differences wrt Jackrabbit 2.x + Jackrabbit Oak - Access Control Management : Differences wrt Jackrabbit 2.x @@ -213,7 +213,7 @@

    See javax.jcr.Repository and org.apache.jackrabbit.api.JackrabbitRepository for further details.

    -

    In addition JCR defines Session.impersonate(Credentials) to impersonate another user or - as of JSR 333 - clone an existing session.

    +

    In addition JCR defines Session.impersonate(Credentials) to impersonate another user or - as of JSR 333 - clone an existing session.

    +

    -

    Oak Authentication

    -
    -

    Oak API

    +

    Oak API

    The Oak API contains the following authentication related methods and interfaces

    -

    Differences wrt Jackrabbit 2.x

    -

    See section differences for complete list of differences wrt authentication between Jackrabbit 2.x and Oak.

    -
    -

    Guest Login

    -

    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);
    -
    -

    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).

    -

    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.

    -
    -
    Guest Login Module
    -

    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.

    -

    Example JAAS Configuration:

    - -
    -
    jackrabbit.oak {
    -   org.apache.jackrabbit.oak.spi.security.authentication.GuestLoginModule  optional;
    -   org.apache.jackrabbit.oak.security.authentication.user.LoginModuleImpl required;
    -};
    -
    -

    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

    - -
      - -
    • 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
    • -
    -
    -

    UserId/Password Login

    -

    Oak 1.0 comes with 2 different login module implementations that can handle SimpleCredentials:

    - - -
    -
    Default Login Module
    -

    The LoginModuleImpl defines a regular userId/password login and requires a repository setup that supports User Management and is designed to supports the following Credentials:

    - -
      - -
    • 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 - -
        - -
      • also, it adds the credentials 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
      • -
    • -
    -

    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
    • -
    -
    -

    Impersonation

    -

    Another flavor of the Oak authentication implementation is covered by javax.jcr.Session#impersonate(Credentials), which allows to obtain an new Session for user identified by the specified credentials. As of JSR 333 this method can also be used in order to clone the existing session (i.e. self-impersonation of the user that holds the session.

    -

    With Oak 1.0 impersonation is implemented as follows:

    - -
      - -
    1. Session#impersonate takes any kind of Credentials
    2. - -
    3. the specified credentials are wrapped in a new instance of ImpersonationCredentials along with the current AuthInfo object.
    4. - -
    5. these ImpersonationCredentials are passed to Repository.login
    6. -
    -

    Whether or not impersonation succeeds consequently both depends on the authentication setup and on some implementation specific validation that make sure the editing session is allowed to impersonate the user identified by the credentials passed to the impersonate call.

    -

    With Oak 1.0 only the default login module (LoginModuleImpl) is able to deal with ImpersonationCredentials and applies the following logic:

    - - -
    -
    ImpersonationCredentials
    -

    Since the implementation of Session.impersonate no longer uses SimpleCredentials to transport the original Subject but rather performs the login with dedicated ImpersonationCredentials, impersonation is no longer restricted to SimpleCredentials being passed to Session#impersonate call. Instead the specified credentials are passed to a new instance of ImpersonationCredentials delegating the evaluation and validation of the specified Credentials to the configured login module(s).

    -

    This modification will not affect applications that used JCR API to impersonate a given session. Note however that applications relying on the Jackrabbit implementation and manually creating SimpleCredentials with a SecurityConstants.IMPERSONATOR_ATTRIBUTE, would need to be refactor after migration to Oak.

    -
    -
    Impersonation with Custom Authentication Setup
    -

    Applications that wish to use a custom authentication setup need to ensure the following steps in order to get JCR impersonation working:

    - -
      - -
    • Respect ImpersonationCredentials in the authentication setup.
    • - -
    • Identify the impersonated from ImpersonationCredentials.getBaseCredentials and verify if it can be authenticated.
    • - -
    • Validate that the editing session is allowed to impersonate: The user associated with the editing session can be identified by the AuthInfo obtained from from ImpersonationCredentials.getImpersonatorInfo().
    • -
    -
    -

    Token Login

    -

    See section Token Authentication 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.

    -
    -

    Pre-Authenticated Login

    -

    Oak provides two different mechanisms to create pre-authentication that doesn’t involve the repositories internal authentication mechanism for credentials validation.

    - - -

    See section Pre-Authentication Login 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 Login Module
    -

    The external login module is a base implementation that allows easy integration of 3rd party authentication and identity systems, such as LDAP. The general mode of the external login module is to use the external system as authentication source and as a provider for users and groups that may also be synchronized into the repository.

    -

    This login module implementation requires an valid SyncHandler and IdentityProvider to be present. The detailed behavior of the ExternalLoginModule is described in section External Authentication.

    +

    Oak Authentication Implementation

    +

    A description of the various requirements covered by Oak by default as well as the characteristics of the corresponding implementations can be found in section [Authentication: Implementation Details].

    +

    See section differences for comprehensive list of differences wrt authentication between Jackrabbit 2.x and Oak.

    +

    API Extension

    @@ -779,15 +614,15 @@ Session anonymous = repository.login(new
  • Authentication: Aimed to validate credentials during the first phase of the (JAAS) login process.
  • -

    In addition this package contains various utilities and base implementations. Most notably an abstract login module implementation ([AbstractLoginModule]) as described below and a default implementation of the AuthInfo interface (AuthInfoImpl).

    +

    In addition this package contains various utilities and base implementations. Most notably an abstract login module implementation (AbstractLoginModule) as described below and a default implementation of the AuthInfo interface (AuthInfoImpl).

    Abstract Login Module
    -

    This package also contains a abstract LoginModule implementation ([AbstractLoginModule]) providing common functionality. In particular it contains Oak specific methods that allow subclasses to retrieve the SecurityProvider, a Root and accesss to various security related interfaces (e.g. PrincipalManager).

    +

    This package also contains a abstract LoginModule implementation (AbstractLoginModule) providing common functionality. In particular it contains Oak specific methods that allow subclasses to retrieve the SecurityProvider, a Root and accesss to various security related interfaces (e.g. PrincipalManager).

    Subclasses are required to implement the following methods:

      -
    • `getSupportedCredentials(): return a set of supported credential classes.
    • +
    • getSupportedCredentials(): return a set of supported credential classes.
    • login(): The login method defined by LoginModule
    • @@ -837,56 +672,8 @@ Session anonymous = repository.login(new return false; } } -
    -
    -

    Token Management

    -

    See section token management for details.

    - -
    -
    -

    User and Group Synchronization

    -

    See section Synchronization for details.

    - -
    -
    -

    External Identity Management

    -

    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 for details.

    - -
    + +

    Configuration

    The configuration of the authentication setup is defined by the AuthenticationConfiguration. This interface provides the following method:

    @@ -909,11 +696,12 @@ Session anonymous = repository.login(new
  • GuestLoginModule: null login falls back to anonymous
  • -
  • TokenLoginModule: covers token base authentication
  • +
  • TokenLoginModule: covers token based authentication
  • LoginModuleImpl: covering regular uid/pw login
  • -
    + +

    Pluggability

    The default security setup as present with Oak 1.0 is able to provide custom implementation on various levels:

    @@ -923,14 +711,15 @@ Session anonymous = repository.login(new
  • The complete authentication setup can be changed by plugging a different AuthenticationConfiguration implementations. In OSGi-base setup this is achieved by making the configuration a service. In a non-OSGi-base setup the custom configuration must be exposed by the SecurityProvider implementation.
  • Within the default authentication setup you replace or extend the set of login modules and their individual settings. In an OSGi-base setup is achieved by making the modules accessible to the framework and setting their execution order accordingly. In a Non-OSGi setup this is specified in the JAAS config.
  • - -
  • The LoginModuleImpl uses UserAuthentication-implementations for performing the authentication process. Which user-authentication implementation to use is determined by the available UserAuthenticationFactorys which provide user- authentication implementations if a given UserConfiguration is accepted. Which user-authentication-factory is chosen depends on its OSGi service ranking property. The default factory has a ranking of 0 (OSGi default). Services with the highest ranking take precedence.
  • -
    + +

    Further Reading