トークンのダウンスコープ
トークンのダウンスコープ
ダウンスコープは、既存のアクセストークンをより制限の厳しい新しいトークンと交換するための方法です。
ダウンスコープする理由
アプリケーションは、完全に制御できない環境とアクセストークンを共有しなければならないことがあります。その一般的な例として、ウェブブラウザでBox UI Elementsを使用する場合があります。
アプリケーションがアクセストークンをブラウザに渡す必要がある場合、解決が必要となるセキュリティリスクが生じる可能性があります。このリスクを抑制するために、アクセストークンを、権限がより厳格な新しいトークンと交換できます。
概要
ダウンスコープされたトークンは、元のトークンよりも権限(スコープ)が少ないトークンです。また、オプションで、特定のファイルへのアクセスのみを許可するようさらに制限される場合もあります。
新しいトークンは、元のトークンの権限を取得し、渡されたトークンのほか、提供されたリソースにその権限を制限します。
ダウンスコープの実例
トークンをダウンスコープするには、POST /oauth2/tokenエンドポイントに既存のアクセストークン、スコープのリストのほか、トークンを制限するファイルのURL(省略可)を渡します。
cURL
curl -X POST https://api.box.com/oauth2/token \
-H 'Content-Type: application/x-www-form-urlencoded' \
-d 'subject_token=[ACCESS_TOKEN]' \
-d 'subject_token_type=urn:ietf:params:oauth:token-type:access_token' \
-d 'scope=item_upload item_preview base_explorer' \
-d 'resource=https://api.box.com/2.0/folders/123456' \
-d 'grant_type=urn:ietf:params:oauth:grant-type:token-exchange'.NET
var exchanger = new TokenExchange(client.Auth.Session.AccessToken, "item_preview");
exchanger.SetResource("https://api.box.com/2.0/files/123456789");
string downscopedToken = exchanger.Exchange();Java
BoxAPIConnection api = new BoxAPIConnection("YOUR-ACCESS-TOKEN");
String resource = "https://api.box.com/2.0/files/RESOURCE-ID";
List<String> scopes = new ArrayList<String>();
scopes.add("item_preview");
scopes.add("item_content_upload");
ScopedToken token = api.getLowerScopedToken(scopes, resource);Python
target_file = client.file(file_id='FILE_ID_HERE')
token_info = client.downscope_token(['item_preview'], target_file)
print('Got downscoped access token: {0}'.format(token_info.access_token))Node
client.exchangeToken('item_preview', 'https://api.box.com/2.0/files/123456789')
.then(tokenInfo => {
// tokenInfo.accessToken contains the new downscoped access token
});| パラメータ | 説明 |
|---|---|
subject_token | The original token to downscope. This can be a token that was acquired through OAuth 2.0, JWT token exchange, or as an App Token. |
scope | A space-delimited list of scopes to limit the new token to. Any valid scope for the application can be used, though a special set of scopes for Box UI elements is available |
resource | An optional full URL path to the file the token should be restricted to. |
subject_token_type | Always set to urn:ietf:params:oauth:token-type:access_token |
grant_type | Always set to urn:ietf:params:oauth:grant-type:token-exchange |
ダウンスコープされたアクセストークンオブジェクト
POST /oauth2/tokenエンドポイントで返されるダウンスコープされたアクセストークンには、特定の制限に関する追加情報が含まれます。
{
"access_token": "1!DgsZ6V9kMWZu2StrxwQDF5BudQNen-xUmU2cfcVKArE....",
"expires_in": 4175,
"token_type": "bearer",
"restricted_to": [
{
"scope": "item_preview",
"object": {
"type": "folder",
"id": "1234567890",
"sequence_id": "0",
"etag": "0",
"name": "Test"
}
}
],
"issued_token_type": "urn:ietf:params:oauth:token-type:access_token"
}
ここで最も重要なのは、restricted_toエントリのリストです。このリストには、新しいトークンが権限を持つobjectとscopeの各組み合わせが含まれます。