ldapsaisie/doc/conf/LSauthMethod/LSauthMethod_HTTP.docbook
Benjamin Renard 0ec390e1fe Add API feature
Some major changes have been made to handle this new feature :
- LSsession now have a flag about API mode. The displayTemplate() and
  displayAjaxReturn() methods have been adjust to correctly handle this
  mode.
- LSauth system have been adjust to handle a custom API mode :
  - LSauthMethod can support or not this mode : the $api_mode_supported
    permit to defined if supported (default, false). Currently, only
    HTTP (default in API mode) and annonymous mode support it.
  - An api_access parameter permit to configure witch type of user
    LSobject types could use the API. This flag must be set to True to
    allow a type of LSobject (default: False). In a same way, a
    web_access parameter now permit to disable Web access for some
    types of users (but this parameter is optional and its default value
    is True).
  - The HTTP method is the privileged first method for API mode. In this
    mode, if auth data aren't present in environment, it will request it
    by triggered a 403 HTTP error. Realm can be configured with new
    LSAUTHMETHOD_HTTP_API_REALM constant.
- The LStemplate system handle API mode to correctly react on errors: it
  return a JSON answer instead of HTML page. Error pages also now return
  adjusted HTTP code (404 or 500).
- The LSurl system have been adjust to handle API mode :
  - On declaring handlers, we could now specify if it's an API view with
    new $api_mode paremeter of add_handler() method
  - The LSurlRequest object have a new attribute to check if it's an API
    request
  - The error_404() method handle the API mode to return JSON answer.
    Furthermore, if no handlers matched with the requested URL, API mode
    is automatically enabled if the requested URL starts with 'api/'.
- LSform implement it own API mode flag and a new submited flag that
  be toggle via the new setSubmited() method. Some major changes also
  occured on LSformElement classes to specifically handle API
  input/output for each types of attributes:
  - a new getApiValue() method permit to retrieve the API value of the
    attribute (on show API view)
  - the getPostData() method now have to correctly handle API input for
    the attribute (on create/modify API views). A programmatic way have
    been adopted for each types of attributes.
- The LSimport and LScli create/modify commands also evolved to enable
  API mode of the LSform. This permit to take advantage of the new
  capability of LSform/LSformElement to handle input values with a
  programmatic way.
- New routes have been add to handle API views. All this new routes
  start with 'api/1.0/' and use the same URL schema as the web UI. The
  API currently permit to search/show/add/modify/remove LSobjects and
  manages their relations.
2021-02-03 14:40:28 +01:00

134 lines
5.4 KiB
Text

