Rich Authorization Requests (RAR)

For Authlete 2.x documentation, see 2.x version.

はじめに

本記事では、Authlete における RAR のサポートと、その機能を使って適切な粒度の権限を処理する方法を説明します。仕様の詳細については RAR 仕様の概要をご参照ください。

設定

Authlete の RAR サポートを利用するためには、サービスとクライアントの双方に、認可詳細 (authorization_details) のタイプ (type) を設定する必要があります。

サービス: サポートする認可詳細タイプの追加
クライアント: 利用できる認可詳細タイプの指定

サービスの設定

「サポート可能な認可詳細タイプ」の設定は、コンソールの各サービスの設定 → 「トークン&クレーム」 → 「詳細設定」 → 「スコープ」タブにあります。ただし、クライアントに対して自動的に利用可能になるものではありません。

クライアントの設定

クライアントが使用する「認可詳細タイプ」の設定は、コンソールの各クライアントの設定 → 「トークンとクレーム」 → 「詳細設定」 → 「スコープ」タブにあります。ここに設定したタイプが、クライアントからリクエスト可能な認可詳細タイプになります。

利用例

認可リクエスト

RAR は、そのまま URL エンコードされているか、リクエストがプッシュ（PAR）されているか、あるいはリクエストオブジェクト（JAR）のメカニズムが使われているかに関わらず、使用することができます。ただし、それらのメカニズムには特有の制約があります。RARのリクエストが非常に大きい場合、クライアントはPARを使用する必要があります。また、リクエストの改ざん検知（改ざんの証拠が残る状態）を確実にする必要がある場合は、リクエストオブジェクト（またはJAR）を使用すべきです。

リクエスト

URL エンコードされたリクエスト

たとえばクライアントが、RAR を URL エンコードして、それを認可リクエストに含めて送信した場合、認可リクエストを受け取った認可サーバーから Authlete の /auth/authorization API へのリクエストは、以下のようになります。

curl --request POST 'https://api.authlete.com/api/auth/authorization' \
     --header 'Content-Type: application/json' \
     --header 'Authorization: Basic OXXXXXXXXXX=' \
     --data '{
         "parameters": "client_id=4025660683512920&
            scope=openid&
            response_type=code&
            redirect_uri=https%3A%2F%2Fmobile.example.com%2Fcb&
            code_challenge=NcCW6zMwKWy5Mya8jopzE1SVeTBJBAHH1jU7TPpYK9A&
            code_challenge_method=S256&
            authorization\_details=%5B%7B%22type%22%3A%20%22customer\_information%22%2C%22locations%22%3A%20%5B%22https%3A%2F%2Fexample.com%2Fcustomers%22%2C%5D%2C%22actions%22%3A%5B%22read%22%2C%22write%22%5D%2C%22datatypes%22%3A%5B%22contacts%22%2C%22photos%22%5D%7D%5"
     }'

JAR でラップされたリクエスト

この RAR の内容を、クライアントが JAR にラップした場合には、以下のサンプルのようになります。ここでは、Authlete が認可サーバーに、認可リクエストの内容をエコーバックしています。認可サーバーはこの内容をもとに、ユーザーの承認を確認します。

curl --request POST 'https://api.authlete.com/api/auth/authorization' \
--header 'Content-Type: application/json' \
--header 'Authorization: Basic OXXXXXX8=' \
--data-raw '{ "parameters": "client_id=4025658857453025request=eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsImtpZCI6InNpZzEifQ.eyJpc3MiOiI0MDI1NjU4ODU3NDUzMDI1IiwiYXVkIjoiaHR0cHM6Ly9hdXRobGV0ZS5jb20iLCJyZXNwb25zZV90eXBlIjoiY29kZSIsImNsaWVudF9pZCI6IjQwMjU2NTg4NTc0NTMwMjUiLCJyZWRpcmVjdF91cmkiOiJodHRwczovL21vYmlsZS5leGFtcGxlLmNvbS9jYiIsInNjb3BlIjoib3BlbmlkIiwic3RhdGUiOiJhZjBpZmpzbGRraiIsImNvZGVfY2hhbGxlbmdlIjoiQW9OM29NcVFvUVF1RGhoQmc2VTF2Y0ljbXRtQ19QWm9UMGNoVEVSVktFZyIsImNvZGVfY2hhbGxlbmdlX21ldGhvZCI6IlMyNTYiLCJhdXRob3JpemF0aW9uX2RldGFpbHMiOlt7InR5cGUiOiJjdXN0b21lcl9pbmZvcm1hdGlvbiIsImxvY2F0aW9ucyI6WyJodHRwczovL2V4YW1wbGUuY29tL2N1c3RvbWVycyJdLCJhY3Rpb25zIjpbInJlYWQiLCJ3cml0ZSJdLCJkYXRhdHlwZXMiOlsiY29udGFjdHMiLCJwaG90b3MiXX1dLCJpYXQiOjE2Mjg1MzE0NDQsIm5iZiI6MTYyODUzMTQ0NCwiZXhwIjoxNjI4NTMyMDQ5LCJqdGkiOiI4WjJEbGpCaUZVckpnTUt3bThiQ3EifQ.PIxVI2GFWi7B_frRfLg9r8AWEz7HGeopMeQo7MLYVEMGpOdoPkt5piBrLXI7PPI7ohrUmhxd-B4kZfm4WfkKH5qSub4A_mdd6pBpTWacBgfVQDIOvzE1yPrawCDEWQn2xgdYd1G-KM6pk8rDngOMEfaBbnoJ5C9krQtgYMHGbDIScgm8Y5AHf5aEF41FboZI67BlvbzXdxcJEPvB2zLGwV9twMrJ07OeRX0NVpIamhhEgfMQ87FyOsPVx9bqYUPN_VjwgB8lkKgrCdIkc9jPs2mQkpUbx0AIg8Pfmwyw0F5Vih7tgBbpb1LlwNgW36La3DPtTY9xSZ7SQGcyGxteIA" }'

