auth/README.md

188 lines
4.7 KiB
Markdown
Raw Normal View History

2022-12-15 09:59:45 +00:00
# Mobicoop V3 - Auth Service
2022-12-15 09:51:09 +00:00
2022-12-15 09:59:45 +00:00
Authentication (AuthN) and Authorization (AuthZ) data management.
2022-12-15 09:51:09 +00:00
2022-12-23 15:10:42 +00:00
## Requirements
2022-12-15 09:51:09 +00:00
2023-01-04 12:51:40 +00:00
You need [Docker](https://docs.docker.com/engine/) and its [compose](https://docs.docker.com/compose/) plugin.
2022-12-15 09:51:09 +00:00
2023-01-06 14:06:54 +00:00
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...).
2022-12-23 15:10:42 +00:00
A RabbitMQ instance is also required to send / receive messages when data has been inserted/updated/deleted.
## Installation
2023-01-06 14:06:54 +00:00
- copy `.env.dist` to `.env` :
2022-12-15 09:51:09 +00:00
2023-01-06 14:06:54 +00:00
```bash
cp .env.dist .env
```
2022-12-15 09:51:09 +00:00
2023-01-06 14:06:54 +00:00
Modify it if needed.
2022-12-15 09:51:09 +00:00
2023-01-06 14:10:40 +00:00
- install the dependencies :
```bash
npm install
```
2023-01-06 14:06:54 +00:00
- start the containers :
2022-12-15 09:51:09 +00:00
2023-01-06 14:06:54 +00:00
```bash
docker compose up -d
```
2022-12-15 09:51:09 +00:00
2023-01-06 14:06:54 +00:00
The app runs automatically on port **5002**.
2022-12-15 09:59:45 +00:00
## Database migration
2022-12-15 09:51:09 +00:00
2023-01-06 14:06:54 +00:00
Before using the app, you need to launch the database migration (it will be launched inside the container) :
2022-12-15 09:51:09 +00:00
2022-12-15 09:59:45 +00:00
```bash
2023-01-06 14:06:54 +00:00
npm run migrate
2022-12-15 09:59:45 +00:00
```
2022-12-15 09:51:09 +00:00
## Usage
2023-01-18 15:08:11 +00:00
The app is used for authentication (aka AuthN) and authorization (aka AuthZ).
### AuthN
2022-12-23 15:10:42 +00:00
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 :
2022-12-16 15:46:14 +00:00
2022-12-23 15:10:42 +00:00
- 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)
2022-12-16 15:46:14 +00:00
```json
{
"uuid": "30f49838-3f24-42bb-a489-8ffb480173ae",
"username": "john.doe@email.com",
2022-12-23 15:10:42 +00:00
"password": "John123",
"type": "EMAIL"
}
```
- **AddUsername** : add a username to an auth
```json
{
"uuid": "30f49838-3f24-42bb-a489-8ffb480173ae",
"username": "+33611223344",
"type": "PHONE"
2022-12-16 15:46:14 +00:00
}
```
2022-12-23 15:10:42 +00:00
- **UpdateUsername** : update a username
2022-12-16 15:46:14 +00:00
```json
{
"uuid": "30f49838-3f24-42bb-a489-8ffb480173ae",
"username": "johnny.doe@email.com",
2022-12-23 15:10:42 +00:00
"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"
2022-12-16 15:46:14 +00:00
}
```
- **Validate** : validate an auth (= authentication with username/password)
```json
{
"username": "john.doe@email.com",
2022-12-23 15:10:42 +00:00
"password": "Johnny123"
2022-12-16 15:46:14 +00:00
}
```
2022-12-15 09:51:09 +00:00
2022-12-23 15:10:42 +00:00
- **Delete** : delete an auth and its associated usernames
```json
{
"uuid": "30f49838-3f24-42bb-a489-8ffb480173ae"
}
```
2023-01-18 15:08:11 +00:00
### 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
}
```
2022-12-23 15:10:42 +00:00
## Messages
Various RabbitMQ messages are sent for logging purpose.
2023-01-06 14:06:54 +00:00
## 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*).
2022-12-15 09:51:09 +00:00
2022-12-15 09:59:45 +00:00
```bash
2023-01-06 14:06:54 +00:00
# run all tests (unit + integration)
npm run test
2022-12-15 09:51:09 +00:00
2023-01-06 14:06:54 +00:00
# unit tests only
npm run test:unit
# integration tests only
npm run test:integration
2022-12-15 09:51:09 +00:00
2023-01-06 14:06:54 +00:00
# coverage
npm run test:cov
```
2022-12-15 09:51:09 +00:00
## License
2022-12-15 09:59:45 +00:00
Mobicoop V3 - Auth Service is [AGPL licensed](LICENSE).