1 - Vue d'ensemble

Cette partie va donner un aperçu des différents scénarii d'autorisation OAuth 2.0 qu’Anywhere prend en charge et de son utilisation à travers les différents services mis à disposition.

Il est important de noter que cette API  est en constante évolution et que le développement sur la plateforme IDentité Numérique n’est pas un évènement ponctuel.

Cette partie présente les moyens mis en œuvre pour la protection de l’accès aux services AnyWhere v2,  qui intègre le Framework OAuth2.

Il est à noter que cette version n’est pas rétro-compatible avec la version AnyWhere v1, du fait du changement de protocole d’authentification (en effet, les workflows ne sont pas compatibles). Néanmoins, il est beaucoup plus aisé d’intégrer la version 2 du protocole OAuth.

1.1 Notions OAuth2

OAuth2 est, comme son nom l’indique la version 2 du protocole OAuth. Il permet à des applications tierces d’obtenir un accès limité à des services disponibles en HTTP à la suite d’une entente préalable entre les parties. L’accès est demandé par ce que le protocole appelle un client, (qui peut être un site internet, mais aussi une application mobile, …) pour une ressource clairement identifiée. Si ces ressources n’appartiennent pas au client, ce dernier doit obtenir la permission de l’utilisateur final pour y accéder.
		CONSUMER_KEY : _ce85bad96eed75f0f7faa8f04a48feedd56b4dcb
CONSUMER_SECRET : _80b312627bf936e6f20510232cf946fff885d1f7

1.1.1. Les rôles

Le protocole définit 4 rôles bien distincts :

Rôle

Description

Resource Owner

le détenteur des données (généralement l’utilisateur final)

Resource Server

le serveur de ressources qui héberge les données protégées

Client Application

le client, une application demandant des données au serveur de ressources (application partenaire),

Authorization Server

le serveur d’autorisation, qui délivre les tokens (ou jetons) au client pour accéder à une ressource protégée.


Le serveur IDentité Numérique AnyWhere joue les rôles ‘Resource Server’ et ‘Authorization Server’, soit le serveur d’autorisation et de ressources.

1.1.2. Les tokens

Les jetons (token) sont des chaines de caractères générées par le serveur d’autorisation et sont émis lorsque le client en fait la demande. On distingue 3 types de jetons :

Rôle

Description

Access Token

Le jeton d’accès, c’est le plus important car c’est lui qui permet au serveur de ressources d’autoriser la mise à disposition des données d’un utilisateur. Ce jeton est envoyé par le client (l’application) en tant que paramètre ou en tant que header dans la requête vers le serveur de ressources. Il a une durée de vie limitée qui est définie par le serveur d’autorisation. Il doit rester confidentiel dès que possible (non connu du détenteur de ressources) mais ce n’est pas toujours possible, notamment lorsque c’est le navigateur qui envoie les requêtes au serveur de ressources via JavaScript.

Refresh Token

Le jeton de renouvellement est délivré au même moment que le jeton d’accès. Il sert simplement à être envoyé au serveur d’autorisation lorsque le jeton d’accès est expiré et que le client so

ID Token

Dans le cas où OpenID Connect est utilisé (= le scope ‘openid’ est présent dans la requête d’autorisation), la réponse du serveur au moment de la requête d’autorisation inclus un paramètre supplémentaire : id_token. Ce paramètre représente un jeton d’identification sécurisé qui contient des informations sur l’authentification d’un utilisateur final.

Il est important pour l’application partenaire de stocker ce jeton car il servira ensuite pour pouvoir déconnecter l’utilisateur.

1.1.3. Le paramètre scope

Le scope est un paramètre qui permet de limiter les droits du jeton d’accès. La liste de l’ensemble des scopes disponibles est maintenue au niveau du serveur d’autorisation. Lors de son inscription, le client souscrit à l’utilisation d’un sous-ensemble de scope. Il doit alors envoyer le ou les scopes qu’il souhaite utiliser lors de sa demande d’autorisation.

Pour plus information sur l’utilisation des scopes : http://tools.ietf.org/html/rfc6749#section-3.3

1.2. Notions OpenID Connect

OpenID Connect (OIDC) est un standard d’identification qui facilite l’utilisation d’identités numériques dans les sites web et les applications pour tout type d’ordinateur ou de terminaux mobiles, comme les smartphones.

OIDC est une couche protocolaire au-dessus d’OAuth2, c’est en quelques sortes une extension. Reposant sur l’architecture OAuth, ce protocole permet de gérer la couche authentification/gestion de la session utilisateur qui manque cruellement au protocole OAuth.

