リクエストオブジェクトの利用

Table of Contents

リクエストオブジェクトの利用

はじめに

リクエストオブジェクト とは、認可リクエストにおけるリクエストパラメーターの組を「クレーム 」として含む JWT のことです。

リクエストオブジェクトに対しては署名の付加や暗号化が可能であり、改ざんや意図しない露見の防止に有用です。またリクエストオブジェクトを「値渡し」ではなく「参照渡し」にして、Web ブラウザーのリダイレクションを介して送信される認可リクエストのサイズを小さくすることも可能です。

本記事では、Authlete がリクエストオブジェクトに対応するための手順を説明します。

設定

リクエストオブジェクトを含む認可リクエストを処理するために、Authlete サービスはリクエストオブジェクトの署名検証を行います。そのためには以下の 2 つの設定が必要です。

  1. リクエストオブジェクトの署名アルゴリズム
  2. 指定した署名アルゴリズムに対応する公開鍵

また Authlete を設定し、クライアントが以下を行えるようにすることも可能です。

  • リクエストオブジェクトの暗号化
  • “request_uri” の使用

これらの設定は、Authlete のクライアントアプリ開発者コンソール にアクセスし、クライアントごとに行います。

request-objects

1. 署名アルゴリズムの指定

「認可」タブの「リクエストオブジェクトの署名アルゴリズム」に、署名アルゴリズムを指定します。以下は “ES256” を指定した例です。

request-objects_1

2. 公開鍵の登録

「JWK セット」タブにて、「JWK セットの内容」に JWK 形式の公開鍵を登録するか、もしくは「JWK セット URI」に URL を指定します。以下は ES256 の公開鍵を登録した例です。

request-objects_2
「JWK セット」タブの「JWK セットの内容」

以上により Authlete サービスは、クライアントからの認可リクエストにリクエストオブジェクトが含まれている場合、設定された署名アルゴリズムによって決定される公開鍵に基づき、署名検証を行い、その後の処理に引き継ぐようになります。

オプション: 暗号化アルゴリズムの指定

暗号化されたリクエストオブジェクトを利用する場合には、「認可」タブの「リクエストオブジェクトのキー暗号化アルゴリズム」と「リクエストオブジェクトの本文暗号化アルゴリズム」に適切な値を指定します。

request-objects_3

オプション: request_uri の値の登録

クライアントが request (値渡し) ではなく request_uri (参照渡し) を含む認可リクエストを送信する場合には、「認可」タブの「リクエスト URI」に、適切な値を登録します。

request-objects_4

実行例

以下に API リクエスト・レスポンスの例を示します。（見やすさのために折り返しています）

リクエスト

クライアントがリクエストオブジェクトを作成

例として、クライアントが以下のペイロードを含む署名付き JWT (リクエストオブジェクト) を作成したとします。

{
   "exp": 1597130002,
   "iss": "17201083166161",
   "aud": "https://as.example.com",
   "scope": "openid profile",
   "response_type": "code",
   "client_id": "17201083166161",
   "redirect_uri": "https://client.example.org/cb/example.com",
   "nonce": "lvzxcjkb78643ki5kigsysigyb",
   "foo": "bar"
}

結果として JWT は以下のようになります。

eyJhbGciOiJFUzI1NiJ9.
ewogICJleHAiOiAxNTk3MTMwMDAyLAogICJpc3MiOiAiMTcyMDE
wODMxNjYxNjEiLAogICJhdWQiOiAiaHR0cHM6Ly9hcy5leGFtcG
xlLmNvbSIsCiAgInNjb3BlIjogIm9wZW5pZCBwcm9maWxlIiwKI
CAicmVzcG9uc2VfdHlwZSI6ICJjb2RlIiwKICAiY2xpZW50X2lk
IjogIjE3MjAxMDgzMTY2MTYxIiwKICAicmVkaXJlY3RfdXJpIjo
gImh0dHBzOi8vY2xpZW50LmV4YW1wbGUub3JnL2NiL2V4YW1wbG
UuY29tIiwKICAibm9uY2UiOiAibHZ6eGNqa2I3ODY0M2tpNWtpZ
3N5c2lneWIiLAogICJmb28iOiAiYmFyIgp9.
JnuCpEL1mRKPBUfXIO5mPtusY2lnz1w6oS6QQdYai7VUXUxfPA7
elMIWdsExc7tsSovTTAMK8mSxz9COAciY-Q

クライアントが認可リクエストを送信

次にクライアントが認可リクエストを作成します。このリクエストには、上記のリクエストオブジェクトの、値 (request パラメーター) もしくは参照 (request_uri) が含まれます。

  • 値として渡す場合
