Combination with Token Authentication

Whenever JCR sessions created with Oak are short-lived (e.g. only lasting for a single HTTP request) authentication against an external IDP may not perform well. It is therefore recommended to use external authentication in combination with an additional authentication mechanism like e.g. the built-in token login.

Make sure the token login module has control flag ‘SUFFICIENT’ and is evaluated prior to the external login that connects to the external IDP.

Combination with Default Authentication

Oak comes with a default login for user accounts stored and managed inside the JCR content repository. This also includes support for default users like ‘anonymous’ (guest) and ‘admin’ with full access to the repository. If this is desired, it is recommend to also add the default LoginModule to the JAAS configuration.

The optional order depends on the frequency of default vs external login: if login or impersonation against local users occurs frequently (e.g. unauthentication login with GuestCredentials) the default login module should have a higher ranking. However, if authentication of local users is unlikely, the external oak login should have a ranking.

External Identity Provider as SSOT

Your external identity provider should be considered the single source of truth (SSOT) for all users and groups defined and managed by it.

In contrast, the users/groups synchronized into the repository should be considered a volatile cache and ideally are immutable (i.e. only maintained by system sessions in charge of the synchronization).

The following features provided by the oak-auth-external module help to prevent unintended modification of synchronized external identities:

• Dynamic Membership: Enabling dynamic membership will result in membership information being stored in a protected property that cannot be altered using regular JCR write or Jackrabbit user management API.
• Dynamic Group: Can be used in combination with dynamic membership when the application requires group principals to also exposed through UserManager (and not just through PrincipalManager as it would be needed for permission setup). Note though that these group accounts cannot have members added (see section Enforcing dynamic groups)
• Protecting External Identities: The module comes with configuration option to protect external identities. If enabled (as warning or as full protection) a dedicated validator that will report/fail attempts to modify synchronized external identities. This will help to identify violations of the immutability contract.

User Management for External Identities

• Properties and membership for external identities must be managed in the external IDP. Changes made in the JCR repository using user management API will be overwritten upon the next sync.
• Never set a password for external users to make sure uid/pw login gets authenticated against the external IDP and never against the synchronized user in the repository.

Membership Nesting

For performance reasons avoid defining unnecessary membership nesting that increase the number of indirections (see Best Practices for Authorization).

Membership crossing IDP boundaries

Introducing membership crossing IDP boundaries should be considered a trust boundary violation.

If adding external identities to local groups cannot be avoided, leverage conditional auto-membership or auto-membership configuration in combination with dynamic membership (see Configuration of the DefaultSyncHandler).

Access control setup

Synchronized external identities (both in default and in dynamic sync mode) are exposed as principals through the Principal Management API and can be used for access control setup as described in Access Control Management.

See also section Best Practices for Authorization for recommendations.

External groups get synchronized together with external users upon repository login. If you wish to defined access control setup for groups prior to the synchronization upon login the following 2 options exist:

• Pre-sync external groups to make them available to the principal manager (see next section)
• Configure ImportMode=besteffort with the default Oak authorization setup and define access control content for principals before they exist (see below).