auth/README.md

140 lines
3.4 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
2022-12-15 09:59:45 +00:00
You need [Docker](https://docs.docker.com/engine/) and [Docker-compose](https://docs.docker.com/compose/).
2022-12-15 09:51:09 +00:00
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
2022-12-15 09:59:45 +00:00
Copy `.env.dist` to `.env` :
2022-12-15 09:51:09 +00:00
2022-12-15 09:59:45 +00:00
```bash
cp .env.dist .env
2022-12-15 09:51:09 +00:00
```
2022-12-15 09:59:45 +00:00
and modify it to suit your needs.
2022-12-15 09:51:09 +00:00
2022-12-15 09:59:45 +00:00
Then execute :
2022-12-15 09:51:09 +00:00
2022-12-15 09:59:45 +00:00
```bash
docker-compose up -d
```
2022-12-15 09:51:09 +00:00
2022-12-16 15:46:14 +00:00
The app runs automatically on the port defined in `SERVICE_PORT` of `.env` file (default : _5002_).
You then need to set the appropriate rights for PGAdmin container :
```bash
sudo chown -R 5050:5050 postgresql/.pgadmin_data
```
2022-12-15 09:51:09 +00:00
2022-12-15 09:59:45 +00:00
## Database migration
2022-12-15 09:51:09 +00:00
2022-12-15 09:59:45 +00:00
Before using the app, you need to launch the database migration :
2022-12-15 09:51:09 +00:00
2022-12-15 09:59:45 +00:00
```bash
docker exec v3_user sh -c "npx prisma migrate dev"
```
2022-12-15 09:51:09 +00:00
## Usage
2022-12-23 15:10:42 +00:00
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 :
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"
}
```
## Messages
Various RabbitMQ messages are sent for logging purpose.
2022-12-15 09:59:45 +00:00
## Test
2022-12-15 09:51:09 +00:00
2022-12-15 09:59:45 +00:00
```bash
# unit tests
docker exec v3_user sh -c "npm run test"
2022-12-15 09:51:09 +00:00
2022-12-15 09:59:45 +00:00
# test coverage
docker exec v3_user sh -c "npm run test:cov"
```
2022-12-15 09:51:09 +00:00
2022-12-15 09:59:45 +00:00
Note : you can run all npm commands directly _outside_ the container (see _scripts_ section of `package.json` for available commands), but you 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.
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).