The clath Reference Manual

This is the clath Reference Manual, generated automatically by Declt version 4.0 beta 2 "William Riker" on Sun Sep 15 04:40:42 2024 GMT+0.

Table of Contents


1 Introduction


2 Systems

The main system appears first, followed by any subsystem dependency.


2.1 clath

Clath is single sign-on middleware for Clack. It allows basic login with OAuth1.0a, OAuth2 and OpenID Connect.

Author

Ben McGunigle <>

License

Apache License, version 2.0

Dependencies
  • ningle (system).
  • clack (system).
  • alexandria (system).
  • cl-hash-util (system).
  • drakma (system).
  • flexi-streams (system).
  • cl-json (system).
  • jose (system).
  • ironclad (system).
  • cl-who (system).
  • ubiquitous (system).
  • north (system).
Source

clath.asd.

Child Components

3 Files

Files are sorted by type and then listed depth-first from the systems components trees.


3.1 Lisp


3.1.1 clath/clath.asd

Source

clath.asd.

Parent Component

clath (system).

ASDF Systems

clath.


3.1.2 clath/package.lisp

Source

clath.asd.

Parent Component

clath (system).

Packages

clath.


3.1.3 clath/util.lisp

Dependency

package.lisp (file).

Source

clath.asd.

Parent Component

clath (system).

Internals

3.1.4 clath/providers.lisp

Dependency

util.lisp (file).

Source

clath.asd.

Parent Component

clath (system).

Internals

3.1.5 clath/bottom.lisp

Dependency

providers.lisp (file).

Source

clath.asd.

Parent Component

clath (system).

Public Interface
Internals

3.1.6 clath/clath.lisp

Dependency

bottom.lisp (file).

Source

clath.asd.

Parent Component

clath (system).

Public Interface
Internals

4 Packages

Packages are listed by definition order.


4.1 clath

Source

package.lisp.

Use List
  • alexandria.
  • cl-who.
  • common-lisp.
Public Interface
Internals

5 Definitions

Definitions are sorted by export status, category, package, and then by lexicographic order.


5.1 Public Interface


5.1.1 Special variables

Special Variable: *callback-extension*
Package

clath.

Source

bottom.lisp.

Special Variable: *in-logout-page*

For code that implements login links. Self destination links should not be used on the logout page, lest the user get stuck in an auto-logout loop. This variable will be set when the logout page is being generated.

Package

clath.

Source

clath.lisp.

Special Variable: *login-destination*
Package

clath.

Source

bottom.lisp.

Special Variable: *login-destination-hook*
Package

clath.

Source

bottom.lisp.

Special Variable: *login-extension*
Package

clath.

Source

bottom.lisp.


5.1.2 Ordinary functions

Function: available-providers ()
Package

clath.

Source

bottom.lisp.

Function: clath-login-page ()

Redefine this function to customize the login page.

Package

clath.

Source

clath.lisp.

Function: clath-logout-page ()

Redefine this function to customize the logout page.

Package

clath.

Source

clath.lisp.

Function: clath-not-logged-page ()

Redefine this function to customize the not-logged-in page.

Package

clath.

Source

clath.lisp.

Function: clath-page-wrapper (title body-func)

Redefine this function to customize the look of all Clath pages.

Package

clath.

Source

clath.lisp.

Function: component (base-url &key extension)
Package

clath.

Source

clath.lisp.

Function: disable-provider (pr)
Package

clath.

Source

clath.lisp.

Function: enable-provider (pr)
Package

clath.

Source

clath.lisp.

Function: initialize-secrets ()
Package

clath.

Source

clath.lisp.

Package

clath.

Source

clath.lisp.

Function: login-url ()
Package

clath.

Source

clath.lisp.

Function: logout-url ()
Package

clath.

Source

clath.lisp.

Function: provider-disabled? (pr)
Package

clath.

Source

clath.lisp.

Function: provider-url-string (provider)
Package

clath.

Source

bottom.lisp.


5.2 Internals


5.2.1 Special variables

Special Variable: *callback-extension-north*
Package

clath.

Source

bottom.lisp.

Special Variable: *clath-version*
Package

clath.

Source

bottom.lisp.

Special Variable: *login-extension-north*
Package

clath.

