Index of /project/cl-openid/darcs/cl-openid

[ICO]NameLast modifiedSizeDescription

[DIR]Parent Directory  -  
[DIR]t/17-Aug-2011 01:19 -  
[DIR]src/23-Feb-2013 05:29 -  
[   ]shelf.lisp18-Aug-2008 17:47 1.6K 
[   ]patch23-Feb-2013 05:29 9.7K 
[   ]log09-Jun-2010 21:28 26K 
[DIR]examples/15-Aug-2011 20:41 -  
[TXT]clopenid.patch04-Sep-2011 22:21 9.4K 
[   ]cl-openid.asd11-Jul-2011 23:47 2.4K 
[DIR]_darcs/23-Feb-2013 05:29 -  
[TXT]README.txt12-Jun-2011 01:02 20K 
[   ]README.org04-Sep-2011 23:24 14K 
[TXT]README.html04-Sep-2011 23:24 31K 

CL-OpenID

CL-OpenID

Cl-OpenID is an implementation of OpenID protocol in Common Lisp. It implements OpenID Authentication 2.0 standard and is compatible with OpenID Authentication 1.1. Both Relying Party (formerly called OpenID Consumer), and OpenID Provider are implemented.

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.

Table of Contents

1 Contact

Discussions 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.

2 Downloading

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/darcs/cl-openid/

2.1 Dependencies

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.

2.1.1 CL-Librarian shelf

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

2.2 Example code

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)

3 API

3.1 Relying Party

3.1.1 Class RELYING-PARTY

Relying Party class.

3.1.1.1 Accessor ROOT-URI relying-partyuri

Root URI address of the Relying Party instance.

Used to generate return_to redirections.

3.1.1.2 Accessor REALM relying-partyuri

Relying Party realm.

3.1.2 Constant +AUTHPROC-HANDLE-PARAMETER+

Name of HTTP GET parameter, sent in return_to URI, which contains AUTH-PROCESS object unique handle.

3.1.3 Function INITIATE-AUTHENTICATION relying-party given-id &key immediate-p extra-parametersuri

Initiate authentication process by relying-party for identifier given-id received from user.

If immediate-p is true, initiates immediate authentication process.

The extra-parameters is an optional key-value list to be added to the authentication request message. The list format is the same as for the MAKE-MESSAGE function. This parameter is needed for OpenID extensions, for example OAuth or Attribute Exchange.

Returns multiple values:

  • the URI to redirect the user's browser to;
  • Unique handle (string) identifying the started authentication process;
  • the AUTH-PROCESS structure identified by the handle.

The latter two values are useful if the client code needs to track the process.

3.1.4 Function HANDLE-INDIRECT-RESPONSE relying-party message request-uri &optional auth-processauthendicated-id auth-process

Handle 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.

3.1.5 Condition OPENID-ASSERTION-ERROR

Error signaled by Relying Party when indirect response cannot be verified correctly.

3.1.5.1 Accessor CODE openid-assertion-errorkeyword

Keyword 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).
3.1.5.2 Accessor REASON openid-assertion-errorstring

Textual description of error.

3.1.5.3 Accessor AUTHPROC openid-assertion-errorauth-process

The AUTH-PROCESS structure that was being verified.

3.1.5.4 Accessor MESSAGE openid-assertion-errormessage

Received message (an association list).

3.1.6 Structure AUTH-PROCESS

Data structure gathering information about an ongoing authentication process.

3.1.6.1 Function AUTH-PROCESS-P objectboolean

Returns true if object is an AUTH-PROCESS structure.

3.1.6.2 Accessor PROTOCOL-VERSION-MAJOR auth-processinteger

Protocol version major number of auth-process.

3.1.6.3 Accessor PROTOCOL-VERSION-MINOR auth-processinteger

Protocol version minor number of auth-process.

3.1.6.4 Accessor PROTOCOL-VERSION auth-processcons

Protocol version of an authentication process, as a cons (MAJOR . MINOR).

3.1.6.5 Accessor CLAIMED-ID auth-processuri

Claimed ID of an auth proces.

