Skip to content

Refresh/Access JWT authentication server with backend + administration frontend supporting HMAC (HS256 HS384 HS512), RSA (RS256 RS384 RS512), ECDSA (ES256 ES384 ES512) and Ed25519 (EdDSA). See also other repos for Javascript, Python and Go client libraries.

License

Notifications You must be signed in to change notification settings

teal-finance/quid

Repository files navigation

❄ Quid       Go Reference Go Report Card

Quid preview

Quid is a JWT server (frontend + backend + client libraries) to manage Administrators, Users, Refresh Tokens and Access Tokens in independent Namespaces providing signature verification for the following algorithms:

  • HS256 = HMAC using SHA-256
  • HS384 = HMAC using SHA-384
  • HS512 = HMAC using SHA-512
  • RS256 = RSASSA-PKCS1-v1_5 using 2048-bits RSA key and SHA-256
  • RS384 = RSASSA-PKCS1-v1_5 using 2048-bits RSA key and SHA-384
  • RS512 = RSASSA-PKCS1-v1_5 using 2048-bits RSA key and SHA-512
  • ES256 = ECDSA using P-256 and SHA-256
  • ES384 = ECDSA using P-384 and SHA-384
  • ES512 = ECDSA using P-521 and SHA-512
  • EdDSA = Ed25519

Authentication flow chart

  1. First, the user logs in with Namespace + Username + Password. The Namespace is usually the final application name, represented by Application API at the bottom of the previous diagram.

  2. Then, the client (e.g. JS code) receives a Refresh Token that is usually valid for a few hours to avoid to log again during the working session.

  3. The client sends this Refresh Token to get an Access Token that is valid for a short time, usually a few minutes, say 10 minutes. So the client must refresh its Access Token every 10 minutes.

  4. During these 10 minutes, the client can request the Application API with the same Access Token.

  5. When the Application API receives a request from the client, it checks the JWT signature and expiration time. The Access Token is stateless: the Application API does not need to store any information about the user (the Access Token content is enough).

Install

Download the latest release to run a binary or clone the repository to compile from source. See also the Dockerfile to run Quid within a light container (less than 20 MB).

Build from source

make all -j

Configure

  1. Create the default config file:

     ./quid -conf
    
  2. Create the quid database: instructions

  3. Edit the configuration file to set your PostgreSQL credentials:

     vim config.json
    
  4. Initialize the quid database and create the administrator user:

     ./quid -init
    

    These registered administrator username and password will be required to login the Administration UI.

Run the backend

./quid

or simply:

go run ./cmd/quid -dev

See also: run in dev mode

Quid serves the static web site. Open http://localhost:8090 to login into the admin interface:

xdg-open http://localhost:8090

Screenshot

Deploy on Heroku

Deploy

Request tokens

Request a refresh token and use it to request access tokens.

Refresh token

A public endpoint is available to request refresh tokens for namespaces. A time to live must be provided.

Example: request a refresh token with a 10 minutes lifetime /token/refresh/10m

curl localhost:8090/token/refresh/10m          \
     -H 'Content-Type: application/json'       \
     -d '{"namespace":"my_namespace","username":"my_username","password":"my_password"}'

Response:

{ "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IzpXVCJ9..." }

Access token

A public endpoint is available to request access tokens for namespaces. A time to live must be provided.

Example: request an access token with a 10 minutes lifetime /token/access/10m

curl localhost:8090/token/access/10m           \
     -H 'Content-Type: application/json'                      \
     -d '{"namespace":"my_namespace","refresh_token":"zpXVCJ9..."}'

Response:

{ "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IzpXVCJ9..." }

Note: if the requested duration exceeds the max authorized tokens time to live for the namespace the demand will be rejected

Decode tokens

Python

import jwt

try:
    payload = jwt.decode(token, key, algorithms=['HS256'])
except jwt.ExpiredSignatureError:
    # ...

Payload example:

{
  "usr": "jane",
  "grp": ["group1", "group2"],
  "org": ["organization1", "organization2"],
  "exp": 1595950745
}

Note: "exp" is the expiration timestamp in Unix time format (seconds since 1970).

Examples

See the examples for various backends.

Client libraries

Client libraries transparently manage the requests to api servers. If a server returns a 401 Unauthorized response when an access token is expired, the client library will request a new access token from a Quid server, using a refresh token, and will retry the request with the new access token.

Javascript

QuidJS : the javascript requests library.

WebAuthn and FIDO2 features

Quid does not support WebAuthn and FIDO2. See the following open-source projects providing these features:

Other Go and JWT related projects: