.. _opauth:

Authentification
================

For user authentification, the REDAC Frontend Access Code (*redaccess*) uses
the `OpenID <https://openid.net/>`_ standard.
For convenience, the identiy and access managament server
`Keycloak <https://www.keycloak.org/>`_ is running on the 
:ref:`Super Controller <opsetup-server>`.
Keycloak provides user federation, strong authentication, user management,
fine-grained authorization, and more.
This section describes the capabilities of this software and how to manage
access to REDAC. Administrators are strongly encouraged to read the relevant
`Keycloak guides <https://www.keycloak.org/guides>`_ and documentation. This
section will only cover the REDAC-specific configuration settings and
intentionally does not provide a general introduction into the Keycloak software.

.. note::

   The Keycloak OpenID service is supposed to secure access to all
   **user facing services**. This intentionally does not cover any services of the
   :ref:`opnetwork`. All operator and administrator services have their local
   on-device user account managament. This is also a resilience measure in order
   to enable maintainability of the overall system even if REDAC-specific services
   are down.

Scope and capablities of Keycloak on REDAC
------------------------------------------

By default the Keycloak installation has two realms:

1. The *master* (or *default*) realm which is only used for managing Keycloak itself.
   Login is at https://auth.redac.anabrid.com/ which shows a big warning that this is
   not the correct login for ordinary users.
2. The *redac1-realm* for actual user authentification, currently
   managed by :ref:`Anabrid for QCI <opanabrid>`. The most important URL for managing
   users and their groups in this realm is
   https://auth.redac.anabrid.com/admin/master/console/#/redac1-realm/users.
   For programming against this realm, the information at the ressource
   https://auth.redac.anabrid.com/realms/redac1-realm/.well-known/openid-configuration may
   be interesting to get the URLs of OpenID endpoints.

The Keycloak itself is currently configured to be able to send out E-Mails via 
an anabrid mailserver with the sending address ``redac1-keycloak@anabrid.dev``. This
is a *no-reply* sender only mail account for the keycloak daemon.

Keycloak is versatile in client policies and modifying the user registration.

REDAC Keycloak clients
----------------------

In Keycloak language, *clients* refer to programs which want to authenticate against
REDAC. Currently, the following *OpenID connect* clients with
*authentification and authorization* capabilities are registered:

* ``redaccess``, served at https://redac.anabrid.com/api
* ``jupyterhub-wup``, served at https://jupyter.redac.anabrid.com/
* Keycloak-internals such as the account console at https://auth.redac.anabrid.com/realms/redac1-realm/account/

The following *OpenID connect* clients with *public access only* capabilities are
registered:

* ``redac-gui``, served at https://redac.anabrid.com/ui