Authentification

La plupart des points d'API requièrent une authentification.
Celle-ci s'effectue selon les spécifications du standard OAuth 2.0.

Les deux méthodes d'autorisation (authorization flows) suivantes sont disponibles :

• Authorization Code
• Client Credentials (lorsque aucun utilisateur n'est requis)

De nombreuses librairies sont disponibles dans presque tous les langages de programmation pour intégrer ces méthodes dans vos clients.

La communication avec le serveur s'effectue toujours en TLS (https).
Les requêtes non sécurisées sont rejetées par l'API.

Enregistrement d'une application cliente

Enregistrez votre application cliente depuis l'Atelier Serveur, pour obtenir les identifiants client nécessaire à l'authentification.

Authorization Code

Cette méthode d'authentification, la plus courrament utilisée, permet d'authentifier un utilisateur spécifique.

Cette section n'a pas été encore documentée.

Client Credentials

Cette méthode d'authentification est suffisante pour les applications n'accédant qu'aux ressources qui ne requièrent pas l'identification d'un utilisateur.

Exemples :

• GET /datasets
• GET /geo/communes

La sélection de cette méthode se fait en assignant la valeur client_credentials au paramètre grant_type.
Aucune authentification de l'utilisateur est requise. Seuls les identifiants de l'application sont transmis.
Les identifiants client peuvent être transmis dans le corps de la requête ou sous forme d'en-tête (Authorization Basic).
La seconde méthode est recommandée par OAuth.

Exemple utilisant l'en-tête Basic :

$ http -jv POST https://api.solutions-territoire.fr/oauth/token \
    Authorization:"Basic ejBXdEdMbTFmL...9GbE05WUNCeUltVDQ0" \
    Accept:"application/json" \
    grant_type='client_credentials'

POST /oauth/token HTTP/1.1
Accept: application/json
Authorization: Basic ejBXdEdMbTFmL...9GbE05WUNCeUltVDQ0
Content-Type: application/json

{
  "grant_type": "client_credentials"
}

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
  "access_token": "dGCMv3RWEcgWjgeKS5D6IUw0gv2VKmaPqJzZg9mM_3A",
  "created_at":   1562833488,
  "expires_in":   7200,
  "token_type":   "Bearer"
}

Exemple utilisant les identifiants dans le corps de requête :

$ http -jv POST https://api.solutions-territoire.fr/oauth/token \
    Accept:"application/json" \
    grant_type='client_credentials' \
    client_id='z0WtGLm1f--KETSFQzqtK4EkJ7y3NBbCksV_-Spjuz0' \
    client_secret='gGb1JZtOWFjzAxGCZdfRUhGNM_1r-OFlM9YCByImT44'

POST /oauth/token HTTP/1.1
Accept: application/json
Content-Type: application/json

{
  "client_id":     "z0WtGLm1f--KETSFQzqtK4EkJ7y3NBbCksV_-Spjuz0",
  "client_secret": "gGb1JZtOWFjzAxGCZdfRUhGNM_1r-OFlM9YCByImT44",
  "grant_type":    "client_credentials"
}

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
  "access_token": "dGCMv3RWEcgWjgeKS5D6IUw0gv2VKmaPqJzZg9mM_3A",
  "created_at":   1562833488,
  "expires_in":   7200,
  "token_type":   "Bearer"
}

Obtention et utilisation du jeton d'accès

Quelque soit la méthode d'authentification choisie, vous recevrez un jeton d'accés (access token) et ses attributs en réponse :

{
  "access_token": "dGCMv3RWEcgWjgeKS5D6IUw0gv2VKmaPqJzZg9mM_3A",
  "created_at":   1562833488,
  "expires_in":   7200,
  "token_type":   "Bearer"
}

Une fois ce jeton obtenu, vous pouvez l'utiliser dans l'en-tête de toutes vos requêtes.

$ http -jv GET https://api.mon-territoire.fr/ \
    Accept:"application/json" \
    Authorization:"Bearer dGCMv3RWEcgWjgeKS5D6IUw0gv2VKmaPqJzZg9mM_3A"

GET / HTTP/1.1
Accept: application/json
Authorization: Bearer dGCMv3RWEcgWjgeKS5D6IUw0gv2VKmaPqJzZg9mM_3A
Content-Type: application/json

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
  "version": "0.13.0"
}