OAuth-JWT-API-Endpunkt für externe Clients erstellen (Computer-zu-Computer-Integration)

  • Freigeben Version: Zurich
  • Aktualisiert 31. Juli 2025
  • 4 Minuten Lesedauer

    • Mit dem OAuth-JWT-Bearer-Token können sich Client-Webanwendungen nahtlos mit dem eingehenden JWT-Gewährungstyp bei Ihrer Instanz authentifizieren, anstatt dass der Endanwender sich manuell anmelden oder das Passwort freigeben muss.

    Bevor Sie beginnen

    Die unterstützten Algorithmen für JSON Web Token (JWT): RS256, RS384, RS512, ES256, ES384, ES512.

    Generieren Sie ein JWT mit den folgenden Ansprüchen auf Clientseite:

    • aud : Muss mit dem Wert der Client-ID übereinstimmen.
    • Untergeordnet : Muss ein Anwenderbezeichner sein, z. B. die E-Mail-Adresse des Anwenders, der Sie das Token zuordnen möchten.
    • iss : Empfohlene Übereinstimmung mit dem Wert der Client-ID. Wenn aud Und iss Stimmt nicht überein, fügen Sie dann hinzu iss Wert in der Anspruchsvalidierung.
    • Verwendbar bis : Beliebiger gewünschter Ablauf.
    Abbildung : 1. Beispiel für decodierte JSON-Webtoken
    Beispiel für decodierte JSON-Webtoken

    Konfiguration in ServiceNow

    Warum und wann dieser Vorgang ausgeführt wird

    Da die Verwendung des JWT-Gewährungstyps das Passwort nicht in der Anforderung enthält, ermöglicht dies eine höhere Sicherheit zwischen Webservices. Sie können beispielsweise eine externe Anwendung entwickeln und Token verwenden, um eingehende Anforderungen bei zu authentifizieren ServiceNow Instanz.

    Erforderliche Rolle: Administrator

    Weitere Informationen zu JSON-Webtoken finden Sie unter https://jwt.io/.

    Prozedur

    1. Fügen Sie den öffentlichen Schlüssel der Client-App zu hinzu sys_certificate Tabelle.
    2. Richten Sie die Konfiguration in ein ServiceNow Instanz zur Verifizierung des eingehenden JWT.
      1. Navigieren zu System-OAuth > Applikationsregistrierungan.
      2. Wählen Sie Aus Erstellen Sie einen OAuth-JWT-API-Endpunkt für externe Clients .
      3. Füllen Sie das Formular mit Informationen zu Ihrem Token aus.
        Tabelle : 1. OAuth-JWT-Tabelle
        Feld Beschreibung
        Name Ein eindeutiger Name, der die Anwendung identifiziert, für die Sie JWT OAuth-Zugriff benötigen.
        Client-ID Die automatisch generierte eindeutige ID der Anwendung. Das System verwendet den Wert dieses Felds, um den öffentlichen oder freigegebenen Schlüssel abzurufen und das JWT zu validieren. Der Wert dieses Felds muss mit dem Wert der Ansprüche des Ausstellers und der Zielgruppe in JWT übereinstimmen.
        Geheimer Clientschlüssel Die Zeichenfolge des gemeinsamen Geheimnisses, die sowohl die Instanz als auch die Client-Anwendung oder -Website verwenden, um Kommunikation miteinander zu autorisieren. Lassen Sie dieses Feld leer, damit die Instanz automatisch ein geheimes Clientgeheimnis generiert. Um vorhandene geheime Clientgeheimnisse anzuzeigen, wählen Sie das Sperrsymbol aus.
        Hinweis:
        Wenn Öffentlicher Client Ist ausgewählt, können Sie auslassen Geheimer Client-Schlüssel .
        Anwenderfeld Feld in der Anwendertabelle (sys_user), das das System verwendet, um den Wert des Antragstellungsanspruchs in der JWT abzugleichen. Wenn Sie beispielsweise ein Token hinzufügen, das den Anspruchswert des Antragstellers user.name@example.com hat, legen Sie fest Anwenderfeld Bis E-Mail . Dieses Feld weist das System an, das E-Mail-Feld nach dem Wert user.name@example.com zu durchsuchen und den übereinstimmenden Anwenderdatensatz in der eingehenden Anforderung zu verwenden.
        JTI-Verifizierung aktivieren Wählen Sie diese Option aus, um bei jedem Tokenaustausch ein neues Token anzufordern.

        Standard: Ausgewählt.
        Anwendung Schreibgeschützter Anwendungsbereich. Dieses Feld wird automatisch gefüllt.
        Zugänglich von Bereichsübergreifende Zugriffsrichtlinie. Weitere Informationen finden Sie unter Einstellungen für Anwendungszugriff .
        Lebensdauer von Zugriffstoken Zeitraum, für den das Token gültig ist.

        Einheit: Sekunden
        Tokenformat Format des zu generierenden Tokens. Das Format bestimmt die Struktur eines Tokens und die darin enthaltenen Informationen.
        Subjektanspruch Feld in der Anwendertabelle (sys_user), das zum Ausfüllen des Werts des Betreffanspruchs eines JWT-Tokens verwendet wird. Der Unteranspruch ist eine Information, die den Betreff oder Anwender des JWT-Tokens identifiziert. Dieses Feld gilt nur, wenn Token-Format Ist JWT.
        Taktversatz Zulässige Zeitdifferenz zwischen Server- und Client-Uhren bei der Validierung von Verwendbar bis Und nbf Ansprüche im JWT.

        Einheit: Sekunden

        Standard: 300
        Tokenbeschränkungen erzwingen Wählen Sie diese Option aus, um nur Token für die Verwendung mit APIs zu aktivieren, die festgelegt sind, um das Authentifizierungsprofil zu aktivieren. Sie können Zugriffsgewährung mithilfe einer API-Zugriffsrichtlinie festlegen. Weitere Informationen finden Sie unter Erstellen Sie EINE REST-API-Zugriffsrichtlinie .

        Standard: Nicht Ausgewählt.
        Kommentare Die der Anwendung zuzuordnenden Informationen.
        Öffentlicher Client Fügen Sie dieses Feld dem Formular hinzu, wenn der JWT-Client öffentlich ist. Wenn diese Option ausgewählt ist, müssen Sie keinen einschließen Geheimer Client-Schlüssel .

        Standard: Nicht Ausgewählt.
        Client-Typ Wählen Sie den Client-Typ basierend auf dem Typ Ihres Clients aus. Optionen:
        • IFrame eingebettet
        • Integration als Anwender
        • Integration als Service
        Weitere Informationen finden Sie unter Konfigurieren Sie den Clienttyp für OAuth- und SSO-Datensätze.
      4. Speichern Sie das Formular.
      5. Fügen Sie der zugehörigen Liste „JWT-Verifiziererzuordnungen“ Datensätze hinzu, um die JWT-Signatur zu überprüfen.
        Tabelle : 2. Tabelle „JWT-Verifiziererzuordnungen“
        Feld Beschreibung
        Name Name des JWT-Zuordnungsdatensatzes.
        Kind Schlüssel-ID aus JWT.
        Freigegebener Schlüssel Der freigegebene Schlüssel für die angegebene Schlüssel-ID.
        Anwendung Schreibgeschützter Anwendungsbereich.
        Sys-Zertifikat Zertifikatdatensatz in der Tabelle „X.509-Zertifikate“ (sys_certificate). Das Zertifikat, das in Schritt 1 hochgeladen wurde.
      6. Fügen Sie der zugehörigen Liste „OAuth-JWT-Anspruchsvalidierungen“ alle anwenderdefinierten Ansprüche hinzu, die Ihrem JWT zugeordnet sind.

        Sie müssen keine Datensätze für die folgenden erforderlichen Ansprüche hinzufügen:

        • iss
        • aud
        • Untergeordnet
        • exp
        Hinweis:
        • Wenn aud Und iss Stimmt nicht überein, fügen Sie dann hinzu iss Wert in der Anspruchsvalidierung.
        • Für Zertifikate können Sie mehrere Überprüfungszuordnungen hinzufügen, die mehreren Schlüsseln zugeordnet sind.
        Tabelle : 3. Tabelle „OAuth-JWT-Anspruchsvalidierungen“
        Feld Beschreibung
        Mein externer Client Wird automatisch mit dem OAuth-JWT-Datensatz ausgefüllt.
        Anspruchwerttyp Datentyp des Anspruchswerts.
        Anspruchname Name des Anspruchs, den Sie hinzufügen möchten.
        Anspruchwert Wert des Anspruchs.
        Anwendung Schreibgeschützter Anwendungsbereich.
    3. Senden Sie eine Curl-Anforderung mit dem JWT-Token, um ein Zugriffstoken von Ihrer Instanz zu erhalten.

      Es folgt ein Beispiel für einen Curl-Befehl, der ein Zugriffstoken anfordert:

      $ 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

      Wenn der JWT-Client ein öffentlicher Client ist, z. B. das Mobile SDK, können Sie die Parameter „Client_ID“ und „Client_Secret“ aus der Anforderung auslassen. Es folgt ein Beispiel für einen Curl-Befehl, der ein Zugriffstoken anfordert, das Client_ID und Client_Secret auslässt:

      $ 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

      Die Instanz gibt das Zugriffstoken in ihrer Antwort zurück:

      {
    "access_token": "KynMY2H0uwWkRc8g8YLXjnQxWbH5_wbnSiLsnaOoKw61GZkkV0ytZP74uF7hJyjfsWfaaFijqQzq2kcABNJxNA",
    "scope": "useraccount",
    "token_type": "Bearer",
    "expires_in": 1799
}
      Hinweis:
      Der eingehende JWT-Gewährungstyp enthält keine Aktualisierungstoken.
    4. Führen Sie einen REST-API-Aufruf durch, um mit dem Zugriffstoken auf eine Ressource zuzugreifen.

      Im Folgenden finden Sie einen Curl-Befehl, um mit dem Token auf die Incident-Tabelle zuzugreifen.

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

    Ergebnisse

    Das System ruft das Zugriffstoken im REST-Aufruf ab und ermöglicht den Zugriff auf die angeforderte Ressource.