Avec OIDC, l’application partenaire aura l’assurance d’un risque plus limité de vol d’informations utilisateurs.

1.2.1. ID Token

Un ID Token représente un jeton d’identification sécurisé qui contient des informations sur l’authentification d’un utilisateur final.

Il est formaté sous la forme d’un jeton JWT (JSON Web Token). Un jeton JWT est une façon de représenter des claims (ou revendication) pour les transférer entre deux parties dans un format compact et compatible URI. Un claim est simplement une collection de paires nom/valeur contenant des informations sur un utilisateur ou tout autre sujet.  Dans un jeton JWT, les claims sont sérialisés en JSON.

Le format d’un jeton JWT est particulièrement bien adapté pour circuler dans une URI et donc pour les applications REST.

Composition d’un jeton JWT

Un jeton JWT est une séquence de plusieurs parties compatibles URI séparées par un point (.). Chaque partie est encodée en base64url, c’est à dire un encodage 64 caractères avec un alphabet compatible avec le nom d’une URI.

Par exemple :

		
eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.
eyJleHAiOjEzODY4OTkxMzEsImlzcyI6ImppcmE6MTU0ODk1OTUiLCJxc2giOiI4MDYzZmY0Y2ExZTQxZGY3YmM5MGM4YWI2ZDBmNjIwN2Q0OTFjZjZkYWQ3YzY2ZWE3OTdiNDYxNGI3MTkyMmU5IiwiaWF0IjoxMzg2ODk4OTUxfQ.
uKqU9dTB6gKwG6jQCuXYAiMNdfNRw98Hw_IWuA5MaMo

Il est composé de 3 parties/segments séparés par des ‘.’ (Le header, les claims et la signature) : <base64-encoded header>.<base64-encoded claims>.<base64-encoded signature>

Les deux parties principales du jeton sont l’entête (header) et les claims.

L’entête est un objet JSON doté des propriétés définies par les normes JWS et JWE selon que l’on encrypte ou bien signe le jeton. Il contient des métas donnés ainsi que le nom des algorithmes précédents et les clefs nécessaires à ces algorithmes.

Les claims sont un ensemble de clés/valeurs dont les noms sont normalisés dans la norme OIDC. L’application partenaire n’est pas obligée de tous les utiliser à chaque requête. Disons qu’ils sont souvent utiles.

Contenu d’un ID Token décodé

Header :

Dans le header, les paramètres suivant :

Nom Exemple Description
typ JWT

Le type de jeton. Sur AnyWhere, il n’y a qu’un seul type de jeton : JWT.

alg HS256

Le type d’algorithme utilisé pour signer le JWT. Il est utilisé pour la vérification de la signature de l’ID Token.

 

Par exemple Header :

{
    "typ":"JWT",
    "alg":"HS256"
}

Claims :

Dans les claims, les paramètres suivant :

Nom Exemple Description
iss https://anywhere-local.idn.laposte.fr

Entité qui émet les revendications (Dans notre cas il correspond à l’URL d’AnyWhere).

iat 1410255630

Date à laquelle le JWT a été généré le JWT

exp 1410255630 Date d’expiration de l’ID Token
sub
a_user_key
Identifiant de l’utilisateur final
aud
c036b0b6f97a394190a00f2d36b213091938d225
Clé cliente de l'audience du JWT. C'est à dire la clé cliente pour pour qui le jeton est destiné.

 

Par exemple Claims :

{   
  "iss": "https:\/\/anywhere-local.idn.laposte.fr",
  "iat":1410255630,
  "exp":1410259230,
  "sub": "a_user_key",
  "aud":"_c036b0b6f97a394190a00f2d36b213091938d225"
}

Des attributs utilisateurs peuvent également se retrouver dans ce segment, ces attributs sont décrit ensuite (cf 2.1.2).

Signature :

La troisième et dernière partie de l’ID Token représente la signature de ce dernier. Afin de vérifier que l’ID Token a bien été délivré pour l’application partenaire (et qu’il n’y a pas eu d’attaque Man in the middle), celle-ci peut vérifier la signature du jeton.

Elle a pour format : signature = sign(‘<base64-encoded header>.<base64-encoded claims>’).

La vérification de la signature dépend de l’algorithme utilisé. Actuellement, l’application partenaire peut choisir sont l’algorithme de signature parmi :

  • HS256 (HMAC using SHA-256 hash algorithm)
  • HS384 (HMAC using SHA-384 hash algorithm)
  • HS512 (HMAC using SHA-512 hash algorithm)
  • RS256 (RSASSA-PKCS-v1_5 using SHA-256 hash algorithm)
  • RS384 (RSASSA-PKCS-v1_5 using SHA-384 hash algorithm)
  • RS512 (RSASSA-PKCS-v1_5 using SHA-512 hash algorithm)

