Defining Policies & Rules

With Policy Based Access Control (“PBAC”), TrustBuilder aims:

• To offer centralized policy governance, whereby all policies and policy rules are made explicit and governed and maintained in a single place, as opposed of being ‘implied’ by different access control systems and applications

• To offer externalized fine-grained authorization, whereby policy decisions happen in 1 place, and not in every application

• To enable transaction authorization, i.e. not only authorization to access an application or a record, but also authorization at the transaction level, for every individual transaction

• To enable consent-driven authorization, i.e. to include the owner’s consent before giving authorization to access a personal record

• To enable pre-assigned entitlements, such as accounts, permissions, privileges, and roles, to be provisioned to RBAC-driven applications.

Policy Based Access Control

PBAC (Policy Based Access Control) and ABAC (Attribute-Based Access Control) are both methods for controlling access to resources, but they work in slightly different ways.

ABAC is a type of access control where access decisions are based on a predefined set of attributes of the subject, resource, and action, as well as the context in which the request is made. ABAC is often used in situations where traditional role-based access control (RBAC) is not sufficient, such as in multi-tenant environments or when dealing with sensitive data.

PBAC extends ABAC and bases access decisions on auditable policies that take attributes of the subject, resource, action and context into account as well as elements that are not predefined, such as dynamic risk scores and derived attributes. With TrustBuilder, these policies can be created, managed, versioned and audited by a central authority. They define the rules for who can access which resources under which circumstances. PBAC is very helpful in combination with the TrustBuilder ‘persona’ concept.

Policy Administration

Policy Administration is implemented using a Git repository (see Git). Policies are versioned, and support branching, merging, copying, and staging. A “commit” instantiates a policy for a specific tenant. As such, Policy Administration contains following components:

• Policy Administration Point (PAP): The point where the policies are actually administered using the Git repository and the the admin portal across the customer’s tenants. 

• Policy Retrieval Point (PRP): The point where the policies are stored for real-time use as part of the Tenant Manager. The PRP contains the policies administered, configured, versioned and released by the customer for each tenant.

To counter the risk of creating policies conflicting rules, the PAP enables policy review from different angles and is able to respond to questions such as "Give me any policies where this rule applies?” “Which SPs use this policy?” and “Which policies include this rule?”.

In fact and as opposed to XACML3 and OPA, TrustBuilder brings control & governance to policy administration. While TrustBuilder borrowed concepts from XACML3 (see eXtensible Access Control Markup Language (XACML) Version 3.0) and OPA Rego (see Policy Reference), we re-engineered the concepts into a usable model that truly embraces control & governance:

1. The TrustBuilder policy language is declarative, concise and readable (inspired by XACML3 and Rego v0.43)

2. TrustBuilder policies are deployed using established mechanisms of open source Git that include versioning, branching, committing, merging, deploying.

This way, TrustBuilder truly enables business people, product managers, marketing managers, security officers, security auditors, and application owners to review the policies in connection with the resources and service providers they take responsibility for.

Policies and Rules

XACML and TrustBuilder have both policies and rules to provide a flexible and powerful mechanism for specifying access control decisions.

Policies provide a high-level view of the access control requirements for a particular resource and are typically used to define the overall access control strategy for an organization.

Rules, on the other hand, are used to define the specific access control decisions that are made for a particular request. They provide a more detailed view of the access control requirements for a particular resource and are typically used to define the specific access control decisions that are made for a particular request.

By using both rules and policies, XACML and TrustBuilder allow for a flexible and powerful mechanism for specifying access control decisions. Policies provide a high-level view of the access control requirements for a particular resource, while rules provide a more detailed view of the access control requirements for a particular request. This allows for a more granular and fine-grained control over access to resources, and yet makes it auditable.

Additionally, the use of both policies and rules allows for a separation of concerns, where policies can be defined and managed by security administrators, while rules can be defined and managed by application developers. This separation allows for a clear and consistent access control strategy, while also allowing for the flexibility to adapt to changing requirements.

Additionally, TrustBuilder offers a library of rule templates and allow customers to re-use rules in different policies.

When deciding what to put in a policy versus what to put in a rule, it's important to consider the following guidelines:

• Granularity: Policies should be used to define the overall access control strategy for an organization or resource, while rules should be used to define specific access control decisions for a particular request.

