Créer un point de terminaison d’API JWT OAuth pour les clients externes (intégration d’ordinateur à ordinateur)

  • Rversion finale: Xanadu
  • Mis à jour 1 août 2024
  • 5 minutes de lecture

    • Le jeton de porteur OAuth JWT permet aux applications Web clientes de s’authentifier auprès de votre instance de manière transparente à l’aide du type d’attribution JWT entrant au lieu de demander à l’utilisateur final de se connecter manuellement ou de partager le mot de passe.

    Avant de commencer

    Générez un jeton Web JSON (JWT) avec les réclamations suivantes côté client :

    • aud : doit correspondre à la valeur de l’ID client.
    • sub : doit être un identificateur d’utilisateur, tel que l’e-mail de l’utilisateur auquel vous souhaitez associer le jeton.
    • iss : correspond recommandée à la valeur de l’ID client. Si l’aud et l’iss ne correspondent pas, ajoutez la valeur iss dans la validation de réclamation.
    • exp : n’importe quelle expiration souhaitée.
    Figure 1. Exemple de jeton Web JSON décodé
    Exemple de jeton Web JSON décodé

    Configuration dans ServiceNow

    Pourquoi et quand exécuter cette tâche

    Étant donné que l’utilisation du type d’attribution JWT n’inclut pas le mot de passe dans la demande, elle permet une plus grande sécurité entre les services Web. Par exemple, vous pouvez développer une application externe et utiliser des jetons pour authentifier les demandes entrantes envoyées à votre ServiceNow instance.

    Rôle requis : administrateur

    Pour plus d’informations sur les jetons Web JSON, reportez-vous à la section https://jwt.io/.

    Procédure

    1. Ajoutez la clé publique de l’application cliente à la table sys_certificate .
    2. Configurez la configuration dans votre ServiceNow instance pour vérifier le JWT entrant.
      1. Accédez à la OAuth système > Registre d'application.
      2. Sélectionnez Créer un point de terminaison d’API JWT OAuth pour les clients externes.
      3. Remplissez le formulaire avec les informations relatives à votre jeton.
        Tableau 1. Table JWT OAuth
        Champ Description
        Nom Un nom unique qui identifie l’application pour laquelle vous avez besoin d’un accès OAuth JWT.
        ID client ID unique de l’application généré automatiquement. Le système utilise la valeur de ce champ pour récupérer la clé publique ou partagée et valider le JWT. La valeur de ce champ doit correspondre à la valeur des réclamations de l’émetteur et de l’audience dans le JWT.
        Secret client Chaîne secrète partagée que l’instance et l’application cliente ou le site web utilisent pour autoriser les communications entre eux. Laissez ce champ vide pour que l’instance génère automatiquement un secret client. Pour afficher les secrets client existants, sélectionnez l’icône de verrouillage.
        Remarque :
        Si Client public est sélectionné, vous pouvez omettre le secret client.
        Champ d'utilisateur Champ dans la table Utilisateur (sys_user) que le système utilise pour correspondre à la valeur de la réclamation objet dans le JWT. Par exemple, si vous ajoutez un jeton dont la valeur de réclamation d’objet est user.name@example.com, vous devez définir le champ Utilisateur sur E-mail. Ce champ indique au système de rechercher la valeur user.name@example.com dans le champ d’e-mail et d’utiliser l’enregistrement d’utilisateur correspondant dans la demande entrante.
        Activer la vérification JTI Sélectionnez cette option pour exiger un nouveau jeton à chaque échange de jeton.

        Par défaut : sélectionné.
        Application Champ d'application de l'application en lecture seule. Ce champ est renseigné automatiquement.
        Accessible depuis Politique d’accès entre périmètres. Pour plus d’informations, consultez Paramètres d’accès à l’application.
        Durée de vie du jeton d'accès Durée de validité du jeton.

        Unité : Secondes
        Décalage d'horloge Décalage horaire autorisé entre les horloges du serveur et du client lors de la validation des réclamations exp et nbf dans JWT.

        Unité : Secondes

        Par défaut : 300
        Appliquer les restrictions de jeton Sélectionnez cette option pour autoriser uniquement l’utilisation des jetons avec des API définies pour activer le profil d’authentification. Vous pouvez définir l’octroi d’accès à l’aide d’une politique d’accès API. Pour plus d’informations, consultez Créer une politique d’accès REST API.

        Par défaut : non sélectionné.
        Commentaires Informations supplémentaires à associer à l’application.
        Client public Ajoutez ce champ au formulaire si le client JWT est public. Lorsque cette option est sélectionnée, vous n’avez pas besoin d’inclure de secret client.

        Par défaut : non sélectionné.
        Type de client Choisissez le type de client en fonction du type de votre client. Options :
        • iframe incorporé
        • Intégration en tant qu'utilisateur
        • Intégration en tant que service
        Pour en savoir plus, reportez-vous à la section Configurer le type de client pour les enregistrements OAuth et SSO.
      4. Enregistrez le formulaire.
      5. Ajoutez des enregistrements à la liste connexe des cartes de vérificateur JWT pour vérifier la signature JWT.
        Tableau 2. Table des cartes de vérificateur JWT
        Champ Description
        Nom Nom de l’enregistrement de mappage JWT.
        Enfant ID clé de JWT
        Clé partagée Clé partagée pour l’ID de clé spécifié.
        Application Champ d'application de l'application en lecture seule.
        Certificat système Enregistrement de certificat dans la table Certificats X.509 (sys_certificate). Le certificat qui a été chargé à l’étape 1.
      6. Ajoutez toutes les réclamations personnalisées associées à votre JWT à la liste connexe Validations des réclamations OAuth JWT.

        Vous n’avez pas besoin d’ajouter des enregistrements pour les déclarations obligatoires suivantes :

        • Iss
        • Aud
        • sub
        • Exp
        Remarque :
        • Si l’aud et l’iss ne correspondent pas, ajoutez la valeur iss dans la validation de réclamation.
        • Pour les certificats, vous pouvez ajouter plusieurs cartes de vérificateur associées à plusieurs clés.
        Tableau 3. Table de validations de réclamation OAuth JWT
        Champ Description
        Mon client externe Renseigné automatiquement avec l’enregistrement JWT OAuth.
        Type de valeur de réclamation Type de données de la valeur de réclamation.
        Nom de la réclamation Nom de la réclamation que vous souhaitez ajouter.
        Valeur de réclamation Valeur de la réclamation.
        Application Champ d'application de l'application en lecture seule.
    3. Envoyez une demande cURL contenant le jeton JWT pour obtenir un jeton d’accès à partir de votre instance.

      Voici un exemple de commande cURL demandant un jeton d’accès :

      $ curl -d"grant_type= urn:ietf:params:oauth:grant-type:jwt-bearer
