Bitbucket Cloud での OAuth
Bitbucket Cloud REST API integrations, and Atlassian Connect for Bitbucket add-ons, can use OAuth 2.0 to access resources in Bitbucket.
OAuth 2.0
アトラシアンの OAuth 2 実装は、RFC-6749 の 4 つの許可フローすべてに対応しています。
このセクションでは、コンシューマーを登録して OAuth 2.0 をセットアップし、API 呼び出しを行うために必要な OAuth 2.0 の基本知識を説明します。
コンシューマーの作成
OAuth にはキーとシークレットが必要です。これらは合わせて OAuth コンシューマーと呼ばれます。コンシューマーは既存の任意のワークスペースで作成できます。コンシューマーを作成するには、以下を実行します。
- 左下のプロファイル アバターから、[Recent Workspaces] 一覧でワークスペースをクリックするか、[All workspaces] をクリックして一覧全体を表示してワークスペースを選択します。
左側のサイドバーで [設定] をクリックして、ワークスペースの設定を開きます。
左側のナビゲーションにある [アプリと機能] で [OAuth コンシューマー] をクリックします。
[コンシューマーを追加] ボタンをクリックします。
システムは次の情報をリクエストします。
フィールド
説明
名前 コンシューマーの表示名。これはアカウント内で固有である必要があります。入力は必須です。 説明 任意で、コンシューマーの実行内容の説明を追加します。 コールバック URL OAuth 2.0 コンシューマーでは必須です。
リクエストの作成時に、コール バック URL をリクエストに含めることができます。
リクエストに URL を含める場合、コンシューマーで構成された URL と同じものを追加する必要があります。したがって、コンシューマーのコールバック URL が
example.com/add-onの場合、リクエスト内の URL はexample.com/add-on/functionなどのようにする必要があります。- リクエストに URL を含めない場合、リダイレクト先はコンシューマーのコールバック URL になります。
URL ご利用のアプリケーションについての詳細情報を確認できる、任意の URL。 - [保存] をクリックします。
システムによってキーとシークレットが生成されます。 - コンシューマー名を選択して、コンシューマー用に生成されたキーとシークレット値を表示します。
アクセス トークン
アトラシアンではアクセス トークンの取得について、次の URL 経由での RFC-6749 の 4 つの許可フローすべてに対応しています。
https://bitbucket.org/site/oauth2/authorizehttps://bitbucket.org/site/oauth2/access_token許可の種類
認可コードの付与
本格的な 3-LO フロー。ブラウザで次の URL に遷移し、エンド ユーザーによる許可を求めます。
https://bitbucket.org/site/oauth2/authorize?client_id={client_id}&response_type=codeコールバックにはアクセス トークンと交換できる ?code={} クエリ パラメーターが含まれます。
$ curl -X POST -u "client_id:secret" \
https://bitbucket.org/site/oauth2/access_token \
-d grant_type=authorization_code -d code={code}暗黙的な許可
サーバー側のバックエンド サポートがないブラウザベースの操作に役立ちます。この許可タイプではブラウザで次の URL に遷移してユーザーの許可を求めます。
https://bitbucket.org/site/oauth2/authorize?client_id={key}&response_type=tokenこれは、アクセス トークン (#access_token={token}&token_type=bearer) を含むフラグメントを持つコールバック URL にリダイレクトされます。ここで、ページの JavaScript により、URL からアクセス トークンを取得できます。
リクエストの作成
アクセス トークンを取得したら、RFC-6750 に従って次のいずれかの方法でリクエストでアクセス トークンを使用できます (以降は推奨順で記載)。
- リクエスト ヘッダーで送信:
Authorization: Bearer {access_token} - (application/x-www-form-urlencoded) の POST の本文に
access_token={access_token}として含める - POST 以外のクエリ文字列に含める:
?access_token={access_token}
トークンのリフレッシュ
アクセス トークンの有効期限は 2 時間です。失効すると、401 レスポンスが返されます。
したがって、応答を許可するほとんどのアクセス トークンは、エンド ユーザーの操作なしで新しいアクセス トークンを生成するために使用できるリフレッシュ トークンを含みます。
$ curl -X POST -u "client_id:secret"
https://bitbucket.org/site/oauth2/access_token \
-d grant_type=refresh_token -d refresh_token={refresh_token}スコープ
スコープはクライアント/コンシューマーのインスタンスで定義されます。現在のところ、Bitbucket Cloud では、個々の許可リクエストでオプションのスコープ パラメーターを使用することはできません。
スコープ パラメーターが指定されると、Bitbucket はクライアント / コンシューマーに存在しているスコープ以外のスコープがパラメーターに含まれていないことを確認します。追加のスコープがリクエストされている場合は失敗しますが、既存のスコープの一部への要求は生成されるアクセス トークンには影響しません。
次のスコープが利用可能です。
| スコープ名 | 説明 |
|---|---|
account | ユーザーのアカウントの全情報への読み取り専用アクセスを許可します。
|
account:write | ユーザーのアカウントのプロパティを変更する権限を付与します。
|
| チーム | 現在のユーザーがメンバーであるチームの一覧を取得する権限を付与します。これは teams エンドポイントに含まれます。
|
team:write |
|
repository | 許可するユーザーがアクセス権を持っているすべてのリポジトリへの読み取りアクセス権限を付与します。このスコープはリポジトリのプル リクエストへのアクセス権を与えるわけではないことにご注意ください。
|
repository:write |
|
repository:admin | 許可するユーザーがアクセス権を持っているすべてのリポジトリへの管理アクセス権限を付与します。公開リポジトリと非公開リポジトリの区別は行われません。このスコープには repository または repository:write は含まれません。1 つのリポジトリの管理機能へのアクセス権のみを付与し、コンテンツへの直接アクセス権は付与しません。別のユーザー アカウントがリポジトリをクローンできるよう、読み取り権限を付与する目的で (誤って) 使用されることがありますが、ソース コードの読み取りまたは書き込みを行う必要があるリポジトリでは、明示的な読み取りまたは書き込みも要求されます。このスコープには次の機能へのアクセス権が含まれています。
|
pullrequest | プル リクエストへの読み取りアクセス権と、コメント、タスク、および承認経由で特定のプル リクエストでコラボレーションする権限を付与します。このスコープは
|
pullrequest:write |
|
snippet | 許可するユーザーがアクセス権を持っているすべてのスニペットへの読み取りアクセス権限を付与します。公開スニペットと非公開スニペットは区別されません (公開スニペットには認証なしでアクセス可能です)。
|
snippet:write | 許可するユーザーが編集できるすべてのスニペットへの書き込みアクセス権限を付与します。公開スニペットと非公開スニペットは区別されません (公開スニペットには認証なしでアクセス可能です)。Snippet Read スコープが含まれるため、これを別途リクエストする必要はありません。
|
issue | 課題トラッカーとのやり取りを許可します。他のリポジトリへのアクセス権はありません。このスコープは他のスコープを含まず、課題が関連付けられているリポジトリへの暗黙的なアクセス権は与えられません。
|
issue:write |
|
| Wiki へのアクセスを許可します。Wiki は常に全ユーザーが編集可能なため、読み取りと書き込みアクセスは区別されません。このスコープは他のスコープを含まず、課題が関連付けられているリポジトリへの暗黙的なアクセス権は与えられません。
|
email | ユーザーの主メール アドレスを表示する権限を付与します。これにより、アドオンや外部アプリケーションへのログイン プロバイダーとして Bitbucket Cloud を使いやすくなります。 |
webhook | このスコープは、ユーザーがアクセス可能なすべてのリソースに関する既存の webhook サブスクリプションへの読み取りアクセス権を付与します。他のスコープは不要です。webhook 関連の操作ではこのスコープが必要です。
つまり、クライアントはリポジトリ foo/bar に関するすべての既存の webhook サブスクリプションを一覧表示できます (ユーザーがこのリポジトリへのアクセス権を持っていることが前提です)。このスコープには追加の repository スコープは不要です。 同様に、リポジトリの課題トラッカーに関する既存の webhook サブスクリプションも issue スコープなしで取得できます。必要なのは webhook スコープのみです。 ただし、issue:created の webhook を作成する場合は、 |
アクセス トークンでリポジトリのクローンを作成する
アドオンは自身の SSH キーをアップロードしてクローンすることはできないため、HTTPS を介して安全にクローンするために、アクセス トークンを Basic HTTP 認証の資格情報として使用できます。
$ git clone https://x-token-auth:{access_token}@bitbucket.org/user/repo.gitユーザー名の代替としてリテラル文字列 x-token-auth が必要です。
このプロセスは GitHub と似ていますが、GitHub はユーザー名フィールドに実際のトークンを挿入する点がわずかに異なります。