README_security.md

gateleen-security

Schema validation

Updating the acl (Access Control List) resources requires a validation against a schema to be positive. Check the schema gateleen_security_schema_acl

Log acl configuration changes

To log the payload of changes to the acl configurations, the RequestLogger can be used.

Make sure to instantiate the RequestLoggingConsumer by calling

RequestLoggingConsumer requestLoggingConsumer = new RequestLoggingConsumer(vertx, loggingResourceManager);

To enable the logging of the acl configurations, make sure the url to the acl configuration is enabled in the logging resource.

Example:

{
  "headers": [],
  "payload": {
    "filters": [
      {
        "url": "/playground/server/security/v1/acls/.*",
        "method": "PUT"
      }
    ]
  }
}

Also you have to enable the logging on the Authorizer by calling

authorizer.enableResourceLogging(true);

RoleMapper

If there are many ACL groups with equal routing setup, it is possible to define RoleMappers which do map the roles to a single ACL role.

The rolemapper object is by default expected at base/server/security/v1/rolemapper

Example - You have different ACL groups for a dedicated system domain and each of them would have the same permission setup:

  acl-domain-admin
  acl-domain-manager
  acl-domain-user

In this case you only define the acl "acl-domain" within your gateleen security configuration and the corresponding RoleMapper:

{
    "mappings": [{
      "pattern":"acl-domain-.*",
      "role":"acl-domain",
      "keepOriginal":false
      }
    ]
 }

Any request with a user group containing 'acl-domain-' will match the defined rolemapper and result in the defined resulting role acl-domain.

Note the additional keepOriginal flag which defines if the original role which matched the mapper must be kept in the list of roles or not.

Note: The rolemapper object is validated against the gateleen_security_schema_rolemapper json schema

Using request headers

In ACLs you can use wildcard definitions in the urls. These wildcards can contain request header names and will be replaced with the actual values from a request.

The wildcards have to be in the format

<header name>

Example:

/gateleen/resources/<foobar>/info

A request with a header foobar: yyy will be transformed to

/gateleen/resources/yyy/info

Practical example

The request header feature in the ACLs can be used to restrict access to user specific resources to the correct user (and maybe an admin) only.

User ACL

{
    "userspecific.get.own": {
        "methods": ["GET"],
        "path": "/resources/userspecific/<x-user>/info"
    }
}

Admin ACL

{
    "userspecific.get.all": {
        "methods": ["GET"],
        "path": "/resources/userspecific/([^/]+)/info"
    }
}

So having a resource /resources/userspecific/batman/info, it can only be loaded by a user having the request header x-user: batman or a user having the admin role.

Content-Type constraints

The ContentTypeConstraintHandler allows the definition of Content-Type Request header constraints on urls.

Use this to block unwanted Content-Type values on specific urls.

Always allowed Content-Type values

In the constructor of the ContentTypeConstraintHandler, you are able to define a list of Content-Type values that are allowed for all requests.

Example:

new ContentTypeConstraintHandler(configResManager, repository,
                        SERVER_ROOT + "/admin/v1/contentTypeConstraints",
                        Arrays.asList(new PatternHolder("application/json"), new PatternHolder("image/.*")));

Note that also regex patterns like image/.* are allowed.

Content-Type constraint configuration resource

The configuration resource for the Content-Type constraints is validated against the schema gateleen_security_contenttype_constraint_schema.

Example:

{
  "/gateleen/contacts/zips/(.*)": {
    "description": "contacts are uploaded as zip files",
    "allowedTypes": ["application/zip"]
  },
  "/gateleen/contacts/storage/(.*)": {
    "description": "contact storage contains images and videos",
    "allowedTypes": ["image/png", "image/bmp", "video/.*"]
  }
}