Appelez votre API à l’aide du flux de code d’autorisation avec PKCE

Découvrez comment appeler votre API depuis une application Native, mobile ou monopage à l’aide du flux de code d’autorisation avec la clé de preuve pour l’échange de code (PKCE).

Ce tutoriel vous aide à appeler votre propre API à partir d’une application native, mobile ou monopage à l’aide du flux de code d’autorisation avec PKCE. Pour savoir comment ce flux fonctionne et pourquoi vous devriez l’utiliser, consultez Authorization Code Flow with Proof Key for Code Exchange (PKCE). Pour apprendre à ajouter la connexion à votre application native, mobile ou monopage, consultez Add Login Using Authorization Code Flow with PKCE.

Auth0 permet à votre application de mettre facilement en œuvre le flux de code d’autorisation avec clé de preuve pour l’échange de code (PKCE) à l’aide de :

• Auth0 Mobile SDKs et Auth0 Single-Page App SDK : la façon la plus simple de mettre en œuvre ce flux; ces outils feront l’essentiel du travail pour vous. Nos Mobile Quickstarts et Single-Page App Quickstarts vous guideront tout au long du processus.
• 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 l’application dans Auth0.

  • Sélectionnez un type d’application Native ou Single-Page App, selon le type de votre application.
  • Ajoutez une URL de rappel autorisée : {yourCallbackUrl}. Le format de votre URL de rappel varie selon le type de votre application et votre plateforme. Pour en savoir plus sur le format correspondant à votre type d’application et à votre plateforme, consultez nos Quickstarts Native/Mobile et Quickstarts Single-Page App.
  • Assurez-vous que les types d’octroi de l’application comprennent Code d’autorisation. Pour savoir comment faire, consultez Mettre à jour les type d’octroi.
  • Si vous voulez que votre application puisse utiliser des jetons d’actualisation, assurez-vous que les types d’octroi de l’application comprennent Jeton d’actualisation. Pour savoir comment faire, consultez Mettre à jour les type 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 afin de pouvoir obtenir de nouveaux jetons lorsque les précédents expirent, activez Allow Offline Access.

​

Étapes

1. Créer le code verifier: Générez un code_verifier qui sera envoyé à Auth0 pour demander des jetons.
2. Créer le code challenge: Générez un code_challenge à partir du code_verifier, qui sera envoyé à Auth0 pour demander un authorization_code.
3. Autoriser l’utilisateur: Demandez l’autorisation de l’utilisateur, puis redirigez-le vers votre application avec un authorization_code.
4. Demander des jetons: Échangez votre authorization_code et votre code_verifier contre des jetons.
5. Appeler l’API: Utilisez le jeton d’accès récupéré pour appeler votre API.
6. Actualiser les jetons: Utilisez un jeton d’actualisation pour demander de nouveaux jetons lorsque les jetons actuels expirent.

Facultatif : Voir des exemples de cas d’utilisation.

​

Créer le code_verifier

Créez un code_verifier, soit une clé encodée en Base64 générée de façon cryptographiquement aléatoire, qui sera ensuite envoyée à Auth0 pour demander des jetons.

​

Exemple en Javascript

