Configuration de l’API et des applications mobiles (Applications mobiles + API)

Configuration de l’API et des applications mobiles pour le scénario d’architecture Applications mobiles + API

Dans cette section, nous verrons comment implémenter une API pour notre cas d’utilisation.

Par souci de simplicité, notre implémentation portera uniquement sur l’authentification et l’autorisation. Comme vous le verrez dans les exemples, l’entrée de feuille de temps sera codée en dur, et l’API ne la conservera pas. Elle renverra simplement une partie des informations.

​

Définir les points de terminaison de l’API

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

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

Un point de terminaison d’API est une URL unique qui représente un objet. Pour interagir avec cet objet, votre application doit utiliser 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 au moyen de différentes méthodes HTTP ; par exemple, POST /orders pourrait créer une nouvelle commande, tandis que GET /orders pourrait récupérer les données d’une ou de plusieurs commandes.

Pour cette implémentation, nous ne définirons que deux points de terminaison : l’un pour récupérer la liste de toutes les feuilles de temps d’un employé, et l’autre pour permettre à un employé de créer une nouvelle entrée de feuille de temps.

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

Consultez l’implémentation dans Node.js

​

Sécuriser les points de terminaison

Lorsqu’une API reçoit une requête avec un jeton d’accès de type Bearer dans l’en-tête, la première chose à faire est de valider le jeton. Cela 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 renvoyé à l’application appelante.

Les validations que l’API doit effectuer sont :

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

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

Le processus de validation comprend aussi la vérification des autorisations de l’application (scopes), mais nous traiterons cet aspect 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 l’implémentation dans Node.js

​

Vérifier les autorisations de l’application

À ce stade, nous avons vérifié que le JWT est valide. La dernière étape consiste à vérifier que l’application possède les autorisations requises pour accéder aux ressources protégées.

Pour ce faire, l’API doit vérifier les scopes du JWT décodé. Cette revendication fait partie de la charge utile et consiste en une liste de chaînes séparées par des espaces.

Consultez l’implémentation dans Node.js

​

Déterminer l’identité de l’utilisateur

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

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

L’une des revendications standard d’un JWT est la revendication sub, qui identifie le principal visé par la revendication. Dans le cas du flux Implicit Grant, cette revendication contient l’identité de l’utilisateur, c’est-à-dire l’identifiant unique de l’utilisateur Auth0. Vous pouvez l’utiliser pour associer à un utilisateur précis toute information stockée dans des systèmes externes.

Vous pouvez aussi utiliser une revendication personnalisée pour ajouter un autre attribut de l’utilisateur, comme son adresse de courriel, au Jeton d’accès et vous en servir pour identifier l’utilisateur de façon unique.

Consultez l’implémentation dans Node.js

​

Implémenter l’application mobile

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

Voir l’implémentation sous Android.

​

Autoriser l’utilisateur

Pour autoriser l’utilisateur, nous allons implémenter le Authorization Code Flow with Proof Key for Code Exchange (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 ID client Auth0. Vous pouvez la trouver dans les paramètres de votre application dans l’Auth0 Dashboard.
audience	La valeur de l’identifiant de votre API. Vous pouvez la trouver dans les paramètres de votre API dans l’Auth0 Dashboard.
scope	Les scopes qui déterminent les revendications 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 exemple d’application mobile, nous utilisons les scopes suivants : create:timesheets read:timesheets openid profile email offline_access. Ces scopes permettent à l’application mobile d’appeler l’API, d’obtenir un Jeton d’actualisation et de renvoyer les revendications name, picture et email de l’utilisateur dans l’ID Token.
response_type	Indique le flux d’authentification à 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 uniquement en charge S256.
redirect_uri	L’URL vers laquelle Auth0 redirigera le navigateur une fois que l’utilisateur aura accordé l’autorisation. Le code d’autorisation sera disponible dans le paramètre d’URL code. Cette URL doit être indiquée comme URL de rappel valide dans les paramètres de votre application.

Voir l’implémentation sur Android.

​

Obtenez les identifiants

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

Vous pouvez ensuite échanger l’authorization_code de la réponse contre un jeton d’accès que vous pourrez utiliser pour appeler votre API. Effectuez une requête POST à l’URL du jeton en incluant les données suivantes :

Paramètre	Description
grant_type	Cette valeur doit être définie à authorization_code.
client_id	La valeur de l’ID client Auth0 de votre application. Vous pouvez la récupérer dans les paramètres de votre application dans le Auth0 Dashboard.
code_verifier	Clé aléatoire générée de façon cryptographiquement sécurisée et utilisée pour générer le code_challenge transmis à l’URL d’autorisation (/authorize).
code	Le authorization_code reçu lors de l’appel précédent à /authorize.
redirect_uri	L’URL doit correspondre au redirect_uri transmis dans la section précédente à /authorize.

La réponse renvoyée par l’URL du 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, défini par audience.
• refresh_token : un Jeton d’actualisation n’est présent que si vous avez inclus le scope offline_access ET activé Allow Offline Access pour votre API dans l’Auth0 Dashboard.
• id_token : un ID Token JWT contenant les renseignements de profil de l’utilisateur.
• token_type : une chaîne indiquant le type de jeton; il s’agit toujours d’un jeton Bearer.
• expires_in : le nombre de secondes avant l’expiration du Jeton d’accès.

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

Voir l’implémentation 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, vous devez vérifier la signature et vérifier les revendications du jeton. Après avoir validé l’ID Token, vous pouvez accéder à son payload, qui contient les renseignements sur 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..."
}

Voir l’implémentation pour Android.

​

Afficher conditionnellement des éléments de l’interface utilisateur 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 devez examiner le scope qui lui a été octroyé au moment de l’authentification. Il s’agit d’une chaîne contenant tous les scopes; vous devez donc vérifier si elle contient le scope requis afin de décider s’il faut afficher un élément particulier de l’interface utilisateur.

Voir l’implémentation 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 envoyées à l’API. Pour ce faire, envoyez le Jeton d’accès dans un en-tête Authorization à l’aide du schéma Bearer.

Voir l’implémentation sur Android.

​

Renouveler le jeton

Les jetons d’actualisation 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 jetons d’actualisation sont compromis ou que vous n’en avez plus besoin, vous pouvez les révoquer au moyen de l’Authentication API.

Pour actualiser votre Jeton d’accès, effectuez une requête POST au point de terminaison /oauth/token en utilisant le Jeton d’actualisation obtenu dans votre résultat d’autorisation.

Un Jeton d’actualisation n’est 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 l’Auth0 Dashboard.

Votre requête doit inclure :

Paramètre	Description
grant_type	Doit être défini sur refresh_token.
client_id	La valeur de votre ID client Auth0. Vous pouvez l’obtenir dans les paramètres de votre application dans l’Auth0 Dashboard.
refresh_token	Le Jeton d’actualisation à utiliser, obtenu à partir du résultat d’authentification précédent.

La réponse inclura le nouveau Jeton d’accès :

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

Consultez l’implémentation sur Android.