- OCaml 100%
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,GoogleandGitlabare built in.Oauth.Provider.custom_providerdefines another and refuses any endpoint that is not HTTPS.Oauth.Provider.of_serverbuilds one from discovered metadata. - Authorization.
Oauth.authorization_urlbuilds the provider's URL.Oauth.State.generatemakes the CSRF state andOauth.State.validatechecks it in constant time.Oauth.Redirect.taccepts only an HTTPS URI (orhttpon a loopback host) with no fragment, following RFC 8252. - PKCE.
Oauth.Pkce.generate_verifierdraws a random verifier andOauth.Pkce.challengederives itsS256challenge. - Client authentication.
Oauth.Client_authoffersnone,basic,post,secret_jwtandprivate_key_jwt. - Token exchange.
Oauth.exchange_code,Oauth.refresh_tokenandOauth.client_credentialsPOST to the token endpoint.Oauth.Tokenwraps 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.Parpushes an authorization request,Oauth.Deviceruns the device grant, andOauth.Flowputs state, PKCE, PAR and DPoP together behind one call to begin and one to complete. - Userinfo.
Oauth.Userinfo.parseturns each provider's user profile into one shape, andOauth.Userinfo.parse_github_emailspicks out the verified primary email from GitHub's list.
Standards #
- RFC 6749: OAuth 2.0
- RFC 6750: Bearer Token Usage
- RFC 7523: JWT client authentication
- RFC 7591: Dynamic Client Registration metadata
- RFC 7636: PKCE
- RFC 8252: OAuth for Native Apps
- RFC 8414: Authorization Server Metadata
- RFC 8628: Device Authorization Grant
- RFC 9126: Pushed Authorization Requests
- RFC 9449: DPoP
- RFC 9728: Protected Resource Metadata
Licence #
ISC. See LICENSE.md.