Ajouter une connexion avec le flux de code d’autorisation avec une clé de preuve pour l’échange de code (PKCE)

Comment ajouter une connexion à votre application native, mobile ou à page unique en utilisant le flux de code d’autorisation avec Proof Key for Code Exchange (PKCE).

Vous pouvez ajouter une connexion à votre 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 à appeler votre API à partir d’une application native, mobile ou à page unique, consultez Appeler votre API en utilisant le flux de code d’autorisation avec PKCE.

Pour implémenter le flux de code d’autorisation avec Proof Key for Code Exchange (PKCE), consultez les ressources suivantes :

• Trousses SDK Auth0 Mobile et Trousse SDK Auth0 pour applications à page unique : Manière la plus simple d’implémenter le flux, qui fera le gros du travail à votre place. Nos Démarrages rapides Mobile et Démarrages rapides pour applications à page unique vous guideront tout au long du processus.
• Authentication API : Si vous préférez créer votre propre solution, poursuivez la lecture pour savoir comment appeler notre API directement.

Une fois la connexion réussie, votre application aura accès au jeton d’ID et au jeton d’accès de l’utilisateur. Le jeton d’ID contient des informations de base sur le profil utilisateur, et le jeton d’accès peut être utilisé pour appeler le point de terminaison Auth0 /userinfo ou vos propres API protégées. Pour en savoir plus sur les jetons d’ID, consultez Jetons d’ID. Pour en savoir plus sur les jetons d’accès, consultez Jetons d’accès.

​

Prérequis

Enregistrez votre application auprès d’Auth0. Pour en apprendre davantage, consultez Enregistrement d’applications natives ou Enregistrement d’applications Web à page unique.

• Sélectionnez un type d’applicationnative ou à page unique, selon le type de votre application.
• Ajoutez une URL de rappel autorisée de VOTRE_URL_RAPPEL. 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 correspondant à votre type d’application et à votre plateforme, consultez Démarrages rapides Native/Mobile et Démarrages rapides Application à page unique.
• Assurez-vous que les Grant Types (Types d’autorisation) de votre application comprennent le code d’autorisation. Pour en savoir plus, lisez Mettre à jour les types d’autorisation.

​

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.

Pour en savoir plus sur l’algorithme de création du code_verifier, consultez la section 4.1 Client crée un vérificateur de code des spécifications de OAuth Proof Key for Code Exchange (PKCE).

​

Exemple 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

// 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.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 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.

Pour en savoir plus sur la façon dont le code_challenge est dérivé du code_verifier, consultez la section 4.2 Client crée le défi du code des spécifications de OAuth Proof Key for Code Exchange (PKCE).

​

Exemple 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 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

Demandez l’autorisation de l’utilisateur et redirigez-le vers votre application à l’aide d’un authorization_code.

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’URL d’autorisation

https://{yourDomain}/authorize?
    response_type=code&
    code_challenge={codeChallenge}&
    code_challenge_method=S256&
    client_id={yourClientId}&
    redirect_uri={yourCallbackUrl}&
    scope={scope}&
    state={state}

​

Paramètres

Nom du paramètre	Description
response_type	Indique le type d’identifiant qu’Auth0 va retourner (code ou jeton). Pour ce flux, la valeur doit être code
code_challenge	Défi généré à partir du code_verifier.
code_challenge_method	Méthode utilisée pour générer le défi (par exemple, S256). La spécification PKCE définit deux méthodes, S256 et plain, la première étant utilisée dans cet exemple et la seule prise en charge par Auth0 puisque la seconde est déconseillée.
client_id	L’ID client de votre application. Vous pouvez trouver cette valeur dans les paramètres de l’application.
redirect_uri	URL vers laquelle Auth0 redirigera le navigateur une fois que l’autorisation aura été accordée par l’utilisateur. Vous devez spécifier cette URL en tant qu’URL de rappel valide dans les paramètre de l’application. <br /&gt ; <br /&gt ; Attention: Conformément à la spécification OAuth 2.0, Auth0 supprime tout ce qui se trouve après le hachage et n’accepte pas les fragments.
scope	Indique les permissions pour lesquels vous souhaitez demander une autorisation, ce qui dicte les demandes (ou les attributs d’utilisateur) que vous souhaitez voir renvoyées. Ils doivent être séparés par un espace. Pour obtenir un jeton d’ID dans la réponse, vous devez spécifier une permission d’au moins openid. Si vous voulez récupérer le profil complet de l’utilisateur, vous pouvez demander openid profile. Vous pouvez demander n’importe lequel des permissions standards d’OpenID Connect (OIDC) sur les utilisateurs, comme email (adresse courriel), ou des demandes personnalisées conformes à un format espace de nom.
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).
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 par falsification de requête intersites , voir la section Atténuer les attaques par falsification de requête intersites avec les paramètres d’état.
connection	( facultatif) Force l’utilisateur à se connecter avec une connexion spécifique. Par exemple, vous pouvez transmettre une valeur de github pour envoyer l’utilisateur directement à GitHub pour qu’il se connecte avec son compte. Si la valeur n’est pas spécifiée, l’utilisateur voit l’écran de verrouillage Auth0 avec toutes les connexions configurées. Vous pouvez voir une liste de vos connexions configurées dans l’onglet Connections (connexions) de votre application.
organization	(facultatif) Identifiant de l’organisation à utiliser pour authentifier un utilisateur. S’il n’est pas fourni et que 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 du ticket d’invitation de l’organization. Lorsque vous invitez un membre à rejoindre une organisation, votre application doit gérer l’acceptation de l’invitation en transmettant les combinaisons de valeurs clés invitation et organization quand l’utilisateur accepte l’invitation.

