A service for all your authn and authz needs.
A list of articles we have found useful to make this service:
- https://cheatsheetseries.owasp.org/cheatsheets/Microservices_security.html
- https://auth0.com/docs/secure/tokens/token-best-practices
The server is composed of the below operations.
This service supports the following endpoints:
The service allows you to generate a secure password. The system uses:
The user can specify a length. The default is 32 and above.
We take recommendations from NIST Password Guidelines.
The service allows you to generate a secure public and private keys.
The service will create a key pair using 4096 bits. This is the default or when you pass the kind rsa
.
The service will generate a key pair of Ed25519. This is achieved by passing the ed25519
kind.
Access tokens are generated with RSA key pair as created by the key service. The user can specify a length. The default is 32 and above.
Once this is generated it is configured as follows:
key:
rsa:
public: base64-public-key
private: base64-private-key
These keys should be stored and retrieved from an application configuration system.
The service needs administrators to create these access tokens. This is configured as follows:
server:
v1:
admins:
- id: su-1234
hash: password-hash
Each admin has an id and a hash. The password and hash are generated by the password service. The user then sends id:password
as Basic Authentication. This will give you an encrypted access token. This token is a password that is encrypted with the public key. So you could always generate your own token if needed.
The password and token should be stored and retrieved from an application configuration system. The hash is safe to just leave as is, not need to securely store it.
This is used to add the issuer to service tokens. This is configured as follows:
server:
v1:
issuer: https://auth.falkowski.io
The service allows you to get the public key by kind. The supported kinds are the same as generating a key.
Service tokens are generated using Ed25519 key pair. Once this is generated it is configured as follows:
key:
ed25519:
public: base64-public-key
private: base64-private-key or env:VARIABLE
The system generates service tokens from the access tokens. This is configured as follows:
server:
v1:
services:
- id: e1602e185cba2a90d8bbcfc3f3c5530c
name: service-name
hash: password-hash
duration: 24h
Each service has an id, hash and duration. The access token is generated by the access token service. The user then sends the access token as Bearer Authentication. This will give you an encrypted service token with subject, audience and issuer that is valid for the duration.
The system will by default generate JWT tokens, or if we specify kind to be jwt
.
The system will generate a paseto token if the kind that is passed in is paseto
.
The systems allows the validation of service tokens. The token is passed as Bearer Authentication along with a kind, audience and action.
Casbin is used to authorize the token. Currently it is configured using ACL, using the following:
casbin:
model: |
[request_definition]
r = sub, obj, act
[policy_definition]
p = sub, obj, act
[policy_effect]
e = some(where (p.eft == allow))
[matchers]
m = r.sub == p.sub && r.obj == p.obj && r.act == p.act
policy: |
p, subject, audience, action
Here is an explanation of the different terms:
Subject
: This is the current service that gets the token to send to the service.Audience
: Is the destination service you will be sending the token to.Action
: Is the action/method of the service you are trying to authorize against.
Check out How it works?
The client provides a few options.
The client can perform actions on tokens.
❯ ./auth token --help
Perform actions with tokens.
Usage:
auth token [flags]
Flags:
-g, --generate string generate a service token
-h, --help help for token
-v, --verify string verify a service token
Global Flags:
-i, --input string input config location (format kind:location) (default "env:AUTH_CONFIG_FILE")
This is configured as follows:
client:
v1:
host: server_host
timeout: 1s
access: token generated by server
There might be a need to rotate all the server configuration. This is why we have the rotate command.
❯ ./auth rotate --help
Regenerate an existing configuration.
Usage:
auth rotate [flags]
Flags:
-a, --admins admins configuration
-h, --help help for rotate
-o, --output string output config location (format kind:location) (default "env:AUTH_APP_CONFIG_FILE")
-s, --services services configuration
Global Flags:
-i, --input string input config location (format kind:location) (default "env:AUTH_CONFIG_FILE")
If you would like to contribute, here is how you can get started.
The project follows the structure in golang-standards/project-layout.
Please make sure that you have the following installed:
- Ruby
- Golang
This project favours the Uber Go Style Guide
The get yourself setup, please run the following:
make setup
To make sure everything compiles for the app, please run the following:
make build-test
To run all the specs, please run the following:
make specs
To run all the features, please run the following:
make features
To see what has changed, please have a look at CHANGELOG.md