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

  • Freigeben Version: Yokohama
  • Aktualisiert 30. Januar 2025
  • 4 Minuten Lesedauer

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

    Bevor Sie beginnen

    Generieren Sie ein JSON-Web-Token (JWT) mit den folgenden Ansprüchen auf Client-Seite:

    • aud: Muss mit dem Wert der Client-ID übereinstimmen.
    • sub: Muss ein Anwenderbezeichner sein, z. B. die E-Mail-Adresse des Anwenders, dem Sie das Token zuordnen möchten.
    • iss: Empfohlene Übereinstimmung mit dem Wert der Client-ID. Wenn aud und iss nicht übereinstimmen, fügen Sie den Wert iss in der Anspruchsvalidierung hinzu.
    • exp: Beliebiger Ablauf.
    Abbildung : 1. Beispiel für das decodierte JSON-Web-Token
    Beispiel für das decodierte JSON-Web-Token

    Konfiguration in ServiceNow

    Warum und wann dieser Vorgang ausgeführt wird

    Da bei Verwendung des Erteilungstyps JWT das Passwort nicht in der Anforderung enthalten ist, erhöht dies die Sicherheit zwischen Webservices. Sie können beispielsweise eine externe Anwendung entwickeln und Token verwenden, um eingehende Anforderungen an Ihre Instanz ServiceNow zu authentifizieren.

    Erforderliche Rolle: Administrator

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

    Prozedur

    1. Fügen Sie den öffentlichen Schlüssel der Client-App der Tabelle „sys_certificate“ hinzu.
    2. Richten Sie die -Konfiguration in Ihrer -Instanz ServiceNow ein, um das eingehende JWT zu überprüfen.
      1. Navigieren zu System-OAuth > Applikationsregistrierung.
      2. Wählen Sie Einen OAuth-JWT-API-Endpunkt für externe Clients erstellen aus.
      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 gemeinsame geheime Zeichenfolge, die sowohl die Instanz als auch die Clientanwendung oder Website verwenden, um die Kommunikation miteinander zu autorisieren. Lassen Sie dieses Feld leer, damit die Instanz automatisch einen geheimen Clientschlüssel generiert. Um vorhandene geheime Clientschlüssel anzuzeigen, wählen Sie das Sperrsymbol.
        Hinweis:
        Wenn „Öffentlicher Client“ ausgewählt ist, können Sie den geheimen Clientschlüsselauslassen.
        Anwenderfeld Feld in der Benutzertabelle (sys_user), das vom System verwendet wird, um den Wert des betreffenden Anspruchs in JWT abzugleichen. Wenn Sie beispielsweise ein Token mit dem Betreff-Anspruchwert user.name@example.com hinzufügen, legen Sie das Benutzerfeld auf E-Mailfest. 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 zu erfordern.

        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 den Anwendungszugriff.
        Lebensdauer von Zugriffstoken Gültigkeitsdauer des Tokens.

        Einheit: Sekunden
        Taktversatz Zulässige Zeitdifferenz zwischen Server- und Client-Uhren beim Validieren der Ansprüche „exp“ und „nbf“ in 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 zum Aktivieren des Authentifizierungsprofils festgelegt sind. Sie können den Gewährungszugriff mithilfe einer API-Zugriffsrichtlinie festlegen. Weitere Informationen finden Sie unter REST-API-Zugriffsrichtlinie erstellen.

        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 Clientschlüsselangeben.

        Standard: Nicht ausgewählt.
        Clienttyp Wählen Sie den Clienttyp 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-Verifizierungszuordnungen“.
        Feld Beschreibung
        Name Name des JWT-Mapping-Datensatzes.
        Kind Schlüssel-ID aus dem 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-Anspruchvalidierungen“ alle anwenderdefinierten Ansprüche hinzu, die Ihrem JWT zugeordnet sind.

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

        • iss
        • aud
        • sub
        • abgel
        Hinweis:
        • Wenn aud und iss nicht übereinstimmen, fügen Sie den Wert iss in der Anspruchsvalidierung hinzu.
        • Für Zertifikate können Sie mehrere Verifiziererzuordnungen hinzufügen, die mehreren Schlüsseln zugeordnet sind.
        Tabelle : 3. OAuth-JWT-Anspruchvalidierungstabelle
        Feld Beschreibung
        Mein externer Client 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, die das JWT-Token enthält, um ein Zugriffstoken von Ihrer -Instanz zu erhalten.

      Im Folgenden finden Sie ein Beispiel für einen cURL-Befehl zum Anfordern eines Zugriffstokens:

      $ 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, wie z. B. das Mobile SDK, können Sie die Parameter „client_id“ und „client_secret“ in der Anforderung weglassen. Im Folgenden finden Sie ein Beispiel für einen cURL-Befehl zum Anfordern eines Zugriffstokens, bei dem client_id und client_secret fehlen:

      $ 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 für den Zugriff auf die Incident-Tabelle mit dem Token.

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

    Ergebnisse

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