CL-OpenID is available on terms of GNU Lesser General Public License version 2.1 with Franz Inc.'s preamble, also known as LLGPL (Lisp Lesser General Public License).
The project is developed as a Google Summer of Code 2008 project, developed by Maciej Pasternacki and mentored by Anton Vodonosov. Original application is published at http://trac.common-lisp.net/cl-openid/wiki/OriginalProposal.
RELYING-PARTY
+AUTHPROC-HANDLE-PARAMETER+INITIATE-AUTHENTICATION relying-party given-id &key immediate-p ⇒ uriHANDLE-INDIRECT-RESPONSE relying-party message request-uri &optional auth-process ⇒ authendicated-id auth-processOPENID-ASSERTION-ERROR
AUTH-PROCESS
AUTH-PROCESS-P object ⇒ booleanPROTOCOL-VERSION-MAJOR auth-process ⇒ integerPROTOCOL-VERSION-MINOR auth-process ⇒ integerPROTOCOL-VERSION auth-process ⇒ consCLAIMED-ID auth-process ⇒ uriOP-LOCAL-ID auth-process ⇒ uriPROVIDER-ENDPOINT-URI auth-process ⇒ uriRETURN-TO auth-process ⇒ uriTIMESTAMP auth-process ⇒ universal-timeXRDS-LOCATION auth-process ⇒ uriOPENID-PROVIDER
+INDIRECT-RESPONSE-CODE+HANDLE-OPENID-PROVIDER-REQUEST op message &key secure-p ⇒ response valuesCANCEL-RESPONSE op message ⇒ response valuesSUCCESSFUL-RESPONSE op message ⇒ response valuesWITH-INDIRECT-ERROR-HANDLER &body body ⇒ response valuesSIGNAL-INDIRECT-ERROR message reason &rest reason-argsHANDLE-CHECKID-IMMEDIATE op message ⇒ generalized-booleanUSER-SETUP-URL op message ⇒ uriHANDLE-CHECKID-SETUP op message ⇒ response valuesDiscussions regarding development are conducted on cl-openid-devel mailing list. This is the best place to bring up questions, suggestions or to discuss issues connected with CL-OpenID.
Important announcements are posted to cl-openid-announce mailing list. This is a low-volume, announcement-only list. All the announcements are also posted on development list.
Bugs are tracked on project's Trac bugtracker. Interface for submitting new tickets is available at http://trac.common-lisp.net/cl-openid/newticket. All ticket change notifications are sent to cl-openid-ticket mailing list.
Miscellaneous information on project, of various quality and relevance, can be found on project's Trac wiki.
Project Web page is http://common-lisp.net/project/cl-openid/. Most recent version of the code can be downloaded with darcs:
darcs get http://common-lisp.net/project/cl-openid/
Project depends on following libraries:
Example code depends also on Hunchentoot. Unit tests depend on FiveAM testing framework.
All required libraries should be ASDF-installable, so running darcs dist and then calling ASDF-INSTALL:INSTALL on resulting tarball
should provide complete dependencies.
As an alternative to ASDF-Install, a CL-Librarian shelf definition for dependencies is provided. To use it, run following shell commands in CL-OpenID directory:
darcs get http://www.pasternacki.net/repos/cl-librarian/ lib cd lib sh bootstrap.sh cd ..Then start your favourite Lisp implementation and call:
(load "shelf") (cl-librarian:download-shelf 'cl-openid.deps) ; for the first time or when new dependency is added (cl-librarian:use-shelf 'cl-openid.deps) ; when libraries are already downloaded (asdf:oos 'asdf:load-op :cl-openid) (asdf:oos 'asdf:test-op :cl-openid) ; run 5am unit tests
Example implementation of Relying Party and OpenID Provider for
Hunchentoot web server is included in examples/ subdirectory. For
convenience, both examples can be loaded as CL-OPENID.EXAMPLES
ASDF system:
(asdf:oos 'asdf:load-op :cl-openid.examples)
RELYING-PARTYRelying Party class.
ROOT-URI relying-party ⇒ uriRoot URI address of the Relying Party instance.
Used to generate return_to redirections.
REALM relying-party ⇒ uriRelying Party realm.
+AUTHPROC-HANDLE-PARAMETER+Name of HTTP GET parameter, sent in return_to URI, which contains AUTH-PROCESS object unique handle.
INITIATE-AUTHENTICATION relying-party given-id &key immediate-p ⇒ uriInitiate authentication process by relying-party for identifier given-id received from user.
If immediate-p is true, initiates immediate authentication process. Returns URI to redirect user to.
HANDLE-INDIRECT-RESPONSE relying-party message request-uri &optional auth-process ⇒ authendicated-id auth-processHandle indirect response message for relying-party, coming at request-uri, concerning authproc.
authproc can be a literal AUTH-PROCESS object, or a string
(unique authproc handle, sent earlier by Relying Party). When
authproc is NIL or not supplied, its handle is taken from
message field named +AUTHPROC-HANDLE-PARAMETER+.
Returns claimed ID URI on success, NIL on failure. As second value, always returns AUTH-PROCESS object.
OPENID-ASSERTION-ERRORError signaled by Relying Party when indirect response cannot be verified correctly.
CODE openid-assertion-error ⇒ keywordKeyword code of error.
Possible values are
:SERVER-ERROR (received response is an erroor message),
:SETUP-NEEDED (negative response to immediate request),
:INVALID-RETURN-TO (request doesn't match previously sent openid.return_to),
:INVALID-NAMESPACE (invalid openid.ns in received message),
:INVALID-ENDPOINT (endpoint specified in assertion does not match previously discovered information),
:INVALID-CLAIMED-ID (received claimed_id differs from specified previously, discovery for received claimed ID returns other endpoint),
:INVALID-NONCE (repeated openid.nonce),
:INVALID-SIGNATURE (signature verification failed),
:INVALID-SIGNED-FIELDS (not all fields that need to be signed, were signed).
REASON openid-assertion-error ⇒ stringTextual description of error.
AUTHPROC openid-assertion-error ⇒ auth-processThe AUTH-PROCESS structure that was being verified.
MESSAGE openid-assertion-error ⇒ messageReceived message (an association list).
AUTH-PROCESSData structure gathering information about an ongoing authentication process.
AUTH-PROCESS-P object ⇒ booleanReturns true if object is an AUTH-PROCESS structure.
PROTOCOL-VERSION-MAJOR auth-process ⇒ integerProtocol version major number of auth-process.
PROTOCOL-VERSION-MINOR auth-process ⇒ integerProtocol version minor number of auth-process.
PROTOCOL-VERSION auth-process ⇒ consProtocol version of an authentication process, as a cons (MAJOR . MINOR).
CLAIMED-ID auth-process ⇒ uriClaimed ID of an auth proces.
OP-LOCAL-ID auth-process ⇒ uriOP-local id of an auth process.
PROVIDER-ENDPOINT-URI auth-process ⇒ uriDiscovered endpoint URI.
RETURN-TO auth-process ⇒ uriAuthentication process' return_to address.
It is Relying Party's root URI with added HTTP GET parameter
named +AUTHPROC-HANDLE-PARAMETER+ whose value is authproc's
unique handle.
TIMESTAMP auth-process ⇒ universal-timeUniversal time of authentication process structure's creation.
XRDS-LOCATION auth-process ⇒ uriAddress of XRDS file used in auth-process discovery.
OPENID-PROVIDEROpenID Provider server abstract class.
This class should be subclassed, and specialized methods should be
provided at least for HANDLE-CHECKID-SETUP (preferably also for
HANDLE-CHECKID-IMMEDIATE).
ENDPOINT-URI op ⇒ uriOpenID Provider instance's endpoint URI
+INDIRECT-RESPONSE-CODE+HTTP code used for indirect response redirections.
HANDLE-OPENID-PROVIDER-REQUEST op message &key secure-p ⇒ response valuesHandle request message for OpenID Provider instance op.
secure-p should be passed by caller to indicate whether it is secure to use unencrypted association method.
Returns two values: first is body, and second is HTTP code. If second value is not returned, 200 OK HTTP code should be assumed.
On HTTP redirections (second value between 300 and 399 inclusive,
actually it will be +INDIRECT-RESPONSE-CODE+), primary returned
value will be an URI to redirect user to.
The same rules apply to all *-RESPONSE functions and
WITH-INDIRECT-ERROR-HANDLER form return values.
CANCEL-RESPONSE op message ⇒ response valuesSend cancel (authenticaction failure) response to MESSAGE from OP.
SUCCESSFUL-RESPONSE op message ⇒ response valuesReturn successful response to message by op.
WITH-INDIRECT-ERROR-HANDLER &body body ⇒ response valuesHandle INDIRECT-ERROR in body.
When INDIRECT-ERROR condition is signaled, immediately return
indirect error response.
SIGNAL-INDIRECT-ERROR message reason &rest reason-argsSignal INDIRECT-ERROR condition as reply to message,
effectively returning indirect error reply from
WITH-INDIRECT-ERROR-HANDLER block.
Reason is textual error message format string, with reason-args being its arguments.
HANDLE-CHECKID-IMMEDIATE op message ⇒ generalized-booleanHandle checkid_immediate requests.
This generic should be specialized on concrete Provider classes to perform immediate login checks on MESSAGE. It should return at once, either true value (to indicate successful login), or NIL (to indicate immediate login failure).
Default method always fails.
This generic is called within scope of
WITH-INDIRECT-ERROR-HANDLER.
USER-SETUP-URL op message ⇒ uriURI for user setup to return on failed immediate request.
When NIL is returned, no user_setup_url is sent in setup_needed responses.
This generic should be specialized on concrete Provider classes to provide entry point to user authentication dialogue.
Default method always returns NIL.
HANDLE-CHECKID-SETUP op message ⇒ response valuesHandle checkid_setup requests.
This generic should be specialized on concrete Provider classes to
perform login checks with user dialogue, that would (possibly
after some HTTP request-response cycles) end in either
SUCCESSFUL-RESPONSE, or in CANCEL-RESPONSE.
Default method always fails.
This generic is called within scope of
WITH-INDIRECT-ERROR-HANDLER.
Messages passed between OpenID Provider and the Relying Party are composed of key-value pairs. Natural Lisp representation of those, and the one used in CL-OpenID, is an association list. A handful of conveniense function is provided to avoid tweaking messages on cons level.
MAKE-MESSAGE &rest parameters ⇒ messageMake new message from arbitrary keyword parameters.
Keyword specifies a message field key (actual key is lowercased symbol name), and value following the keyword specifies associated value.
Value can be a string (which will be literal field value), symbol (symbol's name will be used as a value), vector of (UNSIGNED-BYTE 8) (which will be Base64-encoded), URI object or integer (which both will be PRINC-TO-STRING-ed).
If value is NIL, field won't be included in the message at all.
COPY-MESSAGE message &rest parameters ⇒ messageCreate a copy of MESSAGE, updating PARAMETERS provided as keyword parameters.
If MESSAGE already includes provided key, new value is used in the result; if a key is new, the field will be appended to result message. PARAMETERS are interpreted as by MAKE-MESSAGE function.
IN-NS message &optional namespace ⇒ messageAdd openid.namespace namespace to message.
Default namespace is OpenID v2. Returns updated message alist.
MESSAGE-FIELD message field-name ⇒ valueGet value of field-name field from message.
MESSAGE-V2-P message ⇒ booleanTrue if message is an OpenID v2 message (namespace check).
Date: 2008/08/18 20:05:00