Applications utilisateur "confidentielles" - Authentification

Paramètres d'accès

L'équipe Isogeo référence l'application sur sa plateforme et renseigne les URLs de redirection fournies par le développeur.

Les identifiants sont ensuite transmis au développeur sous la forme d'un fichier client_secrets.json dont la structure est la même que celle utilisée par Google (voir la documentation) :

{
  "installed": {
    "client_id": "837647042410-75ifg...usercontent.com",
    "client_secret":"asdlkfjaskd",
    "redirect_uris": ["https://localhost:5000/login/callback", "urn:ietf:wg:oauth:2.0:oob"],
    "auth_uri": "https://accounts.google.com/o/oauth2/auth",
    "token_uri": "https://accounts.google.com/o/oauth2/token"
  }
}

Noter le nom du dictionnaire installed, qui marque la différence avec les applications utilsiateur de type public.

Authorization Code Grant

La documentation officielle de ce flot est disponible dans la RFC 6749. Ce flot se fait en 2 étapes :

1. la requête d'autorisation :
   1. un formulaire web (encapsulé ou non) demande à l'utilisateur final son identifiant/mot de passe Isogeo.
   2. un code d'autorisation est renvoyé
2. l'obtention du jeton d'accès (access token)

Puis, le rafraîchissement du jeton d'accès (access token) en utilisant le jeton de rafraichissement (refresh token).

Requête d’autorisation

La récupération du code d’autorisation se fait via un navigateur (le navigateur en cours d’utilisation dans le cas d’une application web, un navigateur externe ou un navigateur embarqué dans le cas d’une application native). L'utilisateur doit être redirigé sur la route d’autorisation https://id.api.isogeo.com/oauth/authorize:

• la requête est un GET vers https://id.api.isogeo.com/oauth/authorize

