auth/README.md

# Mobicoop V3 - Auth Service

Authentication (AuthN) and Authorization (AuthZ) data management.

## Requirements

You need [Docker](https://docs.docker.com/engine/) and its [compose](https://docs.docker.com/compose/) plugin.

You also need NodeJS installed locally : we **strongly** advise to install [Node Version Manager](https://github.com/nvm-sh/nvm) and use the latest LTS version of Node (check that your local version matches with the one used in the Dockerfile).

The API will run inside a docker container, **but** the install itself is made outside the container, because during development we need tools that need to be available locally (eg. ESLint, Prettier...).

A RabbitMQ instance is also required to send / receive messages when data has been inserted/updated/deleted.

## Installation

- copy `.env.dist` to `.env` :

    ```bash
    cp .env.dist .env
    ```

    Modify it if needed.

- install the dependencies :

    ```bash
    npm install
    ```
    
- start the containers :

    ```bash
    docker compose up -d
    ```

    The app runs automatically on port **5002**.

## Database migration

Before using the app, you need to launch the database migration (it will be launched inside the container) :

```bash
npm run migrate
```

## Usage

The app is used for authentication (aka AuthN) and authorization (aka AuthZ).

### AuthN

AuthN consists in verifying a username / password couple. A user can have multiple usernames (representing multiple identifiers), all of them sharing the same password. In the app, all the authentication information about a user is called an _auth_. As of 2022/10/23, the possible identifiers are :

-   an email
-   a phone number

Note that all usernames are unique in the system : many users can't have the same email or phone number.

For AuthN, the app exposes the following [gRPC](https://grpc.io/) services :

-   **Create** : create an auth with one username / password (you can't create multiple usernames at once)

    ```json
    {
        "uuid": "30f49838-3f24-42bb-a489-8ffb480173ae",
        "username": "john.doe@email.com",
        "password": "John123",
        "type": "EMAIL"
    }
    ```

-   **AddUsername** : add a username to an auth

    ```json
    {
        "uuid": "30f49838-3f24-42bb-a489-8ffb480173ae",
        "username": "+33611223344",
        "type": "PHONE"
    }
    ```

-   **UpdateUsername** : update a username

    ```json
    {
        "uuid": "30f49838-3f24-42bb-a489-8ffb480173ae",
        "username": "johnny.doe@email.com",
        "type": "EMAIL"
    }
    ```

-   **DeleteUsername** : delete a username (an error is thrown if it's the only username of an auth, as an auth **must** have at least one associated username)

    ```json
    {
        "username": "+33611223344"
    }
    ```

-   **UpdatePassword** : update the password of an auth

    ```json
    {
        "uuid": "30f49838-3f24-42bb-a489-8ffb480173ae",
        "password": "Johnny123"
    }
    ```

-   **Validate** : validate an auth (= authentication with username/password)

    ```json
    {
        "username": "john.doe@email.com",
        "password": "Johnny123"
    }
    ```

-   **Delete** : delete an auth and its associated usernames

    ```json
    {
        "uuid": "30f49838-3f24-42bb-a489-8ffb480173ae"
    }
    ```

### AuthZ

AuthZ consists in verifying if a given **user** has the right permission to execute a given **action** within a given **domain**. Some context-dependant information can be given as well.

For AuthZ, the app exposes the following [gRPC](https://grpc.io/) services :

-   **Decide** : asks the authorization service if a user has the right permission

    ```json
    {
        "uuid": "96d99d44-e0a6-458e-a656-de2a400d60a9",
        "domain": "USER",
        "action": "READ",
        "context": [
            {
                "name": "owner",
                "value": "96d99d44-e0a6-458e-a656-de2a400d60a8"
            },
            {
                "name": "role",
                "value": "admin"
            }
        ]
    }
    ```

    In return, the service gives an authorization response : 

    ```json
    {
        "allow": true
    }
    ```


## Messages

Various RabbitMQ messages are sent for logging purpose.

## Tests

Tests are run outside the container for ease of use (switching between different environments inside containers using prisma is complicated and error prone).
The integration tests use a dedicated database (see *db-test* section of *docker-compose.yml*).

```bash
# run all tests (unit + integration)
npm run test

# unit tests only
npm run test:unit

# integration tests only
npm run test:integration

# coverage
npm run test:cov
```

## License

Mobicoop V3 - Auth Service is [AGPL licensed](LICENSE).