---
name: "Eliom_openid.server"
section: "3o"
platform: "linux"
package: "libeliom-ocaml-doc"
version: "4.0.0-2"
release: "Debian 8 (Jessie)"
platforms: ["linux"]
url: "https://new.carta.tech/Eliom_openid.server"
---

# Eliom\_openid.server(3o)

OpenID identification

## NAME

Eliom\_openid - OpenID identification

## Module

Module   Eliom\_openid

## Documentation

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 extension**

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.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) (default:none)

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

\-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.kind Lwt.t) -\>** **check\_fun**

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