HomeUse CasesConceptsConfig GuidesDeveloper GuidesAPI Reference
Content

Échange d'un jeton d'utilisateur externe contre un jeton d'accès

Suggest Edits

Cet article fournit un guide étape par étape pour échanger un jeton Web JSON personnalisé (JWT) contre un jeton d'accès émis par Verify. L'objectif est d'obtenir un jeton OAuth qui peut ensuite être utilisé pour accéder à des ressources protégées ou pour autoriser des actions. Il s'agit d'un flux d'usurpation d'identité, dans lequel le sujet du JWT est associé à un utilisateur dans le Verify Cloud Directory. L'utilisateur peut également être approvisionné juste à temps.

Le guide utilise une API en ligne fournie par IBM pour générer le JWT signé. Vous pouvez utiliser tout autre outil de votre choix. En règle générale, ce JWT est émis par un fournisseur tiers.

Présentation

Le processus commence par l'obtention ou la génération d'un JWT utilisateur. Le JWT est ensuite échangé contre un jeton d'utilisateur à l'aide de l'échange de jetons OAuth 2.0 Le résultat est un jeton qui contient des autorisations suffisantes pour accéder aux ressources protégées.

662

Prérequis

Installation et configuration

Type de jeton personnalisé

Connectez-vous à la console d'administration IBM Security Verify et suivez les étapes suivantes.

  1. Dans le menu de gauche, sélectionnez "Applications" et cliquez sur "Custom token types".

  2. Cliquez sur "Add custom token type".

    4180

  3. Entrez les détails suivants dans les "Paramètres généraux" et cliquez sur "Suivant". Le "nom", en particulier, est important car il est utilisé pour identifier le jeton dans le flux OAuth.

    1. ID - demojwt
    2. Nom - urn:demo:token-type:user-jwt
    3. Émetteur - https://demo.ibm.com
    4120

  4. Vous verrez apparaître le formulaire "Paramètres de validation". Remplissez les champs suivants et cliquez sur "Suivant".

    1. Algorithmes de signature autorisés - RS256
    2. Période de validité (sec)- n'importe quelle valeur. Vous pouvez laisser la valeur par défaut.
    3. Valider l'ITC - Activé
    4115

  5. Vous verrez apparaître le formulaire "Identity linking". Remplissez les champs suivants et cliquez sur "Terminer l'installation".

    1. Réclamation de jetons entrants - sub
    2. Source d'identité - Cloud Directory
    3. Recherche par - Nom d'utilisateur
    4. Approvisionnement juste à temps - Activé
    4115

📘

Note

Dans la configuration de liaison d'identité fournie dans cette section, le nom d'utilisateur de l'annuaire Cloud est censé correspondre à la valeur figurant dans la revendication "sub" de la JWT externe. Vous pouvez personnaliser cette méthode en utilisant un attribut différent dans la charge utile du JWT ou même en calculant cette valeur. l'option "Rechercher par" vous permet de choisir l'attribut du compte Cloud Directory à utiliser dans le filtre de recherche.

Client STS

Un simple client STS est utilisé pour effectuer l'échange de jetons. Cela conviendrait aux clients qui ne sont pas des applications. Par exemple, les passerelles API, les serveurs de ressources, les programmes CLI, etc.

  1. Dans le menu de gauche, sélectionnez "Applications" et cliquez sur "Clients STS".

  2. Cliquez sur "Ajouter un client STS".

  3. Dans "Paramètres généraux", laissez "ID client" vide et indiquez un "Nom" approprié. Cliquez sur "Suivant".

    4115

  4. Vous verrez "Paramètres d'authentification du client". Cliquez sur "Suivant" sans faire de changement. Cette opération génère un secret client pour le client STS.

  5. Vous verrez maintenant "Token exchange settings". Définissez les valeurs suivantes, puis cliquez sur "Suivant".

    1. Jeton de sujet - urn:demo:token-type:user-jwt
    2. Jeton demandé - Jeton d'accès
    4111

  6. Vous verrez apparaître "Paramètres de jeton demandés". Cliquez sur "Suivant" sans faire de changement. Le flux génère un jeton d'accès opaque.

  7. Cliquez sur "Suivant" sans modifier les "Paramètres de preuve de possession".

  8. Cliquez sur "Next" sans apporter de modifications à la "Endpoint configuration". Vous pouvez personnaliser cette fonction pour ajouter ultérieurement des attributs supplémentaires au jeton.

  9. Cliquez sur "Complete setup" sans apporter de modifications à "Custom scopes and API access". Vous pouvez personnaliser cette procédure pour n'accorder que des champs d'application spécifiques, par exemple, à une date ultérieure.

  10. Prenez note de l'"ID" et du "secret du client". Ces données seront utilisées comme "client_id" et "client_secret" plus tard pour l'échange de jetons.

3432

Générer et configurer les clés de signature

Si vous souhaitez signer un JWT personnalisé, vous aurez besoin d'une clé publique et d'une clé privée. Les étapes décrites ici utilisent "openssl", mais vous pouvez utiliser l'outil de votre choix.

  1. Ouvrez un terminal.

  2. Générer une paire de clés en utilisant "openssl". Dans l'exemple, cert.pem " est la clé publique utilisée pour valider le JWT signé. Le JWT est signé à l'aide de key.pem ".

    openssl req \
    -x509 \
    -newkey rsa:4096 \
    -keyout key.pem \
    -out cert.pem \
    -sha256 \
    -days 365 \
    -nodes \
    -subj "/CN=DemoTokenSigner"

  3. Dans la console d'administration de Verify, dans le menu de gauche, sélectionnez "Sécurité" et cliquez sur "Certificats".

  4. Cliquez sur "Ajouter un certificat de signature".

  5. Téléchargez le fichier cert.pem " et cliquez sur "OK". Nommez le certificat demotokensigner. Ce label sera utilisé lors de la génération du JWT en tant que "kid" dans l'en-tête.

    3992

Exécuter

Générer un JWT personnalisé

Un JWT personnalisé est nécessaire pour exécuter le flux d'échange de jetons. Vous pouvez utiliser n'importe quel générateur de JWT. Les seules exigences sont les suivantes :

  • Sujet (sub): Il doit s'agir du nom d'utilisateur d'un compte dans Cloud Directory. La configuration provisionnera juste à temps le compte s'il n'existe pas.
  • Émetteur (iss): Ce paramètre doit être défini sur https://demo.ibm.com en fonction de la configuration décrite dans la section précédente.
  • Fournir un JTI (JWT ID) unique dans la charge utile.
  • L'en-tête JWT doit contenir un "kid" correspondant à l'étiquette du certificat, c'est-à-dire demotokensigner.
  • Le key.pem " correspondant au certificat de signature téléchargé dans Verify est utilisé pour signer le JWT.

Générer le JWT comme décrit ici. Il utilise une API fournie par IBM

  1. Convertir toutes les nouvelles lignes dans key.pem " avec "\n" pour créer une chaîne aplatie qui peut être incluse dans un corps de requête JSON.

    4074

  2. Appelez l'API de signature JWT pour générer le JWT comme illustré. Si l'API ne stocke rien, n'incluez pas de clés sensibles. Il est fourni à des fins de test uniquement.

    curl 'https://tools-service.12murzlqn27z.us-east.codeengine.appdomain.cloud/jwt/sign' \
    --header 'Content-Type: application/json' \
    --data-raw '{
        "payload": {
            "iss": "https://demo.ibm.com",
            "sub": "[email protected]",
            "iat": 1703048520,
            "exp": 1703049355,
            "jti": "af582a73-f19e-4f94-9107-111102c46128"
        },
        "header": {
            "alg": "RS256",
            "kid": "demotokensigner"
        },
        "key": "-----BEGIN PRIVATE KEY-----\n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\nSQO7gs26y6wtDJO/SOxyvI7q9mPDCQ==\n-----END PRIVATE KEY-----\n"
    }'

    🚧

    Attention !

    L'API JWT fournie par IBM est destinée à être testée uniquement. Bien que l'API ne stocke aucune donnée côté serveur, n'incluez pas de clés privées ni de données sensibles lorsque vous l'utilisez.

  3. Copiez la valeur du JWT dans la propriété de la réponse jwt. Cette valeur JWT est utilisée comme jeton sujet dans le flux d'échange de jetons OAuth 2.0

    {
    "jwt": "eyJhbGciOiJSUzI1NiIsImtpZCI6ImRlbW90b2tlbnNpZ25lciIsInR5cCI6IkpXVCJ9.eyJleHAiOjEuNzAzMDQ5MzU1ZSswOSwiaWF0IjoxLjcwMzA0ODUyZSswOSwiaXNzIjoiaHR0cHM6Ly9kZW1vLmlibS5jb20iLCJqdGkiOiJhZjU4MmE3My1mMTllLTRmOTQtOTEwNy0xMTExMDJjNDYxMjgiLCJzdWIiOiJqc21pdGhAbWFpbGluYXRvci5jb20ifQ.EHn_D2-e5d9r_0fnM7KIo3JG31Z26ATBw4AQibQhMQr1RRi3QO-o7ghFT45d5Fv6uNA566XeDNNzE29sHlaAQXad54_3pWsHYJigWEZRhqTuZKMuylXVJVZ2_c851V-8fAjVckjekvwjt2e8CNU5MBkX55tq6vDHypV65JSQN3_XEmzl9L0i1k2BnKfD7A--PWzI9_pgBDJY8sAWLCM8hpZwof80bOh4H_epAvsR5JOpSiolsgtatUwJ9Wz_6R7EZNoHMciZSuvTAyq7L34YBQrwAQv2PIvFZtrJJcVyGVRU0bSTwodZ5C5xtdGB2KNxQ9c3WaMxH36iaA84-0gWUVRMwZO5n4gEL6-7BBRVYDLa5UH1aSP01V0SBU4N3_NgPMMjX1uBmNDGgeepPO4oSr7rlgI-IaI4bl_vIGD51rtuwQXg2mNnx2Ep37-37y3LqgM_CdSfL7NKaePuERjeXdf0-L_62Ji4HqNXsNEFyHMZ8r1Rq58ROHgTxhloOrJj_blqkd-eEbfxtcMinvNA07nVt3_ysdKbS-p5uYYaQ_U-gQd-YDd3pkIMiR1ltO3WoqEtplm_w4weYRAWE_Gv_Rn4hAskiAc9_R8kKJaq2oMBR9uy6M5OD2reb61bd9oV9m2dLCxToD1JIyJ5_zjOZCMi6G7x0VXQYyHSdb6sCoY"
}

