[cl-openid-devel] provider API (was: cl-openid: API design, code finalization and nearest future plans)

[Anton Vodonosov]

on Wednesday, July 30, 2008, 2:03:04 PM Maciek wrote:

>> For the provider we offer protocol primitives to the library user:
>>
>>     (create-asssociation provider parameters ssl-p)
>>     (check-authentication provider parameters)
>>     (error-response ...)
>>     All these return a string to be used as a response to 
>>     direct HTTP request.
>>
>>     (positive-assertion-uri provider setup-parameters)
>>     (negative-assertion-uri provider setup-parameters)
>>     Both return URL to redirect user's browser to.
>>
>> The PROVIDER parameter here is an object encapsulating all the current
>> provider-related globals.

> So, INDIRECT-RESPONSE would go to an example, INDIRECT-RESPONSE-URI,
> ERROR-RESPONSE and DIRECT-RESPONSE will be exit points, and entry
> points will be registered callbacks.  I have to decide whether they’d
> be slots containing functions, or specialized methods.

> I’m not sure whether to expose CREATE-ASSOCIATION.  I’d rather lean to
> exposing association preferences via provider object.

>> Library user is responsible for creation of web server handler for the
>> OP endpoint URI, based on example we provide (current handle-openid-provider-request
>> function). This handler will dispatch to a necessary protocol
>> primitive based on the "openid.mode" HTTP request parameter. 
>> User handles "checkid_immediate" and "checkid_setup" as he wants.
>>
>> Note, this design, in particular, eliminates server portability
>> question.

> This is great idea, something I’ve started to consider lately after
> looking at python-openid, but it didn’t take enough shape to be posted
> yet.  Let’s go for it.

What I mean, the user must create something like following code,
based on the pattern we will provide in the example:

(define-easy-handler (opendid-provider-endpoint
                      "/openid-provider-endpoint")
    ((mode :real-name "openid.mode")
     (id :real-name "openid.identity"))
  (let ((params (append (hunchentoot:post-parameters)
                        (hunchentoot:get-parameters))))
    (cond ((string= mode "associate")
           (cl-openid:create-association *provider* 
                                         params 
                                         hunchentoot:ssl-p))
          ((string= mode "checkid_immediate")
           ;; here user's code cames, for example:
           (if (and (string= (session-value 'cur-user)
                             id)
                    ;; BTW, it looks like we completelly 
                    ;; missed return_to verification 
                    ;; based on realm; see 9.2.1
                    ;; we must provide some function(s) for this
                    (cl-open-id:realm-is-good ...)) 
               (hunchentoot:redirect (positive-assertion-uri *provider* 
                                                             params))
               (hunchentoot:redirect (negative-assertion-uri *provider* 
                                                             params)))
          ((string= mode "checkid_setup")
             ;; here user's defined code too
             ... )
          ((string= mode "check_authentication")
           (check-authentication *provider* params))
          (t (error-response (format nil 
                                     "Unknown openid.mode ~S" 
                                     mode))))))

I.e. no callbacks, user does not plug into our code, but wraps our
code into his handler. I suspect this would be simpler for him.
He must dispatch all the modes to predefined functions, except
for "checkid_setup" and "checkid_immediate" that he handles
himself.

While writing this code sketch, I realized that not all the details
are clear, e.g. glaring oversight is the return-to verification based
on realm.

More tomorrow, it is late now. We need to think out the details
carefully.

Best regards,
-Anton