.. SPDX-FileCopyrightText: 2026 Univention GmbH
..
.. SPDX-License-Identifier: AGPL-3.0-only

.. _nubus-authorization:

*************
Authorization
*************

:ref:`nubus-authentication` proves who a person is.
Authorization decides what that person may do.
This page explains authorization in Nubus.

Nubus answers authorization questions with the *Guardian* component.
A service asks the *Guardian* one question:
May this actor perform this action on this resource?
The *Guardian* returns a decision.

The *Guardian* is available for the following deployments:

.. TODO: re-check before release, 5.2-7 is in the pipeline

:Nubus for UCS: Available since 5.2-6.
  The *Guardian* runs on a Primary Directory Node
  or on a Backup Directory Node.

:Nubus for Kubernetes: Not available.
  No component of a Kubernetes deployment asks the *Guardian* for decisions.

.. _nubus-authorization-decisions:

How Nubus reaches a decision
============================

Nubus separates the decision from its enforcement.

Decision point
   The *Guardian* evaluates the request against a set of policies
   and returns a decision to allow or deny the request.
   It never blocks the request itself.

Enforcement point
   The service that asked applies the result.
   It rejects the request, hides a menu entry,
   or filters a list of objects.

This split keeps the authorization rules in one place.
Every service asks the same engine
and therefore reaches the same conclusion for the same question.

The *Guardian* has two properties that follow from this design:

The *Guardian* holds no data.
   It decides using the request content
   and the applicable policies.
   It reads neither the *Identity Store* nor a database.
   The service that asks the *Guardian* supplies every attribute
   that the policies evaluate.

The *Guardian* doesn't authenticate the actor.
   The service that asks the *Guardian* authenticates the actor
   and determines the actor's roles first.
   Only then does the service ask for a decision.

.. _nubus-authorization-policies:

Policies
========

A policy states which actor may perform which action on which resource.
The *Guardian* uses :program:`Cerbos` as its decision engine,
so policies use the *Cerbos* policy format.

Policies are files, not database records.
You can review changes to your authorization rules,
keep the policies in version control,
and test a policy change before you apply it.

.. seealso::

   `Cerbos documentation <https://docs.cerbos.dev/cerbos/latest/index.html>`_
      for the policy format and the reference documentation for the decision engine.

.. _nubus-authorization-policy-sources:

Where policies come from
------------------------

A Nubus deployment loads policies from two sources:

Policies of the product
   Nubus ships a set of policies with the software.
   An update of the software replaces them.

Policies of an application
   An application delivers the policies for its own resources.
   It registers them once in the domain.
   Every server that runs the *Guardian* then receives the same set.

No administrator writes these policies.
The product and the applications deliver them.

.. warning::

   A policy change takes effect after you restart *Guardian*.
   Requests to the *Guardian* fail while it restarts.
   Plan policy updates as you plan other service updates.

.. _nubus-authorization-scope:

What Guardian doesn't cover
===========================

The *Guardian* answers authorization questions.
It doesn't manage users, groups, or roles.
Use the *Management UI* for those tasks,
as described in :ref:`nubus-ui`.

The *Guardian* has no user interface.
Only services ask it for decisions.

.. seealso::

   :external+uv-ucs-operation:ref:`iam-authorization-engine`
      in :cite:t:`uv-ucs-operation`
      for information about installing, configuring,
      and troubleshooting the *Guardian* in Nubus for UCS.