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

  • Rversion finale: Zurich
  • Mis à jour 31 juil. 2025
  • 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’accord JWT entrant au lieu de demander à l’utilisateur final de se connecter manuellement ou de partager le mot de passe.

    Avant de commencer

    Les algorithmes pris en charge pour JSON Web Token (JWT) : RS256, RS384, RS512, ES256, ES384, ES512.

    Générer un JWT avec les revendications suivantes côté client :

    • aud : doit correspondre à la valeur de l’ID client.
    • sub : doit être un identificateur utilisateur, tel que l’e-mail de l’utilisateur auquel vous souhaitez associer le jeton.
    • iss : correspondance recommandée avec la valeur de l’ID client. Si l’aud et l’iss ne correspondent pas, ajoutez la valeur iss dans la validation de la réclamation.
    • exp : toute 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’accord 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 : admin

    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 OAuth JWT
        Champ Description
        Nom 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 de la table Utilisateur (sys_user) que le système utilise pour faire correspondre la valeur de la réclamation en question 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 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
        Format du jeton Format du jeton à générer. Le format détermine la structure d’un jeton et les informations qu’il contient.
        Réclamation de sujet Champ de la table Utilisateur (sys_user) utilisé pour renseigner la valeur de l’objet (sous-)réclamation d’un jeton JWT. La sous-revendication est un élément d’information qui identifie le sujet, ou l’utilisateur, du jeton JWT. Ce champ s’applique uniquement si le format de jeton est JWT.
        Décalage d'horloge Différence de temps autorisée entre les horloges serveur et 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 activer uniquement l’utilisation des jetons avec les API définies pour activer le profil d’authentification. Vous pouvez définir l’octroi de l’accès à l’aide d’une stratégie 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 de 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 du 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 d’enregistrements pour les déclarations requises suivantes :

        • Iss
        • Aud
        • sub
        • exp
        Remarque :
        • Si l’aud et l’iss ne correspondent pas, ajoutez la valeur iss dans la validation de la réclamation.
        • Pour les certificats, vous pouvez ajouter plusieurs cartes de vérificateur associées à plusieurs clés.
        Tableau 3. Table des validations des réclamations OAuth JWT
        Champ Description
        Mon client externe Rempli 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 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 le SDK mobile, 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 des 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 dans l’appel REST et active l’accès à la ressource demandée.