レスポンス

{
    "type": "authorizationResponse",
    "resultCode": "A004001",
    "resultMessage": "[A004001] Authlete has successfully issued a ticket to the service (API Key = 979748525706) for the authorization request from the client (ID = 4025658857453025). [response_type=code, openid=true]",
    "action": "INTERACTION",
    "authorizationDetails": {
        "elements": [
            {
                "actions": ["read", "write"],
                "dataTypes": ["contacts", "photos"],
                "locations": ["https://example.com/customers"],
                "type": "customer_information"
            }
        ]
    },
    "requestObjectPayload": "{\"iss\":\"4025658857453025\",\"aud\":\"https://authlete.com\",\"response_type\":\"code\",\"client_id\":\"4025658857453025\",\"redirect_uri\":\"https://mobile.example.com/cb\",\"scope\":\"openid\",\"state\":\"af0ifjsldkj\",\"code_challenge\":\"AoN3oMqQoQQuDhhBg6U1vcIcmtmC_PZoT0chTERVKEg\",\"code_challenge_method\":\"S256\",\"authorization_details\":[{\"type\":\"customer_information\",\"locations\":[\"https://example.com/customers\"],\"actions\":[\"read\",\"write\"],\"datatypes\":[\"contacts\",\"photos\"]}],\"iat\":1628531444,\"nbf\":1628531444,\"exp\":1628532049,\"jti\":\"8Z2DljBiFUrJgMKwm8bCq\"}",
    "ticket": "xTZCagNjVJUltVS-WD7CKZr1fp0zeFTAAva86Rmzuow"
}

トークンリクエスト

ユーザーが承認した後に、認可サーバーは認可コードを生成し、それをクライアントへ返却します。クライアントは認可サーバーのトークンエンドポイントにアクセスします（必要であればそこでクライアント認証を受けます）。認可サーバーから呼び出された Authlete の /auth/token API は、アクセストークンと、もし openid スコープが指定されていれば ID トークンも生成します。

リクエスト

curl --request POST 'https://api.authlete.com/api/auth/token' \
--header 'Content-Type: application/json' \
--header 'Authorization: Basic OXXXXXXXXXXXXXXXX8=' \
--data '{ "parameters": "grant_type=authorization_code&code=wkPCpsu-HsMDeaNFBI78LydnmW7IyadBLloa3Mn7ZzM&redirect_uri=https%3A%2F%2Fmobile.example.com%2Fcb&code_verifier=ZhoMDipQfa7iMabyG-wSQ83ATy1GCVvE8Lh3SlDZdNo", "clientId" : "4025658857453025" }'

レスポンス