&client_id=be3aeb583ace210011c15b24a43e25d8
&client_secret=client_password
&assertion= eyJraWQiOiJzYW1wbGVrZXlpZCIsInR5cCI6IkpXVCIsImFsZyI6IlJTMjU2In0.eyJhdWQiOiI5YzZlMmQxNzU0MzMyMDEwMDFhMTE4Y2FhMGVhMmE0MyIsInN1YiI6ImFkbWluQGV4YW1wbGUuY29tIiwiaXNzIjoiOWM2ZTJkMTc1NDMzMjAxMDAxYTExOGNhYTBlYTJhNDMiLCJleHAiOjE2MjI3MDI1MjYsImlhdCI6MTYyMjcwMjQ2NiwianRpIjoiNWRkMGUxYzctYjY1Ny00YmQ4LTlkY2UtMTdhZDdlZmUwNmFiIn0.PDoffnN2nq9ZNdxhOTLNbzlls4C1gsacahWr0kmPcGJDUJ_OQunmY5YXfpqkASiZixcQDS4kMwyqK9bha1-SnPOXq7zCIlJGCGFOv_OjEpQvMqmiKtLVk3jCsD03eXSoR4V-EzoCChiXpK87K5tMfM5k0YV9KfrxgvjUipgfni5N0JeyqkssMXBdkuE90XW_hBCo9AMMQm6J2PNMWb2O_O8rOX06KHuc4-Ip8wcRZ8a_bndCSmHl8Em7v4DvqTkLzlnF_-BXuM3T7nTI21cDXQKqZnqzzriu8irlAsscJFTxkh-_Ynei5RgYtL_Mvx2-HDO-XGofBhlAY2t9K36sz71HHqFZr5qCOIOAPguNzAy5-MOuZjOU_kH6ugIRycaNMDRjaU7gOvUHEERw3d0sI20OChIWOryBSwdTs7lgB1WzsJWCNVo81ssc2yko3jPoygt90tMwI_6A-4J-mlgq_fS_SvPUAqq_2UUJfVOTT5WGeq58cXfwRJmsDo49IhL3kXDVWT2gxaqhEdBQEW16UmRoTUzRs9A9sOm18y3skmOVtnEOm-MlJMFQZ754UMzbiH0ZsMmk1ivCGIjex5J0_lDjKElWF5RHGz3YShCoa4JKDZsqYMvIk1SvzyQXjuFqPdS2vzg2m1eKGUwr3m6uNs_HflcDystwVdMZ7nLlBG4"
https://instancename.service-now.com/oauth_token.do

      Si le client JWT est un client public, tel que Mobile SDK, vous pouvez omettre les paramètres client_id et client_secret de la demande. Voici un exemple de commande cURL demandant un jeton d’accès qui omet le client_id et client_secret :

      $ curl -d"grant_type= urn:ietf:params:oauth:grant-type:jwt-bearer
