RESTX Security support
Restx provides its own session and security support. The rationale for that is that Restx fully embraces the “no conversation state on web application server” moto, which is incompatible with standard Java session (and therefore security) management.
When used in a servlet container, you can use the container security features. But then you rely on the container session management which is stateful and requires more complex load balancing management and HA tuning.
The session mechanism in Restx is based on signed client cookies storing only a set of session keys, the server being able to reproduce the full session state based only on these keys. The keys being signed, they can’t be tampered on the client side.
The security mechanisms relies on this session facilty and provides convenient authorization management together with a very flexible authentication support.
You can access the currently authenticated principal using
It doesn’t assume how this has been set, so authentication is very flexible, you only need to call
RestxSession#authenticateAs(RestxPrincipal principal) like this in your code:
If you already have an authentication mechanism, call that method once you get an authenticated principal (that is to say a user or a third party app or anything else that you consider can authenticate in your app).
If you don’t already have such authentication mechanism, Restx provides a basic authentication facility in the
We recommend that you read these articles before dealing with password storage and general authentication issues:
All you need to do is:
- add a dependency on the module
- provide an implementation of
BasicPrincipalAuthenticator defines 2 methods that you need to implement:
Optional<? extends RestxPrincipal> authenticate(String name, String passwordHash, ImmutableMap<String, ?> principalData)
Optional<? extends RestxPrincipal> findByName(String name)
restx-security-basic module provides the following endpoints:
Using json object like this:
if the user / passwordHash is valid (according to your implementation of
BasicPrincipalAuthenticator), the principal is authenticated for the duration of the session, otherwise a
401 error is returned.
Returns the currently opened session if any, 401 if no session is opened
Finish the current session, i.e. logout the currently authenticated principal.
Sudoing, aka “run as”
Restx supports out of the box a
su mechanism, which lets you override the current session (and especially the principal) with arbitrary data for the duration of a single request.
To use this mechanism you just need to:
- be authenticated with a Principal with
- use the HTTP Header
RestxSuand give it the content of the session keys you want to override
This mechanism is used in the API-DOCS console, allowing to easily tests your requests for arbitrary principals.
Here is an example:
Handling authorizations on your Restx endpoints is very easy. First, Restx endpoints are secured by default: it means that you need to have a principal authenticated to use a Restx endpoint.
So if you have this:
GET /greetings/world will return a 401 http code by default.
If you want to make an endpoint public, you need to use the @PermitAll annotation:
Note that you can also use that annotation at class level rather than method level, to make all endpoints in a class public.
Restx also allows to specify a role for the principal, using the @RolesAllowed annotation:
With that not only Restx will check that a principal is authenticated, but it will also check that it has the
admin role. In case a principal is authenticated but does not have the
admin role, a
403 HTTP status code will be returned.
For more advanced authorizations, have a look at the
Permission types, which let you define and use very flexible authorizations.