エンドユーザーに認可するスコープを選択させる方法

はじめに

Authlete を用いて認可サーバーを構築する場合、認可画面にてエンドユーザー（リソースオーナー）に認可するスコープを選択させるように設計することができます。本記事では、このような機能を実現するために用いる Authlete の API について紹介します。

認可リクエストからスコープ一覧を取得

最初に必要となるのは、クライアントがリクエストしているスコープの把握です。それらのスコープはクライアントからの認可リクエストの、“scope” パラメーターに含まれています。Authlete の /auth/authorization API は認可リクエストを解析し、認可サーバーに対して、どのスコープが要求されているかを “scopes” の配列として回答します。以下はリクエスト・レスポンスの例です。

• リクエスト

$ curl -s -X POST https://api.authlete.com/api/auth/authorization \
 -u ...:... \
 -H 'Content-type: application/json' \
 -d '{"parameters":
  "redirect_uri=...
   &client_id=...
   &response_type=code
   &scope=read+write"}'

• レスポンス

{
  "type": "authorizationResponse",
  "resultCode": "A004001",
  "resultMessage":
   "[A004001] Authlete has successfully issued a ticket
    to the service (API Key = ...) for the authorization
    request from the client (ID = ...).
    [response_type=code, openid=false]",
...
  "scopes": [
    {
      "defaultEntry": false, "description": "Read",
      "descriptions": [
        { "tag": "en", "value": "Read" },
        { "tag": "ja", "value": "参照" } ],
    "name": "read"
    },
    {
      "defaultEntry": false, "description": "Write",
      "descriptions": [
        { "tag": "en", "value": "Write" },
        { "tag": "ja", "value": "更新" } ],
    "name": "write"
    }
  ]
...

この “scopes” の値をもとに、クライアントに付与するアクセス権をエンドユーザーに選択してもらうような認可ページを構成できるようになります。

エンドユーザーが選択したスコープを指定

エンドユーザーの意図を承けた認可サーバーは、Authlete に対し、ユーザーが選択したスコープを持つアクセストークン (and/or 認可コード) の発行を要求します。

このような、クライアントからの元々の認可リクエストが要求していたスコープを「絞る」機能の実現には、Authlete の /auth/authorization/issue API へのリクエストパラメーターのひとつである “scopes” を用います。空ではない、文字列の配列をこの scopes パラメーターに指定すると、Authlete はそれを発行するトークンのスコープとして用います。以下はリクエスト・レスポンスの例です。

• リクエスト

curl -s -X POST https://api.authlete.com/api/auth/authorization/issue \
-u ...:... \
-H 'Content-type: application/json' \
 -d '{"subject":"...",
   "ticket": "...",
   "scopes":["read"]}
'

• レスポンス

{
  "type": "authorizationIssueResponse",
  "resultCode": "A040001",
  "resultMessage":
    "[A040001] The authorization request was processed successfully.",
  "accessToken": "...",
  "accessTokenDuration": ...,
  "accessTokenExpiresAt": ...,
  "action": "LOCATION",
  "responseContent":
    "https://client.example.org/cb/example.com
     #access_token=...
      &token_type=Bearer
      &expires_in=...
      &scope=read"
}

結果的に認可サーバーは、クライアントに対し、「絞られた」スコープを持つアクセストークンを与えることになります。

上記機能では、最初の認可リクエスト中にないスコープを追加することはできません。あくまでも、認可リクエストでのスコープからスコープを「絞る」ことにのみ利用できます。