&assertion= eyJraWQiOiJzYW1wbGVrZXlpZCIsInR5cCI6IkpXVCIsImFsZyI6IlJTMjU2In0.eyJhdWQiOiI5YzZlMmQxNzU0MzMyMDEwMDFhMTE4Y2FhMGVhMmE0MyIsInN1YiI6ImFkbWluQGV4YW1wbGUuY29tIiwiaXNzIjoiOWM2ZTJkMTc1NDMzMjAxMDAxYTExOGNhYTBlYTJhNDMiLCJleHAiOjE2MjI3MDI1MjYsImlhdCI6MTYyMjcwMjQ2NiwianRpIjoiNWRkMGUxYzctYjY1Ny00YmQ4LTlkY2UtMTdhZDdlZmUwNmFiIn0.PDoffnN2nq9ZNdxhOTLNbzlls4C1gsacahWr0kmPcGJDUJ_OQunmY5YXfpqkASiZixcQDS4kMwyqK9bha1-SnPOXq7zCIlJGCGFOv_OjEpQvMqmiKtLVk3jCsD03eXSoR4V-EzoCChiXpK87K5tMfM5k0YV9KfrxgvjUipgfni5N0JeyqkssMXBdkuE90XW_hBCo9AMMQm6J2PNMWb2O_O8rOX06KHuc4-Ip8wcRZ8a_bndCSmHl8Em7v4DvqTkLzlnF_-BXuM3T7nTI21cDXQKqZnqzzriu8irlAsscJFTxkh-_Ynei5RgYtL_Mvx2-HDO-XGofBhlAY2t9K36sz71HHqFZr5qCOIOAPguNzAy5-MOuZjOU_kH6ugIRycaNMDRjaU7gOvUHEERw3d0sI20OChIWOryBSwdTs7lgB1WzsJWCNVo81ssc2yko3jPoygt90tMwI_6A-4J-mlgq_fS_SvPUAqq_2UUJfVOTT5WGeq58cXfwRJmsDo49IhL3kXDVWT2gxaqhEdBQEW16UmRoTUzRs9A9sOm18y3skmOVtnEOm-MlJMFQZ754UMzbiH0ZsMmk1ivCGIjex5J0_lDjKElWF5RHGz3YShCoa4JKDZsqYMvIk1SvzyQXjuFqPdS2vzg2m1eKGUwr3m6uNs_HflcDystwVdMZ7nLlBG4"
https://instancename.service-now.com/oauth_token.do

      L’instance renvoie le jeton d’accès dans sa réponse :

      {
    "access_token": "KynMY2H0uwWkRc8g8YLXjnQxWbH5_wbnSiLsnaOoKw61GZkkV0ytZP74uF7hJyjfsWfaaFijqQzq2kcABNJxNA",
    "scope": "useraccount",
    "token_type": "Bearer",
    "expires_in": 1799
}
      Remarque :
      Le type d’accord JWT entrant n’inclut pas les jetons d’actualisation.
    4. Effectuez un appel d’API REST pour accéder à une ressource à l’aide du jeton d’accès.

      Ce qui suit est une commande cURL permettant d’accéder à la table d’incidents à l’aide du jeton.

      $ curl -H "Authorization: Bearer KynMY2H0uwWkRc8g8YLXjnQxWbH5_wbnSiLsnaOoKw61GZkkV0ytZP74uF7hJyjfsWfaaFijqQzq2kcABNJxN" 
https://instancename.service-now.com/api/now/v1/table/incident

    Résultats

    Le système récupère le jeton d’accès lors de l’appel REST et autorise l’accès à la ressource demandée.