Authorization policies

In TrustBuilder, an Authorization Policy is a set of Authorization Rules that define the conditions under which a user can access a resource or an application. A combining algorithm determines how the results of these rules are evaluated to either grant or deny access.

This mechanism interprets the XACML (eXtensible Access Control Markup Language) standard, ensuring that authorization decisions are handled in a consistent and structured way.

DEFAULT POLICIES AND RULES

By default, TrustBuilder includes 3 default policies and 2 default rules:

Default Policies:
- admin-portal → controls access to the TrustBuilder Administration Portal.
- built-in → used by default by built-in components.
- self-service-portal → controls access to the Self-Service Portal.
Default Rules:
- require-admin-persona → allows access only for users with the admin persona.
- require-authentication → requires user to be authenticated at AAL3 level.

Administrators can create their own policies and rules to meet the specific authorization requirements of their organization. They can also update the proposed ones according to their needs.

Create a policy

To create a policy from TrustBuilder Admin portal:

Navigate to Authentication > Authorization Policies.
Click on + Add Policy.
Enter a name for your policy (without spaces and lowercase) and a description.
Add one or more rules.
Rules are evaluated in order: the first rule is checked first, then the second and so on.
- If the rule already exists: drag and drop it under the policy.
- If the rule does not yet exist, click on + Create new rule (see Create a rule).
Choose a combination algorithm (see Combination):
Click on Save.

Create a policy using JSON view:

Navigate to Authentication > Authorization Policies.
Click on + Add Policy on the top-right corner.
Click on the tree lines icon to switch to JSON view.

Enter the policy attribute values:

CODE

{
  "name": "policy-name",
  "description": "Optional description",
  "rules": ["rule1", "rule2"],
  "combination": "DENY_OVERRIDES"
}

Click on Save.

Policy Attributes

Name

Unique identifier for the policy

String (in lowercase without space)

Description

Short explanation of the policy

String

Rules

List of rules assigned to the policy

Array of rule names

CODE

"rules": ["rule_name01","rule_name02","rule_name03","rule_name04"]

Combination

How rules are evaluated together to make the policy decision

No combination	If a policy has one rule, no need to apply an algorithm. The rule alone determines the decision.
`DENY_OVERRIDES`	Access is denied unless all rules permit. One deny overrides permit.
`DENY_UNLESS_PERMIT`	Access is denied unless at least one rule permits.

Policy example

Secure admin access

CODE

{
    "name": "secure-admin-access",
    "description": "Requires MFA and admin role for access",
    "rules": ["require_authent_aal1","only-admins","specific_userid"],
    "combination": "DENY_OVERRIDES"
}

Create a rule

CURRENT LIMITATIONS

The graphical rule editor has limitations. Use the JSON view for full capabilities.

To create a rule from TrustBuilder Admin portal:

Navigate to Authentication > Authorization Rules.
Click on + Add Rule.
Click on the tree lines icon to switch to JSON view.
Enter the rule attribute values:
- name → enter a name for your rule (without spaces).
- description (optional) → enter a description of the rule.
- effect → "PERMIT" or "DENY" (see Effect below).
- condition → enter condition(s) (see Condition below).
- obligation (optional) → enter an obligation (see Condition below).
Click on Save.

Rule Attributes

Name

Unique identifier for the rule

String (in lowercase without space)

Description

Short explanation of the rule (optional)

String

Effect

The access decision

"PERMIT" or "DENY"

Condition

A set of conditions that must be satisfied in order for the rule to be applied

Expressions in a rule condition are constructed as follows: { "<operator>": [ "<operand-1>", "<operand-2>", ... ] }

Operators in Conditions

`equals`	Is equal to the specified value
`not_equals`	Is not equal to the specified value
`is_in`	Is present in the list of specified values
`not_in`	Is not present in the list of specified values
`has_value`	Has a non-empty value (for single-valued operands) Has at least one non-empty value (for multi-valued operands)
`is_empty`	Is empty (inverse of “Has a value”)
`older_than`	Is a timestamp and its value is longer ago than the duration stated in ISO 8601 format
`not_older_than`	Is a timestamp and its value is not longer ago than the duration stated in ISO 8601 format
`elem_match`	Is an array in which at least one element meets the embedded condition
`not`	Is the negated value of the nested expression
`greater_or_equals`	Is greater than or equal to the specified value

Operands in Conditions

Operands are values that define conditions. They can be:

Fixed values: strings, numbers, or dates (e.g., "2023-05-17").
Dynamic values: variables that reference session or user attributes.
- Example: $session.user_id refers to the logged-in user's ID.
- Attributes are accessed using a dot . (e.g., $session.persona.name retrieves the active persona's name).

Operand	Description
`$session.user_id`	uuid of the user of the current session
`$session.started_at`	The start data & time of the session identified with `session_id`
`$session.persona.name`	The `name` of the user's active persona in the current session.
`$session.persona.id`	The `id` of the user's active persona in the current session.
`$session.persona.scope`	The `scope` of the user's active persona in the current session.
`$session.persona.is_preferred`	The `is_preferred` value of the user's active persona in the current session.
`$session.persona.entitlements`	The `entitlements` of the user's active persona in the current session.
`$session.persona.email`	The `email` of the user's active persona in the current session.
`$session.persona.valid_from`	The `valid_from` value of the user's active persona in the current session.
`$session.persona.valid_till`	The `valid_till` value of the user's active persona in the current session.
`$session.persona.status.current`	The current `status` of the user's active persona in the current session.
`$session.authentications`	The list of the latest values of the `acr` and `last_supplied_at` of all types of authentications done by the user during this session. You can refer to those values by `~acr` and `~last_supplied_at`
`$session.persona.attributes`	The `attributes` of the user's active persona in the current session.
`$session.persona.persona_definition_id`	The `persona_definition_id` of the user's active persona in the current session.
`$session.persona.attributes.category.name`	The custom attribute `category` and the custom attribute `name` of the user's active persona in the current session.
`$session.user.attributes.category.name`	The custom attribute `category` and the custom attribute `name` of the user in the current session.

Combining Conditions

Use all-of (AND) or any-of (OR) to combine multiple conditions:

all-of → act as AND = all conditions must be met.
any-of → act as OR = at least one condition must be met.

Obligation

Additional actions required before granting access (optional)

`requires_acr`	The user must authenticate with a given assurance level e.g `requires_acr: [ "AAL3" ]`
`requires_at_least_acr`	The user must authenticate with an assurance level equal to or higher than the specified one.
`requires_persona`	The user must switch to the given persona `requires_persona: [ "doctor" ]`

Authentication rule in policy

For a policy to work, it must include at least one rule that allows authentication.
Without authentication, the system cannot identify the user and therefore cannot evaluate conditions based on user attributes, persona or session context.

A typical authentication rule checks whether the user has authenticated with a given authentication level (in our exemple at least AAL1) and enforces this requirement as an obligation:

JSON

{
  "name": "require_authent_aal1",
  "effect": "PERMIT",
  "description": "Simple authentication with one factor",
  "condition": {
    "elem_match": [
      "$session.authentications",
      {
        "greater_or_equals": [
          "~acr",
          "AAL1"
        ]
      }
    ]
  },
  "obligation": {
    "requires_at_least_acr": [
      "AAL1"
    ]
  }
}

The condition checks whether the session includes an authentication with at least AAL1 level.
The obligation ensures the user must authenticate using at least AAL1.