Source

bottom.lisp.

Special Variable: *logout-extension*
Package

clath.

Source

clath.lisp.

Special Variable: *openid-app-address*
Package

clath.

Source

clath.lisp.

Special Variable: *provider-info*
Package

clath.

Source

providers.lisp.

Special Variable: *provider-secrets*
Package

clath.

Source

providers.lisp.

Special Variable: *server-url*
Package

clath.

Source

bottom.lisp.


5.2.2 Macros

Macro: assoc-cdr (key alist &optional test)
Package

clath.

Source

util.lisp.


5.2.3 Ordinary functions

Function: assoc-or (keys alist)

Finds the first key in keys that has a match in alist. Will use equal to match strings.

Package

clath.

Source

util.lisp.

Function: basic-authorization (provider)
Package

clath.

Source

bottom.lisp.

Function: callback-action (provider parameters &optional post-func)
Package

clath.

Source

bottom.lisp.

Function: callback-action-north (provider parameters &optional post-func)
Package

clath.

Source

bottom.lisp.

Function: check-for-error (parameters)
Package

clath.

Source

providers.lisp.

Function: destination-on-login ()
Package

clath.

Source

bottom.lisp.

Function: discover-endpoints (discovery-url)
Package

clath.

Source

bottom.lisp.

Function: ensure-jwk (kid provider)
Package

clath.

Source

bottom.lisp.

Function: extract-keywords (keywords alist &key in-list)
Package

clath.

Source

util.lisp.

Function: fetch-jwks (jwks-uri)
Package

clath.

Source

bottom.lisp.

Function: gen-state (len)
Package

clath.

Source

bottom.lisp.

Function: get-access-token (atdata)
Package

clath.

Source

bottom.lisp.

Function: get-id-token (atdata provider)
Package

clath.

Source

bottom.lisp.

Function: get-jwk (kid provider)
Package

clath.

Source

bottom.lisp.

Function: get-jwk-key (jsonkey)
Package

clath.

Source

bottom.lisp.

Function: logged-in ()
Package

clath.

Source

clath.lisp.

Function: logged-out ()
Package

clath.

Source

clath.lisp.

Function: login-action (provider)
Package

clath.

Source

bottom.lisp.

Function: login-action-north (provider)
Package

clath.

Source

bottom.lisp.

Function: login-app (base-url)
Package

clath.

Source

clath.lisp.

Function: login-page (params)

Internal portion of clath-login-page

Package

clath.

Source

clath.lisp.

Function: logout-action ()
Package

clath.

Source

bottom.lisp.

Function: logout-page (params)
Package

clath.

Source

clath.lisp.

Function: make-callback-url (provider)
Package

clath.

Source

bottom.lisp.

Function: make-login-url (provider)
Package

clath.

Source

bottom.lisp.

Function: mkstr (&rest args)
Package

clath.

Source

util.lisp.

Function: not-logged-page (env result)

Internal portion of clath-not-logged-page

Package

clath.

Source

clath.lisp.

Function: provider-info (provider)
Package

clath.

Source

bottom.lisp.

Function: provider-secrets (provider)
Package

clath.

Source

bottom.lisp.

Function: provider-string (provider)
Package

clath.

Source

bottom.lisp.

Function: repath-clack-env (env newpath)
Package

clath.

Source

util.lisp.

Function: request-access-token (provider code redirect-uri)
Package

clath.

Source

bottom.lisp.

Function: request-user-auth-destination (&key auth-scope client-id auth-endpoint state redirect-uri &allow-other-keys)
Package

clath.

Source

bottom.lisp.

Function: request-user-info-north (provider north-client)
Package

clath.

Source

providers.lisp.

Function: secrets-from-ubiquitous ()
Package

clath.

Source

clath.lisp.

Function: special-url-p (url-path)
Package

clath.

Source

bottom.lisp.

Function: string-equal-case (a b)
Package

clath.

Source

util.lisp.

Function: try-request-user-info (provider access-token)

Sometimes a newly generated access token won’t instantly propagate in the provider’s system, so we try a few times to give it a chance.

Package

clath.

Source

bottom.lisp.

Function: under-path-p (path testpath)
Package

clath.

Source

util.lisp.

