{"id":20793908,"url":"https://github.com/teal-finance/quid","last_synced_at":"2025-05-06T00:15:57.984Z","repository":{"id":37103857,"uuid":"279381701","full_name":"teal-finance/quid","owner":"teal-finance","description":"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.","archived":false,"fork":false,"pushed_at":"2025-02-21T01:23:27.000Z","size":7499,"stargazers_count":11,"open_issues_count":8,"forks_count":2,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-05-06T00:15:50.914Z","etag":null,"topics":["access-token","ecdsa-signature","ed25519","eddsa","es256","es384","es512","golang","hmac-sha256","hmac-signature","hs256","hs512","json-web-token","json-web-token-authentication","jwt","jwt-authentication","refresh-token","refresh-token-rotation","rsa-signature","tokens-checker"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/teal-finance.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2020-07-13T18:29:27.000Z","updated_at":"2025-02-21T01:23:31.000Z","dependencies_parsed_at":"2024-06-19T13:33:51.924Z","dependency_job_id":"c1b9f897-8a63-46bd-b9ed-c9801c092f60","html_url":"https://github.com/teal-finance/quid","commit_stats":null,"previous_names":["synw/quid"],"tags_count":2,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/teal-finance%2Fquid","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/teal-finance%2Fquid/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/teal-finance%2Fquid/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/teal-finance%2Fquid/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/teal-finance","download_url":"https://codeload.github.com/teal-finance/quid/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":252596431,"owners_count":21773846,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["access-token","ecdsa-signature","ed25519","eddsa","es256","es384","es512","golang","hmac-sha256","hmac-signature","hs256","hs512","json-web-token","json-web-token-authentication","jwt","jwt-authentication","refresh-token","refresh-token-rotation","rsa-signature","tokens-checker"],"created_at":"2024-11-17T16:12:17.142Z","updated_at":"2025-05-06T00:15:57.968Z","avatar_url":"https://github.com/teal-finance.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# ![❄](ui/public/img/logo-2em.svg) Quid \u0026emsp; \u0026emsp; \u0026emsp; [![Go Reference](https://pkg.go.dev/badge/github.com/teal-finance/quid.svg \"Go documentation for Quid\")](https://pkg.go.dev/github.com/teal-finance/quid) [![Go Report Card](https://goreportcard.com/badge/github.com/teal-finance/quid \"Go Report Card for Quid\")](https://goreportcard.com/report/github.com/teal-finance/quid)\n\n![Quid preview](ui/public/img/quid-preview.jpg)\n\n**Quid** is a [JWT][jwt] server (frontend + backend + client libraries)\nto manage Administrators, Users, **Refresh Tokens** and **Access Tokens**\nin independent **Namespaces** providing signature verification for the following algorithms:\n\n- HS256 = HMAC using SHA-256\n- HS384 = HMAC using SHA-384\n- HS512 = HMAC using SHA-512\n- RS256 = RSASSA-PKCS1-v1_5 using 2048-bits RSA key and SHA-256\n- RS384 = RSASSA-PKCS1-v1_5 using 2048-bits RSA key and SHA-384\n- RS512 = RSASSA-PKCS1-v1_5 using 2048-bits RSA key and SHA-512\n- ES256 = ECDSA using P-256 and SHA-256\n- ES384 = ECDSA using P-384 and SHA-384\n- ES512 = ECDSA using P-521 and SHA-512\n- EdDSA = Ed25519\n\n[jwt]: https://wikiless.org/wiki/JSON_Web_Token \"JSON Web Token\"\n\n![Authentication flow chart](doc/img/authentication-flow.png)\n\n1. First, the user logs in with **Namespace** + **Username** + **Password**.\n   The **Namespace** is usually the final application name,\n   represented by _Application API_ at the bottom of the previous diagram.\n\n2. Then, the client (e.g. JS code) receives a **Refresh Token**\n   that is usually valid for a few hours\n   to avoid to log again during the working session.\n\n3. The client sends this **Refresh Token** to get an **Access Token**\n   that is valid for a short time,\n   usually a few minutes, say 10 minutes.\n   So the client must _refresh_ its **Access Token** every 10 minutes.\n\n4. During these 10 minutes,\n   the client can request the _Application API_\n   with the same **Access Token**.\n\n5. When the _Application API_ receives a request from the client,\n   it checks the [JWT][jwt] signature and expiration time.\n   The **Access Token** is stateless:\n   the _Application API_ does not need to store any information\n   about the user (the **Access Token** content is enough).\n\n## Install\n\nDownload the latest [release](https://github.com/teal-finance/quid/releases) to run a binary or clone the repository to compile from source. See also the [Dockerfile](Dockerfile) to run **Quid** within a light container (less than 20 MB).\n\n## Build from source\n\n    make all -j\n\n## Configure\n\n1. Create the default config file:\n\n        ./quid -conf\n\n2. Create the `quid` database: [instructions](doc/setup_db.md)\n\n3. Edit the configuration file to set your PostgreSQL credentials:\n\n        vim config.json\n\n4. Initialize the `quid` database and create the administrator user:\n\n        ./quid -init\n\n    These registered administrator username and password will be required to login the Administration UI.\n\n## Run the backend\n\n    ./quid\n\nor simply:\n\n    go run ./cmd/quid -dev\n\nSee also: [run in dev mode](doc/dev_mode.md)\n\nQuid serves the static web site. Open \u003chttp://localhost:8090\u003e to login into the admin interface:\n\n    xdg-open http://localhost:8090\n\n![Screenshot](doc/img/screenshot.png)\n\n## Deploy on Heroku\n\n[![Deploy](https://www.herokucdn.com/deploy/button.svg)](https://heroku.com/deploy?template=https://github.com/teal-finance/quid)\n\n## Request tokens\n\nRequest a refresh token and use it to request access tokens.\n\n### Refresh token\n\nA public endpoint is available to request refresh tokens for namespaces.\nA time to live must be provided.\n\nExample: request a refresh token with a 10 minutes lifetime `/token/refresh/10m`\n\n```php\ncurl localhost:8090/token/refresh/10m          \\\n     -H 'Content-Type: application/json'       \\\n     -d '{\"namespace\":\"my_namespace\",\"username\":\"my_username\",\"password\":\"my_password\"}'\n```\n\nResponse:\n\n```json\n{ \"token\": \"eyJhbGciOiJIUzI1NiIsInR5cCI6IzpXVCJ9...\" }\n```\n\n### Access token\n\nA public endpoint is available to request access tokens for namespaces.\nA time to live must be provided.\n\nExample: request an access token with a 10 minutes lifetime `/token/access/10m`\n\n```php\ncurl localhost:8090/token/access/10m           \\\n     -H 'Content-Type: application/json'                      \\\n     -d '{\"namespace\":\"my_namespace\",\"refresh_token\":\"zpXVCJ9...\"}'\n```\n\nResponse:\n\n```json\n{ \"token\": \"eyJhbGciOiJIUzI1NiIsInR5cCI6IzpXVCJ9...\" }\n```\n\nNote: if the requested duration exceeds the max authorized tokens time to live for the namespace the demand will be rejected\n\n## Decode tokens\n\n### Python\n\n```python\nimport jwt\n\ntry:\n    payload = jwt.decode(token, key, algorithms=['HS256'])\nexcept jwt.ExpiredSignatureError:\n    # ...\n```\n\nPayload example:\n\n```json\n{\n  \"usr\": \"jane\",\n  \"grp\": [\"group1\", \"group2\"],\n  \"org\": [\"organization1\", \"organization2\"],\n  \"exp\": 1595950745\n}\n```\n\nNote: `\"exp\"` is the expiration timestamp in [Unix time](https://en.wikipedia.org/wiki/Unix_time) format (seconds since 1970).\n\n### Examples\n\nSee the [examples](https://github.com/teal-finance/quid_examples) for various backends.\n\n## Client libraries\n\nClient libraries transparently manage the requests to api servers.\nIf a server returns a 401 Unauthorized response when an access token is expired,\nthe client library will request a new access token from a Quid server,\nusing a refresh token, and will retry the request with the new access token.\n\n### Javascript\n\n[QuidJS](https://github.com/teal-finance/quidjs) : the javascript requests library.\n\n## WebAuthn and FIDO2 features\n\nQuid does not support WebAuthn and FIDO2.\nSee the following open-source projects providing these features:\n\n- **Authelia** \u003chttps://github.com/authelia/authelia\u003e  \n  Authentication server with 2FA/SSO/OTP/FIDO2\n  already supported by Traefik, Nginx, HAProxy,\n  [Caddy](https://github.com/caddyserver/caddy/pull/4739)\n\n- **Kratos** \u003chttps://github.com/ory/kratos\u003e  \n  Identity server in Go: MFA, FIDO2, social sign in, password-less, registration, account recovery…\n\n- **WebAuthn** \u003chttps://github.com/duo-labs/webauthn\u003e  \n  WebAuthn/FIDO2 server library in Go\n  (the [Python version](https://github.com/duo-labs/py_webauthn) is more active)\n\n- **WebAuthn Demo** \u003chttps://github.com/fido-alliance/webauthn-demo\u003e  \n  WebAuthn demo in HTML and JavaScript\n\n- **Portier** ([see the reference implementation in Rust](https://github.com/portier/portier-broker))  \n  Password-less login server using email/OpenID/OAuth2/JWT,\n  successor to Persona (Portier is simpler than Persona)\n\nOther Go and JWT related projects:\n\n- https://github.com/kataras/jwt\n\n- Other Authentication tools in Go:  \n  \u003chttps://github.com/avelino/awesome-go#authentication-and-oauth\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fteal-finance%2Fquid","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fteal-finance%2Fquid","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fteal-finance%2Fquid/lists"}