README.org

January 27, 2023 · View on GitHub

Ciao - an OAuth 2.0 Client for Common Lisp

Ciao is an easy-to-use Common Lisp OAuth 2.0 client library. It is a port of the [[https://docs.racket-lang.org/webapi/oauth2.html][Racket OAuth 2.0 Client]] (package: ~~webapi~~) to Common Lisp.

** Installation

To install ~~ciao~~, you should download the repository into your local lisp directory (e.g., "~~/.roswell/local-projects/", "~~/portacle/projects/", "~/quicklisp/local-projects/").

It has been tested for use on [[https://cloud.google.com/docs/authentication][Google]] and [[https://app.clio.com/api/v4/documentation][Clio]] APIs with SBCL and CCL on GNU/Linux and SBCL on MacOS.

*** Notable Dependencies

All of ~~ciao~~'s dependencies are available on [[https://www.quicklisp.org/beta/][Quicklisp]].

~~ciao~~ uses [[https://github.com/fukamachi/dexador][~~dexador~~]] for http requests and [[https://common-lisp.net/project/cl-json/cl-json.html][~~cl-json~~]] to parse JSON responses. To retrieve responses from the OAuth server, ~~ciao~~ starts a [[https://edicl.github.io/hunchentoot/][~~hunchentoot~~]] server that blocks the thread until it receives a response from the OAuth server. Finally, ~~ciao~~ uses [[https://github.com/eudoxia0/trivial-open-browser][~~trivial-open-browser~~]] to open a web browser to obtain client authorization.

** Usage

The simplest method to obtain authorization from an OAuth 2.0 server is to use ~~oauth2/request-auth-code/browser~~, which opens up a browser window to get approval and returns an ~~oauth2~~ object, which represents a client authorized to access some set of resources.

#+BEGIN_SRC lisp ;; load the system (asdf:load-system "ciao")

;; create a parameter oauth-ojb and assign the return value (defparameter oauth-obj nil)

;; assign the value of oauth2/request-auth-code/browser to oauth-obj (setf oauth-obj (ciao:oauth2/request-auth-code/browser ciao:google-auth-server (make-instance 'ciao:oauth2-client :secret "XXXXXXXXXXXXXXXXXXXX" :id "XXXXXXXXXXXXXXXXXXXX") :scopes '("https://www.googleapis.com/auth/drive.readonly")))

;; use dexador to request a file's information (dex:get "https://www.googleapis.com/drive/v3/files/XXXXXXXXXXXXXXXXXXX" :headers (ciao:headers oauth-obj)) #+END_SRC

In the above example, id and ~~secret~~ represent the client authentication information from Google.

** API

Exported symbols:

classes
- :oauth2-auth-server
- :oauth2-client
- :oauth2
functions and methods
- :get-auth-request-url
- :get-access-token
- :get-refresh-token
- :headers
- :oauth2/auth-code
- :oauth2/refresh-token
- :oauth2/request-auth-code/browser
parameters
- :OOB-uri
- :google-auth-server

** License

Consistent with the Racket OAuth 2.0 Client, this package is licensed under the the terms of the GNU Lesser General Public License as published by the Free Software Foundation.

This program is free software: you can redistribute it and/or modify it under the terms of the GNU Lesser General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License and GNU Lesser General Public License for more details.

You should have received a copy of the GNU General Public License and GNU Lesser General Public License along with this program. If not, see http://www.gnu.org/licenses/.