3.1.6.6 Accessor OP-LOCAL-ID auth-processuri

OP-local id of an auth process.

3.1.6.7 Accessor PROVIDER-ENDPOINT-URI auth-processuri

Discovered endpoint URI.

3.1.6.8 Accessor RETURN-TO auth-processuri

Authentication 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.

3.1.6.9 Accessor TIMESTAMP auth-processuniversal-time

Universal time of authentication process structure's creation.

3.1.6.10 Accessor XRDS-LOCATION auth-processuri

Address of XRDS file used in auth-process discovery.

3.2 OpenID Provider

3.2.1 Class OPENID-PROVIDER

OpenID 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).

3.2.1.1 Accessor ENDPOINT-URI opuri

OpenID Provider instance's endpoint URI

3.2.2 Constant +INDIRECT-RESPONSE-CODE+

HTTP code recommented to use for indirect responses sent via HTTP redirect.

3.2.3 Function HANDLE-OPENID-PROVIDER-REQUEST op message &key allow-unencrypted-association-presponse values

Handle 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.

allow-unencrypted-association-p specifies whether it is allowable to use unencrypted association method. Set it to NIL unless your OP endopoint uses HTTPS. See OpenID Authentication 2.0 - Final, section 8.4.1. No-Encryption Association Sessions (http://openid.net/specs/openid-authentication-2\_0.html#assoc\_sess\_types).

Returns two values: first is body, and second is HTTP code.

On HTTP redirections (the second value between 300 and 399 inclusive), the primary returned value will be an URI to redirect the user to.

3.2.4 Function CANCEL-RESPONSE-URI op messageuri

Returns the URI of the Relying Party to redirect the user's browser to. The URI parameters tell the Relying Party that the authentication failed. auth-request-message should be the oritinal OpenID authentication request message that was received from the Relying Party previously and passed to the HANDLE-CHECKID-SETUP.

3.2.5 Function SUCCESSFUL-RESPONSE-URI op auth-request-messageuri

Returns the URI of the Relying Party to redirect the user's browser to. The URI parameters tell the Relying Party that the authentication was successful. auth-request-message should be the oritinal OpenID authentication request message that was received from the Relying Party previously and passed to the HANDLE-CHECKID-SETUP.

3.2.6 Generic HANDLE-CHECKID-IMMEDIATE op messagegeneralized-boolean

Handle 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.

3.2.7 Generic HANDLE-CHECKID-SETUP op messageresponse values

Handles 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 by redirecting the user's browser either to SUCCESSFUL-RESPONSE-URI, or to CANCEL-RESPONSE-URI.

This generic is called by HANDLE-OPENID-PROVIDER-REQUEST, and the values returned by this function are then returned by HANDLE-OPENID-PROVIDER-REQUEST. I.e. it must return two values: response \"body\" and HTTP status code. That way HANDLE-CHECKID-SETUP can either redirect user's browser somewhere, or just show him something. (With hunchentoot, HUNCHNTOOT:REDIRECT may also be used, which is a non-local transfer control).

Default method just returns (VALUES (CANSEL-RESPONSE-URI …) +INDIRECT-RESPONSE-CODE+).

3.2.8 Protocol messages

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.

3.2.8.1 Function MAKE-MESSAGE &rest parametersmessage

Make 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.

3.2.8.2 Function COPY-MESSAGE message &rest parametersmessage

Create 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.

3.2.8.3 Function IN-NS message &optional namespacemessage

Add openid.namespace namespace to message.

Default namespace is OpenID v2. Returns updated message alist.

3.2.8.4 Function MESSAGE-FIELD message field-namevalue

Get value of field-name field from message.

3.2.8.5 Function MESSAGE-V2-P messageboolean

True if message is an OpenID v2 message (namespace check).

3.2.8.6 Function AUTH-REQUEST-REALM auth-request-messagestring

Returns the realm of the OpenID authentication request auth-request-message.

Author: Maciej Pasternacki

Date: 2011-09-04 03:41:16

HTML generated by org-mode 6.36c in emacs 23