SecurityPrincipal abstraction

SecurityPrincipal

The SpringSecurityModule provides an additional abstraction layer on top of the standard Authentication in the form of the SecurityPrincipal interface. Other modules like the UserModule and OAuth2Module provide an implementation of the SecurityPrincipal concept.

Since SecurityPrincipal is a relatively straightforward interface, a principal can be pretty much anything (user, group, machine…). The only requirement is that every SecurityPrincipal has a unique principal name that identifies it.

Several beans are available for interacting with the current security principal:

Type Description

Type	Description
`SecurityPrincipalService`	Allows you to fetch any `SecurityPrincipal` by its unique principal name using a backing `SecurityPrincipalRetrievalStrategy`. Also provides some helper methods to quickly authenticate or de-authenticate a principal.
`CurrentSecurityPrincipalProxy`	Proxies the current security principal (if there is one). Allows authority checking from anywhere in your code using the `hasAuthority(String)` method. The SpringSecurityAclModule wires a `CurrentAclSecurityPrincipalProxy` instead that provides additional methods to check for ACL permissions.

SecurityPrincipalService

Allows you to fetch any SecurityPrincipal by its unique principal name using a backing SecurityPrincipalRetrievalStrategy. Also provides some helper methods to quickly authenticate or de-authenticate a principal.

CurrentSecurityPrincipalProxy

Proxies the current security principal (if there is one). Allows authority checking from anywhere in your code using the hasAuthority(String) method.

The SpringSecurityAclModule wires a CurrentAclSecurityPrincipalProxy instead that provides additional methods to check for ACL permissions.

Example of using the SecurityPrincipalService to authenticate a principal

// execute a section within the scope of an authenticated SecurityPrincipal,
// when the block closes the previous authentication will be reset
try ( CloseableAuthentication authenticatedBlock
                    = securityPrincipalService.authenticate( principal ) ) {
    // do something
}

SecurityPrincipalRetrievalStrategy

The default SecurityPrincipalService uses a backing SecurityPrincipalRetrievalStrategy to fetch the actual principal based on its unique name. If you want to define your own custom implementation you can do so by replacing the strategy implementation, see the javadoc and source code for more information.

SecurityPrincipal caching

The default SecurityPrincipalService uses the securityPrincipalCache for retrieving principal instances. If the cache does not return an instance, the request is delegated to the the SecurityPrincipalRetrievalStrategy. Actually maintaining the cache however is left to the implementation providers, the default SecurityPrincipalService only caches null values (principal not found). Examples can be found in SecurityPrincipal providing modules, for example UserModule.

SecurityPrincipalLabelResolver

Any module can define one or more SecurityPrincipalLabelResolver beans. These are used to generate a pretty label for a given SecurityPrincipal instance. SecurityPrincipalLabelResolver instances are ordered and the first resolver to return a valid label will be used.

SecurityPrincipalLabelResolver beans should not be used directly but through the exposed SecurityPrincipalLabelResolverStrategy.

It is a best practice to provide a SecurityPrincipalLabelResolver for every SecurityPrincipal implementation your module provides. The resolver beans do not need to be exposed.

« Debugging security SecurityPrincipal AllowableActions »