トークンのダウンスコープ
トークンのダウンスコープ
ダウンスコープは、既存のアクセストークンをより制限の 厳しい新しいトークンと交換するための方法です。
ダウンスコープする理由
アプリケーションは、完全に制御できない環境とアクセストークンを共有しなければならないことがあります。その一般的な例として、ウェブブラウザでBox UI Elementsを使用する場合があります。
アプリケーションがアクセストークンをブラウザに渡す必要がある場合、解決が必要となるセキュリティリスクが生じる可能性があります。このリスクを抑制するために、アクセストークンを、権限がより厳格な新しいトークンと交換できます。
概要
ダウンスコープされたトークンは、元のトークンよりも権限 (スコープ) が少ないトークンです。また、オプションで、特定のファイルへのアクセスのみを許可するようさらに制限される場合もあります。
新しいトークンは、元のトークンの権限を取得し、渡されたトークンのほか、提供されたリソースにその権限を制限します。
ダウンスコープの実例
トークンをダウンスコープするには、POST /oauth2/tokenエンドポイントに既存のアクセストークン、スコープのリストのほか、トークンを制限するファイルのURL (省略可) を渡します。
cURL
curl -i -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"TypeScript Gen
let resource = 'https://api.box.com/2.0/files/123456789';
let token = await oauth.downscopeToken(['item_preview'], resource);
const auth = new BoxDeveloperTokenAuth({ token: token.accessToken });
const client = new BoxClient({ auth });Python Gen
from box_sdk_gen import BoxDeveloperTokenAuth, AccessToken, BoxClient
resource = "https://api.box.com/2.0/files/123456789"
downscoped_token: AccessToken = auth.downscope_token(
scopes=["item_preview"],
resource=resource,
)
downscoped_auth = BoxDeveloperTokenAuth(token=downscoped_token.access_token)
client = BoxClient(auth=downscoped_auth).NET Gen
using Box.Sdk.Gen;
resourcePath = 'https://api.box.com/2.0/files/123456789'
AccessToken downscopedToken = await auth.DownscopeTokenAsync(
scopes: Array.AsReadOnly(new [] {"item_rename","item_preview"}), resource: resourcePath
);
BoxClient downscopedClient = new BoxClient(auth: new BoxDeveloperTokenAuth(token: downscopedToken.AccessTokenField));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)
downscoped_client = Client(
OAuth2(
client_id=None,
client_secret=None,
access_token=token_info.access_token
)
).NET
var exchanger = new TokenExchange(client.Auth.Session.AccessToken, "item_preview");
exchanger.SetResource("https://api.box.com/2.0/files/123456789");
string downscopedToken = await exchanger.ExchangeAsync();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 | ダウンスコープする元のトークン。これには、OAuth 2.0やJWTトークン交換で取得したトークン、またはアプリトークンとして取得されたトークンを使用できます。 |
scope | 新しいトークンを制限するためのスコープのスペース区切りリスト。アプリケーションに有効な任意のスコープを使用できますが、Box UI Elementsのスコープの特殊なセットも使 用可能です。 |
resource | トークンが制限されるファイルへの完全なURLパス (省略可)。 |
box_shared_link | Box上のファイルまたはフォルダの共有リンクURL (省略可)。パスワード保護されているリンクはサポートされていません。このオプションは、resourceオプションに追加して使用することができません。また、ウェブリンクに作成された共有リンクを指定することもできません。 |
subject_token_type | 常にurn:ietf:params:oauth:token-type:access_tokenに設定します。 |
grant_type | 常に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の各組み合わせが含まれます。