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

.. _component-authorization-service:

Authorization Service
=====================

The *Authorization Service* is a component that handles authorization requests and results.
Other applications (callers) call the *Authorization Service* (callee) and inquire
whether the authorization service authorizes a certain action.
The *Authorization Service* formulates requests to a component called :program:`Guardian`
that stores authorization information,
and sends the results back to the calling application.
The caller itself is then responsible for enforcing the authorization results.

.. seealso::

   :ref:`interfaces-authorization-service` in interfaces and protocols section
      for information about incoming and outgoing interfaces.

   :ref:`deployment-authorization-service` in the deployment view section
      for information about Docker images, Kubernetes pods, and Helm Charts used for deployment.

   :ref:`overview-components-authorization-service` in the functional components overview section
       for information about purpose and tasks.

   :external+uv-guardian:ref:`what-is-the-guardian` in :cite:t:`uv-guardian-manual`
       for more information about the Guardian.

.. _component-authorization-service-authorization:

Policy-based authorization
--------------------------

The main task of the *Authorization Service* is to receive authorization requests,
forward them to the decision engine
and inform the caller about the result.
To accomplish this task,
the :program:`Guardian` within the *Authorization Service*
uses the :program:`Open Policy Agent` as the decision engine
for policy-based control and decision making.
:numref:`component-authorization-service-authorization-figure` shows the relationships.

.. _component-authorization-service-authorization-figure:

.. figure:: /images/Functional_component_Authorization_Service_authorization.*
   :target: ../_images/Functional_component_Authorization_Service_authorization.svg
   :alt: Authorization Service Authorization

   Policy-based authorization

The Guardian serves as a translation layer to the *Rego* policy language in Open Policy Agent.
It generates the policies from the Guardian entities stored in the database.
A policy consists of *Rego* code and JSON data.
To generate the policies it needs information about
targets and actors.
For more information, see :ref:`component-authorization-service-management`.

The *Authorization Service* uses the Open Policy Agent to answer the following questions:

What's the actor allowed to do?
   Example: the decision is about ten attributes of a user account object.

   * Question: which attributes is the actor allowed to modify?
   * Answer: a list of permissions.

Is the actor permitted to perform the behavior?
   Example: a user *A* wants to modify the attribute *X* of user *B*.

   * Question: does user *A* have the required permissions?
   * Answer: *yes* or *no*.

To answer these questions,
the *Guardian Management HTTP REST API* retrieves the Guardian entities from the database.
These entities are namespaces, roles, and permissions.
The Guardian management translates the Guardian entities to a policy bundle in *Rego* code.

The *Open Policy Agent* periodically retrieves the policy bundle and saves it in a cache.
It makes the decisions based on cached policy bundles.
For the attribute-based access control, ABAC, the Guardian also retrieves attributes from actors and
targets through the *UDM HTTP REST API*.

The *Guardian Authorization HTTP REST API* then verifies an actor's access to a target
and enables the *Authorization Service* to finally communicate the results of authorization requests to the caller.

.. tip::

   The *Authorization Service* only provides authorization.
   It validates the user's permissions in the access control process.

.. seealso::

   `Open Policy Agent <https://www.openpolicyagent.org/>`_
      for more information about the Open Policy Agent.

   `Open Policy Agent | Policy Language <https://www.openpolicyagent.org/docs/policy-language/>`_
      for information about the policy language *Rego*.

   Wikipedia: `Attribute-based access control <https://en.wikipedia.org/wiki/Attribute-based_access_control>`_
      for information about ABAC.

.. _component-authorization-service-management:

Management of authorization rules
---------------------------------

This section describes the management of authorization rules and visualizes them in :numref:`component-authorization-service-management-figure`.

An authorization request includes the following aspects:

* The actor, such as a user.
* The permissions, such as performing a specific action.
* The targets, such as a particular resource or a third-party application.

Persons with the following roles can manage authorization rules:

App Developer
   defines the available permissions for an application.

Guardian Administrator
   defines which user can use which permissions of all applications.
   They define roles and can assign permissions to roles.

