auth-api/README.md

42 lines
1.9 KiB
Markdown
Raw Normal View History

2021-01-06 19:31:51 +01:00
# Auth API
2022-01-22 15:35:58 +01:00
A tiny REST API for auth. Register accounts, auth with api-key or name/password, renew JWT tokens...
2021-01-06 19:31:51 +01:00
2021-06-24 01:59:44 +02:00
## Quick start with docker compose
2022-01-22 15:51:14 +01:00
Start the API (on port 4000 by default): `docker-compose up -d`
2021-06-24 01:59:44 +02:00
2022-01-22 15:51:14 +01:00
Point your browser to `http://localhost:4000` to view the swagger API documentation.
2021-01-04 16:28:03 +01:00
2021-01-02 11:56:24 +01:00
## Admin account
On first startup with a clean database, an account with name "admin" and the field "role" with a value "admin" is created with no password, using the API Key from ADMIN_API_KEY in the .env file.
## Special account field: "role"
The account field "role" is a bit special, in that if it contains "admin" as one of its values, that grants access to all methods on all accounts on this service. It might be a good idea to use the field "role" for authorization throughout your services.
2021-01-04 16:23:45 +01:00
2022-01-22 15:51:14 +01:00
## Tests
2024-02-04 04:15:44 +01:00
Run integration tests: `docker-compose run --rm tests`
2022-01-22 15:51:14 +01:00
## Deploy a new version
2024-02-04 04:23:21 +01:00
Everytime a push is done, tests are ran and if they are successful a new image will be published on https://gitea.larvit.se/pwrpln/auth-api:branch-name and https://gitea.larvit.se/pwrpln/auth-api-db-migrations:branch-name
2021-01-04 16:23:45 +01:00
## Some useful cURLs
Obtain an admin GWT: `curl -d '"api-key-goes-here"' -H "Content-Type: application/json" -i http://localhost:4000/auth/api-key`
2021-06-22 22:52:48 +02:00
2023-05-08 15:29:19 +02:00
Use a bearer token to make a call: `curl -H "Content-Type: application/json" -H "Authorization: bearer your-JWT-token-goes-here" -i http://localhost:4000/accounts/{accountID}`
2021-06-22 22:52:48 +02:00
2023-05-10 22:35:38 +02:00
Create account: `curl -d '{"name": "Bosse", "password": "Hemligt", "fields": [{ "name":"role", "values":["user"]}]}' -H "Content-Type: application/json" -H "Authorization: bearer your-JWT-token-goes-here" -i http://localhost:4000/account`
## Development
For local development, run with .env like: `eval $(cat .env) go run src/main.go`
To regenerate the swagger docs folder:
1. Make sure you have swag installed: https://github.com/swaggo/swag
2. cd src && swag init