Zauth

The name is open for discussion.

Development setup

1. Make sure you have a recent version of rust installed.

2. We currently use a postgresql server for persistent storage (also in development mode). So you'll have to install and run your own postgresql server. After installation, you can start a postgresql shell with psql, but you will likely need access it as the postgres user, so use e.g. sudo -u postgres psql.

3. Next, in this shell, you'll have to create a user with permissions to create a database:

   CREATE USER zauth WITH PASSWORD 'zauth' CREATEDB;

   Note that by default the postgresql server is configured to not allow for username:password authentication. Please refer to the official documentation for information about postgresql authentication.

   Execute SHOW hba_file; in the psql shell to find the location of the client authentication file, which might for example be /var/lib/pgsql/data/pg_hba.conf.

   A configuration allowing password authentication for the zauth user on the local system could look like this:

   host    all             zauth           127.0.0.1/32            md5
   host    all             zauth           ::1/128                 md5
   

4. We use diesel to manage our database. Install the cli with cargo install diesel_cli. If you wish to only install the postgres features of diesel (for nix-shell for example), run

   cargo install diesel_cli --no-default-features --features postgres --force

5. Create the development and testing database with

   diesel database reset --database-url "postgresql://zauth:zauth@localhost/zauth"
   diesel database reset --database-url "postgresql://zauth:zauth@localhost/zauth_test"

   This will also run the migrations.

6. Run npm install to install all the node dependencies.

7. Run npm run build to compile the css assets.
   When working on the stylesheets, you can run npm run watch to automatically recompile them on every change.

8. If you want to receive mails in development you can start the mail server with docker compose up maildev -d and view your mails in the browser at http://localhost:8000.
   Don't forget to set the following config variables in the config file:

  mail_server = "localhost"
  mail_port = 1025
  mail_password = "mailpass"
  mail_username = "mail"

9. You can now start the server with cargo run. If you want to create an admin user you can start it with the ZAUTH_ADMIN_PASSWORD environment variable:

   ZAUTH_ADMIN_PASSWORD=adminadmin cargo run

   The server should then run on localhost:8000 and create an admin user with password 'adminadmin'.

   There are also other environment variables like:

   • ZAUTH_EMPTY_DB=true to clean the database from users and clients
   • ZAUTH_CLIENT_NAME=mozaic_inc to create a client with the name mozaic_inc
   • ZAUTH_SEED_USER=100 to create 100 users, some are active, some are pending (always creates the same users)
   • ZAUTH_SEED_CLIENT=100 to create 100 clients, some need a grant, others don't (always creates the same clients)

You can now start developing! A good way to start is to look at the routes defined in the controllers.

Testing the OAuth2 flow

There are tests trying out the OAuth2 flow which can be run with cargo test.

You can also test the OAuth2 flow manually by running the flask application in test_client/client.py.

Creating a migration

To make a change to the database scheme, we use diesel migrations

1. To create a migration, run diesel migration generate <migration name>
2. Fill in the generated up.sql and down.sql
3. Re-generate src/models/schema.rs by running diesel print-schema

   Caution: at the moment, the users schema cannot be generated correctly automatically.

Using Nix

We have provided a flake.nix for easy setup for Nix users. With flakes enabled, run nix develop.