.TH "Eliom_openid" 3o 2014-07-10 OCamldoc ""
.SH NAME
Eliom_openid \- OpenID identification
.SH Module
Module   Eliom_openid
.SH Documentation
.sp
Module
.BI "Eliom_openid"
 : 
.B sig  end

.sp
OpenID identification
.sp

.sp

.sp
.sp

.PP

.B === This module implements the Relying Party of the OpenID specification,
.B     in stateful mode\&. ===

.PP

.PP

.B === 
.B Library description
.B  ===

.PP

.PP

.B === The library provides means to authenticate an user
.B     to a remote provider using the OpenID protocol\&.
.B     Basically, you need to ask the user its OpenID url, and
.B     the fields you want to require (or none, if you just want to
.B     authenticate an user), along with other information\&.
.B 
.B     The library uses an "hidden service" that is needed when the provider
.B     redirects back to your site\&. This service is registered in the library, all you have
.B     to do is to give a path for that service and a default handler
.B     (if the user connects to that service without being in an authentication process\&.)
.B     Here is a short example of how to use the library
.B     
.B open Eliom_openid
.B let messages = Eliom_state\&.create_volatile_table ()
.B (* The login form *)
.B let login_form = Eliom_service\&.new_service
.B   ~path:["login\-form"]
.B   ~get_params: Eliom_parameter\&.unit
.B   ()
.B 
.B (* Initialize the library, and getting the authenticate function *)
.B let authenticate = Eliom_openid\&.init ~path:["__openid_return_service"]
.B     ~f: (fun _ _ \-> Eliom_registration\&.Redirection\&.send login_form)
.B 
.B (* Create the handler for the form *)
.B (* We have to use Eliom_registration\&.String_redirection as we
.B    redirect the user to her provider *)
.B let form_handler = Eliom_registration\&.String_redirection\&.register_new_post_coservice
.B     ~fallback: login_form
.B     ~post_params: (Eliom_parameter\&.string "url")
.B     (fun _ url \->
.B        authenticate
.B     ~max_auth_age: 4 (* Requires that if the user logged in more that 4 seconds ago
.B                         he needs to relog in *)
.B     ~required: [Eliom_openid\&.Email] (* Requires his e\-mail *)
.B     ~immediate: false
.B    url
.B    (fun result \->
.B      let string =
.B        match result with
.B          | Setup_needed \-> "setup needed" | Canceled \-> "canceled"
.B          | Result result \->
.B            try List\&.assoc Email result\&.fields with Not_found \-> "No e\-mail :("
.B      in
.B      Eliom_state\&.set_volatile_session_data ~table:messages string;
.B      Eliom_registration\&.Redirection\&.send login_form))
.B 
.B open XHTML
.B let _ = Eliom_registration\&.Xhtml\&.register
.B     ~service: login_form
.B     (fun _ _ \->
.B     (match Eliom_state\&.get_volatile_session_data ~table: messages () with
.B      | Eliom_state\&.Data s \->
.B        Eliom_state\&.discard () >>= fun () \->
.B        Lwt\&.return [p [pcdata ("Authentication result: "^ s)]]
.B      | _ \-> Lwt\&.return []) >>= fun message \->
.B     let form =
.B     Eliom_registration\&.Xhtml\&.post_form ~service:form_handler
.B       (fun url \->
.B         [p [pcdata "Your OpenID identifier: ";
.B             Eliom_registration\&.Xhtml\&.string_input ~input_type:`Text ~name:url ();
.B             Eliom_registration\&.Xhtml\&.string_input ~input_type:`Submit ~value:"Login" ();
.B            ]]) ()
.B     in
.B     Lwt\&.return
.B       (html
.B            (head (title (pcdata "A sample test")) [])
.B            (body
.B               (message @ [form]))))
.B  ===

.PP

.PP

.B === 
.B Documentation
.B  ===

.PP

.PP

.B === 
.B Miscallenous
.B  ===

.PP
.I type openid_error 
=
 | Invalid_XRDS_File
.B of 
.B string * string
.I "  "
(* The provider XRDS file was not valid *)
 | Discovery_Error
