uzh / guardian

Role-based access control for OCaml

Guardian

Generic framework for roles and permissions to be used in our projects

Limitations and Notes

• Supported Database: Implementation with MariaDb
• Context (ctx): Allows to have multiple database pools (See next section)

Setup with MariaDB backend (MultiPools)

  let open Guardian_backend.Pools in
  let module MariaConfig = struct
    include DefaultConfig

    let database =
      MultiPools
        [ "pool-one", "mariadb://root@database:3306/dev"
        ; "pool-two", "mariadb://root@database:3306/test"
        ]
    ;;
  end
  in
  let module MariaDb = Guardian_backend.MariaDb.Make (Roles) (Make (MariaConfig))
  let%lwt () = Lwt_list.iter (fun pool -> MariaDb.migrate ~ctx:["pool", pool] ()) ["pool-one"; "pool-two"]
  (** NOTE: To integrate migrations into your applications migration state see
      e.g. function 'MariaDB.find_migrations *)

Usage

The test directory shows an example implementation of how guardian can be used.

• role.ml: Definition of actors and targets
• role.mli: Signature of the defined actors and targets
• guard.ml: Create the guardian service
• article.ml: Definition of the article target
• hacker.ml: Definition of the hacker actor
• user.ml: Definition of the user actor and target
• main.ml: implementation of all test cases

Example usage:

  module Guard = Guardian.Make (Role.Actor) (Role.Target)

  let thomas = "Thomas", Guard.Uuid.Actor.create ()
  let mike = "Mike", Guard.Uuid.Actor.create ()

  let thomas_article = Article.make "Foo" "Bar" thomas
  let mike_article = Article.make "Hello" "World" mike

  let example_rule = `Actor (snd mike), `Update, `Target thomas_article.uuid

  let initialize_authorizables_and_rules ?ctx =
    (* Note: As a user can be an actor and a target, both need to be initialized *)
    let* (_: [> `User ] MariaDb.actor) = User.to_authorizable ?ctx thomas in
    let* (_: [> `User ] MariaDb.actor) = User.to_authorizable ?ctx mike in
    let* (_: [> `User ] MariaDb.target) = UserTarget.to_authorizable ?ctx thomas in
    let* (_: [> `User ] MariaDb.target) = UserTarget.to_authorizable ?ctx mike in
    let* (_: [> `Article ] MariaDb.target) = Article.to_authorizable ?ctx thomas_article in
    let* (_: [> `Article ] MariaDb.target) = Article.to_authorizable ?ctx mike_article in
    let* () = MariaDb.Rule.save ?ctx example_role in
    Lwt.return_unit

  (* let mike Update the title of thomas article -> returns a (Article.t, string) Lwt_result.t  *)
  let update_title = Article.update_title ?ctx mike thomas_article "Updated Title"

Development

A guide how to setup the project with devcontainers can be found here.

Commands

Most used commands can be found in the following list. For the full list of commands, checkout the Makefile.

• make build - to build the project
• make build-watch - to build and watch the project
• make test - to run all tests. This requires a running MariaDB instance.

🚀 Release new version

1. Update CHANGELOG.md and document changes made. Ensure the version to be releases has a header matching the version, follow previous releases.
2. Edit the file dune-project and update version (version 0.0.0).
3. Build the project dune build OR edit the file pool.opam and update version version: "0.0.0"
4. Commit your changes.
5. Tag the commit and push changes and git tag
6. create opam release (opam-publish)

guardian's Issues

add cached option of guardian

Caching would help a lot when multiple requests of the same type check are handled.

https://ocaml.org/p/containers-data/latest/doc/CCCache/index.html

• Smart clear algorithm -- clear cache when certain actions are done:
  • role change -> take the uuid of the actor and remove all its elements
  • rule change -> search for actors with the role of the changed rule and remove them

validate circular dependencies of transitional roles

Currently, role dependencies can be registered with Dependency.register.

They are all handled, but they don't check if it's circular. In worst case, a infinite loop can be implemented.

• the registration should check if there are circular dependencies specified.

refactor single responsibility principle

• reduce redundant calls
• actor and target need to be initialized, also if only one of them is used

Examples

• test case for parametric roles
• decorate function of actor/target

Creation of new roles at runtime

The creation of new roles at runtime is not supported by ocaml_authorize, but I don't think such functionality is strictly necessary.

Yes, if you need additional flexibility you can create roles that look like Manager of Uuidm.t, which I believe covers the behaviour we want to achieve.

logging

• log access requests

Check valid constructors

A constructor `Create and `Uniq does not make sense. Is it possible to disable that through types?