Créer un point de terminaison d'API JWT OAuth pour les clients externes

  • Rversion finale: Washingtondc
  • Mis à jour 1 févr. 2024
  • 4 minutes de lecture

    • Créez un point de terminaison d’API OAuth JSON Web Token (JWT) pour permettre aux clients externes d’accéder à votre ServiceNow instance à l’aide de jetons Web.

    Avant de commencer

    Rôle requis : admin

    Générer un jeton Web JSON (JWT) avec les revendications suivantes :

    • 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 : recommandé pour correspondre à la valeur de l’ID client.
    • exp : n’importe quelle expiration souhaitée.
    Figure 1. Exemple de jeton Web JSON décodé
    Exemple de jeton Web JSON décodé

    Pour plus d’informations sur les jetons Web JSON, consultez https://jwt.io/.

    Pourquoi et quand exécuter cette tâche

    Autorisez les applications Web externes à 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. L’utilisation du type d’attribution JWT n’inclut pas le mot de passe dans la demande, ce qui 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.

    Procédure

    1. Créez une paire de clés et ajoutez la clé publique à la table Certificats X.509 (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 de l’accès JWT OAuth.
        ID client ID unique généré automatiquement pour l’application. 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 affirmations 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 elles. Laissez ce champ vide pour que l’instance génère automatiquement un secret client. Pour afficher les secrets clients existants, cliquez sur l’icône de verrouillage.
        Remarque :
        Si Client public est sélectionné, vous pouvez omettre le secret client.
        URL du logo L’URL qui contient une image à utiliser comme logo de l’application. Le logo apparaît sur la page d’approbation lorsque l’utilisateur reçoit une demande pour accorder à une application cliente l’accès à une ressource restreinte sur l’instance.
        Champ d'utilisateur Champ dans la table Utilisateur (sys_user) que le système utilise pour faire correspondre la valeur de la réclamation concernée dans le JWT. Par exemple, si vous ajoutez un jeton dont la valeur de revendication de l’objet est user.name@example.com, définissez 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 : cette option est sélectionnée.
        Application Champ d'application de l'application en lecture seule.
        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 le 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 autoriser 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é.
      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 de clé du 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).
      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 réclamations requises suivantes :

        • Iss
        • Aud
        • sous-marin
        • Exp
        Tableau 3. Table des 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 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 les 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.

      Voici 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 dans l’appel REST et autorise l’accès à la ressource demandée.