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

  • Freigeben Version: Yokohama
  • Aktualisiert 30. Januar 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

    Generieren Sie ein JSON-Webtoken (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 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 ServiceNowInstanz.

    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 ServiceNowInstanz zum Überprüfen der 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 die JWT zu validieren. Der Wert dieses Felds muss mit dem Wert der Aussteller- und Zielgruppenansprüche in JWT übereinstimmen.
        Geheimer Clientschlüssel Die Zeichenfolge des gemeinsam genutzten geheimen 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 einen geheimen Clientschlüssel generiert. Um vorhandene Client-Geheimnisse anzuzeigen, wählen Sie das Schlosssymbol aus.
        Hinweis:
        Wenn Öffentlicher Client Ist ausgewählt, können Sie auslassen Geheimer Client .
        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 Anwendungszugriffseinstellungen .
        Lebensdauer von Zugriffstoken Zeitraum, für den das Token gültig ist.

        Einheit: Sekunden
        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 Zusätzliche Informationen, die der Anwendung zugeordnet werden sollen.
        Ö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 .

        Standard: Nicht Ausgewählt.
        Clienttyp 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 Client-Typ für OAuth- und SSO-Datensätze.
      4. Speichern Sie das Formular.
      5. Fügen Sie der zugehörigen Liste „JWT-Verifizierungszuordnungen“ 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
        • verwendbar bis
        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 mit 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.

      Das folgende ist 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. Das folgende ist ein Beispiel für einen Curl-Befehl, der ein Zugriffstoken anfordert, bei dem Client_ID und Client_Secret ausgelassen werden:

      $ 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.

      Es folgt ein Curl-Befehl für den Zugriff auf die Incident-Tabelle mithilfe des Tokens.

      $ 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.