Module Eliom_openid

module Eliom_openid : sig..end

OpenID identification

This module implements the Relying Party of the OpenID specification, in stateful mode.

Library description ¶

The library provides means to authenticate an user to a remote provider using the OpenID protocol. Basically, you need to ask the user its OpenID url, and the fields you want to require (or none, if you just want to authenticate an user), along with other information.

The library uses an "hidden service" that is needed when the provider redirects back to your site. This service is registered in the library, all you have to do is to give a path for that service and a default handler (if the user connects to that service without being in an authentication process.) Here is a short example of how to use the library

open Eliom_openid
let messages = Eliom_state.create_volatile_table ()
(* The login form *)
let login_form = Eliom_service.new_service
  ~path:["login-form"]
  ~get_params: Eliom_parameter.unit
  ()

(* Initialize the library, and getting the authenticate function *)
let authenticate = Eliom_openid.init ~path:["__openid_return_service"]
    ~f: (fun _ _ -> Eliom_registration.Redirection.send login_form)

(* Create the handler for the form *)
(* We have to use Eliom_registration.String_redirection as we
   redirect the user to her provider *)
let form_handler = Eliom_registration.String_redirection.register_new_post_coservice
    ~fallback: login_form
    ~post_params: (Eliom_parameter.string "url")
    (fun _ url ->
       authenticate
    ~max_auth_age: 4 (* Requires that if the user logged in more that 4 seconds ago
                        he needs to relog in *)
    ~required: [Eliom_openid.Email] (* Requires his e-mail *)
    ~immediate: false
   url
   (fun result ->
     let string =
       match result with
         | Setup_needed -> "setup needed" | Canceled -> "canceled"
         | Result result ->
           try List.assoc Email result.fields with Not_found -> "No e-mail :("
     in
     Eliom_state.set_volatile_session_data ~table:messages string;
     Eliom_registration.Redirection.send login_form))

open XHTML
let _ = Eliom_registration.Xhtml.register
    ~service: login_form
    (fun _ _ ->
    (match Eliom_state.get_volatile_session_data ~table: messages () with
     | Eliom_state.Data s ->
       Eliom_state.discard () >>= fun () ->
       Lwt.return [p [pcdata ("Authentication result: "^ s)]]
     | _ -> Lwt.return []) >>= fun message ->
    let form =
    Eliom_registration.Xhtml.post_form ~service:form_handler
      (fun url ->
        [p [pcdata "Your OpenID identifier: ";
            Eliom_registration.Xhtml.string_input ~input_type:`Text ~name:url ();
            Eliom_registration.Xhtml.string_input ~input_type:`Submit ~value:"Login" ();
           ]]) ()
    in
    Lwt.return
      (html
           (head (title (pcdata "A sample test")) [])
           (body
              (message @ [form]))))

Documentation ¶

Miscallenous ¶

type openid_error =  | Invalid_XRDS_File of string * string(* <<div class="odocwiki_info"|~The provider ~X~R~D~S file was not valid
>> *) | Discovery_Error of string * string(* <<div class="odocwiki_info"|~An error occured during the discovery of the provider
>> *) | Missing_parameter of string(* <<div class="odocwiki_info"|~The remote server forgot a parameter in its request
>> *) | Invalid_signature of string * string(* <<div class="odocwiki_info"|~We disagree with the server~'s signature
>> *) | Invalid_association of string(* <<div class="odocwiki_info"|~We were unable to associate with a provider
>> *) | Invalid_argument of string * string * string(* <<div class="odocwiki_info"|~The argument provided were not set to a correct value
>> *) | Server_error of string(* <<div class="odocwiki_info"|~The server threw an explicit error
>> *) | Invalid_answer of string(* <<div class="odocwiki_info"|~The answer code was not correct
>> *) | Invalid_html_doc of string

An error occured during the parsing of an user url in html format

val string_of_openid_error : openid_error -> string

exception Error of openid_error

type field =  | Email | Fullname | DateOfBirth | PostCode | Timezone | Language | Country | Gender | Nickname

type 'a extension = {
  headers: (string * string) list;  parse: (string * string) list -> 'a Lwt.t;}

val sreg : 
  ?policy_url:string ->
  required:field list ->
  optional:field list ->
  unit -> (field * string) list extension

val ax : 
  required:field list ->
  optional:field list ->
  unit -> (field * string) list extension

type pape = {
  auth_time: string option;(* <<div class="odocwiki_info"|~The time at which the user last logged in
>> *)  policies: string list option;(* <<div class="odocwiki_info"|~A list of policies ~(url~) describing your usage of the data
>> *)  nist_level: int option;}

val pape : 
  ?max_auth_age:int ->
  ?auth_policies:string list ->
  unit -> pape extension

val ( *** ) : 
  'a extension ->
  'b extension -> ('a * 'b) extension

Product of two extension

type 'a authentication_result =  | Canceled(* <<div class="odocwiki_info"|~The user canceled the login ~(or failed~)
>> *) | Setup_needed(* <<div class="odocwiki_info"|~The provider has not enough information to complete an immediate
                     request~. ~Only returned when using an immediate authentication~.
>> *) | Result of 'a

All went ok.

Low-level interface. ¶

val perform_discovery : string -> (string * string option) Lwt.t

module type HiddenServiceInfo = sig..end

The function called when an user connects to the hidden service (not that hidden) without being in an identication process. Typically you should redirect the user to the login page.

module Make : functor (S : HiddenServiceInfo) -> 
  sig..end

Authenticate an user.

• mode: can be checkid_setup or checkid_immediate whether you want immediate identification or not.
• ext: the extensions you want to use.
• handler: the handler called with the result of the authentication.
• discovery: The discovery information In return you get an URI you have to redirect the user to.

High-level interface ¶

The high-level interface takes care of creating the extension you want, without to use them directly. It yields a result.

type result = {
  fields: (field * string) list;(* <<div class="odocwiki_info"|~The fields you requested
>> *)  pape: pape;}

The pape information

type check_fun = 
  ?immediate:bool ->
  ?policy_url:string ->
  ?max_auth_age:int ->
  ?auth_policies:string list ->
  ?required:field list ->
  ?optional:field list ->
  string ->
  (result authentication_result ->
   Eliom_registration.browser_content Eliom_registration.kind Lwt.t) ->
  Eliom_lib.Url.t Lwt.t

val init : 
  path:string list ->
  f:((string * string) list ->
     unit ->
     Eliom_registration.browser_content Eliom_registration.kind Lwt.t) ->
  check_fun