Apply security

You can protect (authentication + authorizations) the urls of your JAX-RS application by using the SecurityFilter and defining the appropriate mapping. It has the following behaviour:

1. If the HTTP request matches the matchers configuration (or no matchers are defined), the security is applied. Otherwise, the user is automatically granted access.

2. First, if the user is not authenticated (no profile) and if some clients have been defined in the clients parameter, a login is tried for the direct clients.

3. Then, if the user has a profile, authorizations are checked according to the authorizers configuration. If the authorizations are valid, the user is granted access. Otherwise, a 403 error page is displayed.

4. Finally, if the user is still not authenticated (no profile), he is redirected to the appropriate identity provider if the first defined client is an indirect one in the clients configuration. Otherwise, a 401 error page is displayed.

Setup with annotations

In order to bind the filter to an URL, it must be bound to a JAX-RS Resource method using the @Pac4JSecurity annotation.

For example:

    @GET
    @Produces(MediaType.APPLICATION_JSON)
    @Pac4JSecurity(authorizers = "isAuthenticated")
    public UserData getUserData(@Pac4JProfile CommonProfile profile) {
        LOG.debug("Returning infos for {}", profile.getId());

        return new UserData(profile.getId(), profile.getDisplayName());
    }

It is also possible to put @Pac4JSecurity directly on a class resource: the security filter will thus apply to every method of the resource and can be overridden with a method-level @Pac4JSecurity annotation (always takes precedence) or disabled by exploiting the ignore property of the annotation:

@Path("/class")
@Pac4JSecurity(clients = "DirectFormClient", authorizers = "isAuthenticated")
public class TestClassLevelResource {

    @GET
    @Path("no")
    @Pac4JSecurity(ignore = true)
    public String get() {
        return "ok";
    }

    @POST
    @Path("direct")
    public String direct() {
        return "ok";
    }
}

Setup with register

Another option is to register the filter into Jersey as a global filter like so:

resourceConfig.register(
    new Pac4JSecurityFilterFeature(pac4jConfig, null, "isAuthenticated", null, "excludeUserSession", null));

null values are used to denote defaults, see next section.

Available parameters

1. clients (optional): the list of client names (separated by commas) used for authentication:

• in all cases, this filter requires the user to be authenticated. Thus, if the clients is blank or not defined, the user must have been previously authenticated
• if the client_name request parameter is provided, only this client (if it exists in the clients) is selected.

2. authorizers (optional): the list of authorizer names (separated by commas) used to check authorizations:

• if the authorizers is blank or not defined, no authorization is checked and only the csrfCheck authorizer is applied
• the following authorizers are available by default (without defining them in the configuration):
  • isFullyAuthenticated to check if the user is authenticated but not remembered, isRemembered for a remembered user, isAnonymous to ensure the user is not authenticated, isAuthenticated to ensure the user is authenticated (not necessary by default unless you use the AnonymousClient)
  • csrfCheck to check that the CSRF token has been sent as the pac4jCsrfToken header or parameter in a POST request.

3. matchers (optional): the list of matcher names (separated by commas) that the request must satisfy to check authentication/authorizations:

• if the matchers is blank or not defined, it is satisfied and the securityHeaders,csrfToken matchers are applied
• the following matchers are available by default (without defining them in the configuration):
  • hsts to use the StrictTransportSecurityMatcher authorizer, nosniff for XContentTypeOptionsMatcher, noframe for XFrameOptionsMatcher, xssprotection for XSSProtectionMatcher, nocache for CacheControlMatcher or securityHeaders for the five previous authorizers
  • csrfToken to use the CsrfTokenGeneratorMatcher with the DefaultCsrfTokenGenerator (it generates a CSRF token and saves it as the pac4jCsrfToken request attribute and in the pac4jCsrfToken cookie)
  • allowAjaxRequests to allow CORS requests
  • get, put, post, delete to allow the associated HTTP methods.

4. multiProfile (optional): it indicates whether multiple authentications (and thus multiple profiles) must be kept at the same time (false by default).

5. skipResponse (optional): by default pac4j populates an answer (in case of unauthenticated or unauthorized access, but also to add headers to the normal jax-rs response via the authorizers), if this is set to true then the handling of the response will be skipped and jax-rs will be free to process the request.