auth -- user authentication and session management#

auth provides OAuth-based user authentication with server-side session management for OCaml web applications. It handles the full sign-in lifecycle: redirect to provider, exchange authorization code, create or find user, issue session cookie.

Sessions are stored in SQLite for revocability. Cookies are HttpOnly, SameSite=Lax, and Secure (when the base URL is HTTPS). CSRF protection on the OAuth callback uses signed state tokens.

Installation#

Install with opam:

$ opam install auth

If opam cannot find the package, it may not yet be released in the public opam-repository. Add the overlay repository, then install it:

$ opam repo add samoht https://tangled.org/gazagnaire.org/opam-overlay.git
$ opam update
$ opam install auth

Quick Start#

let run () =
  Eio_main.run @@ fun env ->
  Eio.Switch.run @@ fun sw ->
  let fs = Eio.Stdenv.fs env in
  let http = Requests.v ~sw env in
  let store = Auth.Store.v ~sw Eio.Path.(fs / "data" / "auth.db") in
  let cfg =
    Auth.config
      ~oauth_provider:Oauth.Github
      ~client_id:"Iv1.abc"
      ~client_secret:"secret"
      ~base_url:"https://app.com"
      ~cookie_secret:"32-char-min-secret-for-signing!"
      ~http ()
  in
  let routes = Auth.routes cfg store in
  Respond.run
    ~net:(Eio.Stdenv.net env)
    ~port:8080
    ~root:Eio.Path.(fs / "static")
    routes

The library registers three routes:

• GET /auth/<provider> -- redirect to OAuth provider
• GET /auth/<provider>/callback -- handle provider callback, create session
• POST /auth/signout -- revoke session, clear cookie

License#

ISC