Authentification et autorisation


Authentification et autorisation

Ce document décrit la procédure d'accès sécurisé aux APIs de Skalin.

# Sécurité : une priorité

Les APIs de Skalin offrent un moyen puissant de gérer des volumes importants de données potentiellement sensibles (donnée à caractère personnel). C'est la raison pour laquelle la sécurité de ses APIs est une priorité pour Skalin.

La sécurité des APIs repose sur des pratiques à l'état de l'art comme :

  • Le chiffrement des données en transit et au repos
  • La surveillance des flux, un dispositif d'alertes automatisées et une équipe d'astreinte
  • Le filtrage actif des données des requêtes (contre les attaques OWASP TOP 10 (opens new window))
  • La traçabilité des accès
  • La rupture protocolaire
  • La limitation de la quantité de requêtes par seconde (rate-limit)
  • La gestion centralisée des identité et des accès et l'usage de protocoles forts comme OAuth2 ou OIDC
  • Et bien d'autres pratiques...

Les paragraphes suivants détaillent l'implémentation des principes d'authentification, d'autorisation et détail les limitations de la quantité de requêtes par seconde.

# Comment obtenir des clés d'accès

Avant de pouvoir utiliser les APIs, les utilisateurs ou les applications consommatrices doivent obtenir des clés d'accès et comprendre le protocole d'authentification.

Pour créer cette clé, veuillez vous référer à la documentation d'intégration Création d'une clé d'API. Chaque trousseau de clés d'accès contient un client_id et un client_secret qui doivent rester strictement confidentiels.

Il peut être utile de multiplier les trousseaux : chaque trousseau de clés d'accès est associé à une application précise. En cas de compromission des secrets d'une application, il est simple de réaliser une rotation de ce secret localement plutôt que devoir changer la configuration de l'ensembles des applications qui consomment les APIs. Cela permet également de limiter l'impact d'une compromission grâce au cloisonnement.

Chaque trousseau de clés d'accès est lié à un propriétaire responsable de la distribution des secrets auprès des développeurs habilités. Le propriétaire est également en charge de la protection des secrets (empêcher leur fuite, demander une rotation de secret, demander l'invalidation d'une clé, etc.). Par défaut, et sans demande explicite auprès du support, c'est le demandeur du trousseau qui est associé au rôle de propriétaire.

Les autorisations associées à un trousseau de clés d'accès peuvent être restreintes à certaines ressources ou périmètres des APIs. Par défaut, les autorisations associées à un trousseau héritent des même habilitations que celles attribuées au propriétaire du trousseau. Pour toute demande de restriction des permissions, une demande devra être faite au support.

# Comment envoyer une requête authentifiée

Dans l'ensemble, les processus d'authentification et d'autorisation servent les objectifs suivants :

  • Autoriser les appels à l'API uniquement pour les utilisateurs enregistrés
  • Permettre la traçabilité des requêtes
  • Suivre l'usage de l'API
  • Limiter le nombre d'appels à l'API à un usage normal et équitable
  • Appliquer différents niveaux de permission aux utilisateurs

Le schéma ci-dessous détaille le processus d'authentification des requêtes

Skalin oauth flowchart

L'accès aux ressources des API est un processus en deux étapes (basé sur la spécification ouverte OAuth 2 client credentials grant (opens new window)):

  1. Demander au serveur d'authentification (auth.skalin.io) un jeton d'accès temporaire au format JSON Web Token (JWT) en fournissant les client_id et client_secret de voter trousseau
# curl exemple de requête d'authentication
curl --location \
--request POST 'https://auth.skalin.io/oauth/token' \
--header 'Content-Type: application/json' \
--data-raw '{
    "client_id":"{{TokenClientId}}",
    "client_secret":"{{TokenSecret}}",
    "audience":"https://api.skalin.io/",
    "grant_type":"client_credentials"
}'
1
2
3
4
5
6
7
8
9
10
  1. Envoyez votre requête authentifiée à l'API en utilisant la partie access_token du jeton JWT fraîchement généré. Fournissez l'access_token comme en-tête HTTP d'autorisation de la requête (bearer) :
# curl exemple de requête à l'api
curl --request POST https://api.skalin.io/v1/customers?clientId={{clientId}} \
--header "Content-Type: application/json" \
--header "Authorization: Bearer {{AccessToken}}"
1
2
3
4

Info

Veuillez noter que les jetons d'accès JWT expirent après une période de 6 heures. Il est alors nécessaire de répéter la première étape pour renouveler le jeton d'accès (access_token) ou d'utiliser le refresh_token à cette fin.

# Comprendre les limites de taux de requêtes par secondes (rate-limits)

Chaque point d'entrée de nos APIs est protégé par une limite du taux de requêtes par secondes afin d'éviter la surcharge du service. Lorsque les clients dépassent cette limite, une erreur HTTP 503 est renvoyée par nos serveurs. C'est une façon courante de protéger un service contre les utilisations abusives, les scripts bogués ou les attaques par déni de service (DoS).

Vous trouverez ci-dessous le détail des limites de taux de requêtes par secondes par point d'entrée :

# Authentification

Le nombre de requêtes par seconde (rqps) acceptées à partir d'une IP donnée sur le point d'entrée auth.skalin.io est :

  • Limite nominale : 5 rqps
  • Seuil de tolérance exceptionnel : 10 rqps

Avertissement

Vous devez sauvegarder le jeton d'accès en cours et ne le rafraichir qu'à son expiration. Chaque jeton d'accès a une durée de vie de 6 heures. Vous pouvez générer un maximum de 15 jetons d'accès par jour.

# API

Le nombre de requêtes par seconde (rqps) acceptées à partir d'une IP donnée sur le point d'entrée api.skalin.io est :

  • Limite nominale : 20 rqps
  • Seuil de tolérance exceptionnel : 35 rqps

# Gestion des langues

Certains points d'entrée de nos APIs permettent une gestion de la langue, comme par exemple les APIs qui présentent les schémas de données avec des libellés de champs. Pour ces APIs vous pouvez préciser la langue de retour désirée grâce à l'en-tête Accept-Language.

Les valeurs supportées à ce jour sont fr et en, cette dernière étant la valeur par défaut.

# curl - exemple de requête à l'api
curl --request POST https://api.skalin.io/v1/customers?clientId={{clientId}} \
--header "Content-Type: application/json" \
--header "Authorization: Bearer {{AccessToken}}" \
--header "Accept-Language: fr"
1
2
3
4
5

Info

Il est recommandé de tout le temps fournir cet en-tête pour simplifier la gestion des APIs.

Contributeurs: Julien