Access Policies

This Article describes the format and function of Access Policies.

Access Policies process all access requests based on various factor. Any Request against the API is checked against the current policy determined if this request is accepted or denied. The policy Access Policy has a List of Access Rules that decide the outcome of an access decision. The Rules are bias towards denying access, so event if multiple rules match the request a single deny effect determines a denied access.

Access Policies is formatted in Json as follows:

{
    "_version": "1970-01-01",
    "description": "Example Policy",
    "validFrom": "1970-01-01T00:00:00.000+0000",
    "rules": [
        [...]
    ],
    "default_effect": "DENY | ALLOW"
}

• _version: a Version to keep track of the policy state. (this is not used internally and can have any format)
• description: description of this policy
• validFrom: this is used when using multiple policies that will roll over at a specific time. The date format is yyyy-MM-dd'T'HH:mm:ss.SSSZ
• rules: The most important Part of this class. Here all the rules for accessing collections, documents and more can be defined. (More about access rules in the next paragraph.)
• default_effect: if no access rule matches the given request a default effect can be defined. Valid values are DENY and ALLOW. This allows the access policy to act as a white or black list.

An AccessPolicy describes the actions that are permitted within a system through AccessRules that are matched against an authorization request and the authorization effect they mandate.
The matching process works as follows:

• The provided rules are matched - in the ordering given by the list and thus the ordering in which they appear in the JSON file - against authorization requests.
• Rules are matched using the targeted resource(s), the requesting subject(s), the requested action(s) and, optionally, other conditions
• The authorization effect of the first matching rule decides about the outcome of the authorization request.
• If no rule matches, the default effect is used.

An access policy has a date validFrom that indicates the moment at which it becomes applicable, but no date that indicates the moment at which it loses applicability.
Instead, once a policy becomes applicable, it remains applicable until superseded by a policy with a later date. Thus, if more than one policy is defined then the one with the most recent date is currently applicable.
In Output Organizer this date also has to be reflected in the Helm definition.

Access Rules

Access Rules is a decider on a set of predefined resources and actors. If a rule matches a given request if either allows or denies its execution.

Access Policies is formatted in Json as follows:

{
  "name": "Example Rule",
  "effect": "ALLOW | DENY",
  "resources": [
    "*"
  ],
  "actions": [
    "*"
  ],
  "subjects": [
    "*"
  ],
  "conditions": {
    [...]
  }
}

Name:

Descriptive name of the rule.

Effect:

The effect determines the outcome of the access check. If the rule conditions apply, the effect denies resource access.
In most cases this should contrast the default_effect of the policy that the rule it is in. Because of the sequential processing of the rules this can revert the outcome of a previous rule. In such cases it can be useful for the effect to match the default effect.

Resources:

With Resources the rules can be targeted to a specific context. The resources are represented as a string literal in Json path annotation. The resource identifier is usually set by the Rest Controller and matches the resource that this Controller manages.
In Fusion the collection resources are defined with collection and collection element resource with collection-element as their resource key, the collection element resource is a superset of collection and inherits the collection namespace.
The resources can then be indexed in a condition using the identifier path to a resource is analog to the collection json structure (see example at the bottom of tha page).

{
  "equals" : {
    "collection.type": "generic"
  }
}

In addition to the collection json structure the path collection.principal can be used to get an evaluation of ownership:

{
  "equals" : {
    "collection.principal": "own"
  }
}

Possible values are own and any.

Actions:

Actions describe the intent of the request that has to be evaluated. A cation can differentiate actions on the same resource. For example a different rule applies to a delete action than a read access on the same resource. We predefine a set of cor actions defined in com.neverpile.common.authorization.api.CoreActions:
core:GET,core:CREATE, core:UPDATE, core:DELETE, core:QUERY, core:VALIDATE

The CoreActions are loosely based on the HTTP verbs and can be used accordingly when using a REST API.

If the Action is defined as "*" the rule applies to all actions.

Additional actions are:

• document:pages:reorder: reordering pages
• document:pages:delete: deletion of pages
• document:pages:add: adding pages to documents
• document:pages:rotate: rotating pages
• document:pages:gradation: changing the gradation curve
• document:create: creation of new documents
• annotations:add: creation of new annotations
• annotations:edit:own: modification of own annotations
• annotations:edit:all: modification of all annotations

Any other Action can be user defined by implementing a custom com.neverpile.common.authorization.api.Action.

Subjects:

Subjects represent the principal that is trying to access a resource. To get the necessary information we use the spring security context, that provides the user and its authentication. The subject can be checked and restricted in a view different ways:

Predefined strings that act as basic checks without knowledge about the authentication details:
anonymous : any anonymous user without authentication.
authenticated : all authenticated users.
*: all users regardless of authentication.
principal: <NAME> User check : the given name will be compared against Authentication.getName()
role: <ROLE> Role check : the given role will be compared against Authentication.getAuthorities().getAuthority()
claim: <SPEL_EXPRESSION> Claim check : the user authentication will be checked against the given SPEL expression with JwtAuthenticationToken.getToken().getClaims() (only works with JSON Web Tokens)

Conditions:

Conditions allow an almost arbitrarily complex decisions based on an ConditionContext which is responsible for supplying context information through named context variables.

To create more complex statements it is possible to create composite conditions like "and" and "or".

We provide various condition implementations like:

• AndCondition
• OrCondition
• TrueCondition
• FalseCondition
• EqualsCondition
• ExistsCondition
• GreaterThanCondition
• GreaterOrEqualToCondition
• LessThanCondition
• LessOrEqualToCondition
• NotCondition
• RangeCondition

You can implement your own conditions using the provided Interfaces com.neverpile.common.condition.Condition and com.neverpile.common.condition.CompositeCondition

An example for a condition serialized as JSON would look like this:

{
  "and": {
    "conditions": [
      { "equals": { "collection.metadata.test": true } },
      { "equals": { "collection.type": "generic" } }
    ]
  }
}

for more Information about Condition please refer to the Conditions section

Advanced example:

{
  "_version": "1970-01-01",
  "validFrom": "1970-01-01T00:00:00.000+0000",
  "description": "Example authorization policy",
  "default_effect": "DENY",
  "rules": [
    {
      "name": "Allow authorized users read access",
      "effect": "ALLOW",
      "resources": [ "collection" ],
      "actions": [ "core:GET" ],
      "subjects": [ "authenticated" ],
      "conditions": {
        "equals": { "collection.type": "Typ1" }
      }
    },
    {
      "name": "Allow specific user group write access",
      "effect": "ALLOW",
      "resources": [ "collection" ],
      "actions": [ "core:CREATE", "core:UPDATE", "document:delete", "document:pages:delete", "document:pages:reorder", "document:pages:add", "document:pages:copy", "annotations:edit:all", "annotations:add" ],
      "subjects": [ "role:GroupA.WriteAccess",  "role:GroupB.WriteAccess" ],
      "conditions": {
        "equals": { "collection.type": "Typ1" }
      }
    },
    {
      "name": "Deny all users modification of marked documents",
      "effect": "DENY",
      "resources": [ "collection-element" ],
      "actions": [ "document:delete", "document:pages:reorder", "document:pages:delete", "document:pages:add" ],
      "subjects": [ "*" ],
      "conditions": {
        "and": {
          "conditions": [
            { "not": { "equals": { "collection-element.metadata.modifiable": true } } },
            { "equals": { "collection.type": "Typ1" } }
          ]
        }
      }
    }
  ]
}