• avec des paramètres qui indiquent :

  • response_type: code
  • client_id : l’identifiant OAuth de l’application.
  • redirect_uri : l’adresse de l’application vers laquelle renvoyer le code d’autorisation (préalablement enregistrée dans ses paramètres, par exemple https://localhost:5000/login/callback).

La requête est automatiquement redirigée - HTTP 302 Found - vers le formulaire d'authentification intégré à Isogeo (https://id.api.isogeo.com/login) avec un paramètre de retour d'URL correspondant à la requête intiale. C'est l'étape à laquelle l'utilisateur final doit entrer son identifiant/mot de passe Isogeo :

Exemples

Navigateur

L'URL peut être ouverte directement dans un navigateur :

https://id.api.isogeo.com/oauth/authorize?response_type=code&client_id=sample-3rdapp-demo-test-uuid-1a2b3c4d5e6f7g8h9i0j11k12l&http://localhost:5000/login/oauth/callback

Qui redirige donc vers :

https://id.api.isogeo.com/login?ReturnUrl=https%3A%2F%2Fid.api.isogeo.com%2Foauth%2Fauthorize%3Fresponse_type%3Dcode%26client_id%3Dclient_id=sample-3rdapp-demo-test-uuid-1a2b3c4d5e6f7g8h9i0j11k12l%26http%3A%2F%2Flocalhost%3A5000%2Flogin%2Foauth%2Fcallback

En cas de succès le navigateur est redirigé vers l'URI de retour (callback) enrgeistrée sur la plateforme, avec en paramètre le code d’autorisation (code) en paramètre d'URL :

http://localhost:5000/login/oauth/callback?code=%2B7CNjbPnhNbRgieXBS3YDKF%2BtmWLpSQWyQoQd%2Fy3yA6maBTV1cVTtNlyhG7gRvwIlQLlF15hv4dFb8kX%2FMlClU%2B%2FNTZuTRRDCWcop1p8ZF%2BR%2BQ8KbvKNkW%2FSNKWGz43H

cURL

Même si la ligne de commande n'est pas vraiment adaptée, voici la construction de l'URL :

.\curl.exe --location <# suivre la redirection #> `
           --get <# forcer le verbe GET #> `
           --url 'https://id.api.isogeo.com/oauth/authorize' <# url cible #> `
           --data 'response_type=code&http://localhost:5000/login/oauth/callback&client_id={client_id_value}' <# paramètres d'URL #> `
           --verbose <# requête détaillée #> `
           --include <# réponse détaillée #>

Demande du jeton d'accès

Muni du code d’autorisation précédent, la récupération d’un access token se fait sur la route https://id.api.isogeo.com/oauth/token. Donc :

• la requête est un POST vers https://id.api.isogeo.com/oauth/token avec :

  • un contenu qui contient les paramètres :

    • grant_type : authorization_code
    • code : le code d’autorisation obtenu à l'étape précédente
    • redirect_uri : la même adresse que pour la requête d’autorisation.

  • un en-tête d’authentification de type Basic, où l’on considère que :

    • le nom d’utilisateur est le client_id
    • le mot de passe est le client_secret

    Ce qui revient à encoder en Base 64 la chaîne {client_id}:{client_secret} (sans les accolades). Exemple :

    Authorization: Basic czZCaGRSa3F0MzpnWDFmQmF0M2JW

L’access_token est renvoyé au format JSON. Il permet l’accès aux ressources d’Isogeo en lecture seule et est valide pendant 1 heure. Un refresh token est également fourni.

Exemples

Requête

cUrl

.\curl.exe --data 'grant_type=authorization_code&code={authorization_code}' <# on passe le type d'authentification et le code d'authorisation en paramètres d'URL #> `
           -u '{client_id}:{client_secret}' <# la chaîne est automatiquement encodée en Base64 par cURL #> `
           --url https://id.api.isogeo.com/oauth/token <# url cible #> `
           -X POST <# superflu mais plus lisible #> `
           --header 'content-type: application/x-www-form-urlencoded'  <# superflu mais plus lisible #> `
           --verbose <# requête détaillée #> `
           --include <# réponse détaillée #> `
           -o access_token.json <# stocker la réponse dans un fichier JSON #>

Structure de l'access token renvoyé

{
  "access_token": "LoremipsumdolorsitametconsecteturadipiscingelitDonecmaurismaurisvariusacdictumvelviverrainvelitProinidvenenatisipsumutlaciniajustoFusceidexeratDuisutlectusinelitvehiculaconsequatvitaeacnullaDonecnibhnibhtristiqueatenimaliquamcursusultricesvelitQuisquepulvinarurnaveldictumefficiturvelitliberomollisduinecpulvinarliguladoloratquamSedtinciduntnequesitametvolutpat",
  "token_type": "bearer",
  "expires_in": 3599,
  "refresh_token": "acnullaDonecnibhnibhtristiqueatenimaliquamcursusultricesvelitQuisquepulvinarurnaveldictumefficiturvelitliberomollisduinecpulvina"
}

Le refresh token

un refresh token est fourni avec l’access token. Ce jeton peut être utilisé afin de renouveler simplement l’access token. Il doit donc être protégé, de la même manière que les identifiants d’application.

La documentation officielle de l’utilisation d’un refresh token est disponible dans la RFC 6749.

Dans le cas d'Isogeo, le renouvellement d’un access token se fait sur la route https://id.api.isogeo.com/oauth/token. La requête est un POST vers https://id.api.isogeo.com/oauth/token?grant_type=client_credentials, avec :

• un contenu qui indique :

  • grant_type : refresh_token
  • refresh_token : {le token_récupéré_précédemment}

• avec un en-tête d’authentification de typeBasic, où l’on considère que :

  • le nom d’utilisateur est le client_id
  • le mot de passe est le client_secret

  Ce qui revient à encoder en Base 64 la chaîne {client_id}:{client_secret} (sans les accolades). Exemple :

  Authorization: Basic czZCaGRSa3F0MzpnWDFmQmF0M2JW