<sect2 id="config-LSauthMethod_HTTP">
<title>LSauthMethod_HTTP</title>
<para>Cette &LSauthMethod; est utilisée pour gérer l'authentification
via les variables d'environnements définies suite à une authentification,
potentiellement déléguée au serveur web.</para>
<para>Cette méthode récupère dans l'environment d'exécution PHP, le nom
d'utilisateur et le mot de passe de l'utilisateur connecté. À partir du
nom d'utilisateur, une recherche dans l'annuaire sera effectuée pour
trouver l'utilisateur correspondant. L'authentification sera réussie
uniquement si un et un seul utilisateur est retourné par la recherche et
si une authentification auprès de l'annuaire LDAP réussie à l'aide du DN
de l'objet LDAP trouvé et du mot de passe fourni.</para>
<note><simpara>En cas d'authentification déléguée au serveur web, il est
possible de désactiver la vérification du mot de passe via le paramètre
<literal>LSAUTHMETHOD_HTTP_TRUST_WITHOUT_PASSWORD_CHALLENGE</literal>
(voir ci-dessous).</simpara></note>
<para>Les variables d'environnements utilisées pour authentifier l'utilisateur
connecté dépendent de la méthode configurée via la constante <literal>
LSAUTHMETHOD_HTTP_METHOD</literal> (voir ci-dessous). Si ces variables ne sont
pas disponibles, une erreur HTTP 403 sera générée pour réclamer une
authentification à l'utilisateur.</para>
<note><simpara>Cette &LSauthMethod; supporte le mode API et il s'agit de la
méthode utilisée par défaut dans ce mode.</simpara></note>
<para>Cette librairie peut être configurée en éditant le fichier de
configuration
<literal>conf/LSauth/config.LSauthMethod_HTTP.php</literal>.</para>
<programlisting linenumbering="unnumbered">
<citetitle>Structure du fichier</citetitle>/*
*****************************************************
* Configuration of the HTTP authentification support *
*****************************************************
*/
// Don't check HTTP server's login/password by LDAP authentication challenge
//define('LSAUTHMETHOD_HTTP_TRUST_WITHOUT_PASSWORD_CHALLENGE',true);
// Authentication realm (API mode only)
//define('LSAUTHMETHOD_HTTP_API_REALM', ___('LdapSaisie API - Authentication required'));
</programlisting>
<!-- Début Paramètres Configuration -->
<variablelist>
<title>Paramètres de configuration</title>
<varlistentry>
<term>LSAUTHMETHOD_HTTP_TRUST_WITHOUT_PASSWORD_CHALLENGE</term>
<listitem>
<para>Permet de désactiver le test d'authentification auprès de
l'annuaire LDAP. Pour cela, cette constante doit être définie et
valoir <literal>True</literal>.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>LSAUTHMETHOD_HTTP_METHOD</term>
<listitem>
<para>Permet de définir la méthode utilisée par le serveur web pour passer
à PHP l'identifiant de l'utilisateur connecté et son mot de passe.</para>
<para>Cette constance peut pendre les valeurs suivantes :
<variablelist>
<varlistentry>
<term>PHP_PASS</term>
<listitem>
<para>Dans cette méthode, le serveur web défini les variables
d'environnement <literal>PHP_AUTH_USER</literal> et <literal>
PHP_AUTH_PW</literal>. Cette méthode est la méthode par défaut et
convient en cas d'utilisation de <literal>mod_php</literal>.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>REMOTE_USER</term>
<listitem>
<para>Dans cette méthode, le serveur web défini la variable
d'environnement <literal>REMOTE_USER</literal>. Cette variable ne contient
que l'identifiant de l'utilisateur connecté. Cette méthode ne peut donc
être utilisée que conjointement avec l'activation du paramètre
<literal>LSAUTHMETHOD_HTTP_TRUST_WITHOUT_PASSWORD_CHALLENGE</literal>.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>AUTHORIZATION</term>
<listitem>
<para>Dans cette méthode, le serveur web passe le contenu de l'entête
HTTP <literal>Authorization</literal> dans la variable d'environnement
<literal>HTTP_AUTHORIZATION</literal>. Cette méthode convient en cas d'
utilisation de PHP en mode CGI ou encore via PHP-FPM.</para>
<para>Pour utiliser cette méthode, il faudra adapter la configuration du
serveur web. Par exemple, pour Apache HTTPd, vous pouvez utiliser le
module <literal>rewrite</literal> et la règle de réécriture suivante :
<programlisting linenumbering="unnumbered">
<![CDATA[RewriteRule .* - [E=HTTP_AUTHORIZATION:%{HTTP:Authorization}]]]>
</programlisting>
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>LSAUTHMETHOD_HTTP_LOGOUT_REMOTE_URL</term>
<listitem>
<para>URL de déconnexion externe, utile par exemple dans le contexte d'une
connexion via un service SSO. L'utilisateur sera automatiquement redirigé
vers cette URL après sa déconnexion effective au niveau d'LdapSaisie.</para>
<note><simpara>Si cette URL de déconnexion n'est pas défini, le bouton de
déconnexion sera masqué.</simpara></note>
</listitem>
</varlistentry>
<varlistentry>
<term>LSAUTHMETHOD_HTTP_REALM</term>
<listitem>
<para>Domaine d'authentification (<literal>reaml</literal>) utilisé pour
réclamer l'authentification de l'utilisateur (facultatif).</para>
<note><simpara>Pour que le message soit traduit, utilisez la fonction
<literal>___()</literal> (voir exemple).</simpara></note>
</listitem>
</varlistentry>
</variablelist>
</sect2>