Authorization engine

6.3. Authorization engine#

Guardian is the authorization engine in Nubus for UCS. This page explains how to install, configure, and operate it.

For information about authorization and policies, see Authorization in Nubus Manual 1.x [3].

This page covers:

See also

For reference documentation about the decision engine, see Cerbos documentation.

Note

The authorization engine replaces the earlier Guardian apps Guardian Management API, Guardian Authorization API, and Guardian Management UI. No upgrade path exists from these apps. The installation migrates no policies, no roles, and no other data from them.

6.3.1. Authorization engine endpoints#

The engine uses these localhost ports:

  • An HTTP interface on port 3592.

  • A gRPC interface on port 3593.

Services on the same system use these ports. Containers on the system reach the engine through the shared guardian Docker network, under the hostname cerbos.

Warning

The engine accepts every request from the local system. It has no transport authentication. Install it only on Nubus for UCS systems where you trust all local services.

6.3.2. Supported system roles for the authorization engine#

Install the authorization engine on a Primary Directory Node or a Backup Directory Node. The Univention App Center offers it only on these roles. A Replica Directory Node and a Managed Node can’t run it.

The following applies:

Local access only

Install the engine next to the service that needs decisions. The engine answers local callers only. A service on another system can’t reach it. Install the engine on each Nubus for UCS system whose services ask for decisions.

Independent installations

Each installation operates independently. Each engine keeps its own copy of the policies and answers from that copy. The engines share no state and don’t forward requests to each other. The listener module synchronizes the policy copies because every Nubus for UCS system reads the same policy bundles from the LDAP directory.

Warning

The univention-guardian-server package doesn’t check the system role. Install the Univention Guardian app through the App Center. The App Center restricts the authorization engine to Primary and Backup Directory Nodes. Direct package installation bypasses this restriction. It can install the authorization engine and Directory Listener integration on an unsupported system role.

6.3.3. Install the authorization engine#

You need domain administrator permissions and a root account on the target system to install the authorization engine. For information about the domain administrator account, see Choose the right user account in Nubus Manual 1.x [3].

Install the Univention Guardian app from the App Center, or run the command in Listing 6.6. For information about installing apps through the App Center, see Univention App Center.

Listing 6.6 Install the authorization engine#
$ univention-app install univention-guardian

The installation makes the following changes to the system:

  • It installs the univention-guardian-server package.

  • It creates the guardian-server system user and group with the fixed ID 64110. Cerbos runs under this account.

  • It installs the systemd service univention-guardian-server.service. The service runs Cerbos as a container and starts the container after installation. If the container exits, systemd restarts it.

  • It installs the cerbos-policies listener module. The module installs policy bundles from the LDAP directory. For more information, see Manage the policies of the authorization engine.

To verify that the service is active, run the command in Listing 6.7. The output must show active (running). If it doesn’t, see Diagnose the authorization engine.

Listing 6.7 Show the state of the authorization engine#
$ systemctl status univention-guardian-server.service

6.3.4. Verify that the engine returns decisions#

The installation includes a set of example policies. One of them allows the administrator of an application to read a resource of that same application. The two requests in this section use this policy to verify that the engine loads policies and returns decisions.

Both examples show the response fields that contain the decision. The engine returns additional fields.

Note

The example policies demonstrate the policy format. Don’t use the example policies to define your production authorization policies. Univention can change or remove the example policies.

6.3.4.1. Example: Allow decision#

The request in Listing 6.8 asks whether the actor alice, who holds the role guardian:myapp-admin, can read a resource of the application myapp. The role and the resource belong to the same application, so the engine returns EFFECT_ALLOW, as shown in Listing 6.9.

Listing 6.8 Ask for a decision about a resource of the same application#
$ curl -sS http://127.0.0.1:3592/api/check/resources \
    -H 'Content-Type: application/json' \
    -d '{
  "requestId": "r1",
  "principal": {"id": "alice", "roles": ["guardian:myapp-admin"]},
  "resources": [{
    "resource": {"id": "x", "kind": "guardian.management_api",
                 "attr": {"app_name": "myapp"}},
    "actions": ["read_resource"]
  }]
}'
Listing 6.9 Decision for a resource of the same application#
{
  "requestId": "r1",
  "results": [
    {
      "resource": {"id": "x", "kind": "guardian.management_api"},
      "actions": {
        "read_resource": "EFFECT_ALLOW"
      }
    }
  ]
}

6.3.4.2. Example: Deny decision#

The request in Listing 6.10 uses the same actor to request access to a resource of the application otherapp. The role and the resource belong to different applications, so the engine returns EFFECT_DENY, as shown in Listing 6.11.

Listing 6.10 Ask for a decision about a resource of another application#
$ curl -sS http://127.0.0.1:3592/api/check/resources \
    -H 'Content-Type: application/json' \
    -d '{
  "requestId": "r2",
  "principal": {"id": "alice", "roles": ["guardian:myapp-admin"]},
  "resources": [{
    "resource": {"id": "y", "kind": "guardian.management_api",
                 "attr": {"app_name": "otherapp"}},
    "actions": ["read_resource"]
  }]
}'
Listing 6.11 Decision for a resource of another application#
{
  "requestId": "r2",
  "results": [
    {
      "resource": {"id": "y", "kind": "guardian.management_api"},
      "actions": {
        "read_resource": "EFFECT_DENY"
      }
    }
  ]
}

