Provided by: libeliom-ocaml-doc_3.0.3-4build2_all bug


       Eliom_openid - OpenID identification


       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  (* The provider XRDS file was not valid *)
        |  Discovery_Error  of  string  * string  (* An error occured during the discovery of the
       provider *)
        | Missing_parameter of string  (* The remote server forgot a parameter in its request *)
        | Invalid_signature of string * string  (* We disagree with the server's signature *)
        | Invalid_association of string  (* We were unable to associate with a provider *)
        | Invalid_argument of string * string * string  (* The argument provided were not set  to
       a correct value *)
        | Server_error of string  (* The server threw an explicit error *)
        | Invalid_answer of string  (* The answer code was not correct *)
        | Invalid_html_doc of string

       Error that may happen when identifiying an user

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

       val string_of_openid_error : openid_error -> string

       Prettyprint an OpenID Error

       exception Error of openid_error

       Exception thrown by this module's function.

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

       A field you can request to the provider

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

       An extension yielding values of type 'a

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

       The SREG extension

       See also SREG

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

       The AX extension

       See also AX

       type pape = {
        auth_time : string option ;  (* The time at which the user last logged in *)
        policies : string list option ;  (* A list of policies (url) describing your usage of the
       data *)
        nist_level : int option ;

       The pape data returned by the server

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

       The nist level

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

       The PAPE extension.

       See also PAPE

       === Product of two extension ===

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

       The result of an authentication.

       === All went ok. ===

       === Low-level interface.  ===

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

       Perform discovery on an user-supplied url

       module type HiddenServiceInfo = sig end

       Information about the hidden service

       ===  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

       This functor build a hidden service that will be used to receive the remote server's data.
       In return you get a check function

       === 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 ;  (* The fields you requested *)
        pape : pape ;

       The result yielded by the authentication process

       === 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.http_service) Eliom_registration.kind Lwt.t) -> Eliom_lib.Url.t Lwt.t

       The type of the authenticate function.

       -immediate: whether to use immediate identification or not (default: true)

       -policy_url:  an  optional  policy  url  to  describe  what  you  do  with the data (sreg)

       -required: optional fields you really need (although the provier  may  not  provide  them)

       -optional: optional fields you don't really need (default: empty)

       -max_auth_age:  Requires  that the user logged in less than n seconds ago. (default: up to
       the provider)

       -auth_policies: A list of url describing your policies regarding the data (default: empty)

       -the url the user gave you

       -an handler, that'll be called after checking the  parameters  with  the  result  and  the
       server  params  of  the  GET  request.  You can send whatever page you want but you should
       redirect the user to a page so he can't bookmark  it,  or  send  some  piece  of  html  to
       interface with javascript.

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

       Init the OpenID for your site.  Takes a path and a handler for the hidden service