github-oauth#

GitHub OAuth URL generation and token exchange helpers for OCaml.

Overview#

This library provides helpers for implementing GitHub OAuth 2.0 authorization flows. It supports both GitHub Apps (with token expiry and refresh tokens) and traditional OAuth Apps.

Features#

• Cryptographically secure state generation for CSRF protection
• Authorization URL generation with scope support
• Token exchange request body generation (JSON)
• Token response parsing (access tokens, refresh tokens, expiry)
• Refresh token request body generation

Installation#

opam install github-oauth

Usage#

(* Generate authorization URL *)
let state = Github_oauth.generate_state () in
let url =
  Github_oauth.authorization_url ~client_id:"your_client_id"
    ~callback_url:"https://yourapp.com/callback" ~state ~scope:[ "repo" ]
in

(* After user authorizes, exchange code for token *)
let body =
  Github_oauth.exchange_request_body ~client_id:"your_client_id"
    ~client_secret:"your_secret" ~code ~redirect_uri:"https://yourapp.com/callback"
in
(* POST body to Github_oauth.access_token_url with headers:
   Content-Type: application/json
   Accept: application/json *)

(* Parse the response *)
match Github_oauth.parse_token_response response_body with
| Ok token ->
    Printf.printf "Access token: %s\n" token.access_token;
    (* For GitHub Apps, handle refresh *)
    (match token.refresh_token with
     | Some rt -> (* store for later refresh *)
     | None -> (* OAuth App, no refresh needed *))
| Error e ->
    Printf.eprintf "Error: %a\n" Github_oauth.pp_parse_token_error e

API#

• Github_oauth.generate_state - Generate CSRF protection state
• Github_oauth.authorization_url - Build GitHub authorization URL
• Github_oauth.access_token_url - Token exchange endpoint URL
• Github_oauth.exchange_request_body - Build token exchange request
• Github_oauth.parse_token_response - Parse token response JSON
• Github_oauth.refresh_request_body - Build refresh token request

Standards#

• RFC 6749 - OAuth 2.0
• GitHub OAuth Documentation

Related Work#

• github-oauth2 - Full OAuth2 client with HTTP handling
• oauth2 - Generic OAuth2 library

This library focuses on URL and request body generation without HTTP dependencies, allowing integration with any HTTP client (Cohttp, Dream, Eio, etc.).

Licence#

MIT License. See LICENSE.md for details.