v9 (current) v8
Edit Page

Authorizers

RESTHeart

Authorizers check if the authenticated client can execute the request according to the security policy.

RESTHeart provides two implementations of Authorizer:

Multiple Authorizers can be enabled; an Authorizer can be either a VETOER or an ALLOWER.

Important
 A request is allowed when no VETOER denies it and any ALLOWER allows it.

Implementation

The Authorizer implementation class must implement the org.restheart.plugins.security.Authorizer interface.

public interface Authorizer extends ConfigurablePlugin {

    /**
     *
     * @param request
     * @return true if request is allowed
     */
    boolean isAllowed(final Request request);

    /**
     *
     * @param request
     * @return true if not authenticated user won't be allowed
     */
    boolean isAuthenticationRequired(final Request request);
}

Registering

The Authorizer class must be annotated with @RegisterPlugin:

@RegisterPlugin(name="myAuthorizer",
        description = "my custom authorizer",
        authorizerType = ALLOWER)
public class MyAuthorizer implements Authorizer {

}

Explaining a denial

Tip
 Available since version 9.9.0.

By default, when a request is denied (no ALLOWER allows it, or a VETOER vetoes it) RESTHeart replies with a plain 403 Forbidden and an empty body. This is often not enough to understand why the request was rejected, especially for a client without access to the server logs.

An Authorizer can attach a specific reason for the denial by setting the Authorizer.VETO_MESSAGE request parameter before returning false:

request.attachParam(Authorizer.VETO_MESSAGE, "Origin " + origin + " not allowed");
return false;

When set, RESTHeart includes it as the message field of the JSON body of the 403 Forbidden response:

{ "message": "Origin https://evil.example.com not allowed" }

If no Authorizer sets Authorizer.VETO_MESSAGE, the response body stays empty, as before.

This does not depend on the target service: the denial is evaluated before the request reaches it, so it works the same whether the service would have returned JSON, plain text (StringService), binary data (ByteArrayService), or anything else — the service is never actually invoked.

org.restheart.security.authorizers.OriginVetoer uses this mechanism, so a request rejected because its Origin header is missing or not whitelisted gets a body explaining exactly that.

Configuration

The Authorizer can receive parameters from the configuration file using the @Inject("config") annotation:

@Inject("config")
private Map<String, Object> config;

@OnInit
public void init() throws ConfigurationException {
    // get configuration arguments
    int number  = argValue(this.config, "number");
    String string = argValue(this.config, "string");
}

The parameters are defined in the configuration using the name of the authorizer as defined by the @RegisterPlugins annotation:

myAuthorizer:
    number: 10
    string: a string