Two flows: service-account JWT bearer (RFC 7523) for server-to-server access from a JSON key file, and an interactive local OAuth flow for CLI tools that spins up a localhost listener and exchanges the authorization code for tokens. Both return a token that transparently refreshes credentials near expiry.

Installation#

Install with opam:

$ opam install gauth

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 gauth

Usage#

Service account#

Parse a service-account JSON key and mint an access token for a set of OAuth scopes. The Requests.t HTTP client and the Eio clock are required for refresh:

let fetch_token http ~clock ~key_path =
  match Gauth.Service_account.of_file key_path with
  | Error (`Msg m) -> Error m
  | Ok key ->
      let scopes =
        [ "https://www.googleapis.com/auth/documents.readonly" ] in
      match Gauth.Service_account.token http ~clock ~scopes key with
      | Ok token -> Ok (Gauth.access token)
      | Error (`Msg m) -> Error m

Pass ?subject:"alice@example.com" to Service_account.token to use domain-wide delegation and impersonate a Workspace user.

Interactive local flow#

Local_flow.run binds an ephemeral port on 127.0.0.1, prints a Google consent URL to stderr, and waits up to ?timeout seconds (default 120) for the user to complete the flow:

let login http ~clock ~net ~sw ~client_id ~client_secret =
  Gauth.Local_flow.run http ~clock ~net ~sw
    ~client_id ~client_secret
    ~scopes:[ "https://www.googleapis.com/auth/documents.readonly" ]
    ()

Override ?on_url to launch a browser automatically instead of printing the URL.

Persistence#

Serialize a token to JSON, restore it later — useful for "login once, use many times" CLIs:

let save token = Gauth.to_json token

let restore http ~clock ~client_id ~client_secret json =
  Gauth.of_json http ~clock ~client_id ~client_secret json

access and try_access return a current access token, refreshing synchronously if the cached one is near expiry.

Licence#

MIT

Configure Feed