Brize Auth

A tiny async authentication library.

Summary

A tool for simplifying authentication for RESTful ecosystems. Purposefully built to be agnostic of your specific business/schema logic for managing users. Primarily controls the user credentials and optionally managing sessions. Built asynchronously with the Tokio runtime, and supports MySql, SurrealDB, and Redis.

Credentials

Brize auth credentials has 3 fields, an id for linking to your specific business/schema logic, the user_identity which should be a unique way to identify a user such as an email, and a hashed_password. This will be stored in a user_credentials table on your database.

Sessions

The sessions are optional, in case you want to use some other session solution. If you do enable sessions, Brize auth offers classic table sessions, which have an id field as the token, created_at and expired_at for managing the expiration. The sessions will be stored in a user_sessions table on your database. Brize auth also offers JWT session management.

Setup

First install the crate

cargo add brize_auth

Next, set up the database tables with this schema, if using a SQL database

-- Credentials table
CREATE TABLE user_credentials (
    id CHAR(36) PRIMARY KEY,
    user_identity VARCHAR(255) NOT NULL,
    hashed_password VARCHAR(255) NOT NULL
);

-- Sessions table
CREATE TABLE user_sessions (
    id CHAR(36) PRIMARY KEY,
    created_at BIGINT UNSIGNED NOT NULL,
    expires_at BIGINT UNSIGNED NOT NULL
);

Usage

use brize_auth::{Auth, AuthConfig, DatabaseConfig, Expiry, GatewayType, SessionType};

#[tokio::main]
fn main {
    // Set your database params
    let db_config = DatabaseConfig {
        host: "localhost:3306".to_string(),
        db_name: "mysql".to_string(),
        user_name: "root".to_string(),
        password: "my-secret-pw".to_string(),
        namespace: None
    };

    // Start your auth config
    let config = AuthConfig::new()
        .set_credentials_gateway(GatewayType::MySql(db_config))
        .set_session_type(SessionType::Session(Expiry::Month(1)));

    // Init auth with configs
    let mut auth = Auth::new(config).await.unwrap();

    // Get user credentials from a request
    let user_identity = "test@gmail.com";
    let raw_password = "plokij1234!";

    // Create a new set of credentials..
    // .. returns the id of the credentials row, use this as some kind of reference key on YOUR user table
    let credentials_id: Option<String> = auth.register(user_identity, raw_password).await;

    // Log user in and get a session token back
    let session_token: Result<String> = auth.login(user_identity, raw_password).await;

    // Validate token later for user
    let validation: Result<bool> = auth.validate_session(session_token).await;

    // Logout user and delete the session
    let logout_status = Result<()> = auth.logout(session_token).await;
}

See the src/examples directory for more information.

Config

The preferred database and session type can be configured to your use case.

use brize_auth::{Auth, AuthConfig, DatabaseConfig, Expiry, GatewayType, SessionType};

pub struct DatabaseConfig {
    pub db_name: String, // Name of database
    pub password: String, // Password for user
    pub user_name: String, // Name of user
    pub host: String, // Host IP
    pub namespace: Option<String> // Optional namespace in db
}

enum GatewayType {
    MySql(DatabaseConfig), // MySql databases
    Surreal(DatabaseConfig), // SurrealDB
    Redis(DatabaseConfig), // Redis instances
}

enum SessionType {
    JWT(Expiry), // JWT session management
    Session(Expiry), // Classic table sessions management
    None, // Disable sessions
}

enum Expiry {
    Second(u64), // Epoch seconds
    Day(u64), // Days in EPOCH
    Week(u64), // Weeks in EPOCH
    Month(u64), // Months in EPOCH
    Year(u64), // Years in EPOCH
}

let config = AuthConfig::new()
    // Set your preferred database tech for the credentials table
    .set_credentials_gateway(GatewayType::MySql(DatabaseConfig))

    // Set your session type, Session, JWT, or None to disable and the duration
    .set_session_type(SessionType::Session(Expiry::Month(1)));

    // Override the default session GatewayType from above
    .set_session_gateway(GatewayType::Redis(DatabaseConfig))

let auth = Auth::new(config).await;

Supported Databases

• MySql (credentials + sessions)
• SurrealDB (credentials + sessions)
• Redis (sessions only)

Testing

Setup

Install docker and run make sure the daemon is running

• Link to docker

Fork this repo

gh repo fork xbrize/brize_auth

Running Tests

All test scripts are in ./scripts but feel free to make your own. You will need to chmod +x to the script files.

After giving permission to execute, simply run them. Each is designed to spin up docker containers that are hosting generic databases. These are then used to run the tests against.

scripts/tests/<desired_script>.sh

Roadmap

Prototype phase

• User Registration
  • Create user credentials if none exist
  • Deny if user credentials does exist
  • Return credentials foreign key
• Login
  • Match user credentials
  • Return session token if matched (if sessions enabled)
  • Deny user if no match
  • Hash password
• Session Management
  • Create session
  • Validate session
  • Delete sessions based on age and logout
• Logout
  • Delete users session
• Change Credentials
  • Update user_identity
  • Update user_password
• Delete User
  • Remove credentials and session from database

Alpha testing phase

• Code refactoring
  • Domain module
  • Application module
  • Infrastructure module
  • Library
• Live testing
  • Secure production db testing
  • Benchmarking
• Code Review

Beta features

• Configure custom table names for credentials and sessions
• Configure custom claims for JWT
• Add refresh config for Session and JWT
• Add OAuth