Oak Documentation

OSGi Setup

Since Oak 1.3.7 the core bundle will install a dedicated OSGi component (SecurityProviderRegistration, labeled “Apache Jackrabbit Oak SecurityProvider”), which registers the SecurityProvider once all mandatory references have successfully been resolved. This new approach addresses issues present with the initial security provider implementation and has been backported to existing branches (see OAK-3201 and OAK-3441).

While optional configuration setting can be changed or extended at runtime, modules and extensions considered required for a functional security setup, need to be listed in the “Required Service PIDs” property. This asserts both reliable security setup and proper initialization of the individual modules. See also sections Configuration and Pluggability below.

Non-OSGi Setup

In a non-OSGi setup the SecurityProvider (be it the default or a custom implementation) gets passed to the repository constructor. See section pluggability for details wrt module initialization.

The following example has been extracted from the basic test setup:

NodeStore nodeStore = ...

ConfigurationParameters params = ... // TODO: provide config options
// Optional: set additional/custom implementations of the supported `SecurityConfiguration`s via the params
SecurityProvider sp = SecurityProviderBuilder.newBuilder().with(params).build();

Repository repository = new Jcr(nodeStore).with(sp).createRepository();

Mandatory and Optional Modules

While Oak ships default implementation for all security configurations listed above, only authentication and authorization are mandatory for a functional Oak repository.

This is compliant with the security requirements defined by JSR 283 which defines API to login into the repository and mandates minimal permission evaluation, be it implementation specific of imposed by the optional access control management.

The minimal security setup may consequently be reduced to a setup as defined by the following imaginary, custom SecurityProvider (see also OpenSecurityProvider)

 public class MySecurityProvider implements SecurityProvider {
 
     [...]
 
     public <T> T getConfiguration(Class<T> configClass) {
         if (AuthenticationConfiguration.class == configClass) {
             return (T) new MyAuthentication();
         } else if (AuthorizationConfiguration.class == configClass) {
             return (T) new MyAuthorization();
         } else {
             throw new IllegalArgumentException();
         }
     }
     
     private final class MyAuthentication extends SecurityConfiguration.Default implements AuthenticationConfiguration {   
         [...]
     }
     
     private final class MyAuthorization extends SecurityConfiguration.Default implements AuthorizationConfiguration { 
         public AccessControlManager getAccessControlManager(Root root, NamePathMapper namePathMapper) {
             throw new UnsupportedOperationException();
         }
         public RestrictionProvider getRestrictionProvider() {
             throw new UnsupportedOperationException();
         }
         public PermissionProvider getPermissionProvider(Root root, String workspaceName, Set<Principal> principals) {
             return MyPermissionProvider.getInstance(principals);
         }
     }
 }

All other security modules can be considered optional from an Oak repository point of view. Please note the following dependencies and special cases:

1. Authentication is mandatory and expected to bind a set of Principals to the Subject. This may happen before or during the repository login.
2. Permission Evaluation is mandatory and associated with the set of Principals bound to to the Subject during the authentication step.
3. Principals represent the link between authentication and authorization and MAY be exposed by Principal Management module as described above.
4. Access Control Management is optional and usually goes along with Principal and Privilege Management
5. Principal Management is optional and is NOT tied to User Management. However, supporting User Management in a given repository setup usually goes along with exposing the corresponding principals as part of the Principal Management.
6. User Management is optional and MAY be used for credentials validation during the authentication step. If present it is usually used as a source for principals exposed by Principal Management.

OSGi setup

The following steps are required to replace an existing unary security component or add an additional implementation (for multiple configurations only):

• Deploy the bundle containing your custom implementation
• Configure the component according to your needs
• For multiple configurations make sure you have set the desired ranking
• Find the SecurityProviderRegistration (“Apache Jackrabbit Oak SecurityProvider”) config and enter the PID of your custom security module as additional value to the requiredServicePids property.
• In case of a replacement remove the PID of the module to be replaced and make sure your implementation gets a higher SERVICE_RANKING or deactivate the obsolete module altogether.

Non-OSGi setup

In this case the individual security modules get “manually” bound/unbound to the SecurityProvider instance. The provider itself might be the default or a custom implementation of the interface. If and how security modules can be added to the provider remains an implementation detail and is not part of the SecurityProvider interface definition.

MyPrincipalConfiguration pc = new MyPrincipalConfiguration();

ConfigurationParameters params = ConfigurationParameters.EMPTY;
pc.setParameters(params);
SecurityProvider securityProvider = SecurityProviderBuilder.newBuilder().with(params).build();

CompositeConfiguration<PrincipalConfiguration> composite = (CompositeConfiguration) securityProvider
    .getConfiguration(PrincipalConfiguration.class);
PrincipalConfiguration defConfig = composite.getDefaultConfig();

pc.setSecurityProvider(securityProvider);
pc.setRootProvider(((ConfigurationBase) defConfig).getRootProvider());
pc.setTreeProvider(((ConfigurationBase) defConfig).getTreeProvider());
composite.addConfiguration(pc);
composite.addConfiguration(defConfig);

Repository repo = new Jcr(new Oak()).with(securityProvider).createRepository();

Initialization of SecurityConfiguration(s)

If a given security modules mandates repository and|or workspace initialization steps such as e.g. node type registration or persisting new index definitions, the deployment of the module requires a reload of the SecurityProvider.

In the default OSGi-based setup this is achieved by adding the PID of corresponding service to the Required Service PIDs property mentioned above ultimately forcing the re-registration of the SecurityProvider service with the bundle context.

Other setup scenarios would need to recreate the ContentRepository object or adjust the repository ‘initial’ content before binding the new configuration to the SecurityProvider in order to avoid inconsistencies.