外部クライアント向けの OAuth JWT API エンドポイントの作成 (マシン間の統合)
OAuth JWT ベアラートークンは、エンドユーザーに手動ログインを要求したり、パスワードを共有したりしなくても、受信 JWT 権限許可タイプを使用して、クライアント Web アプリケーションがシームレスにインスタンスの認証を行えるようにします。
開始する前に
JSON Web トークン (JWT) でサポートされているアルゴリズム: RS256、RS384、RS512、ES256、ES384、ES512。
クライアント側で次の要求を含む JWT を生成します。
aud：クライアント ID の値と一致する必要があります。sub：トークンを関連付けるユーザーのメールなど、ユーザー識別子である必要があります。iss：クライアント ID の値と一致させることをお勧めします。audとissが一致しない場合は、要求検証にiss値を追加します。exp：任意の有効期限
ServiceNow での構成
このタスクについて
必要なロール：admin
JSON Web トークンの詳細については、「https://jwt.io/」を参照してください。
手順
- クライアントアプリの公開鍵を sys_certificate テーブルに追加します。
-
ServiceNow インスタンスの構成を設定して、受信 JWT を確認します。
- 移動先 システム OAuth > アプリケーションレジストリー.
- [外部クライアント向けの OAuth JWT API エンドポイントの作成] を選択します。
-
トークンに関する情報をフォームに入力します。
表 : 1. [OAuth JWT] テーブル フィールド 説明 名前 JWT OAuth アクセスが必要なアプリケーションを識別する一意の名前 クライアント ID 自動生成された一意のアプリケーション ID。システムは、このフィールドの値を使用して公開鍵または共有鍵を取得し、JWT を検証します。このフィールドの値は、JWT の発行者要求および対象者要求の値と一致する必要があります。 クライアントシークレット インスタンスとクライアントアプリケーションまたは Web サイトの両方が、相互通信を許可するために使用する共有シークレット文字列。インスタンスでクライアントシークレットを自動生成するには、このフィールドを空白のままにします。既存のクライアントシークレットを表示するには、ロックアイコンを選択します。 注:[公開クライアント] を選択した場合は、[クライアントシークレット] を省略できます。ユーザーフィールド JWT の件名要求の値を照合するためにシステムが使用するユーザー (sys_user) テーブル内のフィールド。たとえば、件名要求の値が user.name@example.com であるトークンを追加する場合は、ユーザーフィールドを [メール] に設定します。このフィールドは、メールフィールドで user.name@example.com の値を検索し、一致するユーザーレコードを受信要求で使用するようにシステムに指示します。 JTI 検証を有効化 トークン交換のたびに新しいトークンを要求する場合に選択します。 デフォルト：オン
アプリケーション 読み込み専用のアプリケーションスコープこのフィールドは自動入力されます。 アクセス可能 Cross-scope Access ポリシー。詳細については、「アプリケーションのアクセス設定」を参照してください。 アクセストークン有効期間 トークンが有効である時間 単位：秒
トークン形式 生成するトークンの形式。形式によって、トークンの構造とそれに含まれる情報が決まります。 件名要求 JWT トークンの件名 (サブ) クレームの値を入力するために使用されるユーザー (sys_user) テーブルのフィールド。サブ要求は、JWT トークンのサブジェクトまたはユーザーを識別する情報です。このフィールドは、[ トークン形式 ] が [JWT] の場合にのみ適用されます。 クロックスキュー JWT の expおよびnbf要求を検証する際のサーバークロックとクライアントクロック間の許容時間差単位：秒
デフォルト：300
トークン制限の適用 認証プロファイルを有効にするように設定された API でのみトークンの使用を有効にする場合に選択します。API アクセスポリシーを使用してアクセス許可を設定できます。詳細については、「REST API アクセスポリシーの作成」を参照してください。 デフォルト：未選択。
コメント アプリケーションに関連付ける追加情報。 公開クライアント JWT クライアントが公開の場合は、このフィールドをフォームに追加します。選択した場合、クライアントシークレットを含める必要はありません。 デフォルト：未選択。
クライアントタイプ クライアントのタイプに基づいて、クライアントタイプを選択します。オプション： - iFrame 埋め込み
- ユーザーとして連携
- サービスとして連携
- フォームを保存します。
-
[JWT 検証者マップ] 関連リストにレコードを追加して、JWT 署名を検証します。
表 : 2. JWT 検証者マップテーブル フィールド 説明 名前 JWT マッピングレコードの名前。 Kid JWT からのキー ID。 共有キー 指定されたキー ID の共有キー。 アプリケーション 読み込み専用のアプリケーションスコープ システム外部審査済み書 X.509 証明書 (sys_certificate) テーブルの証明書レコード。ステップ 1 でアップロードした証明書。 -
JWT に関連付けられているカスタム要求をすべて [OAuth JWT 要求検証] 関連リストに追加します。
次に示す必須要求には、レコードを追加する必要はありません。
- iss
- aud
- sub
- exp
注:audとissが一致しない場合は、要求検証にiss値を追加します。- 証明書の場合は、複数のキーに関連付けられた複数の検証者マップを追加できます。
表 : 3. [OAuth JWT 要求検証] テーブル フィールド 説明 自分の外部クライアント (My external client) OAuth JWT レコードが自動入力されます。 要求値タイプ 請求値のデータタイプ 要求名 追加する要求の名前 要求値 要求の値 アプリケーション 読み込み専用のアプリケーションスコープ
-
JWT トークンを含む cURL 要求を送信して、インスタンスからアクセストークンを取得します。
アクセストークンを要求する cURL コマンドのサンプルを次に示します。
$ 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.doJWT クライアントが Mobile SDK などの公開クライアントである場合は、要求から client_id パラメーターと client_secret パラメーターを省略できます。client_id および client_secret を省略するアクセストークンを要求する cURL コマンドのサンプルを次に示します。
$ 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インスタンスは、その応答でアクセストークンを返します。
{ "access_token": "KynMY2H0uwWkRc8g8YLXjnQxWbH5_wbnSiLsnaOoKw61GZkkV0ytZP74uF7hJyjfsWfaaFijqQzq2kcABNJxNA", "scope": "useraccount", "token_type": "Bearer", "expires_in": 1799 }注:受信 JWT 権限許可タイプには、リフレッシュトークンは含まれません。 -
アクセストークンを使用してリソースにアクセスするための REST API 呼び出しを行います。
トークンを使用してインシデントテーブルにアクセスする cURL コマンドは次のとおりです。
$ curl -H "Authorization: Bearer KynMY2H0uwWkRc8g8YLXjnQxWbH5_wbnSiLsnaOoKw61GZkkV0ytZP74uF7hJyjfsWfaaFijqQzq2kcABNJxN" https://instancename.service-now.com/api/now/v1/table/incident