{"id":15877834,"url":"https://github.com/HectorMRC/rauth","last_synced_at":"2025-10-24T23:31:36.642Z","repository":{"id":46101855,"uuid":"299891163","full_name":"alvidir/rauth","owner":"alvidir","description":"A simple SSO implementation in Rust ","archived":false,"fork":false,"pushed_at":"2024-08-26T11:14:20.000Z","size":1248,"stargazers_count":31,"open_issues_count":13,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-01-26T02:12:45.021Z","etag":null,"topics":["grpc","hexagonal-architecture","postgres","rabbitmq","redis","rust","sso"],"latest_commit_sha":null,"homepage":"","language":"Rust","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/alvidir.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-09-30T11:00:54.000Z","updated_at":"2024-11-20T02:35:11.000Z","dependencies_parsed_at":"2024-05-31T17:29:13.451Z","dependency_job_id":"298e3aa8-e965-426d-8794-a3d1f48934d8","html_url":"https://github.com/alvidir/rauth","commit_stats":{"total_commits":482,"total_committers":3,"mean_commits":"160.66666666666666","dds":0.06016597510373445,"last_synced_commit":"7cac505c11249a2dd1cee8a2ad4d0d3d5022f090"},"previous_names":["alvidir/authentication","alvidir/tp-auth"],"tags_count":10,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alvidir%2Frauth","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alvidir%2Frauth/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alvidir%2Frauth/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alvidir%2Frauth/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/alvidir","download_url":"https://codeload.github.com/alvidir/rauth/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":238044093,"owners_count":19407128,"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":["grpc","hexagonal-architecture","postgres","rabbitmq","redis","rust","sso"],"created_at":"2024-10-06T02:04:12.813Z","updated_at":"2025-10-24T23:31:36.242Z","avatar_url":"https://github.com/alvidir.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"# rauth\n\n[![Continuos Integration](https://github.com/alvidir/rauth/actions/workflows/ci.yaml/badge.svg?branch=main)](https://github.com/alvidir/rauth/actions/workflows/ci.yaml)\n[![Code Coverage](https://codecov.io/github/alvidir/rauth/coverage.svg?branch=main\u0026token=)](https://codecov.io/gh/alvidir/rauth)\n[![Dependency status](https://deps.rs/repo/github/alvidir/rauth/status.svg)](https://deps.rs/repo/github/alvidir/rauth)\n[![rauth](https://img.shields.io/github/v/release/alvidir/rauth.svg)](https://github.com/alvidir/rauth)\n\nA simple SSO implementation in Rust\n\n## Table of contents\n\n1. [About](#about)\n1. [Endpoints](#example2)\n   1. [Signup](#signup)\n   1. [Reset](#reset)\n   1. [Delete](#delete)\n   1. [Totp](#totp)\n   1. [Login](#login)\n   1. [Logout](#logout)\n1. [Setup environment](#setup-environment)\n1. [Server configuration](#server-configuration)\n1. [Deployment](#deployment)\n1. [Debugging](#debugging)\n\n## About\n\nThe rauth project provides a **SSO** (Single Sign On) implementation that can be consumed as any of both, a [Rust](https://www.rust-lang.org/) library or a [gRPC](https://grpc.io/) service. Currently, the project includes all regular session-related actions as signup, login, logout, and so on. Plus **TOTP**(Time-based One Time Password) and email verification support.\n\n## Endpoints\n\n### **Signup**\n\nAllows a new user to get registered into the system if, and only if, `email` and `password` are both valid.\n\n#### Request\n\nThe **signup** transaction requires of **two steps** to get completed: the _signup request_, and the _email verification_. Both of them use the same endpoint to get performed, nonetheless, the _signup request_ is the only one that must all fields. The _email verification_ instead, shall provide the **verification token** in the corresponding header.\n\n```yaml\n# Example of a gRPC message for the signup endpoint\n\n{\n    \"email\": \"dummy@test.com\" # an string containing the user's email,\n    \"pwd\": \"1234567890ABCDEF\" # an string containing the user's password encoded in base64\n}\n```\n\n#### Response\n\n- If, and only if, the first step of the signup transaction completed successfully, Rauth will respond with the error `E003` (require email verification).\n- If, and only if, the email verification completed successfully, is sent an Empty response with the session token in the corresponding header.\n- Otherwise, is provided one of the errors down below.\n\n#### Error codes\n\n| **Code** | Name               | Description                                                                                                                                                |\n| :------- | :----------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| **E001** | ERR_UNKNOWN        | Unprevisible errors                                                                                                                                        |\n| **E002** | ERR_NOT_FOUND      | Token header not found                                                                                                                                     |\n| **E005** | ERR_INVALID_TOKEN  | Token is invalid because of any of the following reasons: bad format, `exp` time exceeded, bad signature, `nbf` not satisfied, wrong `knd` or not catched. |\n| **E006** | ERR_INVALID_FORMAT | Invalid format for `email` or `password`                                                                                                                   |\n| **E007** | ERR_INVALID_HEADER | Token header must be encoded in base64                                                                                                                     |\n\n### **Reset**\n\nAllows an existing user to reset its password.\n\n#### Request\n\nThe **reset** transaction requires of **two steps** to get completed: the _email verification_, and the _password reset_. Both of them use the same endpoint to get performed, nonetheless, they do differ in which fields are mandatory.\n\n```yaml\n# Example of a gRPC message for the first step of the reset endpoint\n\n{\n    \"email\": \"dummy@test.com\" # an string containing the user's email,\n    \"pwd\": \"\" # not required\n    \"totp\": \"\" # not required\n}\n\n# Example of a gRPC message for the second step of the reset endpoint\n{\n    \"email\": \"\" # not required\n    \"pwd\": \"1234567890ABCDEF\" # an string containing the user's password encoded in base64\n    \"totp\": \"123456\" # the TOTP of the user, if enabled\n}\n```\n\n\u003e The second step must provide in the corresponding header the token that the verification email gave to ensure the legitimacy of the action.\n\n#### Response\n\n- If, and only if, the first step of the reset transaction completed successfully, Rauth will respond with the error `E003` (require email verification).\n- If, and only if, the password reset completed successfully, is sent an Empty response with no errors.\n- Otherwise, is provided one of the errors down below.\n\n#### Error codes\n\n| **Code** | Name                  | Description                                                                                                                                                |\n| :------- | :-------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| **E001** | ERR_UNKNOWN           | Unprevisible errors                                                                                                                                        |\n| **E002** | ERR_NOT_FOUND         | Token header not found                                                                                                                                     |\n| **E004** | ERR_UNAUTHORIZED      | Totp required                                                                                                                                              |\n| **E005** | ERR_INVALID_TOKEN     | Token is invalid because of any of the following reasons: bad format, `exp` time exceeded, bad signature, `nbf` not satisfied, wrong `knd` or not catched. |\n| **E006** | ERR_INVALID_FORMAT    | Password must be encoded in base64                                                                                                                         |\n| **E007** | ERR_INVALID_HEADER    | Token header must be encoded in base64                                                                                                                     |\n| **E008** | ERR_WRONG_CREDENTIALS | The new password cannot match the old one or invalid `user id`.                                                                                            |\n\n### **Delete**\n\nAllows an existing user to delete its account.\n\n#### Request\n\nThe **delete** transaction requires the user to be logged in, so its session token must be provided in the corresponding header of the request.\n\n```yaml\n# Example of a gRPC message for the delete endpoint\n\n{\n    \"pwd\": \"1234567890ABCDEF\" # an string containing the user's password encoded in base64\n    \"totp\": \"123456\" # the TOTP of the user, if enabled\n}\n```\n\n#### Response\n\n- If, and only if, the deletion completed successfully, is sent an Empty response with no errors.\n- Otherwise, is provided one of the errors down below.\n\n#### Error codes\n\n| **Code** | Name                  | Description                                                                                                                                                |\n| :------- | :-------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| **E001** | ERR_UNKNOWN           | Unprevisible errors                                                                                                                                        |\n| **E002** | ERR_NOT_FOUND         | Token header not found                                                                                                                                     |\n| **E004** | ERR_UNAUTHORIZED      | Totp required                                                                                                                                              |\n| **E005** | ERR_INVALID_TOKEN     | Token is invalid because of any of the following reasons: bad format, `exp` time exceeded, bad signature, `nbf` not satisfied, wrong `knd` or not catched. |\n| **E007** | ERR_INVALID_HEADER    | Token header must be encoded in base64                                                                                                                     |\n| **E008** | ERR_WRONG_CREDENTIALS | Password does not match or invalid `user id`.                                                                                                              |\n\n### **Totp**\n\nAllows an existing user to enable or disable the time-based one time password\n\n#### Request\n\nThe **totp** transaction requires the user to be logged in, so its session token must be provided in the corresponding header of the request. Besides, the enabling option requires of **two steps** to get completed: the action itself, and the totp verification. In any case, the same endpoint is consumed.\n\n```yaml\n# Example of a gRPC message for the totp endpoint\n\n{\n    \"action\": x, # where x may be 0 or 1 for enabling or disabling totp respectively\n    \"pwd\": \"1234567890ABCDEF\" # an string containing the user's password encoded in base64\n    \"totp\": \"\" # not required if, and only if, is the first step of enabling totp\n}\n\n# Example of a gRPC message for the second step of enabling the totp\n\n{\n    \"action\": 0, # 0: enable totp action\n    \"pwd\": \"1234567890ABCDEF\" # an string containing the user's password encoded in base64\n    \"totp\": \"123456\" # the correct totp for the given secret\n}\n```\n\n#### Response\n\n- If, and only if, the first step of enabling the TOTP completed successfully, is provided the TOTP's secret in the corresponding header.\n- If, and only if, the second step of enabling the TOTP completed successfully, is sent an Empty response with no errors.\n- If, and only if, disabling TOTP completed successfully, is sent an Empty response with no errors.\n- Otherwise, is provided one of the errors down below.\n\n#### Error codes\n\n| **Code** | Name                  | Description                                                                                                                                                |\n| :------- | :-------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| **E001** | ERR_UNKNOWN           | Unprevisible errors                                                                                                                                        |\n| **E002** | ERR_NOT_FOUND         | Token header not found                                                                                                                                     |\n| **E003** | ERR_NOT_AVAILABLE     | The action cannot be performed                                                                                                                             |\n| **E004** | ERR_UNAUTHORIZED      | Invalid `totp` value                                                                                                                                       |\n| **E005** | ERR_INVALID_TOKEN     | Token is invalid because of any of the following reasons: bad format, `exp` time exceeded, bad signature, `nbf` not satisfied, wrong `knd` or not catched. |\n| **E007** | ERR_INVALID_HEADER    | Token header must be encoded in base64                                                                                                                     |\n| **E008** | ERR_WRONG_CREDENTIALS | Password does not match or invalid `user id`.                                                                                                              |\n\n### **Login**\n\nAllows an existing user to log in.\n\n#### Request\n\n```yaml\n# Example of a gRPC message for the login endpoint\n\n{\n    \"ident\": \"dummy\" # username or password\n    \"pwd\": \"1234567890ABCDEF\" # an string containing the user's password encoded in base64\n    \"totp\": \"123456\" # the TOTP of the user, if enabled\n}\n```\n\n#### Response\n\n- If, and only if, the login completed successfully, is sent an Empty response with the session token in the corresponding header.\n- Otherwise, is provided one of the errors down below.\n\n#### Error codes\n\n| **Code** | Name                  | Description                      |\n| :------- | :-------------------- | :------------------------------- |\n| **E001** | ERR_UNKNOWN           | Unprevisible errors              |\n| **E004** | ERR_UNAUTHORIZED      | Totp required                    |\n| **E008** | ERR_WRONG_CREDENTIALS | Invalid `username` or `password` |\n\n### **Logout**\n\nAllows an existing user to log out.\n\n#### Request\n\nThe **logout** transaction requires the user to be logged in, so its session token must be provided in the corresponding header of the `Empty` request.\n\n#### Response\n\n- If, and only if, the logout completed successfully, is sent an Empty response with no errors.\n- Otherwise, is provided one of the errors down below.\n\n#### Error codes\n\n| **Code** | Name               | Description                                                                                                                                                |\n| :------- | :----------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| **E001** | ERR_UNKNOWN        | Unprevisible errors                                                                                                                                        |\n| **E002** | ERR_NOT_FOUND      | Token header not found                                                                                                                                     |\n| **E005** | ERR_INVALID_TOKEN  | Token is invalid because of any of the following reasons: bad format, `exp` time exceeded, bad signature, `nbf` not satisfied, wrong `knd` or not catched. |\n| **E007** | ERR_INVALID_HEADER | Token header must be encoded in base64                                                                                                                     |\n\n## Setup environment\n\nTo get the environment ready for the application to run, several steps have to be completed. Luckily all commands are in the [Makefile](./Makefile) of this project, so don't panic ;)\n\nRunning the following command in your terminal will create an sql setup script at `migrations/.postgres` as well as a `.ssh` directory where to find the JWT keypair required by the server:\n\n```bash\n$ make setup\n```\n\n\u003e This command requires python3 and openssl to be installed\n\nSince is expected to deploy the application using [podman](https://podman.io/), build the rauth image:\n\n```bash\n$ make build\n```\n\nLast but not least, the service will expect a directory (`templates` by default) with the following email templates:\n\n| Filename                  | Description                                                                           |\n| :------------------------ | :------------------------------------------------------------------------------------ |\n| `verification_email.html` | The html template to render and send when an email has to be verified.                |\n| `reset_email.html`        | The html template to render and send when a user requests for resetting its password. |\n\n\u003e Both templates may consume the same variables: `name` and `token`, provided by the server while rendering.\n\n## Server configuration\n\nThe server expects a set of environment variables to work properly. Although some of them has a default value, it is recommended to set all of them to have absolute awareness about how the service will behave.\n\n| Environment variable    |           Default value           | Description                                                                                                                                          |\n| :---------------------- | :-------------------------------: | :--------------------------------------------------------------------------------------------------------------------------------------------------- |\n| SERVICE_PORT            |               8000                | Port where to expose the service service                                                                                                                |\n| SERVICE_ADDR            |             127.0.0.1             | Address where to expose the service service                                                                                                             |\n| POSTGRES_DSN            |                                   | `Postgres` data source name                                                                                                                          |\n| POSTGRES_POOL           |                10                 | `Postgres` connection pool size                                                                                                                      |\n| REDIS_URL               |                                   | `Redis` URL                                                                                                                                          |\n| REDIS_POOL              |                10                 | `Redis` connection pool size                                                                                                                         |\n| TOKEN_TIMEOUT           |               7200                | The timeout any token should have                                                                                                                    |\n| JWT_SECRET              |                                   | The JWT secret to sign with all generated tokens (tip: it could be the content of the .ssh/pkcs8_key.base64 file generated on the setup step)        |\n| JWT_PUBLIC              |                                   | The JWT public key to verify with all comming tokens (tip: it could be the content of the .ssh/pkcs8_pubkey.base64 file generated on the setup step) |\n| JWT_HEADER              |           authorization           | Header where to find/store all JWT                                                                                                                   |\n| TOTP_HEADER             |           x-totp-secret           | Header where to set the TOTP secret                                                                                                                  |\n| SMTP_ISSUER             |               rauth               | Name to identify where the emails are sent from                                                                                                      |\n| SMTP_ORIGIN             |                                   | Email to set as the `from` for all sent emails                                                                                                       |\n| SMTP_TRANSPORT          |                                   | Smtp transporter URL (ex.: smtp.gmail.com)                                                                                                           |\n| SMTP_TEMPLATES          | /etc/rauth/smtp/templates/\\*.html | Path where to find all email's templates                                                                                                             |\n| SMTP_USERNAME           |                                   | If required, a username to enable the application to send emails                                                                                     |\n| SMTP_PASSWORD           |                                   | If required, an application password to enable the application to send emails                                                                        |\n| PWD_SUFIX               |           ::PWD::RAUTH            | A suffix to append to all passwords before hashing and storing them                                                                                  |\n| RABBITMQ_USERS_EXCHANGE |                                   | The RabbitMQ exchange to emit user related events                                                                                                    |\n| RABBITMQ_URL            |                                   | `RabbitMQ` URL                                                                                                                                       |\n| RABBITMQ_POOL           |                10                 | `RabbitMQ` connection pool size                                                                                                                      |\n| EVENT_ISSUER            |                                   | Issuer name for all emited events                                                                                                                    |\n| TOTP_SECRET_LEN         |                                   | Length of the random generated secret to be used for the TOTP                                                                                        |\n| TOTP_SECRET_NAME        |                                   | Name by which every TOTP secret will be stored in the database                                                                                       |\n| TOKEN_ISSUER            |                                   | Issuer value for the `iss` field of any generated token                                                                                              |\n\n\u003e All these environment variables can be set in a .env file, since Rauth uses dotenv to set up the environment\n\n## Deployment\n\nSince the application needs some external services to be launched, the easiest way to deploy them all is by using [podman-compose](https://github.com/containers/podman-compose) as following:\n\n```bash\n$ make deploy\n```\n\nThis command will deploy a pod with all those services described in the [compose file](./compose.yaml) of this project. Once completed, the application endpoints will be reachable in two different ways:\n\n- via `grpc` messaging on port `8000`\n- via `grpc-web` requests on port `8080`\n\n## Debugging\n\nBy default, the deployment command has the `-d` flag enabled, so no logs are displayed. If you really want to see them, you have two options: removing the `-d` flag from the `deploy` command of the [Makefile](./Makefile), which will display all logs of all services, or running the following command to display only those coming from the `rauth-server`:\n\n```bash\n$ make follow\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FHectorMRC%2Frauth","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FHectorMRC%2Frauth","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FHectorMRC%2Frauth/lists"}