// Dépendance : module crypto de Node.js
// https://nodejs.org/api/crypto.html#crypto_crypto
function base64URLEncode(str) {
    return str.toString('base64')
        .replace(/\+/g, '-')
        .replace(/\//g, '_')
        .replace(/=/g, '');
}
var verifier = base64URLEncode(crypto.randomBytes(32));

​

Exemple en Java

// Dépendance : Apache Commons Codec
// https://commons.apache.org/proper/commons-codec/
// Importez la classe Base64.
// import org.apache.commons.codec.binary.Base64;
SecureRandom sr = new SecureRandom();
byte[] code = new byte[32];
sr.nextBytes(code);
String verifier = Base64.getUrlEncoder().withoutPadding().encodeToString(code);

​

Exemple pour Android

// See https://developer.android.com/reference/android/util/Base64
// Importer la classe Base64
// import android.util.Base64;
SecureRandom sr = new SecureRandom();
byte[] code = new byte[32];
sr.nextBytes(code);
String verifier = Base64.encodeToString(code, Base64.URL_SAFE | Base64.NO_WRAP | Base64.NO_PADDING);

​

Exemple en Swift 5

var buffer = [UInt8](repeating: 0, count: 32)
_ = SecRandomCopyBytes(kSecRandomDefault, buffer.count, &buffer)
let verifier = Data(buffer).base64EncodedString()
    .replacingOccurrences(of: "+", with: "-")
    .replacingOccurrences(of: "/", with: "_")
    .replacingOccurrences(of: "=", with: "")

​

Exemple en Objective-C

NSMutableData *data = [NSMutableData dataWithLength:32];
int result __attribute__((unused)) = SecRandomCopyBytes(kSecRandomDefault, 32, data.mutableBytes);
NSString *verifier = [[[[data base64EncodedStringWithOptions:0]
                        stringByReplacingOccurrencesOfString:@"+" withString:@"-"]
                        stringByReplacingOccurrencesOfString:@"/" withString:@"_"]
                        stringByTrimmingCharactersInSet:[NSCharacterSet characterSetWithCharactersInString:@"="]];

​

Créer un code challenge

Générez un code_challenge à partir du code_verifier, qui sera envoyé à Auth0 pour demander un authorization_code.

​

Exemple en Javascript

// Dépendance : module crypto de Node.js
// https://nodejs.org/api/crypto.html#crypto_crypto
function sha256(buffer) {
    return crypto.createHash('sha256').update(buffer).digest();
}
var challenge = base64URLEncode(sha256(verifier));

​

Exemple en Java

// Dépendance : Apache Commons Codec
// https://commons.apache.org/proper/commons-codec/
// Importation de la classe Base64.
// import org.apache.commons.codec.binary.Base64;
byte[] bytes = verifier.getBytes("US-ASCII");
MessageDigest md = MessageDigest.getInstance("SHA-256");
md.update(bytes, 0, bytes.length);
byte[] digest = md.digest();
String challenge = Base64.encodeBase64URLSafeString(digest);

​

Exemple en Swift 5

import CommonCrypto

// ...

guard let data = verifier.data(using: .utf8) else { return nil }
var buffer = [UInt8](repeating: 0, count: Int(CC_SHA256_DIGEST_LENGTH))
_ = data.withUnsafeBytes {
    CC_SHA256($0.baseAddress, CC_LONG(data.count), &buffer)
}
let hash = Data(buffer)
let challenge = hash.base64EncodedString()
    .replacingOccurrences(of: "+", with: "-")
    .replacingOccurrences(of: "/", with: "_")
    .replacingOccurrences(of: "=", with: "")

​

Exemple en Objective-C

// Dépendance : bibliothèque Apple Common Crypto
// http://opensource.apple.com//source/CommonCrypto
u_int8_t buffer[CC_SHA256_DIGEST_LENGTH * sizeof(u_int8_t)];
memset(buffer, 0x0, CC_SHA256_DIGEST_LENGTH);
NSData *data = [verifier dataUsingEncoding:NSUTF8StringEncoding];
CC_SHA256([data bytes], (CC_LONG)[data length], buffer);
NSData *hash = [NSData dataWithBytes:buffer length:CC_SHA256_DIGEST_LENGTH];
NSString *challenge = [[[[hash base64EncodedStringWithOptions:0]
                         stringByReplacingOccurrencesOfString:@"+" withString:@"-"]
                         stringByReplacingOccurrencesOfString:@"/" withString:@"_"]
                         stringByTrimmingCharactersInSet:[NSCharacterSet characterSetWithCharactersInString:@"="]];

​

Autoriser l’utilisateur

Une fois que vous avez créé le code_verifier et le code_challenge, vous devez obtenir l’autorisation de l’utilisateur. Techniquement, c’est le début du flux d’autorisation, et 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 de permission demandé, à moins que ce consentement n’ait déjà été accordé.

Pour autoriser l’utilisateur, votre application doit le rediriger vers l’URL d’autorisation, en incluant le code_challenge généré à l’étape précédente ainsi que la méthode utilisée pour générer le code_challenge.

​

Exemple d’URL d’autorisation

Paramètres

Notez que pour autoriser un utilisateur lors d’une requête vers une API personnalisée, vous :

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

Parameter Name	Description
response_type	Indique le type d’identifiant qu’Auth0 renverra (code ou token). Pour ce flow, la valeur doit être code.
code_challenge	Challenge généré à partir du code_verifier.
code_challenge_method	Méthode utilisée pour générer le challenge (p. ex., S256). La spécification PKCE définit deux méthodes, S256 et plain; la première est utilisée dans cet exemple et c’est la seule prise en charge par Auth0, puisque la seconde est déconseillée.
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 l’autorisation accordée par l’utilisateur. Le Authorization Code sera disponible dans le paramètre d’URL code. Vous devez indiquer cette URL comme callback URL valide dans vos paramètres de l’application. Avertissement : Conformément à la spécification OAuth 2.0, Auth0 supprime tout ce qui suit le dièse et ne tient pas compte des fragments.
scope	Les scopes pour lesquels vous souhaitez demander une autorisation. Ils doivent être séparés par un espace. Vous pouvez demander n’importe lequel des scopes OpenID Connect (OIDC) standard concernant les utilisateurs, comme profile et email, des custom claims conformes à un format namespaced, 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 mobile souhaite 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é) Chaîne alphanumérique opaque et arbitraire que votre application ajoute à la request 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 falsification de requête intersites (CSRF), consultez Mitigate CSRF Attacks With State Parameters.
organization	(facultatif) ID de l’organisation à utiliser lors de l’authentification d’un utilisateur. Si aucune valeur n’est fournie 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) Ticket ID de l’invitation à l’organisation. Lorsque vous invitez un membre à une Organization, 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.