• Reusability: Policies can be reused across multiple resources, while rules can be reused across multiple policies.

• Flexibility: Policies provide a high-level view of the access control requirements for a resource, while rules provide a more detailed view. This allows for a more granular and fine-grained control over access to resources.

• Separation of concerns: Policies can be defined and managed by security administrators, while rules can be defined and managed by application developers. This separation allows for a clear and consistent access control strategy, while also allowing for the flexibility to adapt to changing requirements.

• Complexity: If a rule is becoming too complex and hard to manage, it might be a good idea to refactor it into a policy.

It's worth noting that these are general guidelines and the specific decision of what to put in a policy versus what to put in a rule will depend on the specific use case and requirements. It's important to keep in mind that XACML provides a flexible and powerful mechanism for specifying access control decisions, and the use of both policies and rules can be used to meet a wide range of access control requirements.

Policy Language

TrustBuilder adopts a declarative Policy Language that fundamentally splits up traditional access flows into a set of policies and rules. A policy consists of rules that stand on their own and that can be re-used in other policies.

XACML3 (eXtensible Access Control Markup Language) is an OASIS standard for access control, which provides a way to express policies for access control decisions in a consistent and interoperable format. TrustBuilder supports a user-friendly variant of the XACML3 policy language and enables our customers to implement fine-grained, policy-based access control (PBAC) in their systems for more precise and dynamic control of access to resources. This is particularly important in situations where traditional role-based access control (RBAC) is not sufficient, such as in multi-tenant environments or when dealing with sensitive data and transactions.

Formally, the Policy Language consists of following constructs:

<policy> ::= <rule> | <combination algorithm> <rule>+
<combination algorithm> ::=deny-unless-permit | deny-overrides | permit-unless-deny | permit-overrides

<rule> ::= ( permit | deny) <condition> [ <obligations> ]
<condition> ::= <expression> | <rule operator> <expression>+
<rule operator> ::= any-off | all-off

<expression> ::= <expression operator> <operand>+
<expression operator> ::= equals | not_equals | is_in | not_in | has_value | ...
<operand> ::= <literal> | $<field-name>

Rules are combined in a policy adopting the conventions stated in eXtensible Access Control Markup Language (XACML) Version 3.0:

Conditions in a rule can be combined using the following operators:

• all-of

• any-of acts as the logical-or between conditions

The result of a policy and of its subordinate rules are twofold:

• the effect is either permit or deny and they refer to the result in case the conditions of the rule are met.

• if a condition is not met, the result is the reverse of the effect:

  • if the effect of a rule is permit the result will be deny if the condition is not met

  • if the effect of a rule is deny the result will be permit if the condition is not met

• <obligation> is an array referring to pre-configured obligations referred to by their name.

Declaring a Policy

In XACML and TrustBuilder, a policy is a statement that specifies a combination of rules that represent conditions under which a particular request for access to a resource will be granted or denied.

A TrustBuilder policy includes the following elements:

• name to give a unique identifier to the policy

• description to provide guidance as to the goal of this policy

• rules of the applicable rules

• combination to specify how the decisions of the rules must be combined to make a policy decision

XACML also includes ‘target’ in the policy definition, which defines the conditions under which the policy applies. In contrast, TrustBuilder allows customers to associate any policy with resources (such as service providers) and with points in a workflow. The TrustBuilder approach enables a more versatile use as it makes the policies re-usable.

A policy is maintained by the Policy Administration Point in JSON format as follows:

{
  "name": "<policy name>",
  "description": "<text to describe the aim of the policy>",
  "rules": ["<rule1 name>", ...]
  "combination": "DENY_UNLESS_PERMIT"
}

Here is a policy example in JSON format:

{
  "name": "must-select-persona-nurse",
  "description": "You need the persona nurse to access",
  "rules": [ "only-nurses", "hourly-authentication", "must-supply-recent-mfa"], 
  "combination": "DENY_OVERRIDES"
}

Declaring a Rule

In XACML and TrustBuilder, a rule is a statement that defines actual conditions under which a particular request for access to a resource will be granted or denied.

A XACML and TrustBuilder rule includes the following elements:

• name to give a unique identifier to the rule

• description to provide guidance as to the goal of this rule

