151 lines
3.8 KiB
Markdown
151 lines
3.8 KiB
Markdown
# 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.
|
|
|
|
- start the containers :
|
|
|
|
```bash
|
|
docker compose up -d
|
|
```
|
|
|
|
The app runs automatically on port **5002**.
|
|
|
|
- install the dependencies :
|
|
|
|
```bash
|
|
npm install
|
|
```
|
|
|
|
## 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 : _to be developped_).
|
|
|
|
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"
|
|
}
|
|
```
|
|
|
|
## 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).
|