.B of 
.B string * string
.I "  "
(* An error occured during the discovery of the provider *)
 | Missing_parameter
.B of 
.B string
.I "  "
(* The remote server forgot a parameter in its request *)
 | Invalid_signature
.B of 
.B string * string
.I "  "
(* We disagree with the server\&'s signature *)
 | Invalid_association
.B of 
.B string
.I "  "
(* We were unable to associate with a provider *)
 | Invalid_argument
.B of 
.B string * string * string
.I "  "
(* The argument provided were not set to a correct value *)
 | Server_error
.B of 
.B string
.I "  "
(* The server threw an explicit error *)
 | Invalid_answer
.B of 
.B string
.I "  "
(* The answer code was not correct *)
 | Invalid_html_doc
.B of 
.B string
 
.sp
Error that may happen when identifiying an user
.sp

.sp

.PP

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

.PP

.I val string_of_openid_error 
: 
.B openid_error -> string
.sp
Prettyprint an OpenID Error
.sp

.sp

.I exception Error 
.B of 
.B openid_error

.sp
Exception thrown by this module\&'s function\&.
.sp

.sp
.I type field 
=
 | Email
 | Fullname
 | DateOfBirth
 | PostCode
 | Timezone
 | Language
 | Country
 | Gender
 | Nickname
 
.sp
A field you can request to the provider
.sp

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

.sp
An extension yielding values of type \&'a
.sp

.sp

.I val sreg 
: 
.B ?policy_url:string ->
.B   required:field list ->
.B   optional:field list ->
.B   unit -> (field * string) list extension
.sp
The SREG extension
.sp
.B "See also"
SREG
.sp

.sp

.I val ax 
: 
.B required:field list ->
.B   optional:field list ->
.B   unit -> (field * string) list extension
.sp
The AX extension
.sp
.B "See also"
AX
.sp

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

.sp
The pape data returned by the server
.sp

.sp

.I val pape 
: 
.B ?max_auth_age:int ->
.B   ?auth_policies:string list ->
.B   unit -> pape extension
.sp
The nist level
.sp

.sp

.I val ( *** ) 
: 
.B 'a extension ->
.B   'b extension -> ('a * 'b) extension
.sp
The PAPE extension\&.
.sp
.B "See also"
PAPE
.sp

.sp

.PP

.B === Product of two extension ===

.PP
.I type 
.B 'a
.I 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
.B of 
.B 'a
 
.sp
The result of an authentication\&.
.sp

.sp

.PP

.B === All went ok\&. ===

.PP

.PP

.B === 
.B Low\-level interface\&.
.B  ===

.PP

.I val perform_discovery 
: 
.B string -> (string * string option) Lwt.t
.sp
Perform discovery on an user\-supplied url
.sp

.sp
.I module type HiddenServiceInfo = 
.B sig  end

.sp
Information about the hidden service
.sp

.sp

.PP

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

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

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

.sp

.PP

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

.PP

.PP

.B === 
.B High\-level interface
.B  ===

.PP

.PP

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

.PP
.I type result 
= {
 fields : 
.B (field * string) list
;  (* The fields you requested *) 
 pape : 
.B pape
;
 }

.sp
The result yielded by the authentication process
.sp

.sp

.PP

.B === The pape information ===

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

.sp
The type of the authenticate function\&.
.sp
\-immediate: whether to use immediate identification or not (default: true)
.sp
\-policy_url: an optional policy url to describe what you do with the data (sreg) (default:none)
.sp
\-required: optional fields you really need (although the provier may not provide them) (default:empty)
.sp
\-optional: optional fields you don\&'t really need (default: empty)
.sp
\-max_auth_age: Requires that the user logged in less than 
.B n
seconds ago\&. (default: up to the provider)
.sp
\-auth_policies: A list of url describing your policies regarding the data (default: empty)
.sp
\-the url the user gave you
.sp
\-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\&.

.sp

.sp

.I val init 
: 
.B path:string list ->
.B   f:((string * string) list ->
.B      unit -> Eliom_registration.browser_content Eliom_registration.kind Lwt.t) ->
.B   check_fun
.sp
Init the OpenID for your site\&.
Takes a path and a handler for the hidden service
.sp

.sp