Par exemple, votre snippet HTML pour l’URL d’autorisation lors de l’ajout d’une connexion à votre application pourrait ressembler à ceci :

<a href="https://{yourDomain}/authorize?
  response_type=code&
  code_challenge=E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM&
  code_challenge_method=S256&
  client_id={yourClientId}&
  redirect_uri={yourCallbackUrl}&
  scope=openid%20profile&
  state=xyzABC123">
  Sign In
</a>

​

Réponse

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

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

​

Jetons de requête

Échangez votre authorization_code et code_verifier pour 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 d’URL « POST to token »

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.

​

Cas d’utilisation

​

Demande d’authentification de base

Cet exemple montre la requête la plus basique que vous pouvez faire lorsque vous autorisez l’utilisateur à l’étape 1. L’écran de connexion Auth0 permet à l’utilisateur de se connecter avec l’une des connexions configurées.

https://{yourDomain}/authorize?
    response_type=code&
    code_challenge={codeChallenge}&
    code_challenge_method=S256&
    client_id={yourClientId}&
    redirect_uri={yourCallbackUrl}&
    scope=openid

Désormais, lorsque vous demanderez des jetons, votre jeton d’ID contiendra les autorisations les plus élémentaires. Lorsque vous décodez le jeton d’ID, il ressemble à ce qui suit :

{
  "iss": "https://auth0pnp.auth0.com/",
  "sub": "auth0|581...",
  "aud": "xvt9...",
  "exp": 1478112929,
  "iat": 1478076929
}

​

Demander le nom et la photo de profil de l’utilisateur

Outre l’authentification habituelle de l’utilisateur, cet exemple montre comment demander des informations supplémentaires sur l’utilisateur, telles que son nom et sa photo.

Pour demander le nom et la photo de l’utilisateur, vous devez ajouter les permissions appropriées lors de l’autorisation de l’utilisateur :

https://{yourDomain}/authorize?
    response_type=code&
    code_challenge={codeChallenge}&
    code_challenge_method=S256&
    client_id={yourClientId}&
    redirect_uri={yourCallbackUrl}&
    scope=openid%20name%20picture&
    state={state}

Désormais, lorsque vous demanderez des jetons, votre jeton d’ID contiendra le nom et la photo demandés. Lorsque vous décodez le jeton d’ID, il ressemble à ce qui suit :

{
  "name": "auth0user@...",
  "picture": "https://example.com/profile-pic.png",
  "iss": "https://auth0user.auth0.com/",
  "sub": "auth0|581...",
  "aud": "xvt...",
  "exp": 1478113129,
  "iat": 1478077129
}

​

Demande de connexion d’un utilisateur avec GitHub

En plus de l’authentification habituelle des utilisateurs, cet exemple montre comment envoyer les utilisateurs directement à un fournisseur d’identité sociale, tel que GitHub. Pour que cet exemple fonctionne, vous devez aller dans Auth0 Dashboard > Authentification > Social et configurer la connexion appropriée. Obtenez le nom de la connexion dans l’onglet Paramètres.

Pour envoyer les utilisateurs directement à l’écran de connexion de GitHub, vous devez passer le paramètre connection et définir sa valeur au nom de la connexion (dans ce cas, github) lors de l’autorisation de l’utilisateur :

https://{yourDomain}/authorize?
    response_type=code&
    code_challenge={codeChallenge}&
    code_challenge_method=S256&
    client_id={yourClientId}&
    redirect_uri={yourCallbackUrl}&
    scope=openid%20name%20picture&
    state={state}&
    connection=github

Désormais, lorsque vous demandez des jetons, votre jeton d’ID contiendra une demande sub avec l’ID unique de l’utilisateur renvoyé par GitHub. Lorsque vous décodez le jeton d’ID, il ressemble à ce qui suit :

{
  "name": "John Smith",
  "picture": "https://avatars.example.com",
  "email": "jsmith@...",
  "email_verified": true,
  "iss": "https://auth0user.auth0.com/",
  "sub": "github|100...",
  "aud": "xvt...",
  "exp": 1478114742,
  "iat": 1478078742
}

​

En savoir plus

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