lockrs

A RESTful authentication and authorization API written in Rust (specifically using axum) and web app using Leptos and TailwindCSS. All data is stored in Redis or PostgreSQL with tokio async support using diesel_async and deadpool. Targeting OAuth2 specifications.
Explore the docs

View Demo . Report Bug . Request Feature

Table of Contents

1. About The Project
   • Built With
2. Getting Started
   • Prerequisites
   • Installation
3. Usage
4. Roadmap
5. Contributing
6. License
7. Contact

About The Project

(back to top)

Built With

• 
• 
• 
• 
• 
• 
• 

(back to top)

Getting Started

To get a local copy up and running follow these steps.

Prerequisites

To run this application, you will need to have cargo and cargo-leptos installed, and Redis and PostgreSQL setup

• Cargo installation docs
• Cargo-leptos installation docs
• Redis download page
• PostgreSQL download page

After installing postgres, make sure you setup a database to be used with the api, e.g.

CREATE DATABASE lockrs;

Side Note:

I also highly recommend cargo-watch for allowing live reloads on the server as changes are saved. If you do go this route, don't forget to ignore the log folder or cargo will just keep restarting the server!

Installation

1. Clone the repo

   git clone https://github.com/quasiuslikecautious/lockrs.git

2. Install cargo crates

   cargo build

3. Setup your .env file with the database path and secrets

   echo DATABASE_URL=postgres://username:password@localhost/diesel_demo > .env
   echo REDIS_URL=redis://localhost:6379 > .env
   echo KEY_INTERVAL={Seconds} > .env
   echo AUTH_INTERVAL={Seconds} > .env

4. Install the diesel CLI and initialize diesel in the project

   # run this command in the server project root e.g. .../lockrs/server
   cd server
   cargo install diesel_cli
   diesel setup

5. Initialize your database with the tables this project will use

   diesel migration run

(back to top)

Usage

Running the API on /server

To start the API, simply run

cd server # go to server binary directory
cargo run # default run command
# OR
cargo watch -x run -i log # if you have cargo-watch installed and want live reloads

in the project's root, and the server will start up.

By default, the server runs on port 9000, though this can be changed by changing the port number defined in the main function in server/main.rs.

Example Auth Flow

    # start up server
    cargo run

    curl -X POST http://127.0.0.1:9000/api/v1/auth \
        -H 'Authorization: Basic <Basic Auth Credentials>'

    # user recieves session token in response, e.g.
    # { "session_token": <Some nonce>, "expires_at": <UNIX timestamp> }

    curl -X POST http://127.0.0.1:9000/api/v1/session \
        -c ./lockrs.cookies -b ./lockrs.cookies \
        -H 'Authorization: Bearer <session_token value>'

    # jwt cookie is set, and session token has been consumed and is not longer expired.

For convenience, a few standard requests have been stored in server/curls. If you want to run them, check out the scripts to see what params are required, and chmod +x the server/curls/* directory if you need to run anything.

Running the web app on /frontend

To start the web application, first we must start the backend api using the steps above. This project requires the use of nightly rust, so make sure to run:

    # run in /path/to/lockrs/frontend
    rustup override set nightly

After you have the backend running, open a new terminal instance and run

    # run if not in frontend from last step already.
    # Go to frontend binary directory
    cd frontend

    cargo leptos watch

From this point, open up a browser and navigate to http://127.0.0.1:8000/signup and register a new user, /login to authenticate existing users, etc.

If you do plan on making any changes to styling, make sure to have a terminal running:

    # run in /path/to/lockrs/frontend
    npx tailwindcss -i ./input.css -o ./style/output.css --watch

to enable hot rebuilding of tailwind as you develop!

For more examples, please refer to the Documentation TODO will add link to API docs here

(back to top)

Roadmap

• Documentation
  • Add a README
  • Create API documentation
  • Add docs to code
• Testing
  • Add unit tests
  • Add integration tests
  • Add a few end to end tests
• Frontend
  • Switch from Yew to Leptos
  • Create pages for /user operations
  • Create pages for /client operations
  • Create pages for /redirect uri operations
• Backend
  • Finish /api controllers
  • Finish /oauth2 controllers
  • Add scopes to authorization functionality
  • Add support of OIDC

See the open issues for a full list of proposed features (and known issues).

(back to top)

Contributing

Contributions are what make the open source community such an amazing place to learn, inspire, and create. Any contributions you make are greatly appreciated.

If you have a suggestion that would make this better, please fork the repo and create a pull request. You can also simply open an issue with the tag "enhancement". Don't forget to give the project a star! Thanks again!

1. Fork the Project
2. Create your Feature Branch (git checkout -b feature/AmazingFeature)
3. Commit your Changes (git commit -m 'Add some AmazingFeature')
4. Push to the Branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

(back to top)

License

Distributed under the MIT License. See LICENSE for more information.

(back to top)

Contact

Your Name - @zquasius - zach@quasius.dev

Project Link: https://github.com/quasiuslikecautious/lockrs

(back to top)