Oak Documentation

Overview

The purpose of the external login module is to provide 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.

What it does:

• facilitate the use of a 3rd party system for authentication
• simplify populating the oak user manager with identities from a 3rd party system

What it does not:

• provide a transparent oak user manager
• provide a transparent oak principal provider.
• offer services for background synchronization of users and groups

See also Best Practices for External Authentication.

Implementation Details

The external identity and login handling is split into 3 parts:

• External Login Module: LoginModule implementation that represents the connection between JAAS login mechanism, the external identity provider and the synchronization handler.
• External Identity Provider (IDP): This is a service implementing the ExternalIdentityProvider interface and is responsible to retrieve and authenticate identities towards an external system (e.g. LDAP).
• User and Group Synchronization: This is a service implementing the SyncHandler interface and is responsible to actually managing the external identities within the Oak user management. A very trivial implementation might just create users and groups for external ones on demand.

This modularization allows to reuse the same external login module for different combinations of IDPs and synchronization handlers. Although in practice, systems usually have 1 of each.

An example where multiple such entities come into play would be the case to use several LDAP servers for authentication. Here we would configure 2 LDAP IDPs, 1 Sync handler and 2 ExtLMs.

Configuration

jackrabbit.oak {
     org.apache.jackrabbit.oak.security.authentication.token.TokenLoginModule sufficient;
     org.apache.jackrabbit.oak.spi.security.authentication.external.impl.ExternalLoginModule sufficient
        sync.handlerName="default"
        idp.name="ldap";
     org.apache.jackrabbit.oak.security.authentication.user.LoginModuleImpl sufficient;
 };

Pluggability

The design of the ExternalLoginModule allows for customization of the key features associated with third party authentication. In an OSGi-based setup these are covered by references within the ExternalLoginModuleFactory:

• ExternalIdentityProviderManager: Mandatory, unary reference for the ExternalIdentityProvider lookup; see External Identity Management for details.
• SyncManager: Mandatory, unary reference for the SyncHandler lookup; see User/Group Synchronization for details.

The default implementations (ExternalIDPManagerImpl and SyncManagerImpl) extend AbstractServiceTracker and will automatically keep track of new ExternalIdentityProvider and SyncHandler services, respectively.

Since Oak 1.5.1 support for different or multiple types of Credentials can easily be plugged by providing an ExternalIdentityProvider that additionally implements CredentialsSupport. This is an optional extension point for each IDP; if missing the ExternalLoginModule will fall back to a default implementation and assume the IDP only supports SimpleCredentials. See details below.

  @Component()
  @Service(ExternalIdentityProvider.class, CredentialsSupport.class)
  public class MyIdentityProvider implements ExternalIdentityProvider, CredentialsSupport {

      public MyCredentialsSupport() {}

      //-----------------------------------------< CredentialsSupport >---
      @Nonnull
      @Override
      public Set<Class> getCredentialClasses() {
          return ImmutableSet.<Class>of(MyCredentials.class);
      }

      @CheckForNull
      @Override
      public String getUserId(@Nonnull Credentials credentials) {
          if (credentials instanceof MyCredentials) {
              return ((MyCredentials) credentials).getID();
          } else {
              return null;
          }
      }

      @Nonnull
      @Override
      public Map<String, ?> getAttributes(@Nonnull Credentials credentials) {
          // our credentials never contain additional attributes
          return ImmutableMap.of();
      }
      
      //-------------------------------------< ExternalIdentityProvider >---
      
      @CheckForNull
      @Override
      public ExternalUser authenticate(@Nonnull Credentials credentials) {
          if (credentials instanceof MyCredentials) {
              MyCredentials mc = (MyCredentials) credentials;
              if (internalAuthenticate(mc)) {
                  return new MyExternalUser(mc.getID());
              } else {
                  throw new LoginException();
              }
          } else {
              return null;
          }
      }

      [...]
      
      //----------------------------------------------< SCR Integration >---
      @Activate
      private void activate() {
          // TODO
      }
  }