Function: unpack-and-check-jwt (jwt provider)
Package

clath.

Source

bottom.lisp.

Function: update-jwks (provider jwks-uri)
Package

clath.

Source

bottom.lisp.

Function: url-from-env (env)

Extract the current request url from a clack environment.

Package

clath.

Source

util.lisp.

Function: user-agent (provider)

Some providers, such as Reddit, want a fairly unique user-agent.

Package

clath.

Source

bottom.lisp.

Function: userinfo-get-user-id (provider userinfo)
Package

clath.

Source

bottom.lisp.

Function: uses-north-p (provider)
Package

clath.

Source

bottom.lisp.

Function: valid-state (received-state)
Package

clath.

Source

bottom.lisp.


5.2.4 Generic functions

Generic Function: request-user-info (provider access-token)
Package

clath.

Source

providers.lisp.

Methods
Method: request-user-info ((provider (eql :stackexchange)) access-token)
Method: request-user-info ((provider (eql :linkedin)) access-token)
Method: request-user-info ((provider (eql :github)) access-token)
Method: request-user-info ((provider (eql :reddit)) access-token)
Method: request-user-info ((provider (eql :google)) access-token)
Method: request-user-info (provider access-token)

Appendix A Indexes


A.1 Concepts


A.2 Functions

Jump to:   A   B   C   D   E   F   G   I   L   M   N   P   R   S   T   U   V  
Index Entry  Section

A
assoc-cdr: Private macros
assoc-or: Private ordinary functions
available-providers: Public ordinary functions

B
basic-authorization: Private ordinary functions

C
callback-action: Private ordinary functions
callback-action-north: Private ordinary functions
check-for-error: Private ordinary functions
clath-login-page: Public ordinary functions
clath-logout-page: Public ordinary functions
clath-not-logged-page: Public ordinary functions
clath-page-wrapper: Public ordinary functions
component: Public ordinary functions

D
destination-on-login: Private ordinary functions
disable-provider: Public ordinary functions
discover-endpoints: Private ordinary functions

E
enable-provider: Public ordinary functions
ensure-jwk: Private ordinary functions
extract-keywords: Private ordinary functions

F
fetch-jwks: Private ordinary functions
Function, assoc-or: Private ordinary functions
Function, available-providers: Public ordinary functions
Function, basic-authorization: Private ordinary functions
Function, callback-action: Private ordinary functions
Function, callback-action-north: Private ordinary functions
Function, check-for-error: Private ordinary functions
Function, clath-login-page: Public ordinary functions
Function, clath-logout-page: Public ordinary functions
Function, clath-not-logged-page: Public ordinary functions
Function, clath-page-wrapper: Public ordinary functions
Function, component: Public ordinary functions
Function, destination-on-login: Private ordinary functions
Function, disable-provider: Public ordinary functions
Function, discover-endpoints: Private ordinary functions
Function, enable-provider: Public ordinary functions
Function, ensure-jwk: Private ordinary functions
Function, extract-keywords: Private ordinary functions
Function, fetch-jwks: Private ordinary functions
Function, gen-state: Private ordinary functions
Function, get-access-token: Private ordinary functions
Function, get-id-token: Private ordinary functions
Function, get-jwk: Private ordinary functions
Function, get-jwk-key: Private ordinary functions
Function, initialize-secrets: Public ordinary functions
Function, logged-in: Private ordinary functions
Function, logged-out: Private ordinary functions
Function, login-action: Private ordinary functions
Function, login-action-north: Private ordinary functions
Function, login-app: Private ordinary functions
Function, login-links: Public ordinary functions
Function, login-page: Private ordinary functions
Function, login-url: Public ordinary functions
Function, logout-action: Private ordinary functions
Function, logout-page: Private ordinary functions
Function, logout-url: Public ordinary functions
Function, make-callback-url: Private ordinary functions
Function, make-login-url: Private ordinary functions
Function, mkstr: Private ordinary functions
Function, not-logged-page: Private ordinary functions
Function, provider-disabled?: Public ordinary functions
Function, provider-info: Private ordinary functions
Function, provider-secrets: Private ordinary functions
Function, provider-string: Private ordinary functions
Function, provider-url-string: Public ordinary functions
Function, repath-clack-env: Private ordinary functions
Function, request-access-token: Private ordinary functions
Function, request-user-auth-destination: Private ordinary functions
Function, request-user-info-north: Private ordinary functions
Function, secrets-from-ubiquitous: Private ordinary functions
Function, special-url-p: Private ordinary functions
Function, string-equal-case: Private ordinary functions
Function, try-request-user-info: Private ordinary functions
Function, under-path-p: Private ordinary functions
Function, unpack-and-check-jwt: Private ordinary functions
Function, update-jwks: Private ordinary functions
Function, url-from-env: Private ordinary functions
Function, user-agent: Private ordinary functions
Function, userinfo-get-user-id: Private ordinary functions
Function, uses-north-p: Private ordinary functions
Function, valid-state: Private ordinary functions