• effect to represent he decision that the rule will return, which can be "Permit", "Deny" or "Indeterminate".

• condition as a set of conditions that must be satisfied in order for the rule to be applied. This element can include logical operations, functions, and attributes.

• obligation that represent a set of additional actions that must be performed before a "permit" can be granted. They are represented as a collection of obligation elements.

Even though XACML does not give clear indications on the meaning of “Indeterminate”, TrustBuilder treats such decision as equivalent to a "Deny" with “Obligations” decision.

A rule is maintained by the Policy Administration Point in JSON format as follows:

{
  "name": "<rule name>",
  "description": "<text to describe the aim of the rule>",
  "effect": "<PERMIT or DENY>",
  "condition": {
    "all-of": [
      { "<operator>": [ "<operand-1>", "<operand-2>", ... ] },
      ...
    ]
  },
  "obligation": {
    "<obligation1>": [ "<value1>", ... ],
  }
}

Declaring Rule Expressions

Expressions in a rule condition are constructed as follows:

{ "<operator>": [ "<operand-1>", "<operand-2>", ... ] }

The <operator> in a rule refers to the operation to evaluate the first <operand-1> in combination with zero, one or more following <operands>. The table below shows the currently supported <operator>. The list of available <operator> will continuously be extended with every new version of the Policy Model.

The <operand> $abc123 in the given examples is a fictitious one and cannot be used. The available operands are listed in the table below.

An <operand> can be a literal value or be an attribute of the current session, the user profile, or the actual request:

• session refers to the current session during which the request was sent;

• user refers to the user profile identified with sub in the current session;

• request refers to the set of attributes supplied in the request.

The list below shows the currently supported <operand>. The list of available <operand> will continuously be extended.

Literals can be any string. To enter a specific data, use the format of date as standardised by ISO 8601. For example 2023-05-17 to refer to May 17th, 2023. To enter a period of time, use the format of duration as standardised by ISO 8601. For example PT1H means "1 hour", PT2M means 2 minutes, PT30S means 30 seconds, P5D means 5 days and P1Ymeans 1 year.

To distinguish literal values from referenced values (so-called variables), the latter must be preceded by a $-sign. To denote an attribute of a variable, use a “.” to separate the variable and the attribute. For example, “$session.user_id" refers to the session attribute user_id of the session, while "user_id"would refers to a literal string. To denote an attribute in an elem_match construct, use the “~” to refer to the enclosing variable. For example “~acr" refers to “$session.authentications[i].acr”, even though the construct to address an element in the array is not directly supported.

See “Managing User Personas” to know more about the persona object.

The operator elem_match deserves some further explanation. In plain English it means “in the array of records in <operand-1>, find a record that matches the criteria given in <operand-2> and if found, the result is TRUE else FALSE. Individual fields in the record are identified by preceding it with the “~” for example "~acr".

For example:

"elem_match": [
  "$session.authentications",
  { "not_older_than" : [ "~last_supplied_at", "PT1H" ] }
] 

means “in the array session.authentications, find a record of which the last_supplied_at field is not older than 1 hour ago” which means “does the session contain an authentication record that is more recent than 1 hour ago?”

Another example:

"elem_match": [
  "$session.authentications",
  { "equals" : [ "~acr", "AAL3" ] }
]

means “does the session contain an authentication record with authentication assurance level AAL3?”

Declaring Obligations

XACML obligations are a feature of the XACML standard that allow additional actions to be taken in response to a decision. Obligations are associated with a decision (Permit, Deny, or Indeterminate) and are triggered when the decision is made. They are used to express additional requirements or actions that must be performed in order to grant the access request.

Obligations can be associated with a specific rule. They consist of an obligation identifier, and a set of attributes (name-value pairs).

Here's an example of how XACML obligations work:

• An access request is made for a particular resource.

• The Policy Engine evaluates the policies and rules associated with the resource and returns a decision of "Deny".

• Along with the "Deny" decision, the Policy Engine also returns an associated obligation with the identifier "provide-mfa".

• The PEP (Policy Enforcement Point, i.e. the client application or the API gateway) that received the decision, now must perform (or delegate this to requesting client) the action specified by the obligation. In this case, it must ask the user to supply MFA.

It's worth mentioning that the PEP is responsible for executing the obligations, not the Policy Engine.

The following obligations are currently supported: