Einen OAuth-JWT-API-Endpunkt für externe Clients erstellen

  • Freigeben Version: Washingtondc
  • Aktualisiert 1. Februar 2024
  • 4 Minuten Lesedauer

    • Erstellen Sie einen OAuth-JSON-Web-Token-API-Endpunkt (JWT), um externen Clients den Zugriff auf Ihre ServiceNow -Instanz mit Web-Token zu ermöglichen.

    Vorbereitungen

    Erforderliche Rolle: admin

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

    • aud: Muss mit dem Wert der Client-ID übereinstimmen.
    • sub: Muss ein Benutzerbezeichner sein, z. B. die E-Mail-Adresse des Benutzers, dem Sie das Token zuordnen möchten.
    • iss: Empfohlen, um dem Wert der Client-ID zu entsprechen.
    • exp: Beliebiger Ablauf.
    Abbildung : 1. Beispiel für decodiertes JSON-Web-Token
    Beispiel für decodiertes JSON-Web-Token

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

    Warum und wann dieser Vorgang ausgeführt wird

    Lassen Sie zu, dass sich externe Webanwendungen nahtlos mit dem eingehenden JWT-Gewährungstyp bei Ihrer Instanz authentifizieren, anstatt dass sich der Endbenutzer manuell anmelden muss. Bei Verwendung des JWT-Gewährungstyps wird das Passwort nicht in die Anforderung aufgenommen, was eine höhere Sicherheit zwischen Webservices ermöglicht. Sie können beispielsweise eine externe Anwendung entwickeln und Token verwenden, um eingehende Anforderungen an Ihre Instanz ServiceNow zu authentifizieren.

    Prozedur

    1. Erstellen Sie ein Schlüsselpaar, und fügen Sie den öffentlichen Schlüssel der Tabelle „X.509-Zertifikate“ (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 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 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 Aussteller- und Zielgruppenansprüche im 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, klicken Sie auf das Sperrsymbol.
        Hinweis:
        Wenn Öffentlicher Client ausgewählt ist, können Sie den geheimenClientschlüssel auslassen.
        Logo-URL Die URL, die ein Bild enthält, das als Anwendungslogo verwendet werden soll. Das Logo wird auf der Genehmigungsseite angezeigt, wenn der Benutzer eine Anforderung erhält, einer Client-Anwendung Zugriff auf eine eingeschränkte Ressource in der Instanz zu gewähren.
        Benutzerfeld Feld in der Benutzertabelle (sys_user), das vom System verwendet wird, um den Wert des betreffenden Anspruchs im JWT abzugleichen. Wenn Sie beispielsweise ein Token hinzufügen, dessen Anspruchswert user.name@example.com lautet, 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 Benutzerdatensatz in der eingehenden Anforderung zu verwenden.
        JTI-Verifizierung aktivieren Wählen Sie diese Option aus, um bei jedem Token-Austausch ein neues Token zu erfordern.

        Standard: Ausgewählt.
        Anwendung Schreibgeschützter Anwendungsbereich.
        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 den Server- und Clientuhren bei der Validierung der Ansprüche „ exp “ und „nbf“ im JWT.

        Einheit: Sekunden

        Standard: 300
        Tokenbeschränkungen erzwingen Wählen Sie diese Option aus, um nur die Verwendung von Token mit APIs zuzulassen, die so festgelegt sind, dass sie das Authentifizierungsprofil zulassen. Sie können den Gewährungszugriff mithilfe einer API-Zugriffsrichtlinie festlegen. Weitere Informationen finden Sie unter REST API-Zugriffsrichtlinien erstellen.

        Standard: Deaktiviert.
        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 geheimen Clientschlüssel angeben.

        Standard: Deaktiviert.
      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-Verifizierungszuordnungen“.
        Feld Beschreibung
        Name Name des JWT-Zuordnungsdatensatzes.
        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).
      6. Fügen Sie alle benutzerdefinierten Ansprüche, die Ihrem JWT zugeordnet sind, der zugehörigen Liste „OAuth-JWT-Anspruchsvalidierungen“ hinzu.

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

        • ist
        • aud
        • Sub
        • ab
        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, die das JWT-Token enthält, um ein Zugriffstoken von Ihrer Instanz zu erhalten.

      Das Folgende ist ein cURL-Beispielbefehl, 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. Mobile SDK, können Sie die Parameter client_id und client_secret in der Anforderung weglassen. 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.

      Das Folgende ist ein 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 das Zugriffstoken im REST-Aufruf ab und ermöglicht den Zugriff auf die angeforderte Ressource.