.. _hub-admin-guide-auth:

Authentication service
=======================

The authentication service is responsible for authenticating users and nodes. It uses
the popular `Keycloak <https://www.keycloak.org/>`_ service to handle authentication
within the vantage6 infrastructure. Vantage6 uses Keycloak because it is a mature
and well-supported authentication service that is easy to deploy, customize and
integrate with existing authentication services.

Configure
---------

The Keycloak operator requires a YAML file to configure the Keycloak instance. This file
is generated by the ``v6 hub new`` :ref:`command <use-hub>`.

Below, we list all possible configuration options. You can download this file here:
:download:`auth_config.yaml <yaml/auth_config.yaml>`

.. _auth-configuration-file:

.. literalinclude :: yaml/auth_config.yaml
    :language: yaml

Customize
--------

The number of configuration options in Keycloak is enormous. The vantage6 helm chart
intends to provide a way to deploy a Keycloak instance that is both adapted to the
vantage6 infrastructure and secure by default. To support all the Keycloak configuration
options is not in scope of this project. However, you can customize your Keycloak
deployment further by logging in to the Keycloak admin console, or by using the Keycloak
CLI or API.

You can login to the Keycloak admin console by opening a browser and navigating to
the address where you deployed the Keycloak service. For sandbox environments, this
will be ``http://localhost:30764``. For production environments, this will be the
address of the Keycloak service in your Kubernetes cluster. You can login with the
Keycloak admin credentials - see where these are configured in the `admin` section of
the configuration file above.

Once you are logged in, you customize your Keycloak deployment in any way you want. Take
care that you don't overwrite the vantage6-specific configuration, such as the backend
client, as this may cause issues in communicating with vantage6 HQ and store.

.. note::

    With keycloak, it is also possible to use another identity provider. For instance,
    you could configure a Microsoft or Google login page. It is also possible to
    configure your own Keycloak instance and link it to the vantage6 keycloak service.

Install and use
---------------

Once you have configured Keycloak, you can start it in a similar way to the other
components. You can start it with the following command:

.. code-block:: bash

    v6 auth start

Or you can start it as part of the hub:

.. code-block:: bash

    v6 hub start

The Helm chart for the Keycloak authentication service is based on the
`Keycloak Operator <https://www.keycloak.org/operator/installation>`_, which is
Keycloak's recommended way to deploy Keycloak in a Kubernetes cluster.
The first time you start the authentication service, it will install the Keycloak
Operator automatically. The custom resource definitions (CRDs) for the Keycloak Operator
are downloaded and installed in your Kubernetes cluster. These custom Kubernetes
resources specify how your Kubernetes service should deploy Keycloak.

If you prefer to install the CRDs yourself (and not as part of the ``v6 auth start``
command), you can install them using the following command:

.. code-block:: bash

    v6 auth install-keycloak