{
    "type": "tokenResponse",
    "resultCode": "A050001",
    "resultMessage": "[A050001] The token request (grant_type=authorization_code) was processed successfully.",
    "accessToken": "Q4nS7518ZP4W0JaabMGJRBYGj919SY1IyxuDHZUw_Qc",
    "action": "OK",
    "authorizationDetails": {
        "elements": [
            {
                "actions": [
                    "read",
                    "write"
                ],
                "dataTypes": [
                    "contacts",
                    "photos"
                ],
                "locations": [
                    "https://example.com/customers"
                ],
                "type": "customer_information"
            }
        ]
    },
    "idToken": "eyJraWQiOiIzIiwiYWxnIjoiUlMyNTYifQ.eyJjcGYiOiIzOTY3ODczNjY4MyIsIm5hbWUiOiJDYXNleSBQdXJkeSIsImVtYWlsIjoiQ2lhcmFfU3BvcmVyQGdtYWlsLmNvbSIsImlzcyI6Imh0dHBzOi8vYXV0aGxldGUuY29tIiwic3ViIjoiQ2lhcmFfU3BvcmVyQGdtYWlsLmNvbSIsImF1ZCI6WyI0MDI1NjU4ODU3NDUzMDI1Il0sImV4cCI6MjUzNDAyMTI4MDAwLCJpYXQiOjE2Mjg1MzIzMjAsInNfaGFzaCI6ImJPaHRYOEY3M0lNalNQZVZBcXh5VFEifQ.Vrc3BcXtnAUtrnfSOPWagTWnV_SB0DL5cEp535pt33n8S4op94GSM51waTS6OcoZ-R7YKQ0l7FrMGxFl6MGFd6Wn_FjHNyu7J2TmEH9sARZTW7ZmWQo5euWkLx6NjgMAp_9LsjDXwB8Cjr3ujkVt3DdKRg6fkETwgGYYkEIrfdtRO_yJLANunHG-wm92TzOd44xXaTBF4bBinBcZFUrpr2nCPRM0rrUmBLw...",
    "responseContent": "{\"access_token\":\"Q4nS7518ZP4W0JaabMGJRBYGj919SY1IyxuDHZUw_Qc\",\"authorization_details\":[{\"type\":\"customer_information\",\"locations\":[\"https://example.com/customers\"],\"actions\":[\"read\",\"write\"],\"datatypes\":[\"contacts\",\"photos\"]}],\"scope\":\"openid\",\"id_token\":\"eyJraWQiOiIzIiwiYWxnIjoiUlMyNTYifQ.eyJjcGYiOiIzOTY3ODczNjY4MyIsIm5hbWUiOiJDYXNleSBQdXJkeSIsImVtYWlsIjoiQ2lhcmFfU3BvcmVyQGdtYWlsLmNvbSIsImlzcyI6Imh0dHBzOi8vYXV0aGxldGUuY29tIiwic3ViIjoiQ2lhcmFfU3BvcmVyQGdtYWlsLmNvbSIsImF1ZCI6WyI0MDI1NjU4ODU3NDUzMDI1Il0sImV4cCI6MjUzNDAyMTI4MDAwLCJpYXQiOjE2Mjg1MzIzMjAsInNfaGFzaCI6ImJPaHRYOEY3M0lNalNQZVZBcXh5VFEifQ.Vrc3BcXtnAUtrnfSOPWagTWnV_SB0DL5cEp535pt33n8S4op94GSM51waTS6OcoZ-R7YKQ0l7FrMGxFl6MGFd6Wn_FjHNyu7J2TmEH...
    ...
}

トークンイントロスペクションリクエスト

アクセストークンを含む API リクエストを受信したリソースサーバーは、そのアクセストークンにどのような認可が与えられているかを確認するために、イントロスペクションエンドポイントを用います。

リクエスト

以下は、リソースサーバーが認可サーバーに RFC 7662 準拠のトークンイントロスペクションを行い、そして認可サーバーが Authlete の /auth/introspection/standard API を呼び出す例です。

curl --request POST 'https://api.authlete.com/api/auth/introspection/standard' \
--header 'Content-Type: application/json' \
--header 'Authorization: Basic OXXXXXXXXXXXXXXXXXX8=' \
--data '{ "parameters": "token=Q4nS7518ZP4W0JaabMGJRBYGj919SY1IyxuDHZUw_Qc"}'

レスポンス

認可サーバーは API レスポンスから responseContent を抽出し、イントロスペクションレスポンスとしてリソースサーバーに返却します。このレスポンスには、アクセストークンにひもづく認可詳細 (authorization_details) が含まれています。リソースサーバーはこの内容をもとに、API リクエストを処理するか拒否するかを決定します。

{
    "type": "standardIntrospectionResponse",
    "resultCode": "A145001",
    "resultMessage": "[A145001] Introspection was performed successfully (type=access_token, active=true).",
    "action": "OK",
    "responseContent": "{        \"sub\":\"Ciara_Sporer@gmail.com\",
        \"authorization_details\":[ {
            \"type\":\"customer_information\",
            \"locations\":[\"https://example.com/customers\"],
            \"actions\":[\"read\",\"write\"],
            \"datatypes\":[\"contacts\",\"photos\"]
        }],        \"scope\":\"openid\",
        \"iss\":\"https://authlete.com\",
        \"active\":true,
        \"token_type\":\"Bearer\",
        \"exp\":1628618721,
        \"client_id\":\"4025658857453025\"
    }"
}

エンドポイント

トークン & クレーム

鍵管理

メタデータ

Error Handling & Debugging

セキュリティ

クライアント管理

サービス設定

はじめに

設定

サービスの設定

クライアントの設定

利用例

認可リクエスト

リクエスト

レスポンス

トークンリクエスト

リクエスト

レスポンス

トークンイントロスペクションリクエスト

リクエスト

レスポンス

​はじめに

​設定

​サービスの設定

​クライアントの設定

​利用例

​認可リクエスト

​リクエスト

​レスポンス

​トークンリクエスト

​リクエスト

​レスポンス

​トークンイントロスペクションリクエスト

​リクエスト

​レスポンス

はじめに

設定

サービスの設定

クライアントの設定

利用例

認可リクエスト

リクエスト

レスポンス

トークンリクエスト

リクエスト

レスポンス

トークンイントロスペクションリクエスト

リクエスト

レスポンス