Appeler votre API avec le flux de code d’autorisation avec une clé de preuve pour l’échange de code (PKCE)

Découvrez comment appeler votre API à partir de votre application native, mobile ou à page unique en utilisant le flux Codes d’autorisation à l’aide d’une Proof Key for Code Exchange (PKCE).

Ce tutoriel vous aide à appeler votre propre API à partir d’une application native, mobile ou à page unique en utilisant le flux de code d’autorisation avec PKCE. Pour savoir comment fonctionne le flux et pourquoi vous devriez l’utiliser, consultez Flux de code d’autorisation avec Proof Key for Code Exchange (PKCE). Pour apprendre à ajouter une connexion à votre application native, mobile ou à page unique, consultez Ajout d’une connexion avec le flux de code d’autorisation avec une Proof Key for Code Exchange (PCKE).

Auth0 facilite l’implémentation du Flux de code d’autorisation avec Proof Key for Code Exchange (PKCE) en utilisant :

• Trousse SDK mobile d’Auth0 et trousse SDK pour application Web monopage d’Auth0 : la manière la plus simple d’implémenter le flux, qui fera le gros du travail à votre place. Notre Guide de démarrages rapides mobiles et Guide de démarrages rapides d’applications Web monopages vous guideront tout au long du processus.
• 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 l’application avec Auth0.

  • Sélectionnez un Type d’application entre Natif ou à page unique, en fonction de votre type de demande.
  • Ajoutez une URL de rappel autorisée de {yourCallbackUrl}. Le format de l’URL de rappel varie en fonction du type d’application et de la plateforme. Pour plus de détails sur le format de votre type d’application et de votre plateforme, consultez notre Guide de démarrages rapides natifs/mobiles et Guide de démarrages rapides pour application Web à page unique .
  • Assurez-vous que les Grant Types (Types d’autorisation) de l’application comprennent 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 d’autorisation 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

1. Créer un vérificateur de code : Générez un code_verifier qui sera envoyé à Auth0 pour demander des jetons.
2. Créer un défi-réponse avec code : 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 et redirigez-le vers votre application à l’aide d’un authorization_code.
4. Demande de jeton : Échangez votre authorization_code et votre code_verifier pour des jetons.
5. Appel d’API : Utilisez le jeton d’accès récupéré pour appeler votre API.
6. Jetons d’actualisation : Utilisez un jeton d’actualisation pour demander de nouveaux jetons lorsque les jetons existants expirent.

Facultatif : Découvrez des cas d’utilisation.

​

Créer un vérificateur de code

Créez un code_verifier, qui est une clé cryptographiquement aléatoire encodée en Base64 et qui sera finalement envoyée à Auth0 pour demander des jetons.

​

Exemple de JavaScript

// Dependency: Node.js crypto module
// 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 Java

// Dependency: Apache Commons Codec
// https://commons.apache.org/proper/commons-codec/
// Import the Base64 class.
// 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 Android

// See https://developer.android.com/reference/android/util/Base64
// Import the Base64 class
// 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);

​

Échantillon 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 défi de code

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

​

Exemple de JavaScript

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

​

Exemple Java

// Dependency: Apache Commons Codec
// https://commons.apache.org/proper/commons-codec/
// Import the Base64 class.
// 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);

​

Échantillon 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

// Dependency: Apple Common Crypto library
// 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. Il s’agit techniquement du début du flux d’autorisation, et cette étape peut inclure un ou plusieurs des processus suivants :

* Authentification de l’utilisateur; * Rediriger l’utilisateur vers un fournisseur d’identité pour gérer l’authentification; * Vérification des sessions d’authentification unique (SSO) actives; * Obtention du consentement de l’utilisateur pour le niveau d’autorisation demandé, sauf si le consentement a été préalablement donné.

Pour autoriser l’utilisateur, votre application doit envoyer l’utilisateur vers l’URL d’autorisation, y compris le code_challenge que vous avez généré à l’étape précédente et la méthode que vous avez utilisée pour générer le code_challenge.

​

Exemple d’un URL d’autorisation