À titre d’exemple, l’extrait HTML de votre authorization URL lors d’une requête à une API pourrait ressembler à ceci :

​

Réponse

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

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

​

Demander des jetons

Maintenant que vous avez un Authorization Code, vous devez l’échanger contre des jetons. À l’aide de l’Authorization Code (code) extrait à l’étape précédente, vous devrez envoyer une requête POST au URL du jeton en y joignant le code_verifier.

​

Exemple de requête POST au URL du jeton

Paramètres

Nom du paramètre	Description
grant_type	Définissez cette valeur sur « authorization_code ».
code_verifier	La clé générée aléatoirement de façon cryptographiquement sûre à la première étape de ce tutoriel.
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 vos Paramètres 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 dans une 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",
  "expires_in":86400
}

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

Les jetons d’identité contiennent des renseignements sur l’utilisateur qui doivent être décodés puis extraits.

Les jetons d’accès servent à 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 qu’elle devra faire sera de vérifier le jeton d’accès.

Les jetons d’actualisation servent à obtenir un nouveau jeton d’accès ou jeton d’identité 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 le 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 depuis une application native/mobile, l’application doit transmettre le jeton d’accès obtenu comme jeton Bearer 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 requête d’authentification par le 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’a besoin d’un nouveau jeton d’accès qu’après l’expiration du précédent ou lorsqu’il accède à une nouvelle ressource pour la première fois. Il n’est pas recommandé d’appeler le point de terminaison pour obtenir un nouveau jeton d’accès chaque fois que vous faites une requête à une API, et Auth0 applique des limites de débit qui restreignent le nombre de requêtes au point de terminaison pouvant être exécutées avec le même jeton à partir de la même adresse IP.

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

​

Exemple de requête POST vers 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 les Paramètres de l’application.
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 ensemble réduit de portées. Notez que cette valeur doit être encodée pour l’URL.

​

Réponse

Si tout se passe bien, vous recevrez une réponse HTTP 200 dont la charge utile contient un nouvel access_token, sa durée de validité en secondes (expires_in), les valeurs de scope accordées, ainsi que token_type. Si la portée du token initial comprenait openid, la réponse inclura é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 les valider, consultez Valider le jeton d’identité et Valider les jetons d’accès.

​

Exemples de scénarios d’utilisation

​

Personnaliser les jetons

Vous pouvez utiliser les Actions pour modifier les scopes renvoyés dans les Access Tokens et/ou ajouter des claims aux Access Tokens et aux ID Tokens. (Pour en savoir plus sur les Actions, consultez Auth0 Actions. ) Pour ce faire, ajoutez l’Action 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');
};

Les scopes seront disponibles dans le jeton une fois l’Action exécutée.

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

​

Voir un exemple d’application : application mobile + API

Pour un exemple de mise en œuvre, consultez le scénario d’architecture Mobile + API. Cette série de tutoriels s’accompagne d’un exemple de code accessible sur GitHub.

​

En savoir plus

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