Configuration de l’API et du mobile (applications mobiles + API)

Configuration de l’API et du mobile pour le scénario d’architecture Mobile + API

Dans cette section, nous verrons comment implémenter une API pour notre scénario.

Par souci de simplicité, nous limiterons notre mise en œuvre à l’authentification et à l’autorisation. Comme vous le verrez dans les exemples, l’entrée de feuille de temps fournie en entrée sera codée en dur, et l’API n’enregistrera pas cette entrée. Elle se contentera plutôt de renvoyer une partie des informations.

​

Définir les API points de terminaison

Nous devons d’abord définir les points de terminaison de notre API.

Qu’est-ce qu’un API point de terminaison ?

Un API point de terminaison est une URL unique qui représente un objet. Pour interagir avec cet objet, votre application doit pointer vers son URL. Par exemple, si vous aviez une API capable de renvoyer soit des commandes, soit des clients, vous pourriez configurer deux points de terminaison : /orders et /customers. Votre application interagirait avec ces points de terminaison à l’aide de différentes méthodes HTTP; par exemple, POST /orders pourrait créer une nouvelle commande, ou GET /orders pourrait récupérer l’ensemble de données d’une ou de plusieurs commandes.

Pour cette mise en œuvre, nous ne définirons que deux points de terminaison : un pour récupérer la liste de tous les timesheets d’un Employee, et un autre qui permettra à un Employee de créer une nouvelle timesheet entry.

Une requête HTTP GET vers le point de terminaison /timesheets permettra à un utilisateur de récupérer ses timesheets, et une requête HTTP POST vers le point de terminaison /timesheets permettra à un utilisateur d’ajouter une nouvelle timesheet.

Consultez la mise en œuvre dans Node.js

​

Sécuriser les points de terminaison

Lorsqu’une API reçoit une requête avec un jeton d’accès porteur dans l’en-tête, la première chose à faire est de valider le jeton. Ce processus comprend une série d’étapes et, si l’une d’elles échoue, la requête doit être rejetée avec le message d’erreur Missing or invalid token à l’intention de l’application appelante.

Les validations que l’API doit effectuer sont les suivantes :

• Vérifier que le JWT est bien formé
• Vérifier la signature
• Valider les claims standard

JWT.io fournit une liste de bibliothèques qui peuvent faire l’essentiel du travail pour vous : analyser le JWT, vérifier la signature et les claims.

Le processus de validation comprend aussi la vérification des permissions du client (scopes), mais nous y reviendrons séparément dans le paragraphe suivant de ce document.

Pour en savoir plus sur la validation des jetons d’accès, consultez Valider les jetons d’accès.

Consultez la mise en œuvre dans Node.js

​

Vérifier les permissions du client

À ce stade, nous avons vérifié que le JWT est valide. La dernière étape consiste à vérifier que le client dispose des permissions requises pour accéder aux ressources protégées.

Pour ce faire, l’API doit vérifier les scopes du JWT décodé. Ce claim fait partie du payload, et il s’agit d’une liste de chaînes séparées par des espaces.

Voir la mise en œuvre dans Node.js

​

Déterminer l’identité de l’utilisateur

Pour les deux endpoints (récupération de la liste des feuilles de temps et ajout d’une nouvelle feuille de temps), nous devrons déterminer l’identité de l’utilisateur.

Pour récupérer la liste des feuilles de temps, cela permet de nous assurer que nous renvoyons uniquement les feuilles de temps qui appartiennent à l’utilisateur qui fait la requête; et pour ajouter une nouvelle feuille de temps, cela permet de nous assurer que la feuille de temps est associée à l’utilisateur qui fait la requête.

L’une des claims standard d’un JWT est la claim sub, qui identifie le principal auquel la claim s’applique. Dans le cas du flux Implicit Grant, cette claim contiendra l’identité de l’utilisateur, c’est-à-dire l’identifiant unique de l’utilisateur Auth0. Vous pouvez vous en servir pour associer à un utilisateur particulier toute information stockée dans des systèmes externes.

Vous pouvez également utiliser une custom claim pour ajouter un autre attribut de l’utilisateur — comme son adresse courriel — au jeton d’accès et vous en servir pour identifier l’utilisateur de façon unique.

Consultez la mise en œuvre dans Node.js

​

Mettre en œuvre l’application mobile

Dans cette section, nous verrons comment mettre en œuvre une application mobile pour notre scénario.

Voir la mise en œuvre sur Android.

​

Autoriser l’utilisateur

Pour autoriser l’utilisateur, nous mettrons en œuvre le flux de code d’autorisation avec clé de preuve pour l’échange de code (PKCE). L’application mobile doit d’abord rediriger l’utilisateur vers l’URL d’autorisation avec le code_challenge et la méthode utilisée pour le générer :

La requête GET vers l’URL d’autorisation doit inclure les valeurs suivantes :

Parameter	Description
client_id	La valeur de votre Auth0 Client Id. Vous pouvez la trouver dans les Settings de votre Application dans le Auth0 Dashboard.
audience	La valeur de votre API Identifier. Vous pouvez la trouver dans les Settings de votre API dans le Auth0 Dashboard.
scope	Les scopes qui déterminent les claims renvoyées dans l’ID Token et le jeton d’accès. Par exemple, le scope openid renverra un ID Token dans la réponse. Dans notre application mobile d’exemple, nous utilisons les scopes suivants : create:timesheets read:timesheets openid profile email offline_access. Ces scopes permettent à l’application mobile d’effectuer une requête à l’API, d’obtenir un Refresh Token et de renvoyer les claims name, picture et email de l’utilisateur dans l’ID Token.
response_type	Indique le Authentication Flow à utiliser. Pour une application mobile utilisant PKCE, cette valeur doit être définie sur code.
code_challenge	Le code challenge généré à partir du code verifier. Vous trouverez des instructions pour générer un code challenge ici.
code_challenge_method	Méthode utilisée pour générer le challenge. Auth0 prend en charge uniquement S256.
redirect_uri	L’URL vers laquelle Auth0 redirigera le navigateur une fois que l’utilisateur aura accordé l’autorisation. L’Authorization Code sera disponible dans le paramètre d’URL code. Cette URL doit être indiquée comme callback URL valide dans les Settings de votre Application.