G
gen-state: Private ordinary functions
Generic Function, request-user-info: Private generic functions
get-access-token: Private ordinary functions
get-id-token: Private ordinary functions
get-jwk: Private ordinary functions
get-jwk-key: Private ordinary functions

I
initialize-secrets: Public ordinary functions

L
logged-in: Private ordinary functions
logged-out: Private ordinary functions
login-action: Private ordinary functions
login-action-north: Private ordinary functions
login-app: Private ordinary functions
login-links: Public ordinary functions
login-page: Private ordinary functions
login-url: Public ordinary functions
logout-action: Private ordinary functions
logout-page: Private ordinary functions
logout-url: Public ordinary functions

M
Macro, assoc-cdr: Private macros
make-callback-url: Private ordinary functions
make-login-url: Private ordinary functions
Method, request-user-info: Private generic functions
Method, request-user-info: Private generic functions
Method, request-user-info: Private generic functions
Method, request-user-info: Private generic functions
Method, request-user-info: Private generic functions
Method, request-user-info: Private generic functions
mkstr: Private ordinary functions

N
not-logged-page: Private ordinary functions

P
provider-disabled?: Public ordinary functions
provider-info: Private ordinary functions
provider-secrets: Private ordinary functions
provider-string: Private ordinary functions
provider-url-string: Public ordinary functions

R
repath-clack-env: Private ordinary functions
request-access-token: Private ordinary functions
request-user-auth-destination: Private ordinary functions
request-user-info: Private generic functions
request-user-info: Private generic functions
request-user-info: Private generic functions
request-user-info: Private generic functions
request-user-info: Private generic functions
request-user-info: Private generic functions
request-user-info: Private generic functions
request-user-info-north: Private ordinary functions

S
secrets-from-ubiquitous: Private ordinary functions
special-url-p: Private ordinary functions
string-equal-case: Private ordinary functions

T
try-request-user-info: Private ordinary functions

U
under-path-p: Private ordinary functions
unpack-and-check-jwt: Private ordinary functions
update-jwks: Private ordinary functions
url-from-env: Private ordinary functions
user-agent: Private ordinary functions
userinfo-get-user-id: Private ordinary functions
uses-north-p: Private ordinary functions

V
valid-state: Private ordinary functions


A.3 Variables

Jump to:   *  
S  
Index Entry  Section

*
*callback-extension*: Public special variables
*callback-extension-north*: Private special variables
*clath-version*: Private special variables
*in-logout-page*: Public special variables
*login-destination*: Public special variables
*login-destination-hook*: Public special variables
*login-extension*: Public special variables
*login-extension-north*: Private special variables
*logout-extension*: Private special variables
*openid-app-address*: Private special variables
*provider-info*: Private special variables
*provider-secrets*: Private special variables
*server-url*: Private special variables

S
Special Variable, *callback-extension*: Public special variables
Special Variable, *callback-extension-north*: Private special variables
Special Variable, *clath-version*: Private special variables
Special Variable, *in-logout-page*: Public special variables
Special Variable, *login-destination*: Public special variables
Special Variable, *login-destination-hook*: Public special variables
Special Variable, *login-extension*: Public special variables
Special Variable, *login-extension-north*: Private special variables
Special Variable, *logout-extension*: Private special variables
Special Variable, *openid-app-address*: Private special variables
Special Variable, *provider-info*: Private special variables
Special Variable, *provider-secrets*: Private special variables
Special Variable, *server-url*: Private special variables