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

Apprenez à appeler votre propre API à partir d’applications Web standard à l’aide du flux de code d’autorisation.

Ce tutoriel vous aidera à appeler votre propre API en utilisant le flux de code d’autorisation. Pour en savoir plus sur le fonctionnement du flux et pourquoi l’utiliser, voir Flux de code d’autorisation. Si vous souhaitez apprendre comment ajouter la connexion à votre application Web classique, consultez Ajout d’une connexion avec le flux de code d’autorisation.

Auth0 permet à votre application d’implémenter facilement le Code d’autorisation flux à l’aide de(s) :

• Guides de démarrage rapide pour applications Web classiques : la manière la plus simple d’implémenter le flux.
• Authentication API : Si vous préférez créer votre propre solution, continuez à lire pour savoir comment appeler notre API directement.

​

Prérequis

Avant de commencer ce tutoriel :

• Enregistrez votre application avec Auth0.

  • Sélectionnez un Type d’application parmi les Applications Web classiques.
  • Ajoutez une URL de rappel autorisée de {https://yourApp/callback}.
  • Assurez-vous que les Types de consentement de votre application englobent le code d’autorisation. Pour en savoir plus, lisez Mettre à jour les types d’autorisation.
  • Si vous souhaitez que votre application puisse utiliser des jetons d’actualisation, assurez-vous que les types de consentement de l’application incluent le jeton d’actualisation. Pour en savoir plus, lisez Mettre à jour les types d’autorisation. Pour en savoir plus sur les jetons d’actualisation, lisez Jetons d’actualisation.

• Enregistrez votre application avec Auth0

  • Si vous souhaitez que votre API reçoive des jetons d’actualisation afin d’obtenir de nouveaux jetons lorsque les précédents expirent, activez Autoriser l’accès hors ligne.

​

Étapes

accordion.expand_all/accordion.collapse_all

1 Autoriser l’utilisateur

Cette étape peut comprendre un ou plusieurs des procédés suivant :

• Authentifier l’utilisateur
• Redirection de l’utilisateur vers un fournisseur d’identité pour gérer l’authentification
• Vérification des sessions actives d’authentification unique (SSO)
• Obtenir le consentement de l’utilisateur pour le niveau de permission demandé, sauf si obtenu précédemment.

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

​

Exemple d’URL d’autorisation

https://{yourDomain}/authorize?
    response_type=code&
    client_id={yourClientId}&
    redirect_uri={https://yourApp/callback}&
    scope={scope}&
    audience={apiAudience}&
    state={state}

Paramètres

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

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

Nom du paramètre	Description
response_type	Jeton le type d’identifiant qu’Auth0 va retourner (code ou token). Pour ce flux, la valeur doit être code.
client_id	L’ID client de votre application. Vous pouvez trouver cette valeur dans vos Paramètres d’application.
redirect_uri	L’URL vers laquelle Auth0 redirigera le navigateur après que l’autorisation a été accordée par l’utilisateur. Le code d’autorisation sera indiqué dans le paramètre URL code. Vous devez définir cette URL comme une URL de rappel valide dans vos Paramètres d’application. Avertissement : Selon la Spécification OAuth 2.0, Auth0 supprime tout ce qui se trouve après le hachage et n’honore pas les fragments.
scope	Précise les permissions pour lesquelles vous souhaitez demander une autorisation, ce qui dicte les permissions (ou attributs utilisateur) que vous souhaitez voir renvoyées. Elles doivent être séparées par un espace. Vous pouvez demander n’importe lequel des scopes standard OpenID Connect (OIDC) sur les utilisateurs, comme profile ou email, demandes personnalisées conforme à un format d’espace de noms, ou n’importe quelle permission prise en charge par l’API cible (p. ex., read:contacts). Incluez offline_access pour obtenir un Jeton d’actualisation (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 Identifiant dans l’onglet Settings (Paramètres) pour l’API que vous avez déterminée dans le cadre des prérequis pour ce tutoriel.
state	(recommandé) Une chaîne alphanumérique arbitraire opaque que votre application ajoute à la requête initiale qu’Auth0 inclut lorsqu’elle redirige vers votre application. Pour voir comment utiliser cette valeur pour prévenir les attaques de falsification de requête intersites (CSRF), consultez Atténuer les attaques CSRF avec les paramètres d’état.
organization	(facultatif) Identifiant de l’organisation à utiliser lors de l’authentification d’un utilisateur. S’il n’est pas fourni, si votre application est configurée pour afficher l’invite de l’organisation, l’utilisateur pourra saisir le nom de l’organisation lors de l’authentification.
invitation	(facultatif) Identifiant de l’invitation à l’organisation. Lors de l’invitation d’un membre à 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, votre extrait HTML pour l’URL d’autorisation lors de l’ajout de l’enregistrement à votre application peut avoir l’air de ce qui suit :

<a href="https://{yourDomain}/authorize?
  response_type=code&
  client_id={yourClientId}&
  redirect_uri={https://yourApp/callback}&  
  scope=appointments%20contacts&
  audience=appointments:api&
  state=xyzABC123">
  Sign In
</a>

​

Réponse

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

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

2 Demander des jetons

Maintenant que vous avez un code d’authentification, vous pouvez l’échanger pour des jetons. En utilisant le code d’autorisation (code) extrait de l’étape précédente, vous devrez POST sur l’URL du jeton.

​

Exemple d’un POST à une URL de jeton

cURL

curl --request POST \
  --url 'https://{yourDomain}/oauth/token' \
  --header 'content-type: application/x-www-form-urlencoded' \
  --data grant_type=authorization_code \
  --data 'client_id={yourClientId}' \
  --data 'client_secret={yourClientSecret}' \
  --data 'code=yourAuthorizationCode}' \
  --data 'redirect_uri={https://yourApp/callback}'

Paramètres

Nom de paramètres	Description
grant_type	Définir sur authorization_code.
code	authorization_code récupéré à l’étape précédente de ce tutoriel.
client_id	L’ID client de votre application. Vous pouvez trouver cette valeur dans les paramètres de votre application.
client_secret	Le secret client de votre application. Vous pouvez trouver cette valeur dans les paramètres de votre application. Pour en savoir plus sur les méthodes d’authentification d’application disponibles, lisez Identifiants d’applications.
redirect_uri	L’URL de rappel valide définie dans les paramètres de votre Application. Cela doit correspondre exactement à redirect_uri passé à l’ URL d’autorisation à l’étape précédente de ce tutoriel. Notez que cela doit être codé 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 en savoir plus, lisez Valider les jetons d’ID et Valider les jetons d’accès.

Les Jetons d’ID contiennent des informations de 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’Authentication API 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 sont utilisés pour obtenir un nouveau jeton d’accès ou un nouveau 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 permission offline_access et activé Autoriser l’accès hors ligne pour votre API dans le Dashboard.

Les jetons d’actualisation doivent être stockés en toute sécurité car ils permettent aux utilisateurs de rester authentifiés pratiquement indéfiniment.

3 Effectuer un appel à l’API

Pour appeler votre API à partir d’une application web ordinaire, l’application doit transmettre le jeton d’accès récupéré en tant que jeton du porteur dans l’en-tête Authorization (Autorisation) de votre requête HTTP.

cURL

curl --request GET \
  --url https://myapi.com/api \
  --header 'authorization: Bearer {accessToken}' \
  --header 'content-type: application/json'

4 Échange de jetons 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 autoriser l’accès hors ligne
• inclus la permission offline_access lorsque vous avez lancé la demande d’authentification via le point de terminaison d’autorisation.

Vous pouvez utiliser le jeton d’actualisation pour obtenir le nouveau jeton d’accès. Généralement, un utilisateur aura besoin d’un nouveau jeton d’accès uniquement après l’expiration du précédent ou lorsqu’il accède à une nouvelle ressource pour la première fois. Il est déconseillé d’appeler le point de terminaison pour obtenir un nouveau jeton d’accès à chaque fois que vous appelez une API, et Auth0 impose des limites anti-attaques qui réduiront la quantité de requêtes au point de terminaison pouvant être exécutées en utilisant le même jeton depuis la même adresse IP.

Pour actualiser votre jeton, effectuez une requête POST au point de terminaison /oauth/token dans l’Authentication API, à l’aide de grant_type=refresh_token.

Exemple de requête POST à une URL de jeton

cURL

curl --request POST \
  --url 'https://{yourDomain}/oauth/token' \
  --header 'content-type: application/x-www-form-urlencoded' \
  --data grant_type=refresh_token \
  --data 'client_id={yourClientId}' \
  --data 'refresh_token={yourRefreshToken}'

Paramètres

Nom du paramètre	Description
grant_type	Définir ce paramètre à refresh_token.
client_id	L’ID client de votre application. Vous pouvez trouver cette valeur dans vos Paramètres d’application.
refresh_token	Le jeton d’actualisation à utiliser.
scope	(facultatif) Une liste délimitée par des espaces des permissions demandées. Si elle n’est pas envoyée, les permissions originales seront utilisées; sinon vous pouvez demander un ensemble réduit de permissions. Veuillez noter que cela doit être codé URL.

Réponse

Si tout se passe bien, vous recevrez une réponse HTTP 200 avec une charge utile contenant un nouveau access_token, sa durée de vie en secondes (expires_in), les valeurs de permissions accordées et le token_type . Si la permission du jeton initial incluait openid, alors la réponse inclura également un nouveau 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 en savoir plus, lisez Valider les jetons d’ID et Valider les jetons d’accès.

​

Exemples de cas d’utilisation

​

Personnalisation des jetons

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

Pour ce faire, ajoutez l’Action post-connexion suivante, qui s’exécutera après l’authentification de l’utilisateur :

exports.onExecutePostLogin = async (event, api) => {
  // Add custom claims to Access Token and ID Token
  api.accessToken.setCustomClaim('https://foo/bar', 'value');
  api.idToken.setCustomClaim('https://fiz/baz', 'some other value');

  // Modify the scope of the Access Token
  api.accessToken.addScope('foo');
  api.accessToken.addScope('bar');
};

Auth0 renvoie les informations de profil contenues dans un format de demande structuré tel que défini par la spécification OpenID Connect (OIDC). Cela signifie que les demandes personnalisées ajoutées aux jetons d’ID ou aux jetons d’accès doivent respecter des directives et des restrictions pour éviter d’éventuels conflits.

​

En savoir plus

• Cadre d’applications Authorization OAuth 2.0
• Protocole OpenID Connect
• Jetons