OAuth 2.0 authorization and token exchange
README.md

oauth #

OAuth 2.0 authorization and token exchange for OCaml, on Eio.

Signing users in with GitHub, Google or GitLab looks simple and has several ways to go wrong: a CSRF state compared with =, a missing PKCE challenge, a redirect URI that leaks the code, the wrong client authentication on the token request. This library does the Authorization Code grant of RFC 6749 with PKCE (RFC 7636), and gives each of those pieces its own type so you cannot forget one.

With PKCE, the client makes up a random verifier (43 to 128 characters) and sends challenge = BASE64URL(SHA-256(verifier)) when it asks for authorisation. The verifier itself only goes out with the code exchange, and the server checks it against the challenge. An intercepted code is useless without it (RFC 7636, sections 4.1 to 4.6).

The state is random too. It lives in the user's session and has to come back unchanged on the callback, which proves the callback answers a request this client made. Without it, an attacker can log the victim in to the attacker's own account (CSRF; RFC 6749, section 10.12). The check is constant-time, so timing leaks nothing about how much of a guess matched.

Past the code flow there is token refresh, the client credentials grant, the device grant (RFC 8628), pushed authorization requests (RFC 9126), DPoP-bound tokens (RFC 9449), JWT client authentication (RFC 7523), and discovery from authorization-server (RFC 8414) and protected-resource (RFC 9728) metadata. HTTP goes through Requests_eio.t.

Installation #

Install with opam:

$ opam install oauth

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 oauth

Usage #

(* 1. Before redirect: generate state and PKCE *)
let run http callback_state code =
  let redirect_uri =
    Oauth.Redirect.of_string "https://app.com/callback" |> Result.get_ok
  in
  let state = Oauth.State.generate () in
  let verifier = Oauth.Pkce.generate_verifier () in
  let challenge = Oauth.Pkce.challenge S256 verifier in
  (* Store [state] and [verifier] in the user's session. *)
  let _url =
    Oauth.authorization_url Github ~client_id:"xxx" ~redirect_uri ~state
      ~scope:[ "user:email" ] ~code_challenge:challenge ()
  in
  (* Redirect user to [_url]. *)

  (* 2. On callback: validate state, then exchange code *)
  if not (Oauth.State.validate ~expected:state ~actual:callback_state) then
    failwith "CSRF state mismatch";
  let client_auth =
    Oauth.Client_auth.basic ~client_id:"xxx" ~client_secret:"yyy"
  in
  match
    Oauth.exchange_code http Github ~client_auth ~code ~redirect_uri
      ~code_verifier:verifier ()
  with
  | Ok token -> Printf.printf "Access token: %s\n" token.access_token
  | Error e -> Fmt.epr "Error: %a@." Oauth.Response.pp_error e

API #

oauth.mli documents the whole interface, with a worked example in each section. The main entry points follow.

  • Providers. Oauth.Provider.Github, Google and Gitlab are built in. Oauth.Provider.custom_provider defines another and refuses any endpoint that is not HTTPS. Oauth.Provider.of_server builds one from discovered metadata.
  • Authorization. Oauth.authorization_url builds the provider's URL. Oauth.State.generate makes the CSRF state and Oauth.State.validate checks it in constant time. Oauth.Redirect.t accepts only an HTTPS URI (or http on a loopback host) with no fragment, following RFC 8252.
  • PKCE. Oauth.Pkce.generate_verifier draws a random verifier and Oauth.Pkce.challenge derives its S256 challenge.
  • Client authentication. Oauth.Client_auth offers none, basic, post, secret_jwt and private_key_jwt.
  • Token exchange. Oauth.exchange_code, Oauth.refresh_token and Oauth.client_credentials POST to the token endpoint. Oauth.Token wraps the result in a token that Eio fibers can share and that refreshes itself when it is within 60 seconds of expiry.
  • Other grants. Oauth.Par pushes an authorization request, Oauth.Device runs the device grant, and Oauth.Flow puts state, PKCE, PAR and DPoP together behind one call to begin and one to complete.
  • Userinfo. Oauth.Userinfo.parse turns each provider's user profile into one shape, and Oauth.Userinfo.parse_github_emails picks out the verified primary email from GitHub's list.

Standards #

Licence #

ISC. See LICENSE.md.