Voir la mise en œuvre dans Android.

​

Obtenir les identifiants

Après avoir envoyé une requête à l’URL d’autorisation avec succès, vous devriez recevoir la réponse suivante :

Ensuite, vous pouvez échanger l’authorization_code de la réponse contre un jeton d’accès qui peut être utilisé pour faire des requêtes à votre API. Effectuez une requête POST vers l’URL du jeton en incluant les données suivantes :

Paramètre	Description
grant_type	Cette valeur doit être définie sur authorization_code.
client_id	La valeur de votre Auth0 Client Id. Vous pouvez l’obtenir dans les Settings de votre Application, dans l’Auth0 Dashboard.
code_verifier	Clé aléatoire sécurisée sur le plan cryptographique qui a servi à générer le code_challenge transmis à l’URL d’autorisation (/authorize).
code	Le authorization_code reçu de la requête authorize précédente.
redirect_uri	L’URL doit correspondre au redirect_uri transmis dans la section précédente à /authorize.

La réponse de l’URL de jeton contiendra :

{
  "access_token": "eyJz93a...k4laUWw",
  "refresh_token": "GEbRxBN...edjnXbL",
  "id_token": "eyJ0XAi...4faeEoQ",
  "token_type": "Bearer",
  "expires_in":86400
}

• access_token: un jeton d’accès pour l’API, précisé par l’audience.
• refresh_token: un Refresh Token ne sera présent que si vous avez inclus le scope offline_access ET activé Allow Offline Access pour votre API dans le Dashboard.
• id_token: un ID Token JWT contenant des renseignements du profil utilisateur.
• token_type: une chaîne indiquant le type de jeton; il s’agira toujours d’un jeton Bearer.
• expires_in: le nombre de secondes avant l’expiration du jeton d’accès.

Vous devrez stocker les identifiants ci-dessus dans le stockage local afin de les utiliser pour appeler votre API et récupérer le profil utilisateur.

Voir la mise en œuvre sur Android.

​

Récupérer le profil de l’utilisateur

Pour récupérer le profil de l’utilisateur, votre application mobile peut décoder le ID Token à l’aide de l’une des bibliothèques JWT. Pour ce faire, il faut vérifier la signature et vérifier les claims du token. Après avoir validé l’ID Token, vous pouvez accéder à son payload, qui contient les renseignements de l’utilisateur :

{
  "email_verified": false,
  "email": "[e-mail]",
  "clientID": "q2hnj2iu...",
  "updated_at": "2016-12-05T15:15:40.545Z",
  "name": "[e-mail]",
  "picture": "https://s.gravatar.com/avatar/dummy.png",
  "user_id": "auth0|58454...",
  "nickname": "test.account",
  "created_at": "2016-12-05T11:16:59.640Z",
  "sub": "auth0|58454..."
}

Consultez la mise en œuvre sur Android.

​

Afficher des éléments de l’interface utilisateur de façon conditionnelle selon le scope

Selon le scope de l’utilisateur, vous pourriez vouloir afficher ou masquer certains éléments de l’interface utilisateur. Pour déterminer le scope accordé à un utilisateur, vous devrez examiner le scope qui lui a été accordé au moment de son authentification. Il s’agira d’une chaîne contenant tous les scopes; vous devrez donc l’examiner pour vérifier si elle contient le scope requis et décider, en conséquence, s’il faut afficher un élément particulier de l’interface utilisateur.

Voir la mise en œuvre sur Android

​

Appeler l’API

Pour accéder aux ressources sécurisées de votre API, le jeton d’accès de l’utilisateur authentifié doit être inclus dans les requêtes qui y sont envoyées. Pour ce faire, envoyez le jeton d’accès dans un en-tête Authorization en utilisant le schéma Bearer.

Voir la mise en œuvre sur Android.

​

Actualiser le jeton

Les Refresh Tokens doivent être stockés de manière sécurisée par une application, puisqu’ils n’expirent pas et permettent à un utilisateur de rester authentifié pratiquement indéfiniment. Si des Refresh Tokens sont compromis ou si vous n’en avez plus besoin, vous pouvez les révoquer à l’aide de l’Authentication API.

Pour actualiser votre jeton d’accès, envoyez une requête POST au point de terminaison /oauth/token à l’aide du Refresh Token obtenu dans votre résultat d’autorisation.

Un Refresh Token ne sera présent que si vous avez inclus le scope offline_access dans la requête d’autorisation précédente et activé Allow Offline Access pour votre API dans le Dashboard.

Votre requête doit inclure :

Paramètre	Description
grant_type	Ce paramètre doit être défini à refresh_token.
client_id	La valeur de votre Auth0 Client Id. Vous pouvez l’obtenir dans les Settings de votre Application dans l’Auth0 Dashboard.
refresh_token	le Refresh Token à utiliser, provenant du résultat d’authentification précédent.

La réponse comprendra le nouveau jeton d’accès :

{
  "access_token": "eyJz93a...k4laUWw",
  "refresh_token": "GEbRxBN...edjnXbL",
  "id_token": "eyJ0XAi...4faeEoQ",
  "token_type": "Bearer",
  "expires_in":86400
}

Voir la mise en œuvre sur Android.