Aller au contenu principal

Certificat Client

Okapi permet d'utiliser des certificats pour sécuriser les échanges entre Okapi et les requêtes clientes ou/et pour sécuriser les échanges entre l'API distante et Okapi. Nous distinguons deux types de certificats :

  • Les certificats entre Okapi et les API distantes nommé certificat d'API. Ils sont déclarés dans la configuration de l'API via le champ agentOptions.
  • Les certificats entre Okapi et les requêtes clientes nommé certificat x509. Ils sont déclarés dans la configuration de l'API via le champ x509.

Sécurisation entre Okapi et l’API distante par certificat (Certificat d’API)​

L'authentification par certificat API, lorsqu'elle est activée, permet à l'API de vérifier que l'origine de la requête est bien Okapi.

Le certificat sera généré par Okapi et envoyé à l'API distante en utilisant les informations prédéfinit dans la configuration de l'API via le champ agentOptions.

Cas d'un cas d'authentification par certificat API OK​

Cas OK

Cas d'un cas d'authentification par certificat API KO​

Cas KO

Cas d'usage​

Cette fonctionnalité est opérationnelle en production avec les API suivantes :

  • API Lin Scan v1

Principe de fonctionnement​

L'API déclare dans son raccordement les éléments de configuration du certificat sous le namespace agentOptions dans les données optionnelles (extra).

Ce champ agentOptions porte les clés suivantes :

  • cert (string) : Clé publique, avec la chaine complète de certification, au format PEM.

  • key (string) : Clé privée au format PEM.

Configuration dans le raccordement de l'API​

api:
    name: My API
    urlContext: myapi
    version: "1"
    ...
    extra: 
      agentOptions:
        cert: |-
          -----BEGIN CERTIFICATE-----
          <Clé publique>
          -----END CERTIFICATE-----
           -----BEGIN CERTIFICATE-----
          <cert intermediaire 1>
          -----END CERTIFICATE-----
          -----BEGIN CERTIFICATE-----
          <cert intermediaire 2>
          -----END CERTIFICATE-----
          -----BEGIN CERTIFICATE-----
          <Certificat Racine>
          -----END CERTIFICATE-----
        key: |- 
          -----BEGIN RSA PRIVATE KEY-----
          <Clé privée>
          -----END RSA PRIVATE KEY-----

Manipulation des certificats​

La clé privée est chiffrée​

Si la clé privée est chiffrée (contient Encrypted sous le BEGIN PRIVATE KEY), alors il vous faut utiliser la commande OpenSSL suivante:

openssl rsa -in <private_key.pem> -out private.pem
# Après avoir saisi le mot de passe, vous aurez la clé privée déchiffrée dans le fichier private.pem.
# Elle peut être copier/collée telle quelle dans le fichier de configuration Okapi dans l'attribut `key`

Des soucis ?​

RequestError: error:1E08010C:DECODER routines::unsupported​

Cela peut provenir d'une erreur de format sur la clé privée (key). Il faut s'assurer que la clé est bien une clé RSA, non chiffrée au bon format: PKCS#1

RequestError: error:05800074:x509 certificate routines::key values mismatch​

Le certificat public doit être le premier de la liste, suivi des certificats intermédiaires et racine.

Sécurisation par certificat x.509 entre le Client et Okapi (Certificat X.509)​

Le certificat X.509 est une norme spécifiant les formats pour les certificats à clé publique, les listes de révocation de certificat, les attributs de certificat, et un algorithme de validation du chemin de certification, définie par l'Union internationale des télécommunications (UIT).

X.509 établit un format standard de certificat électronique et un algorithme pour la validation de chemin de certification.

Nous utilisons cette fonctionnalité pour sécuriser les appels entre les requêtes clientes et Okapi.

Cas d'un cas d'authentification par certificat X.509 client OK​

Cas OK

Cas d'un cas d'authentification par certificat X.509 client KO​

Cas KO

Cas d'usage X.509​

Cette fonctionnalité est opérationnelle en production avec les API suivantes :

  • API order-consignment Phoenix v1

Principe de fonctionnement X.509​

L'API déclare dans son raccordement un tableau de certificat sous le namespace x509 dans les données optionnelles (extra).

Chaque élément du tableau x509 est un certificat x509 au format PEM.

L'ancien format où le certificat x509 était mis à plat est déprécié et ne doit plus être utilisé.

Configuration dans le raccordement de l'API X.509​

api:
    name: My API
    urlContext: myapi
    version: "1"
    ...
    extra: 
      x509:
        - |
          -----BEGIN CERTIFICATE-----
          Certificat Client 1
          -----END CERTIFICATE-----
        - |
          -----BEGIN CERTIFICATE-----
          Certificat Client 2
          -----END CERTIFICATE-----
        ...
        - |
          -----BEGIN CERTIFICATE-----
          Certificat Client n
          -----END CERTIFICATE-----

Les autorités connues par Okapi​

Voici la liste des autorités authorisées pour le certificat client :

  • C = FR, O = Certinomis, OU = 0002 433998903, CN = Certinomis - Root CA
  • C = FR, O = LA POSTE, OU = 0002 356000000, OU = Branche Services-Courrier-Colis, CN = AC racine La Poste BSCC
  • C = FR, O = Certinomis, organizationIdentifier = NTRFR-433998903, CN = Certinomis - Root CA G4
  • CN = AC_Racine_Production_SHA2, OU = DISFE, O = La Poste, C = FR
  • CN = AC_Racine_Hors_Production_SHA2, OU = DISFE, O = La Poste, C = FR
developer.laposte.frNous contacter