Appeler votre API à l’aide du flux hybride

Découvrez comment utiliser le flux hybride afin que votre application puisse se servir d’un jeton d’identité pour accéder aux informations sur l’utilisateur, tout en obtenant un code d’autorisation pouvant être échangé contre un Jeton d’accès.

Ce tutoriel vous aidera à appeler votre propre API à l’aide du Hybrid Flow. Si vous souhaitez comprendre le fonctionnement de ce flux et pourquoi l’utiliser, consultez Hybrid Flow.

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

• Authentication API : Si vous préférez créer votre propre solution, poursuivez votre lecture pour découvrir comment appeler directement notre API.

​

Prérequis

Avant de commencer ce tutoriel :

• Enregistrez votre application dans Auth0.

  • Sélectionnez le Application Type approprié.
  • Ajoutez une Allowed Callback URL de {https://yourApp/callback}.
  • Assurez-vous que les Grant Types de votre application incluent Implicit et Authorization Code. Pour savoir comment faire, consultez Update Grant Types.
  • Si vous voulez que votre application puisse utiliser des Jetons d’actualisation, assurez-vous que les Grant Types de l’application incluent Jeton d’actualisation. Pour savoir comment faire, consultez Update Grant Types. Pour en savoir plus sur les Jetons d’actualisation, consultez Refresh Tokens.

• Enregistrez votre API dans Auth0

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

​

Étapes

1. Autoriser l’utilisateur: Demandez à l’utilisateur d’autoriser l’accès, puis redirigez-le vers votre application avec un code d’autorisation.
2. Demander des jetons: Échangez votre code d’autorisation contre des jetons.
3. Appeler l’API: Utilisez le Jeton d’accès obtenu pour appeler votre API.
4. Actualiser les jetons: Utilisez un Jeton d’actualisation pour demander de nouveaux jetons lorsque les jetons actuels expirent.

Facultatif : Explorer des exemples de cas d’utilisation

​

Autoriser l’utilisateur

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

• Authentifier l’utilisateur
• Rediriger l’utilisateur vers un fournisseur d’identité pour prendre en charge l’authentification
• Vérifier s’il existe des sessions d’authentification unique (SSO) actives
• Obtenir le consentement de l’utilisateur pour le niveau d’autorisation demandé, sauf si ce consentement a déjà été accordé.

Pour autoriser l’utilisateur, votre application doit le rediriger 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 retournera (code ou token). Pour ce flux, la valeur doit inclure code, mais peut aussi inclure id_token, token ou id_token token. Plus précisément, id_token retourne un ID Token, et token retourne un Jeton d’accès.
response_mode	Spécifie la façon dont les paramètres de réponse doivent être renvoyés. Pour des raisons de sécurité, la valeur devrait être form_post. Dans ce mode, les paramètres de réponse sont encodés comme des valeurs de formulaire HTML transmises au moyen de la méthode HTTP POST et encodées dans le corps à l’aide du format application/x-www-form-urlencoded.
client_id	L’ID client de votre application. Vous trouverez cette valeur dans vos paramètres de l’application.
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. 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 se trouve après le hash et ne tient pas compte des fragments.
scope	Spécifie les scopes pour lesquels vous souhaitez demander une autorisation, lesquels déterminent quelles claim (ou quels attributs d’utilisateur) vous voulez obtenir en retour. Ils doivent être séparés par une espace. Vous pouvez demander n’importe lequel des scopes OpenID Connect (OIDC) standards sur les utilisateurs, comme profile ou email, des custom claims 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 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 veut accéder. Utilisez la valeur Identifier dans l’onglet Settings de l’API que vous avez créée dans le cadre des prérequis de ce tutoriel.
state	(recommandé) Une chaîne alphanumérique opaque et arbitraire que votre application ajoute à la requête initiale et qu’Auth0 inclut lors de la redirection vers votre application. Pour savoir comment utiliser cette valeur afin de prévenir les attaques de type falsification de requête intersite (CSRF), consultez Atténuer les attaques CSRF avec les paramètres state.
nonce	Une chaîne aléatoire cryptographiquement sécurisée que votre application ajoute à la requête initiale et qu’Auth0 inclut dans l’ID Token, utilisée pour prévenir les attaques par rejeu de jeton.
organization	(facultatif) ID de l’organisation à utiliser lors de l’authentification d’un utilisateur. S’il n’est pas fourni et que votre application est configurée pour Display Organization Prompt, l’utilisateur pourra saisir le nom de l’organisation lors de l’authentification.
invitation	(facultatif) ID du ticket d’invitation à l’organisation. Lors de l’invitation d’un membre dans une Organisation, votre application doit gérer l’acceptation de l’invitation en transférant les paires clé-valeur invitation et organization lorsque l’utilisateur accepte l’invitation.

À titre d’exemple, votre extrait HTML pour l’URL d’autorisation lors de l’ajout de la connexion à votre application pourrait ressembler à ceci :

​

Réponse

Si tout se passe bien, vous recevrez une réponse HTTP 302. Les identifiants demandés sont encodés dans le corps de la réponse :

HTTP/1.1 302 Found
Content-Type: application/x-www-form-urlencoded
code=AUTHORIZATION_CODE&
access_token=ey...MhPw
&expires_in=7200
&token_type=Bearer
id_token=eyJ...acA&
state=xyzABC123

Notez que les valeurs renvoyées dépendent de ce que vous avez demandé comme response_type.

Type de réponse	Composants
code	code d’autorisation
id_token	ID Token
token	Jeton d’accès (ainsi que les valeurs expires_in et token_type)
id_token token	ID Token, Jeton d’accès (ainsi que les valeurs expires_in et token_type)

Auth0 renverra également toute valeur state que vous avez incluse dans votre appel à l’URL d’autorisation.

Le Jeton d’accès que vous recevez dans cette transaction n’est que le premier Jeton d’accès qui vous sera renvoyé. Nous vous déconseillons de l’utiliser pour appeler des API.

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

Lorsque vous décodez et analysez votre jeton d’identité, vous remarquerez une revendication supplémentaire, c_hash, qui contient un hash du code. Cette revendication est obligatoire lorsqu’un jeton d’identité est émis en même temps qu’un code, et vous devriez la valider :

1. À l’aide de l’algorithme de hachage indiqué dans la revendication alg de l’en-tête du ID Token, hachez les octets de la représentation ASCII du code.
2. Encodez en Base64url la moitié gauche du hash.
3. Vérifiez que le résultat correspond à la valeur c_hash.

​

Obtenir des jetons

Maintenant que vous avez un code d’autorisation, vous devez l’échanger contre des jetons. À l’aide du code d’autorisation (code) extrait à l’étape précédente, vous devez envoyer une requête POST à l’URL du jeton.

Le Jeton d’accès que vous recevez à cette étape est celui que vous devez utiliser pour appeler votre API. Assurez-vous de le conserver séparément du Jeton d’accès reçu à l’étape précédente de ce tutoriel.

​

Exemple de requête POST à l’URL du jeton

Paramètres

Nom du paramètre	Description
grant_type	Définissez cette valeur sur authorization_code.
code	Le authorization_code obtenu à l’étape précédente de ce tutoriel.
client_id	L’ID client 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 Application Credentials.
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 au format URL.

​

Réponse

Si tout se passe bien, vous recevrez une réponse HTTP 200 avec un payload 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 faire, consultez Valider les ID tokens et Valider les jetons d’accès.

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

Les jetons d’accès servent à appeler le point de terminaison /userinfo de l’Auth0 Authentication API ou une autre API. Si vous appelez votre propre API, la première chose à faire pour votre API sera de vérifier le jeton d’accès.

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

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.

​

Appeler l’API

Pour appeler votre API à partir d’une Application Web régulière (ou dans des cas similaires où les identifiants de l’application peuvent être stockés de manière sécuritaire), l’application doit inclure le Jeton d’accès récupéré comme Bearer Token dans l’en-tête Authorization de la requête HTTP.

​

Jetons d’actualisation

Vous avez déjà reçu un jeton d’actualisation si vous avez suivi ce tutoriel et effectué les étapes suivantes :

• configuré votre API pour autoriser l’accès hors ligne
• inclus le scope offline_access lorsque vous avez lancé la demande d’authentification au moyen du point de terminaison d’autorisation.

Vous pouvez utiliser le Jeton d’actualisation pour obtenir un nouveau jeton d’accès. En général, un utilisateur n’a besoin d’un nouveau jeton d’accès qu’après l’expiration du précédent ou lors du premier accès à une nouvelle ressource. 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 applique des limites de débit qui limiteront le nombre de requêtes vers ce point de terminaison pouvant être exécutées avec le même jeton depuis la même adresse IP.

Pour actualiser votre jeton, envoyez une requête POST au point de terminaison /oauth/token de l’Authentication API, en utilisant grant_type=refresh_token.

​

Exemple de requête POST à l’URL du jeton

Paramètres

Nom du paramètre	Description
grant_type	Définissez cette valeur sur refresh_token.
client_id	L’ID client de votre application. Vous trouverez cette valeur dans vos paramètres de l’application.
refresh_token	Le jeton d’actualisation à utiliser.
scope	(facultatif) Une liste de scopes demandés, séparés par des espaces. S’il n’est pas envoyé, les scopes d’origine seront utilisés; sinon, vous pouvez demander un ensemble réduit de scopes. Notez que cette valeur doit être encodée URL.

​

Réponse

Si tout se passe bien, vous recevrez une réponse HTTP 200 avec un payload contenant un nouvel access_token, sa durée de validité en secondes (expires_in), les valeurs de scope accordées et le token_type. Si le scope du jeton initial comprenait 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 faire, consultez Valider les ID Tokens et Valider les jetons d’accès.

​

Exemples de cas d’utilisation

​

Personnaliser les jetons

Vous pouvez utiliser des Rules pour modifier les scopes renvoyés dans les jetons d’accès et/ou ajouter des claim aux jetons d’accès et aux ID Tokens. (Pour en savoir plus sur les Rules, consultez Auth0 Rules.) Pour ce faire, ajoutez la Rule suivante, qui s’exécutera après l’authentification de l’utilisateur :

exports.onExecutePostLogin = async (event, api) => {
  // Ajouter des claim 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 le scope du jeton d'accès
  api.accessToken.addScope('foo');
  api.accessToken.addScope('bar');
};

Les scopes seront disponibles dans le jeton après l’exécution de toutes les Rules.

Auth0 renvoie les informations de profil sous forme de claim structurées, conformément à la spécification OpenID Connect (OIDC). Cela signifie que les claim personnalisées ajoutées aux ID tokens ou aux jetons d’accès doivent respecter les directives et les restrictions afin d’éviter d’éventuelles collisions.

​

En savoir plus

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