https://{yourDomain}/authorize?
    response_type=code&
    code_challenge={codeChallenge}&
    code_challenge_method=S256&
    client_id={yourClientId}&
    redirect_uri={yourCallbackUrl}&
    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	Indique le genre d’identifiant que Auth0 retournera (code ou token). Pour ce flux, la valeur doit être code.
code_challenge	Défi généré par le code_verifier.
code_challenge_method	Méthode utilisée pour générer le défi (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 est seulement prise en charge par Auth0 puisque cette dernière est déconseillée.
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 autorisation accordée par l’utilisateur. Le code d’autorisation sera disponible dans le paramètre URL du code. Vous devez spécifier cette URL comme URL de rappel valide dans vos [Paramètres d’application].(https://manage.auth0.com/#/Applications/{yourClientId}/settings). Avertissement: Selon la spécification OAuth 2.0, Auth0 supprime tout après le hachage et n’honore aucun fragment.
scope	Les permissions pour lesquelles vous voulez demander l’autorisation. Elles doivent être séparées par un espace. Vous pouvez demander l’une des permissions standard OpenID Connect (OIDC) au sujet des utilisateurs, comme le profile et le email, demandes personnalisées conformes à un format avec espace de noms, ou toute permission prise en charge par l’API cible (p. ex., read:contacts). Inclure offline_access pour obtenir un Jeton d’actualisation (assurez-vous que le champ Allow Offline Access est activé dans les Paramètres d’application).
audience	L’identifiant unique de l’API à laquelle votre application mobile souhaite accéder. Utilisez la valeur Identifier dans l’onglet Paramètres pour 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 est ajoutée à la demande initiale que Auth0 inclut lors de la redirection vers votre application. Pour voir comment utiliser cette valeur pour empêcher les attaques de falsification des requêtes entre sites (CSRF), voir Atténuer les attaques CSRF avec les paramètres d’état.
organization	(facultatif) ID de l’organisation à utiliser pour authentifier un utilisateur. Lorsqu’il n’est pas fourni, si votre application est configurée pour Afficher l’invite de l’organisation, l’utilisateur pourra entrer le nom de l’organisation lors de l’authentification.
invitation	(facultatif) Identifiant de billet de l’invitation d’organisation. Au moment d’inviter un membre à une organisation, votre application doit traiter 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 votre URL d’autorisation lorsque vous appelez un API pourrait ressembler à ceci :

<a href="https://{yourDomain}/authorize?
  response_type=code&
  client_id={yourClientId}&
  code_challenge=E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM&
  code_challenge_method=S256&
  redirect_uri={yourCallbackUrl}&
  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: {yourCallbackUrl}?code={authorizationCode}&state=xyzABC123

​

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 en l’envoyant avec le code_verifier.

​

Exemple de POSR à 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 'code_verifier={yourGeneratedCodeVerifier}' \
  --data 'code={yourAuthorizationCode}' \
  --data 'redirect_uri={https://yourApp/callback}'

Paramètres

Nom du paramètre	Description
grant_type	Définissez sur « authorization_code ».
code_verifier	La clé de chiffrement aléatoire qui a été générée à la première étape de ce tutoriel.
code	Le 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 [Paramètres de l’application] (https://manage.auth0.com/#/Applications/{yourClientId}/settings).
redirect_uri	L’URL de rappel valide défini dans les paramètres de votre application. Cela doit correspondre exactement au redirect_uri transmis à 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",
  "expires_in":86400
}

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.

​

Appel d’API

Pour appeler votre API à partir d’une application native/communication entre machines (M2M), 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'

​

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 POSR à 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 des règles pour modifier les permissions renvoyées des jetons d’accès ou ajouter des demandes aux jetons d’accès et d’ID. (Pour en savoir plus sur les règles, lisez Règles d’Auth0). Pour ce faire, ajoutez la règle 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');
};

Les permissions seront disponibles dans le jeton une fois toutes les règles exécutées.

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.

​

Voir l’exemple d’application : Applications mobiles + API

Pour un exemple d’implémentation, consultez le scénario d’architecture Mobile + API. Cette série de tutoriels est accompagnée d’un exemple de code que vous pouvez consulter sur GitHub.

​

En savoir plus

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