Mise en place HMAC

L'objectif de la fonctionnalité HMAC de l'API gateway Okapi est de permettre une bonne sécurisation du lien entre la plateforme Okapi (client) et le backend d'une API (serveur), sans les inconvénients des certificats X.509, et avec une empreinte relativement neutre.

Cas d'usage

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

• Code de la route
• SSU (suivi unifié v2)

Principe de fonctionnement

L'API déclare dans son raccordement les éléments de configuration de l'algoritme HMAC d'Okapi, sous le namespace hmac dans les données optionnelles (extra).

La simple présence d'un objet JSON sous hmac activera la fonctionnalité au niveau de l'API gateway.

La signature HMAC apparaît dans la requête initiée par Okapi à destination de l'API, sous la forme d'un entête d'autorisation authorization {serviceLabel} {clientId}:{code}, avec :

• {serviceLabel} : le nom du service tel que configuré dans l'API
• {clientId} : le clientId configuré dans l'API
• {code} : une chaîne de caractère représentant la valeur du code HMAC (voir ci après)

Cette signature une fois vérifiée par le backend API permet d'établir une zone de confiance et garantir que la requête provient bien de la plateforme Okapi.

Cela peut permettre à l'API de discriminer simplement les appels pour ne pas traiter ceux qui proviendrait d'une source non reconnue (noeud internet), et authentifier l'"origine Okapi" afin de pouvoir jouir des autres méta données fournies.

Remarques :

• le clientId n'a de valeur que pour le fournisseur d'API, le but étant de lui permettre d'identifier correctement la requête et la discriminer ; peu importe sa valeur elle doit juste permettre au fournisseur de qualifier l'origine de l'appel.
• le nom de l'entête qui sera soumis dans la requête envoyée par Okapi à l'API peut être customisé, utile en cas de collision avec une autre autorisation, par exemple OAuth2 ; pour cela il suffit de préciser le nom de l'entête voulu (par exemple : 'x-hmac') dans le raccordement de l'API via l'attribut optionnel headerName (toujours sous extra.hmac).

Valeur HMAC

La valeur du code HMAC utilisé dans l'autorisation HMAC est du type {method}\n{url}, avec :

• {method} : méthode HTTP utilisée pour consommer le endpoint du backend API (en majuscules)
• {url} : URL du endoint API, incluant les paramètres de requêtes (querystring)

Elle fait l'objet d'un algoritme de génération standard HMAC, qui s'appuie sur les paramètres suivants (cf. crypto.createHmac) :

• secret : code secret à utiliser pour hasher les données
• algorithm : par défaut sha256
• encoding : par défaut base64

Exemple

Avec les données fournies suivantes :

• serviceLabel : ETG
• clientId : YWY0Yjk0NzgtZGE0MC00ZTQxLTk2ODUt
• secret : r3EBG83d1V8F8SC7735N3sI3MaoyqT6N

L'autorisation générée sera :

Authorization ETG YWY0Yjk0NzgtZGE0MC00ZTQxLTk2ODUt:V3lZSnlWb3JUMkM2eURibEMyendpbndmVzZYK1FkTCsvOGR1M2h4cVp5Zz0=

Options de configuration

• sandboxHmac: utilisé en complément de hmac afin de fournir une configuration alternative pour le endpoint de sandbox, respectant le même format
• includeQuerystring (booléen) : inclure ou pas les paramètres de requête (querystring) dans la construction du HMAC (activé par défaut)
• secret
• algorithm
• encoding

Configuration dans le raccordement de l'API

- type: api
  value:
    name: My Api
    urlContext: monapi
    version: '1'
    ...
    extra:
      hmac:
        serviceLabel: Secured
        clientId: '?'
        secret: '?'
        includeQuerystring: true
      sandboxHmac:
        serviceLabel: Another Secured
        clientId: '?'
        secret: '?'

Intégration de la feature HMAC en PHP {#intégration-de-la-feature-hmac-en-php}

Afin de contrer la divergence dans la génération du hmac, la solution Okapi supporte la 'bufferisation' du code HMAC. Cela entraine un double encodage du code HMAC.

Snippet de code à intégrer {#snippet-de-code-à-intégrer}

$dataCode="string"; // {method}\n{uri}
$clientSecret= "Secret Key";
$hexHash=base64_encode(hash_hmac('sha256', $dataCode, $clientSecret));
$base64Hash = base64_encode($hexHash);