Jeton d'échange

Maintenant que vous disposez d'un JWT signé, ce jeton peut être échangé contre un jeton d'accès émis par Verify. Vous utiliserez l'ID client et le secret générés pour le client STS que vous avez configuré et le JWT généré à l'étape précédente.

  1. Exécutez le flux d'échange de jetons OAuth 2.0

    curl 'https://<tenant>.verify.ibm.com/oauth2/token' \
    --header 'Content-Type: application/x-www-form-urlencoded' \
    --data-urlencode 'client_id=<sts_client_id>' \
    --data-urlencode 'client_secret=<sts_client_secret>' \
    --data-urlencode 'grant_type=urn:ietf:params:oauth:grant-type:token-exchange' \
    --data-urlencode 'subject_token=<jwt>' \
    --data-urlencode 'subject_token_type=urn:demo:token-type:user-jwt'

  2. Verify répond avec le jeton d'accès.

    {
    "access_token": <access_token>,
    "expires_in": 3599,
    "grant_id": <grant_id>,
    "issued_token_type": "urn:ietf:params:oauth:token-type:access_token",
    "scope": "",
    "token_type": "bearer"
}

  3. Introspecter le jeton pour en inspecter le contenu. Vous obtiendrez ainsi l'identifiant de l'utilisateur dans la demande "sub". Vous pouvez l'utiliser pour rechercher l'utilisateur dans la console d'administration Verify.

    curl 'https://<tenant>.ice.ibmcloud.com/oauth2/introspect' \
    --header 'Content-Type: application/x-www-form-urlencoded' \
    --data-urlencode 'client_id=<sts_client_id>' \
    --data-urlencode 'client_secret=<sts_client_secret>' \
    --data-urlencode 'token=<access_token>'

L'enveloppe

Ce guide a démontré comment un JWT émis en externe peut être échangé contre un jeton d'accès utilisateur émis par Verify. Bien que ce guide propose des étapes pour générer un JWT à l'aide d'un outil fourni par IBM, vous pouvez utiliser n'importe quel mécanisme pour générer un JWT, y compris en exécutant un flux OIDC pour obtenir un id_token qui peut ensuite être utilisé comme JWT externe. Il s'agit d'une forme très courante d'usurpation d'identité utilisée dans un écosystème disparate de fournisseurs d'identité à l'intérieur et à l'extérieur d'une organisation.

Nous vous encourageons à configurer différents types de jetons pour mieux comprendre ce qui est possible.

💎

Vivek Shankar, IBM Security

Updated about 2 months ago