.. _integration_certificats_SIA_Personae: 

Intégration d'une application externe dans Vitam
################################################

Prérequis
=========

L'application externe devra être en mesure de requêter les composants :term:`VITAM` ``ingest-external`` et ``access-external`` sur leurs ports de service respectifs par le protocole HTTPS.

Il faut donc prévoir une ouverture de flux réseau pour le protocole TCP (selon l'infrastructure en place) sur les ports de service des composants :term:`VITAM` ``ingest-external`` et ``access-external``. 

La sécurisation des connexions HTTP avec les applications externes est déléguée aux composants :term:`VITAM` ``ingest-external`` et ``access-external`` (ou bien éventuellement à un reverse-proxy, selon l'infrastructure de déploiement :term:`VITAM` retenue). 

La création d'un certificat TLS client pour l'application externe est requise afin de permettre l'habilitation et l'authentification applicative des requêtes émises depuis l'application externe vers les composants :term:`VITAM` ingest-external et access-external. 

Intégration de certificats clients de VITAM
===========================================

.. note:: Cette section décrit l'ajout de certificats :term:`SIA` ou personnels (*Personae*) dans le cadre des procédures d'exploitation de la solution logicielle :term:`VITAM`. L'intégration de certificats clients de :term:`VITAM` au déploiement est décrite dans le document d'installation (:term:`DIN`). 

Authentification applicative :term:`SIA`
-----------------------------------------

Le certificat client de l'application externe doit être ajouté dans la base de données du composant ``security-internal``, afin de permettre la gestion des habilitations et l'authentification applicative de l'application externe. 

L'exemple suivant permet d'ajouter un certificat présent sous ``/path/to/certificate`` et associé au contexte applicatif portant l'identifiant ``contexte_identifier``.

Ajout d'un certificat pour l'authentification applicative :term:`SIA`
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. code-block:: bash

    curl -XPOST -H "Content-Type:application/json" 'http://<ip admin security-internal>:<port admin security-internal>/v1/api/identity' -d "
    {  
        \"contextId\":\"contexte_identifier\",
        \"certificate\":\"$(base64 /path/to/certificate)\" 
    }"

.. note:: Se repporter à la documentation sur la gestion des habilitations pour ce qui concerne l'ajout de contextes applicatifs. 

.. Warning:: Lorsque l'authentification du client, par le protocole TLS, est réalisée, la :term:`CA` du certificat client doit être déployée dans le *truststore* des composants :term:`VITAM` ``ingest-external`` et ``access-external``. Dans ce cas de figure, suivre la procédure de la section :ref:`CertifAnchor`, en ayant pris soin au préalable de déposer les certificats de la chaîne de certification client dans le répertoire `environments/certs/client-external/ca`. Si le certificat client est passé dans le *header* http (cas de l'authentification applicative par *header* http X-SSL-CLIENT-CERT), le certificat client n'est alors pas utilisé dans la négociation TLS et il n'est donc pas nécéssaire d'inclure la :term:`CA` associée dans le *truststore* des composants :term:`VITAM` ``ingest-external`` et ``access-external``. 


Authentification *Personae*
---------------------------

Le certificat personnel (*Personae*) doit être ajouté dans la base de données du composant ``security-internal``, afin de permettre l'authentification renforcée de l'utilisateur. 

Les exemples suivants permettent d'ajouter ou supprimer un certificat présent sous ``/path/to/certificate``.

Ajout d'un certificat pour l'authentification *Personae*
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. code-block:: bash

   curl -XPOST -H "Content-type: application/octet-stream" --data-binary @/path/to/certificate 'http://<ip admin security-internal>:<port admin security-internal>/v1/api/personalCertificate'


Suppression d'un certificat pour l'authentification *Personae*
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. code-block:: bash

   curl -XDELETE -H "Content-type: application/octet-stream" --data-binary @/path/to/certificate 'http://<ip admin security-internal>:<port admin security-internal>/v1/api/personalCertificate'

Révocation de certificats clients de VITAM
===========================================

La release « R8 » introduit une nouvelle fonctionnalité permettant la révocation des certificats :term:`SIA` et *Personae* afin d’empecher des accès non autorisés aux :term:`API` de la solution logicielle :term:`VITAM` (vérification dans la couche https des :term:`CRL`). 

Le fonctionnement de la validation des certifcats de la solution logicielle :term:`VITAM` :term:`SIA` et `Personae` par :term:`CRL` est le suivant : 

* L'administrateur transmet à la solution logicielle :term:`VITAM` le :term:`CRL` d'un :term:`CA` qui a émis le certificat présent dans la solution logicielle :term:`VITAM`, via le point d'API suivant ::

    http://{{ hosts_security_internal }}:{{vitam.security_internal.port_admin}}/v1/api/crl

.. caution:: La CRL fournie doit être obligatoirement au format DER (cf. http://www.ietf.org/rfc/rfc3280.txt">RFC 3280: *Internet X.509 Public Key Infrastructure Certificate and CRL Profile*) 

Exemple::

    curl -v -X POST -u {{ admin_basic_auth_user }}:{{ admin_basic_auth_password }}  http://{{ hosts_security_internal }}:{{vitam.security_internal.port_admin}}/v1/api/crl -H 'Content-Type: application/octet-stream' --data-binary @/path/to/crl/my.crl

Le paramètre ``adminUser`` correspond à la valeur ``admin_basic_auth_user`` déclarée dans le fichier ``vitam_security.yml``

Le paramètre ``adminPassword`` correspond à la valeur ``admin_basic_auth_password`` déclarée dans le fichier ``vault-vitam.yml``

* Le système va contrôler tous les certificats (collections ``identity.Certificate`` et ``identity.PersonalCertificate``) émis par le `IssuerDN` correspondant à la :term:`CRL`, en vérifiant si ces derniers sont révoqués ou non. Si c'est le cas, alors la solution logicielle :term:`VITAM` positionne le statut du certificat révoqué à **REVOKED**. Cela a pour conséquence le rejet de tout accès aux :term:`API` :term:`VITAM` avec utilisation du certificat révoqué (les filtres de sécurité émettront des exceptions dans les journaux de `log`). 

* Une alerte de sécurité est émise dans les journaux en cas de révocation. 

Déploiement des keystores
=========================

Vitam n'est pas encore déployé
------------------------------

Déployer Vitam en suivant la procédure indiquée dans le :term:`DIN`.

Vitam est déjà déployé
----------------------

Suivre la procédure de la section :ref:`CertifAnchor`.