GET /cb/example.com
 &client_id=...
 &scope=openid
 &response_type=code
 &request=eyJhbGciOiJFUzI1NiJ9.
   ewogICJleHAiOiAxNTk3MTMwMDAyLAogICJpc3MiOiAiMTcyMDE
   wODMxNjYxNjEiLAogICJhdWQiOiAiaHR0cHM6Ly9hcy5leGFtcG
   xlLmNvbSIsCiAgInNjb3BlIjogIm9wZW5pZCBwcm9maWxlIiwKI
   CAicmVzcG9uc2VfdHlwZSI6ICJjb2RlIiwKICAiY2xpZW50X2lk
   IjogIjE3MjAxMDgzMTY2MTYxIiwKICAicmVkaXJlY3RfdXJpIjo
   gImh0dHBzOi8vY2xpZW50LmV4YW1wbGUub3JnL2NiL2V4YW1wbG
   UuY29tIiwKICAibm9uY2UiOiAibHZ6eGNqa2I3ODY0M2tpNWtpZ
   3N5c2lneWIiLAogICJmb28iOiAiYmFyIgp9.
   JnuCpEL1mRKPBUfXIO5mPtusY2lnz1w6oS6QQdYai7VUXUxfPA7
   elMIWdsExc7tsSovTTAMK8mSxz9COAciY-Q HTTP/1.1
Host: as.example.com
...
  • 参照として渡す場合

クライアントはリクエストオブジェクトを、request_uri によって示される場所 (例: https://client.example.org/request.jwt) に配置し、Authlete からアクセスできるようにする必要があります。

GET /cb/example.com
&client_id=...
&scope=openid
&response_type=code
&request\_uri=https://client.example.org/request.jwt

HTTP/1.1
Host: as.example.com
...

認可サーバーが Authlete API にリクエストを送信

認可サーバーは Authlete の /auth/authorization API に対してリクエストを送信します。この API リクエストには、クライアントからの認可リクエストが “parameters” の値として含まれています。さらにこの認可リクエストには、クライアントが生成した署名つき JWT が、request の値として含まれています。

curl -s -X POST https://api.authlete.com/api/auth/authorization
 -u $apiKey:$apiSecret
 -H 'Content-type: application/json'
 -d '{"parameters":
       "redirect_uri=https://client.example.org/cb/example.com
        &client_id=...
        &scope=openid
        &response_type=code
        &request=eyJhbGciOiJFUzI1NiJ9.
          ewogICJleHAiOiAxNTk3MTMwMDAyLAogICJpc3MiOiAiMTcyMDE
          wODMxNjYxNjEiLAogICJhdWQiOiAiaHR0cHM6Ly9hcy5leGFtcG
          xlLmNvbSIsCiAgInNjb3BlIjogIm9wZW5pZCBwcm9maWxlIiwKI
          CAicmVzcG9uc2VfdHlwZSI6ICJjb2RlIiwKICAiY2xpZW50X2lk
          IjogIjE3MjAxMDgzMTY2MTYxIiwKICAicmVkaXJlY3RfdXJpIjo
          gImh0dHBzOi8vY2xpZW50LmV4YW1wbGUub3JnL2NiL2V4YW1wbG
          UuY29tIiwKICAibm9uY2UiOiAibHZ6eGNqa2I3ODY0M2tpNWtpZ
          3N5c2lneWIiLAogICJmb28iOiAiYmFyIgp9.
          JnuCpEL1mRKPBUfXIO5mPtusY2lnz1w6oS6QQdYai7VUXUxfPA7
          elMIWdsExc7tsSovTTAMK8mSxz9COAciY-Q"}
'

レスポンス

適切に設定されている場合、Authlete は以下のようなレスポンスを返却します。

{
  "type": "authorizationResponse",
  "resultCode": "A004001",
  "resultMessage":
    "[A004001] Authlete has successfully issued a ticket
     to the service (API Key = 14156727624613) for the
     authorization request from the client (ID = ...).
     [response_type=code, openid=true]",
  "requestObjectPayload":
    "{\"exp\":1597130002,
      \"iss\":\"17201083166161\",
      \"aud\":\"https://as.example.com\",
      \"scope\":\"openid profile\",
      \"response_type\":\"code\",
      \"client_id\":\"17201083166161\",
      \"redirect_uri\":
        \"https://client.example.org/cb/example.com\",
      \"nonce\":\"lvzxcjkb78643ki5kigsysigyb\",
      \"foo\":\"bar\"}",
  "ticket": "rja...GiE"
[...]

この中に含まれる “requestObjectPayload” に注目してください。このキーにペイロードの値が含まれます。認可サーバーはこの内容を、続く認可プロセスに活用できます。