Si l’application partenaire souhaite vérifier/valider les ID Token qu’elle reçoit d’AnyWhere, elle doit utiliser des clés (publique et/ou privé) fournies par IDN lors de son inscription.

Pour plus d’informations sur les jetons JWT : https://tools.ietf.org/html/draft-ietf-jose-json-web-signature-31

1.2.2. Les attributs utilisateurs (user claims)

Les attributs utilisateurs qui peuvent se retrouver dans un ID Token ou dans la réponse du connecteur /me (cf 3.1.2) sont décrit dans le tableau ci-dessous.

Pour plus information sur la description des claims : http://openid.net/specs/openid-connect-core-1_0.html#Claims

Standart Claims

Nom du paramètre sur Anywhere

Format

Description

sub

string

Sujet – Identifiant de l’utilisateur final.

name

string

Nom entier de l’utilisateur final (incluant la civilité, le nom et le prénom).

given_name

string

Prénom de l’utilisateur final.

family_name

string

Nom de famille de l’utilisateur final.

nickname

string

Le pseudonyme de l’utilisateur final.

email

string

L’e-mail de l‘utilisateur final.

email_verified

boolean

Renvoie vrai si l’adresse e-mail de l’utilisateur final a été vérifiée par le provider d’identité (IDN), et faux autrement.

gender

string

Sexe de l’utilisateur final (female ou male).

birthdate

string

Date de naissance de l’utilisateur final [format ISO8601‑2004] YYYY-MM-DD.

phone_number

string

Numéro de téléphone de l’utilisateur final [format : +33656127849]

phone_number_verified

boolean

Renvoie vrai si le numéro de téléphone de l’utilisateur final a été vérifié par le provider d’identité (IDN), et faux autrement.

address

JSON object

