authentication.md

# Authentication service

## Features

This service allows users to login to / logout from the Web Portal. Establishing an authenticated session is a prerequisite for managing user rights to restricted-access resources.

## Dependencies

The service relies on

* the [API Gateway](../off-the-shelf-apps/api-gateway.md), in particular its Admin API;
* external identity providers, which actually store user profiles and can verify user credentials. Despite being designed to potentially support different identity providers, in the present implementation only the [Legacy AUTH Identity Provider](../core/legacy-auth.md) is supported. A [middleware](../middlewares/legacy-auth.md) was developed, so as to facilitate the interaction between this service and the Legacy AUTH Identity Provider.

![authentication-service](../../assets/authentication-service.png)

## Endpoints

This service provides five **endpoints**:

1. A **login** endpoint per identity provider (just one in the present implementation, namely `/login/legacy`), allowing users to authenticate using a username/password pair. In case the identity provider confirms that user credentials are correct, a couple of cookies are set:
    1. an HTTP-only cookie including an **access token**, including in turn a JSON Web Token (JWT), signed by the API Gateway, namely Kong.
    2. a cookie including an **XSRF token** (generated as a version 4 UUID).

    Both the access token and the XSRF token are needed to issue authenticated requests. We refer the reader to a [dedicated page](../../miscellaneous/security.md) for further information about security.

2. A **logout** endpoint, `/logout`, which signs out the user by deprecating the cookie set by the login endpoint.

3. An **user info** endpoint, allowing one to fetch an user profile.

4. An **user info update** endpoint, `/user/update` allowing one to update an user profile.

5. An **health** endpoint, `/health`, returning a `200` HTTP Status Code in case the service is healthy, `503` in the opposite case. For this service to be healthy, two conditions must be fulfilled:
    * the [API Gateway](../off-the-shelf-apps/api-gateway.md) must be up;
    * the [Legacy AUTH Middleware](../middlewares/legacy-auth.md) must be up.

## Implementation

The service is implemented using the [NestJS](https://nestjs.com/) framework. We refer the reader to the [NestJS-based micro-services](../../miscellaneous/nestjs-micro-services.md) page for further details concerning the latter framework and the features it provides.

### TO FURTHER DEVELOP

* What's the interplay between this service and Kong? Let's provide sequence diagrams!
* How is the access token generated and signed?
* What is the difference between the cookie expiration time and that of the JWT for the Legacy Middleware?


<!-- ## How it works

The entrypoint of the service is a REST API provided by a [NestJS](https://github.com/nestjs/nest) application. It depends on two other services:

* The Legacy Authentication Middleware to verify the identity of the user and retrieve its profile (called through our api gateway: Kong)
* The Admin API of Kong to get the user specific secrets in order to sign the JSON Web Tokens -->