6.3.5. Configure the authorization engine#

The univention-guardian-server package manages these UCR variables:

Changing either variable restarts the authorization engine. Requests fail while the service restarts. For the procedure that uses these variables to diagnose a policy evaluation, see Diagnose the authorization engine.

The remaining settings of the engine are static. Nubus for UCS generates the files /usr/share/univention-guardian-server/docker-compose.yaml and /usr/share/univention-guardian-server/config/cerbos.yaml from UCR templates. Don’t edit these files. A UCR update overwrites your changes.

See also

Configure the local system with Univention Configuration Registry

for information about local system configuration with UCR.

6.3.6. Manage the policies of the authorization engine#

A policy defines the actions that an actor can perform on a resource. The engine loads every policy file in /usr/share/univention-guardian-server/policies/ and its subdirectories. Each subdirectory holds the policies of one source.

An application or a package registers its policies as a policy bundle in the LDAP directory. The listener module cerbos-policies installs each bundle into the subdirectory policies/APPLICATION/ on every Nubus for UCS system that runs the engine. The module validates each bundle before applying it. If the bundle doesn’t compile, the module keeps the previous policies and discards the bundle.

To list the policy files in the local policy directory, run the command in Listing 6.12.

Listing 6.12 List the policy files in the local policy directory#
$ ls -R /usr/share/univention-guardian-server/policies/

The engine doesn’t reload policies while it runs. Every policy change requires a service restart. After the listener module installs a policy bundle, it automatically restarts the service. If you copy a policy file to the Nubus for UCS system yourself, restart the authorization engine service with the command in Listing 6.13.

Listing 6.13 Restart the authorization engine#
$ systemctl restart univention-guardian-server.service

Note

Copy a policy file to a Nubus for UCS system only for local testing. The next package update removes the file, and no other authorization engine in the domain receives it.

See also

Cerbos | Policies

for information about the policy format.

6.3.7. Diagnose the authorization engine#

This section describes the authorization engine logs and common causes of problems.

To see which policies the engine loaded and why it skipped a policy, read the log of the service with the command in Listing 6.14.

Listing 6.14 Read the log of the authorization engine#
$ journalctl -u univention-guardian-server.service

Check the listener log with the command in Listing 6.15. It shows whether the listener module installed or rejected a policy bundle.

Listing 6.15 Read the listener log for policy bundles#
$ grep cerbos-policies /var/log/univention/listener.log

To diagnose a policy evaluation, do the following as root:

  1. Run the command in Listing 6.16 to set the log level and enable audit logging. If you stop diagnosing or can’t complete the diagnosis, immediately run the command in Listing 6.17 to reset the variables to their default values.

    Caution

    Debug and audit logs contain request payloads, which can include personal data. Enable these settings only for as long as you need them.

    Listing 6.16 Enable diagnostic logging for policy evaluation#
    $ ucr set \
  guardian/cerbos/log-level=DEBUG \
  guardian/cerbos/audit-logging/enabled=true

  2. Wait until the authorization engine has restarted.

  3. Reproduce the policy evaluation that you want to diagnose.

  4. Read the service log with the command in Listing 6.14.

  5. Run the command in Listing 6.17 to reset the variables to their default values.

    Listing 6.17 Reset diagnostic logging for policy evaluation#
    $ ucr set \
  guardian/cerbos/log-level=WARN \
  guardian/cerbos/audit-logging/enabled=false

  6. Run the command in Listing 6.18 to verify the default values.

    Listing 6.18 Verify diagnostic logging defaults#
    $ ucr get guardian/cerbos/log-level
WARN
$ ucr get guardian/cerbos/audit-logging/enabled
false

The following list describes common symptoms and their causes:

The engine denies an action that a policy allows.

The engine bases its decision on the request content. Enable guardian/cerbos/audit-logging/enabled and compare the logged request with the condition in the policy. In most cases, the calling service didn’t send an expected attribute or role.

A policy change has no effect.

The engine doesn’t reload policies while it runs. Restart the service as shown in Listing 6.13. If you registered a policy bundle, read the listener log. The module rejects a bundle that doesn’t compile.

The engine ignores a policy file.

Cerbos treats a file whose name ends in _test.yaml as a test file, not as a policy. Rename the file.

The engine doesn’t start.

The authorization engine Cerbos runs as a container. Run the commands in Listing 6.19 to check the service, the container runtime, and the container.

If docker.service doesn’t run, start it, then restart the authorization engine as shown in Listing 6.13. If the service starts but the container exits, the container log identifies the cause.

A policy file with invalid content is a common cause. If the log doesn’t identify a cause, contact Univention support and include the output of these commands.

Listing 6.19 Check the state of the authorization engine container#
$ systemctl status univention-guardian-server.service
$ systemctl status docker.service
$ docker ps -a --filter name=cerbos
$ docker logs cerbos
On this page