Appeler votre API à l’aide du flux de code d’autorisation

Découvrez comment appeler votre propre API depuis des applications Web traditionnelles à l’aide du flux de code d’autorisation.

Ce tutoriel vous aidera à appeler votre propre API à l’aide du flux de code d’autorisation. Si vous souhaitez comprendre le fonctionnement de ce flux et pourquoi vous devriez l’utiliser, consultez flux de code d’autorisation. Si vous souhaitez apprendre à ajouter une fonctionnalité de connexion à votre application web traditionnelle, consultez Add Login Using the flux de code d’autorisation.

Auth0 permet à votre application d’implémenter facilement le flux de code d’autorisation à l’aide de :

• Quickstarts pour les applications web traditionnelles : La façon la plus simple d’implémenter ce flux.
• Authentication API : Si vous préférez créer votre propre solution, poursuivez votre lecture pour apprendre à appeler directement notre API.

​

Prérequis

Avant de commencer ce tutoriel :

• Enregistrez votre application dans Auth0.

  • Sélectionnez le Type d’application Regular Web Apps.
  • Ajoutez l’URL de rappel autorisée {https://yourApp/callback}.
  • Assurez-vous que les Types d’octroi de votre application incluent le Code d’autorisation. Pour savoir comment faire, consultez Mettre à jour les types d’octroi.
  • Si vous voulez que votre application puisse utiliser des jetons d’actualisation, assurez-vous que les Types d’octroi de l’application incluent le jeton d’actualisation. Pour savoir comment faire, consultez Mettre à jour les types d’octroi. Pour en savoir plus sur les jetons d’actualisation, consultez jetons d’actualisation.

• Enregistrez votre API dans Auth0

  • Si vous voulez que votre API reçoive des jetons d’actualisation pour pouvoir obtenir de nouveaux jetons lorsque les précédents expirent, activez Allow Offline Access.

​

Étapes

Autoriser un utilisateur

Cette étape peut inclure un ou plusieurs des processus suivants :

• Authentifier l’utilisateur
• Rediriger l’utilisateur vers un fournisseur d’identité pour gérer l’authentification
• Vérifier la présence de sessions actives d’authentification unique (SSO)
• Obtenir le consentement de l’utilisateur pour le niveau de permission demandé, sauf si ce consentement a déjà été accordé.

Pour autoriser l’utilisateur, votre application doit rediriger l’utilisateur vers l’URL d’autorisation.

​

Exemple d’URL d’autorisation

Paramètres

Notez que pour autoriser un utilisateur lors de l’appel d’une API personnalisée, vous :

• devez inclure un paramètre audience
• pouvez inclure des scopes supplémentaires pris en charge par l’API cible

Nom du paramètre	Description
response_type	Indique le type d’identifiant qu’Auth0 renverra (code ou token). Pour ce flux, la valeur doit être code.
client_id	Le Client ID de votre application. Vous trouverez cette valeur dans les Paramètres de l’application.
redirect_uri	L’URL vers laquelle Auth0 redirigera le navigateur une fois que l’autorisation aura été accordée par l’utilisateur. Le code d’autorisation sera disponible dans le paramètre d’URL code. Vous devez indiquer cette URL comme URL de rappel valide dans vos Paramètres de l’application. Avertissement : Conformément à la spécification OAuth 2.0, Auth0 supprime tout ce qui suit le hash et ne prend pas en charge les fragments.
scope	Précise les scopes pour lesquels vous souhaitez demander une autorisation, lesquels déterminent quelles claims (ou quels attributs utilisateur) vous souhaitez voir renvoyés. Ceux-ci doivent être séparés par une espace. Vous pouvez demander n’importe lequel des scopes OpenID Connect (OIDC) standard concernant les utilisateurs, comme profile ou email, des claims personnalisées conformes à un format avec espace de noms, ou tout scope pris en charge par l’API cible (p. ex. read:contacts). Incluez offline_access pour obtenir un Refresh Token (assurez-vous que le champ Allow Offline Access est activé dans les Paramètres de l’application).
audience	L’identifiant unique de l’API à laquelle votre application web veut accéder. Utilisez la valeur Identifier dans l’onglet Paramètres de l’API que vous avez créée dans le cadre des prérequis de ce tutoriel.
state	(recommandé) Une chaîne alphanumérique arbitraire opaque que votre application ajoute à la requête initiale et qu’Auth0 inclut lors de la redirection vers votre application. Pour voir comment utiliser cette valeur afin de prévenir les attaques de falsification de requêtes intersites (CSRF), consultez Mitiger les attaques CSRF avec les paramètres d’état.
organization	(facultatif) ID de l’organisation à utiliser lors de l’authentification d’un utilisateur. Lorsqu’il n’est pas fourni, si votre application est configurée pour Display Organization Prompt, l’utilisateur pourra saisir le nom de l’organisation au moment de l’authentification.
invitation	(facultatif) ID du ticket d’invitation à l’organisation. Lorsque vous invitez un membre dans une organisation, votre application doit gérer l’acceptation de l’invitation en transmettant les paires clé-valeur invitation et organization lorsque l’utilisateur accepte l’invitation.

Par exemple, l’extrait HTML de votre URL d’autorisation pourrait ressembler à ceci lorsque vous ajoutez la connexion à votre application :

​

Réponse

Si tout se passe bien, vous recevrez une réponse HTTP 302. Le code d’autorisation est inclus à la fin de l’URL :

HTTP/1.1 302 Found
Location: {https://yourApp/callback}?code={authorizationCode}&state=xyzABC123

Jetons de requête

Maintenant que vous disposez d’un code d’autorisation, vous devez l’échanger contre des jetons. À l’aide du code d’autorisation extrait (code) à l’étape précédente, vous devrez effectuer un POST vers l’URL du jeton.

​

Exemple de POST vers l’URL du jeton

Paramètres

Nom du paramètre	Description
grant_type	Réglez ce paramètre à authorization_code.
code	Le authorization_code récupéré à l’étape précédente de ce tutoriel.
client_id	Le Client ID de votre application. Vous trouverez cette valeur dans les Paramètres de l’application.
client_secret	Le secret client de votre application. Vous trouverez cette valeur dans les paramètres de l’application. Pour en savoir plus sur les méthodes d’authentification d’application disponibles, consultez Identifiants de l’application.
redirect_uri	L’URL de rappel valide définie dans les paramètres de votre application. Elle doit correspondre exactement au redirect_uri transmis à l’URL d’autorisation à l’étape précédente de ce tutoriel. Notez qu’elle doit être encodée pour une URL.

​

Réponse

Si tout se passe bien, vous recevrez une réponse HTTP 200 avec une charge utile contenant les valeurs access_token, refresh_token, id_token et token_type :

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

Validez vos jetons avant de les enregistrer. Pour savoir comment, consultez Valider les jetons d’identité et Valider les jetons d’accès.

Les jetons d’ID contiennent des informations sur l’utilisateur qui doivent être décodées et extraites.

Les jetons d’accès sont utilisés pour appeler le point de terminaison /userinfo de l’API d’authentification Auth0 ou une autre API. Si vous appelez votre propre API, la première chose que votre API devra faire est de vérifier le jeton d’accès.

Les jetons d’actualisation servent à obtenir un nouveau jeton d’accès ou un jeton d’ID après l’expiration du précédent. Le refresh_token ne sera présent dans la réponse que si vous avez inclus la portée offline_access et activé Allow Offline Access pour votre API dans le tableau de bord.

Les jetons d’actualisation doivent être stockés de façon sécurisée, puisqu’ils permettent à un utilisateur de rester authentifié pratiquement indéfiniment.

Effectuez un appel d’API

Pour appeler votre API à partir d’une application Web traditionnelle, l’application doit transmettre le jeton d’accès récupéré comme jeton Bearer dans l’en-tête Authorization de votre requête HTTP.

Échanger un jeton d’actualisation

Vous avez déjà reçu un jeton d’actualisation si vous avez suivi ce tutoriel et complété ce qui suit :

• configuré votre API pour permettre l’accès hors ligne
• inclus la portée offline_access lorsque vous avez lancé la requête d’authentification au moyen du point de terminaison authorize.

Vous pouvez utiliser le Refresh Token pour obtenir un nouveau jeton d’accès. En général, un utilisateur n’aura besoin d’un nouveau jeton d’accès qu’après l’expiration du précédent ou lors de l’accès à une nouvelle ressource pour la première fois. Il est déconseillé d’envoyer une requête à l’endpoint pour obtenir un nouveau jeton d’accès chaque fois que vous effectuez une requête vers une API. Auth0 applique des limites de débit qui restreignent le nombre de requêtes vers l’endpoint pouvant être exécutées avec le même jeton depuis la même adresse IP.

Pour actualiser votre jeton, effectuez une requête POST vers le point de terminaison /oauth/token de l’API d’authentification, en utilisant grant_type=refresh_token.

Exemple de POST vers l’URL du jeton

Paramètres

Nom du paramètre	Description
grant_type	Réglez cette valeur sur refresh_token.
client_id	Le Client ID de votre application. Vous trouverez cette valeur dans Application Settings.
refresh_token	Le jeton d’actualisation à utiliser.
scope	(facultatif) Une liste des portées demandées, séparées par des espaces. Si ce paramètre n’est pas envoyé, les portées d’origine seront utilisées ; sinon, vous pouvez demander un sous-ensemble de portées. Notez que ce paramètre doit être encodé dans l’URL.

Réponse

Si tout se passe bien, vous recevrez une réponse HTTP 200 avec une charge utile contenant un nouvel access_token, sa durée de vie en secondes (expires_in), les valeurs de scope accordées et le token_type. Si le scope du jeton initial incluait openid, la réponse comprendra également un nouvel id_token :

{
  "access_token": "eyJ...MoQ",
  "expires_in": 86400,
  "scope": "openid offline_access",
  "id_token": "eyJ...0NE",
  "token_type": "Bearer"
}

Validez vos jetons avant de les enregistrer. Pour savoir comment, consultez Valider les jetons d’identité et Valider les jetons d’accès.

​

Exemples de scénarios d’utilisation

​

Personnaliser les jetons

Vous pouvez utiliser Auth0 Actions pour modifier les scopes d’un jeton d’accès et/ou ajouter des claims personnalisées aux jetons d’accès et aux jetons d’identification. Pour en savoir plus sur Auth0 Actions, consultez Comprendre le fonctionnement d’Auth0 Actions.

Pour ce faire, ajoutez l’Action Post-Login suivante, qui s’exécutera une fois l’utilisateur authentifié :

exports.onExecutePostLogin = async (event, api) => {
  // Ajouter des revendications personnalisées au jeton d'accès et au jeton d'identité
  api.accessToken.setCustomClaim('https://foo/bar', 'value');
  api.idToken.setCustomClaim('https://fiz/baz', 'some other value');

  // Modifier la portée du jeton d'accès
  api.accessToken.addScope('foo');
  api.accessToken.addScope('bar');
};

Auth0 renvoie les informations du profil dans un format de claim structuré, tel que défini par la spécification OpenID Connect (OIDC). Cela signifie que les claims personnalisés ajoutés aux ID tokens ou aux jetons d’accès doivent respecter les directives et les restrictions afin d’éviter d’éventuels conflits.

​

En savoir plus

• Cadre d’autorisation OAuth 2.0
• Protocole OpenID Connect
• Jetons