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 Dossier 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 resource is represented as a string literal and has to be predefined by the class that uses the . The resource is usually set by the Rest Controller and matches the resource that this Controller managers. In Fusion the CollectionResource and CollectionElementResource Rest Controller both define "collection" as their resource key. For some Checks from the Fusion Client "collection-element" is defined to make checks for a single element in a collection.

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:
GET,CREATE, UPDATE, DELETE, QUERY, 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.

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. User check : "principal: <NAME>" the given name will be compared against Authentication.getName() Role check : "role: <ROLE>" the given role will be compared against Authentication.getAuthorities().getAuthority() Claim check : "claim: <SPEL_EXPRESSION>"+ 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