Appeler votre API avec le flux de code d’autorisation avec une clé de preuve pour l’échange de code (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

Créer un vérificateur de code : Générez un code_verifier qui sera envoyé à Auth0 pour demander des jetons.
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.
Autoriser l’utilisateur : Demandez l’autorisation de l’utilisateur et redirigez-le vers votre application à l’aide d’un authorization_code.
Demande de jeton : Échangez votre authorization_code et votre code_verifier pour des jetons.
Appel d’API : Utilisez le jeton d’accès récupéré pour appeler votre API.
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

Paramètres

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

devez inclure un paramètre d’
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 :

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

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.

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

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.

Intégration d’Auth0

Apprendre les bases

Configuration d’Auth0

Planification et conception

Auth0 AI

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

Prérequis

Étapes

Créer un vérificateur de code

Exemple de JavaScript

Exemple Java

Exemple Android

Échantillon Swift 5

Exemple en Objective-C

Créer un défi de code

Exemple de JavaScript

Exemple Java

Échantillon Swift 5

Exemple en Objective-C

Autoriser l’utilisateur

Exemple d’un URL d’autorisation

Paramètres

Réponse

Demander des jetons

Exemple de POSR à une URL de jeton

Paramètres

Réponse

Appel d’API

Jetons d’actualisation

Exemple de POSR à une URL de jeton

Paramètres

Réponse

Exemples de cas d’utilisation

Personnalisation des jetons

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

En savoir plus

​Prérequis

​Étapes

​Créer un vérificateur de code

​Exemple de JavaScript

​Exemple Java

​Exemple Android

​Échantillon Swift 5

​Exemple en Objective-C

​Créer un défi de code

​Exemple de JavaScript

​Exemple Java

​Échantillon Swift 5

​Exemple en Objective-C

​Autoriser l’utilisateur

​Exemple d’un URL d’autorisation

Paramètres

​Réponse

​Demander des jetons

​Exemple de POSR à une URL de jeton

Paramètres

​Réponse

​Appel d’API

​Jetons d’actualisation

​Exemple de POSR à une URL de jeton

Paramètres

​Réponse

​Exemples de cas d’utilisation

​Personnalisation des jetons

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

​En savoir plus

Prérequis

Étapes

Créer un vérificateur de code

Exemple de JavaScript

Exemple Java

Exemple Android

Échantillon Swift 5

Exemple en Objective-C

Créer un défi de code

Exemple de JavaScript

Exemple Java

Échantillon Swift 5

Exemple en Objective-C

Autoriser l’utilisateur

Exemple d’un URL d’autorisation

Réponse

Demander des jetons

Exemple de POSR à une URL de jeton

Réponse

Appel d’API

Jetons d’actualisation

Exemple de POSR à une URL de jeton

Réponse

Exemples de cas d’utilisation

Personnalisation des jetons

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

En savoir plus