Adresse de l’utilisateur final. Les informations sur cette adresse sont contenues dans un tableau formaté en JSON (voir ci-dessous

 

Address Claims

Nom du paramètre sur Anywhere

Format

Description

formatted

string

Adresse complète de l’utilisateur final (N°, rue, Ville, CP)

place

string

Nom entier de l’utilisateur final (incluant la civilité, le nom et le prénom).

details

string

SNA2 : Appartement, chez, sonnerie. (Ex: Appartement A12 - Chez M. Georges Martin - Sonnerie 15)

street_address

string

SNA3 : Bâtiment, immeuble (Ex: Bâtiment B24 - Immeuble LATOUR)

locality

string

SNA5 : Lieu-dit

city

string

SNA6-1 : Ville

postal_code

string

SNA6-2 : Code Postale

country

string

SNA7 : Pays

address_verified

boolean

Renvoie vrai si l’adresse de l’utilisateur final a été vérifiée par le provider d’identité (IDN), et faux autrement.

1.3. Inscription des clients

L'inscription d'une application partenaire est réalisée en contactant les services concernés La Poste.

Le partenaire doit fournir les informations suivantes:

• Nom de l'application (maximum de 50 caractères encodés RFC-3986),

• Logo carré de l'application au format png ou jpg (dimensions : 60x60 pixels minimum),

• URL d'accès à la page principale de l'application

• Description (maximum de 255 caractères encodés RFC-3986)

 

Le processus d'inscription d'un client délivre les clefs propres à ce dernier. Il est nécessaire de sauvegarder les clefs client_id et client_secret.

Ces informations sont obligatoires pour accéder aux services simples de l’API, obtenir des jetons autorisés access_token dans le cas de services protégés.

Workflow :

		client_id :_ce85bad96eed75f0f7faa8f04a48feedd56b4dcb 
client_secret : _80b312627bf936e6f20510232cf946fff885d1f7

1.4. Les types d’autorisation

Le protocole OAuth2 définit 4 types d’autorisation possibles selon l’emplacement, la nature des intervenants dans l’obtention du jeton d’accès.

1.4.1. L’autorisation via un code (Authorization Code Grant)

Ce type d’autorisation, tripartite,  doit être privilégié par rapport aux autres types d’autorisation et tout particulièrement quand le client est un serveur web. Il permet d’obtenir un jeton d’accès de longue durée qui pourra être renouvelé via un jeton de renouvellement (si le serveur d’autorisation le permet).

L’utilisateur final n’accède jamais au jeton d’accès car  il sera stocké par le site internet (en session par exemple). AnyWhere envoie également d’autres informations en dehors du jeton d’accès comme la durée de validité du jeton d’accès et un jeton de renouvellement par exemple.

C’est le scénario idéal et le plus sûr car le jeton d’accès n’est pas transmis côté client (votre navigateur web dans notre exemple).

Plus d’informations : RFC 6749 — Authorization Code Grant

Cas d’usage :

Rôle

Description

Détenteur des données

Vous

Serveur de Ressources

IDentité Numérique - AnyWhere

Client

Un site internet partenaire

Serveur d’Autorisation

IDentité Numérique - AnyWhere

 

Scénario en 2 étapes :

  1. Requête d'obtention du code d’autorisation :
    1. Un site internet partenaire souhaite accéder aux informations de votre profil IDentité Numérique.

    2. L'utilisateur, connecté à son Identité Numérique, est redirigé par le site internet partenaire vers le serveur d’autorisation (IDentité Numérique - AnyWhere).
    3. Si l'utilisateur autorise l’accès à ses informations selon le scope, le serveur d’autorisation (IDentité Numérique - AnyWhere) envoie un code d’autorisation au site internet partenaire.

  1. requête d'obtention du token d’accès :

    1. Le code d'autorisation est échangé - entre le site internet partenaire et IDentité Numérique - AnyWhere - par un jeton d’accès (access_token) de façon transparente pour l'utilisateur.
    2. Le site internet partenaire peut donc maintenant utiliser ce jeton d’accès (access_token) pour accéder aux données du profil de l'utilisateur par le serveur de ressources (IDentité Numérique - AnyWhere).

 

Diagramme de Séquence :

1.4.1.1. 1ère étape : Requête d'obtention du code d’autorisation

La demande de jeton d’autorisation (code) permet d’obtenir un jeton utilisable (une seule fois) pour demander à l'utilisateur d'accorder l'autorisation à ses informations protégées.

Requête :

Une requête de type GET est envoyée vers le serveur ({{base_url}}/oauth/v2/authorize) avec les paramètres suivants (format HTTPS) :

 

Nom Exemple Description
client_id _ce85bad96eed75f0f7faa8f04a48feedd56b4dcb

La clé unique du Client, obtenu lors du processus d’inscription de l’application partenaire.

response_type

code

Correspond au type de réponse attendue. Dans le cas de cette requête, on attend un coded’autorisation, on indique alors que l’on souhaite recevoir un code en définissant « response_type=code ». D’autres valeurs peuvent être utilisé (dans le cas d’un rafraichissement de jeton suite à une expiration ou à une autorisation implicite. Ces valeurs possibles sont décrites dans les sections correspondantes

state 0113sd5sqf4za5az6a44ae4a41q3qd1q

Le client envoie ce paramètre lors de la demande de code d’autorisation, il sera retourné tel quel par le serveur d’autorisation dans la réponse et pourra donc être comparé par le client avant la demande d’échange du code par un token d’accès. Ce paramètre correspond généralement à un hash unique d’un nombre aléatoire qui sera stocké dans la session de l’utilisateur. Il est utilisé afin d’empêcher l’exploitation de failles CSRF (cf. RFC 6749 — Cross-Site Request Forgery)

redirect_uri1 http://monsitepartenaire/receiveAuthorizedToken

URL de l’application partenaire sur laquelle l'utilisateur doit être redirigé après avoir autorisé l'accès à ces informations protégées.

scope2 openid profile

Liste de privilèges/périmètres que l’application partenaire cible veut obtenir du service. Plusieurs scopes peuvent être demandés par un même partenaire en même temps (séparés par des espaces et URLencoded)

prompt3 none Lorsque l’application souhaite contrôler l’état de la session utilisateur, elle peut réappeler l’URL d’autorisation avec le paramètre prompt=none. Si l’utilisateur n’est plus connecté ou a supprimé son consentement pour l’application partenaire donnée, une erreur sera retournée.
login_hint3 khcompte@gmail.com Lorsque votre application sait quel utilisateur essai de s'authentifier, elle peut fournir ce paramètre comme un indice pour le serveur d'authentification. La présence de ce paramètre permet de pré-remplir le champ login lors de l’affichage de la fenêtre de connexion.
nonce4 azearaerer054aze51 Cette chaine permet d’associer une session cliente (application partenaire) avec un ID Token. La valeur du paramètre nonce doit inclure un jeton et être impossible à deviner pour les attaquants. Il permet également d’éviter les attaques de type rejeu.
1paramètre optionnel
2paramètre optionnel, obligatoire uniquement dans le cadre du service /me (3.1.3. anywhere/oauth/v2/me). un seul scope est défini pour l'instant pour ce service, le scope "profil".
3paramètre optionnel, obligatoire lors de l'utilisation de l'openID
4paramètre optionnel, obligatoire lors de l'utilisation de l'openID en mode implicit (cf 2.4.2)
		GET https//__SERVER-URL__/anywhere/oauth/v2/authorize?
client_id=_ce85bad96eed75f0f7faa8f04a48feedd56b4dcb&
response_type=code&
state=0113sd5sqf4za5az6a44ae4a41q3qd1q&
redirect_uri=http%3A%2F%2Fwww.test.loc%2FcallBack_getAccess.php&
scope=openid profile

Réponse :

La réponse du service OAuth d’IDN ne se fait pas directement. En effet, IDN a besoin de contrôler l'identité de l'utilisateur, puis lui demander son consentement sur les informations que l'application demande. Le processus de réponse suit les différentes étapes suivantes :

  1. Contrôle de la validité de la demande : validation du scope et duredirect_uri  fournit dans la requête (voir ci-dessous pour le retour)

    Type de Retour Retour
    Retour OK
    200
    Retour KO
    401
    Content-Type

    text/html

  2. Si le retour est OK, authentification de l'Utilisateur :
    1. si l'utilisateur est déjà connecté à l'IDN, ce dernier valide le cookie de session qui a été enregistré par le navigateur de l'utilisateur puis continue le processus de réponse.
    2. si l'utilisateur n'est pas connecté à l'IDN, il est redirigé vers une page sur laquelle il peut rentrer ses informations d'identification (voir image ci-dessous).

  3. Une fois que l'IDN a réussi à authentifier l'utilisateur, une boite de dialogue s'ouvre (voir image ci-dessous). Elle demander le consentement de l'utilisateur à faire les actions ou à fournir les informations demandées - précédemment identifiées par le paramètre scope - à l'application Partenaire.

  4. Deux réponses différente pourront être fournies selon l'action de l'utilisateur :
    1. Si l'utilisateur refuse, en cliquant sur "Ne pas Autoriser" un retour KO sera renvoyé (voir format tableau ci-dessous)

      Type de Retour Retour
      Retour KO 400
      Content-Type

      text/html

    2. Si l'utilisateur accepte, en cliquant sur "Autoriser", le consentement étant accordé, l’utilisateur est redirigé vers l’URL précisée par le paramètre redirect_uri de la requête. Le jeton d’autorisation (code) est fournis en réponse en paramètre GET (voir ci-dessous).

Paramètres :

Nom Exemple Description

code

bbb1e7a8bd77d06c18b70e242d1231693e17a8b2

Le code d'autorisation

state

0113sd5sqf4za5az6a44ae4a41q3qd1q

C'est le jeton anti failles csrf passé par l'application partenaire au moment de la première étape (et qui doit être de la même valeur qu’à l’étape 1). Il est généré par le partenaire puis retourné par Anywhere. Il permet de s'assurer de la provenance des échanges.

 
		GET https://monsitepartenaire/receiveAuthorizedToken? 
code=bbb1e7a8bd77d06c18b70e242d1231693e17a8b2&
state=0113sd5sqf4za5az6a44ae4a41q3qd1q

1.4.1.2. 2ème étape : requête d'obtention du jeton d’accès


Une fois le jeton d’autorisation obtenu, l’utilisateur est identifié. Vous disposez alors d’un code d’autorisation qui va pouvoir être échangé afin d’obtenir un jeton d’accès valide.

Requête :

Une requête de type POST est envoyée vers le serveur ({{base_url}}/oauth/v2) avec les paramètres suivants (format HTTPS + JSON) :

Nom Exemple Description
client_id _ce85bad96eed75f0f7faa8f04a48feedd56b4dcb

La clé unique du Client, obtenu lors du processus d’inscription de l’application partenaire.

grant_type authorization_code

Type d’autorisation utilisé par le client. Ici on indique que l’on utilise le grant type « Authorization code » en définissant : « grant_type=authorization_code »

code

bbb1e7a8bd77d06c18b70e242d1231693e17a8b2

Code d’autorisation reçu lors de la première étape du processus (2.3.1.1.).

		POST https://__SERVER-URL__/anywhere/oauth/v2
{
"client_id" : "_ce85bad96eed75f0f7faa8f04a48feedd56b4dcb",
"grant_type" : "authorization_code",
"code" : "bbb1e7a8bd77d06c18b70e242d1231693e17a8b2"
}

Réponse :

La réponse du service OAuth d’IDN se fait ensuite directement. Le processus de réponse suit les étapes suivantes :

  1. Contrôle de la validité de la demande : validation du code et du client_id fournit dans la requête.

    Type de Retour Retour
    Retour OK
    200
    Retour KO 401
    Content-Type

    application/json

  2. Réponse au format JSON présentant le jeton d’accès, sa durée de vie, ainsi qu’éventuellement un jeton de rafraichissement.

Paramètres

Nom Exemple Description

access_token

ac0c11e4b07a1aec4a386c0495a29b544b7df911

Le token d’accès utilisable ensuite pour accéder aux services

expires_in 3600

La durée de validation du token avant qu’il n’expire (exprimé en seconde)

token_type Bearer

Le type de token (à priori toujours de type Bearer

scope2 profil Liste de privilèges/périmètres que l’application partenaire cible veut obtenir du service. Plusieurs scopes peuvent être demandés par un même partenaire en même temps (séparés par des espaces et URLencoded)
refresh_token1 ecfca5f45a67590a1f7d97f44d16c022ce987864 Le token de renouvellement permet d'obtenir directement l'access token

1
paramètre optionnel
2paramètre optionnel, obligatoire uniquement dans le cadre du service /me (3.1.3. anywhere/oauth/v2/me). un seul scope est défini pour l'instant pour ce service, le scope "profil".
		{ 
"access_token": "ac0c11e4b07a1aec4a386c0495a29b544b7df911",
"expires_in": "3600",
"scope": "profil",
"token_type": "Bearer",
"refresh_token": "ecfca5f45a67590a1f7d97f44d16c022ce987864"
}

1.4.2. L’autorisation serveur à serveur (Client Credentials Grant)

Ce type d’autorisation est utilisé lorsque le client est lui-même le détenteur des données/ressources. Il n’a donc pas d’autorisation à obtenir de la part de l’utilisateur final.

Plus d’information : RFC 6749 — Client Credentials Grant

Cas d’usage :

Rôle

Description

Détenteur des données

Un site internet quelconque

Serveur de Ressources

IDentité Numérique - AnyWhere

Client

Un site internet partenaire

Serveur d’Autorisation

IDentité Numérique - AnyWhere

 

Scénario en 1 étape - Requête d'obtention du code d’autorisation :

    1. Un site internet partenaire stocke des informations (exemple : des fichiers) sur AnyWhere.
    2. Le site internet doit passer par l’API AnyWhere pour récupérer ou modifier ces informations et donc doit s’authentifier auprès du serveur d’autorisation.
    3. Lorsqu’il est authentifié, le site internet partenaire obtient un jeton d’accès qu’il peut désormais utiliser auprès du serveur de ressource AnyWhere.
    4. Le site internet partenaire peut donc maintenant utiliser ce jeton d’accès (access_token) pour accéder aux données du profil de l'utilisateur par le serveur de ressources (IDentité Numérique - AnyWhere).

 

Diagramme de Séquence :

1.4.2.1. Requête d'obtention du jeton d’autorisation

La demande de jeton d’accès se fait directement. On échange les « credentials » de l’application (client_id  et client_secret) pour obtenir un jeton valide. 

Requête :

Une requête de type GET est envoyée vers le serveur ({{base_url}}/oauth/v2/authorize) avec les paramètres suivants (format HTTPS) :

Nom Exemple Description
client_id _ce85bad96eed75f0f7faa8f04a48feedd56b4dcb

La clé unique du Client, obtenu lors du processus d’inscription de l’application partenaire.

grant_type client_credentials

Type d’autorisation utilisé par le client. Ici on indique que l’on utilise le grant type « Client Credentials » en définissant : « grant_type=client_credentials »

client_secret

_80b312627bf936e6f20510232cf946fff885d1f7

Le mot de passe associé au ‘client_id’, obtenu lors du processus d’inscription.

scope1 AdressRedrss Liste de privilèges/périmètres que l’application partenaire cible veut obtenir. Plusieurs scopes peuvent être demandés (séparés par des espaces et bien sûr URLencoded)
1paramètre optionnel, obligatoire uniquement dans le cadre du service /me (3.1.3. anywhere/oauth/v2/me). un seul scope est défini pour l'instant pour ce service, le scope "profil".
		
{
"grant_type" : "client_credentials",
"client_id" : "_ce85bad96eed75f0f7faa8f04a48feedd56b4dcb",
"client_secret" : "_80b312627bf936e6f20510232cf946fff885d1f7",
"scope": "AdressRedress",
}

Réponse :

La réponse du service OAuth d’IDN se fait directement. Le processus de réponse suit les étapes suivantes :

  1. Contrôle de la validité de la demande : validation du code et du client_id fournit dans la requête.

    Type de Retour Retour
    Retour OK
    200
    Retour KO
    401
    Content-Type

    text/html

     

  2. Réponse au format JSON présentant le jeton d’accès, sa durée de vie, ainsi qu’éventuellement un jeton de rafraichissement.

Paramètres

Nom Exemple Description

access_token

ac0c11e4b07a1aec4a386c0495a29b544b7df911

Le token d’accès utilisable ensuite pour accéder aux services

expires_in 3600

La durée de validation du token avant qu’il n’expire (exprimé en seconde)

token_type Bearer

Le type de token (à priori toujours de type Bearer

scope2 AdressRedress Liste de privilèges/périmètres que l’application partenaire cible veut obtenir du service. Plusieurs scopes peuvent être demandés par un même partenaire en même temps (séparés par des espaces et URLencoded)
refresh_token1 ecfca5f45a67590a1f7d97f44d16c022ce987864 Le token de renouvellement permet d'obtenir directement l'access token
1paramètre optionnel
2paramètre optionnel, obligatoire uniquement dans le cadre du service /me (3.1.3. anywhere/oauth/v2/me). un seul scope est défini pour l'instant pour ce service, le scope "profil".

1.4.3. L’autorisation via un token de renouvellement (Refresh Token grant)

Ce type d’autorisation est bipartite. Il est utilisé par l’application partenaire pour obtenir un nouveau token d’accès lorsque celui-ci est expiré et que le client souhaite le renouveler.

Requête :

Format :

Langage Préfixe Méthode Action

URL

https://__SERVER-URL__/anywhere/oauth/v2/authorize

Méthode HTTPS + Json

POST

 

Format Header HTTPS :

Type de Retour Retour

Accept

application/json

Content-Type

application/json

 

Paramètre :

Nom Exemple Description
client_id _ce85bad96eed75f0f7faa8f04a48feedd56b4dcb

Correspond à l'Identifiant de l'application partenaire

grant_type refresh_token

Type d’autorisation : refresh_token

refresh_token

 ecfca5f45a67590a1f7d97f44d16c022ce987864

Le token de renouvellement (reçu au même moment que l’access_token). Le refresh token n’est pas accordé dans tous les mode d’autorisation (ex : pour le mode implicite, il n’existe pas).

 

		{ 
"access_token": "ac0c11e4b07a1aec4a386c0495a29b544b7df911",
"expires_in": "3600",
"scope": "AdressRedress",
"token_type": "Bearer",
"refresh_token": "ecfca5f45a67590a1f7d97f44d16c022ce987864"
}
		POST https://__SERVER-URL__/oauth? 
{
"grant_type" : "refresh_token",
"client_id" : "_ce85bad96eed75f0f7faa8f04a48feedd56b4dcb",
"refresh_token" : " ecfca5f45a67590a1f7d97f44d16c022ce987864"
}

Réponse :

Format :

Type de Retour Retour

Status Code

200

Content-Type

application/json

 

Paramètres

Nom Exemple Description

access_token

ac0c11e4b07a1aec4a386c0495a29b544b7df911

Le token d’accès utilisable ensuite pour accéder aux services

expires_in 3600

La durée de validation du token avant qu’il n’expire (exprimé en seconde)

token_type Bearer

Le type de token (à priori toujours de type Bearer

refresh_token1 ecfca5f45a67590a1f7d97f44d16c022ce987864 Le token de renouvellement permet d'obtenir directement l'access token

 1paramètre optionnel

		{ 
"access_token": "10f85091978e4c7159b79b82911134ec14fa58e8",
"expires_in": 3600,
"token_type": "Bearer",
"refresh_token": "ecfca5f45a67590a1f7d97f44d16c022ce987864"
}

1.5. Accès à une ressource Anywhere

Pour accéder à une ressource via OAuth2, il faut au préalable avoir obtenu un jeton d’accès. Ce jeton doit être passé dans la requête d’accès à une ressource.

Pour fournir le jeton d’accès à AnyWhere, on utilise le Header HTTP Authorization (préférable aux paramètres GET/POST car le jeton pourrait se retrouver dans les logs d’accès du serveur web) avec comme valeur :

Bearer <Access Token>.

La liste des ressources AnyWhere est décrite dans la chapitre "Description des Services"

1.6.  Sécurité

OAuth2 impose l’utilisation de HTTPS pour les échanges entre le client et le serveur d’autorisation du fait des données sensibles qui transitent entre les 2 (jeton d’accès, identifiants et mots de passe, …) :

 

  • Faille dans l’autorisation par code

Il existe une faille dans ce type d’autorisation qui permet à une personne malveillante de voler le compte d’un utilisateur dans certaines conditions. Cette faille revient souvent et a affecté beaucoup de sites connus (Pinterest, SoundCloud, Digg, …) qui n’ont pas correctement implémenté le type d’autorisation par code.

Il existe un moyen d’empêcher cela grâce au paramètre « state » préconisé dans OAuth2. Ce paramètre est seulement recommandé et non obligatoire dans les spécifications. Si le client envoie ce paramètre lors de la demande de code d’autorisation, il sera retourné tel quel par le serveur d’autorisation dans la réponse et pourra donc être comparé par le client avant la demande d’échange du code par un jeton d’accès.

Il est demandé à tout client d’implémenter ce paramètre.

Pour plus information : RFC 6749 — Cross-Site Request Forgery.

 

  • Faille dans l’autorisation implicite

Ce type d’autorisation est le moins sécurisé de tous étant donné qu’il expose le jeton d’accès côté client (Javascript la plupart du temps). Il existe une faille très répandue qui provient du fait que le client ne sait pas si le jeton d’accès a été généré pour lui ou non (Confused Deputy Problem) et qui permet de subtiliser le compte d’une victime.

Pour éviter cela, le serveur d’autorisation doit mettre à disposition dans son API un moyen de récupérer les informations d’un jeton d’accès. Ainsi, le site internet A aurait pu récupérer les informations du jeton d’accès que le pirate avait substitué dans l’url puis aurait comparé le client_id retourné par l’API avec son propreclient_id. Comme le jeton d’accès subtilisé avait été généré pour le site internet B, le client_id aurait été différent du sien et la connexion aurait pu être refusée.

Pour plus information : http://tools.ietf.org/html/rfc6819#section-4.4.2.6

 

  • Clickjacking

Cette technique permet de tromper l’internaute en cachant la page d’autorisation d’accès à ses données dans une iFrame transparente et en l’incitant à cliquer sur un lien qui se situe visuellement sur le bouton « Autoriser » de la page d’autorisation.

Pour éviter cela, il faut que le serveur d’autorisation renvoie un header nommé X-Frame-Options sur sa page d’autorisation avec comme valeur DENY ouSAMEORIGIN. Cela empêche la page d’autorisation d’être affichée dans une iFrame (DENY) ou oblige la concordance du nom de domaine entre l’url de la page appelante et l’url de l’iFrame (SAMEORIGIN).

Ce header n’est pas standard mais est supporté par IE8+, Firefox3.6.9+, Opera10.5+, Safari4+, Chrome 4.1.249.1042+.

Pour plus d’informations : https://developer.mozilla.org/en-US/docs/HTTP/X-Frame-Options 

1.7. Limite d'usage

Pour le moment, il n’y a pas de limite d’usage sur les appels à l’API.

La limitation du nombre d’appel permet de protéger la plateforme IDentité Numérique et l’accès aux informations sensibles de chaque utilisateur. Ainsi, il est prévu que cette limite soit intégrée, filtrant le nombre d’appels par jour pour une application partenaire donnée.

1.8. Révocation

Il y a certains cas pour lesquels une application partenaire peut être révoquée. Si votre application ne parvient plus à obtenir un accès à l’API, veuillez vérifier les points suivants :

  • La validité temporelle de votre jeton d’accès (access_token),
  • Les gestionnaires du service IDentité Numérique ont suspendu votre accès (suite à une limite d’usage atteinte par exemple),
  • L’utilisateur ayant précédemment autorisé votre accès a été suspendu ou supprimé de l’annuaire de l’IDentité Numérique.

1.9. Retour Erreur

Plusieurs erreurs sont possibles. Elles sont retournées sous format Json

Format retour Erreur : (JSON)

Type

(Option) Type de l’erreur (lien vers la référence de l’erreur dans les spécifications OAuth2)

title

Titre de l’erreur

status

Code de retour HTTP

detail

Détails sur l’erreur

Exemple de retour Erreur

		{ 
  "type": "http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html",
  "title":"invalid_request",
  "status": 400,
  "detail": "The grant type was not specified in the request"
}

Liste des erreur possibles sur IDN Oauth (non exhaustif) :

Status
Titre
Description
400 invalid_client Client non renseigné ou invalide
400 bad_request Erreur dans la requête (ex : paramètres absents)
400 unsupported_grant_type Grant Type non autorisé ou invalide
400 invalid_scope Scope non autorisé ou invalide