Guardian App Administrator
   defines which user can use which permissions for one specific application.
   They can define roles and can assign permissions to roles.
   They have less permissions than the *Guardian Administrator*.

An *App Developer* for an application interacts with the *Guardian Management HTTP REST API*
to register the application with the *Authorization Service*.
The registration process involves setting up the namespace, roles, and permissions for the application as Guardian entities.
And the *Guardian Management HTTP REST API* manages the Guardian entities in a database.

The *Guardian Administrator* and the *Guardian App Administrator*
use the graphical *Guardian Management UI* to configure, what users can do with a target.
In fact, they define the rules as Guardian entities,
which the *Guardian Management HTTP REST* manages and stores in a database.

.. _component-authorization-service-management-figure:

.. figure:: /images/Functional_component_Authorization_Service_management.*
   :target: ../_images/Functional_component_Authorization_Service_management.svg
   :alt: Management of authorization rules and Guardian entities in the *Authorization Service*

   Management of authorization rules and Guardian entities in the *Authorization Service*

.. _component-authorization-service-provisioning:

Registration of Authorization Service in Identity Provider
----------------------------------------------------------

The *Authorization Service* uses OAuth 2.0 to verify the actor's identity in the authorization requests.
*Keycloak* is the identity provider.
The *Authorization Service* registers its components in Keycloak for a trust relationship.

*Guardian Provisioning* takes care of this one-time job during Nubus initial startup
and creates the client configurations in Keycloak.
:numref:`component-authorization-service-provisioning-figure` shows this relationship.
*Guardian Provisioning* is a Kubernetes jobs.

.. _component-authorization-service-provisioning-figure:

.. figure:: /images/Functional_component_Authorization_Service_provisioning.*
   :target: ../_images/Functional_component_Authorization_Service_provisioning.svg
   :alt: Registration of Authentication Service in Identity Provider
   :width: 650px

   Registration of *Authentication Service* in *Identity Provider*

.. seealso::

   :ref:`deployment-authorization-service` in deployment view section
      for information about Docker images and Kubernetes jobs responsible for deployment of the *Authorization Service*.

   :ref:`component-identity-provider` in functional components section
      for information about parts, behavior, and relationships of the *Identity Provider*.

.. _component-authorization-service-storage:

Storage
-------

The *Authorization Service* stores the Guardian entities in a relational database management system,
as shown in :numref:`component-authorization-service-storage-figure`.
The *Guardian Management HTTP REST API* manages the Guardian entities in the database,
using the usual database connection protocols through TCP/IP,
and translates them to a *Policy bundle* from the *Rego* code and JSON data in the Guardian entities.
For the database management system, Nubus uses :program:`PostgreSQL`.

.. _component-authorization-service-storage-figure:

.. figure:: /images/Functional_component_Authorization_Service_storage.*
   :target: ../_images/Functional_component_Authorization_Service_storage.svg
   :alt: Authorization Service Storage
   :width: 600px

   Authorization Service Storage

.. _component-authorization-service-dependencies:

.. seealso::

   :ref:`deployment-postgresql` in the deployment section
      for more information about the database deployment.

Dependencies
------------

The *Authorization Service* needs the *Directory Manger* to work properly.
And it needs a trust relationship through OAuth 2.0 with the identity provider.
:numref:`component-authorization-service-dependencies-figure` shows the relationships.

The *Guardian Management HTTP REST API* uses OAuth 2.0 to verify the identity of an actor in the authorization request.
For the validation it doesn't need to contact *Keycloak*.
The component already established a trust relationship in :ref:`component-authorization-service-provisioning`.

The *Guardian Authorization HTTP REST API* needs the *UDM HTTP REST API*
to retrieve attributes for the actors and targets involved in the authorization request.

.. _component-authorization-service-dependencies-figure:

.. figure:: /images/Functional_component_Authorization_Service_dependencies.*
   :target: ../_images/Functional_component_Authorization_Service_dependencies.svg
   :alt: Authorization Service Dependencies

   Dependencies of the Authorization Service