Bitbucket Cloud で OAuth を使用する

Bitbucket Cloud の REST API 連携および Atlassian Connect for Bitbucket アドオンは OAuth 2.0 を使用して Bitbucket のリソースにアクセスできます。

OAuth 2.0

アトラシアンの OAuth 2 実装は、RFC-6749 の 4 つの許可フローすべてに対応しています。

このセクションでは、コンシューマーを登録して OAuth 2.0 をセットアップし、API 呼び出しを行うために必要な OAuth 2.0 の基本知識を説明します。

コンシューマーの作成

OAuth にはキーとシークレットが必要です。これらは合わせて OAuth コンシューマーと呼ばれます。コンシューマーは既存の任意のワークスペースで作成できます。コンシューマーを作成するには、以下を実行します。

  1. 左下のプロファイル アバターから、[Recent Workspaces] 一覧でワークスペースをクリックするか、[All workspaces] をクリックして一覧全体を表示してワークスペースを選択します。

  2. 左側のサイドバーで [設定] をクリックして、ワークスペースの設定を開きます。

  3. 左側のナビゲーションにある [アプリと機能] で [OAuth コンシューマー] をクリックします。

  4. [コンシューマーを追加] ボタンをクリックします。  

    システムは次の情報をリクエストします。

    フィールド

    説明

    名前: コンシューマーの表示名。これはアカウント内で固有である必要があります。入力は必須です。説明: 任意で、コンシューマーの実行内容の説明を追加します。コールバック URL

    OAuth 2.0 コンシューマーでは必須です。

    リクエストの作成時に、コール バック URL をリクエストに含めることができます。

    • リクエストに URL を含める場合、コンシューマーで構成された URL と同じものを追加する必要があります。したがって、コンシューマーのコールバック URL が example.com/add-on の場合、リクエスト内の URL は example.com/add-on/function などのようにする必要があります。

    • リクエストに URL を含めない場合、リダイレクト先はコンシューマーのコールバック URL になります。

    URL: ご利用のアプリケーションについての詳細情報を確認できる、任意の URL。

  5. [保存] をクリックします。
    システムによってキーとシークレットが生成されます。

  6. コンシューマー名を選択して、コンシューマー用に生成されたキーシークレット値を表示します。

アクセス トークン

アトラシアンではアクセス トークンの取得について、次の URL 経由での RFC-6749 の 4 つの許可フローすべてに対応しています。

1 https://bitbucket.org/site/oauth2/authorize
1 https://bitbucket.org/site/oauth2/access_token

許可の種類

認可コードの付与

本格的な 3-LO フロー。ブラウザで次の URL に遷移し、エンド ユーザーによる許可を求めます。

1 https://bitbucket.org/site/oauth2/authorize?client_id={client_id}&response_type=code

コールバックにはアクセス トークンと交換できる ?code={} クエリ パラメーターが含まれます。

1 2 3 $ curl -X POST -u "client_id:secret" \ https://bitbucket.org/site/oauth2/access_token \ -d grant_type=authorization_code -d code={code}

暗黙的な許可

サーバー側のバックエンド サポートがないブラウザベースの操作に役立ちます。この許可タイプではブラウザで次の URL に遷移してユーザーの許可を求めます。

1 https://bitbucket.org/site/oauth2/authorize?client_id={key}&response_type=token

これは、アクセス トークン (#access_token={token}&token_type=bearer) を含むフラグメントを持つコールバック URL にリダイレクトされます。ここで、ページの JavaScript により、URL からアクセス トークンを取得できます。

リクエストの作成

アクセス トークンを取得したら、RFC-6750 に従って次のいずれかの方法でリクエストでアクセス トークンを使用できます (以降は推奨順で記載)。

  1. リクエスト ヘッダー内に含めて送信: Authorization: Bearer {access_token}

  2. (application/x-www-form-urlencoded) の POST の本文に access_token={access_token} として含める

  3. POST 以外のクエリ文字列に含める: ?access_token={access_token}

トークンのリフレッシュ

アクセス トークンの有効期限は 2 時間です。失効すると、401 レスポンスが返されます。

したがって、応答を許可するほとんどのアクセス トークンは、エンド ユーザーの操作なしで新しいアクセス トークンを生成するために使用できるリフレッシュ トークンを含みます。

1 2 3 $ 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

ユーザーのアカウントの全情報への読み取り専用アクセスを許可します。

  • すべてのメール アドレスの閲覧

  • language

  • 場所

  • website

  • 氏名

  • SSH キー

  • ユーザー グループ

アカウント: 書き込み

ユーザーのアカウントのプロパティを変更する権限を付与します。

  • 認可しているユーザーのアカウントの削除

  • ユーザーのグループの管理

  • ユーザーのメール アドレスの操作

  • ユーザー名、表示名、アバターの変更

team

現在のユーザーがメンバーであるチームの一覧を取得する権限を付与します。これは teams エンドポイントに含まれます。

  • 自身がメンバーまたは管理者であるすべてのグループとチームについての情報

team:write

team スコープを暗黙的に許可し、許可するユーザーが管理者であるチームの管理権限を追加します。

  • チームの管理権限

repository

許可するユーザーがアクセス権を持っているすべてのリポジトリへの読み取りアクセス権限を付与します。このスコープはリポジトリのプル リクエストへのアクセス権を与えるわけではないことにご注意ください。

  • リポジトリのソース コードへのアクセス

  • https:// 経由でのクローン

  • API を使用したファイルへのアクセス

  • リポジトリのコンテンツの zip アーカイブのダウンロード

  • すべてのリポジトリでの課題トラッカーの表示および使用権限 (作成済みの課題、コメント、投票など)

  • すべてのリポジトリでの Wiki の表示および使用権限 (ページの作成/編集)

repository:write

repository スコープを暗黙的に許可し、許可するユーザーがアクセス権を持っているすべてのリポジトリへの書き込みアクセス権限を追加します。公開リポジトリと非公開リポジトリの区別は行われません。このスコープは単独ではプル リクエスト API へのアクセス権を付与しません。

  • https 経由でのプッシュ アクセス

  • リポジトリのフォーク

repository:admin

許可するユーザーがアクセス権を持っているすべてのリポジトリへの管理アクセス権限を付与します。公開リポジトリと非公開リポジトリの区別は行われません。このスコープには repository または repository:write は含まれません。1 つのリポジトリの管理機能へのアクセス権のみを付与し、コンテンツへの直接アクセス権は付与しません。別のユーザー アカウントがリポジトリをクローンできるよう、読み取り権限を付与する目的で (誤って) 使用されることがありますが、ソース コードの読み取りまたは書き込みを行う必要があるリポジトリでは、明示的な読み取りまたは書き込みも要求されます。このスコープには次の機能へのアクセス権が含まれています。

  • コミッター マッピングの表示および操作

  • デプロイ キーの一覧表示および編集

  • リポジトリの削除

  • リポジトリ権限の表示および編集

  • ブランチ権限の表示および編集

  • 課題トラッカーのインポートおよびエクスポート

  • 課題トラッカーの有効化および無効化

  • 課題トラッカーのバージョン、マイルストーン、およびコンポーネントの一覧表示および編集

  • Wiki の有効化および無効化

  • 既定のレビュワーの一覧表示および編集

  • リポジトリ リンク (Jira/Bamboo/Custom) の一覧表示および編集

  • リポジトリの web hook の一覧表示および編集

  • リポジトリ所有権の譲渡の開始

pullrequest

プル リクエストへの読み取りアクセス権限と、コメント、タスク、および承認経由で特定のプル リクエストでコラボレーションする権限を付与します。このスコープは repository スコープを含み、プル リクエストの宛先リポジトリへの読み取りアクセス権を付与します。

  • プル リクエストの閲覧および一覧表示

  • タスクの作成および解決

pullrequest:write

pullrequest スコープを暗黙的に許可し、プル リクエストの作成、マージ、および却下を行う権限を追加します。このスコープには repository:write も含まれ、プル リクエストの宛先リポジトリへの書き込みアクセス権を付与します。マージを活用するにはこのスコープが必要です。

  • プル リクエストのマージ

  • プル リクエストの却下

  • プルリクエストの作成

  • プル リクエストへのコメント

  • プル リクエストの承認

snippet

許可するユーザーがアクセス権を持っているすべてのスニペットへの読み取りアクセス権限を付与します。公開スニペットと非公開スニペットは区別されません (公開スニペットには認証なしでアクセス可能です)。

  • 任意のスニペットの表示

  • スニペット コメントの作成

snippet:write

許可するユーザーが編集できるすべてのスニペットへの書き込みアクセス権限を付与します。公開スニペットと非公開スニペットは区別されません (公開スニペットには認証なしでアクセス可能です)。Snippet Read スコープが含まれるため、これを別途リクエストする必要はありません。

  • スニペットの編集

  • スニペットの削除

課題

課題トラッカーとのやり取りを許可します。他のリポジトリへのアクセス権はありません。このスコープは他のスコープを含まず、課題が関連付けられているリポジトリへの暗黙的なアクセス権は与えられません。

  • 課題の表示、一覧表示、および検索

  • 新しい課題の作成

  • 課題にコメントする

  • 課題のウォッチ

  • 課題への投票

issue:write

issue スコープを暗黙的に許可し、課題のトランジションおよび削除を行う権限を追加します。このスコープは他のスコープを含まず、課題が関連付けられているリポジトリへの暗黙的なアクセス権は与えられません。

  • 課題のトランジション

  • 課題の削除

wiki

Wiki へのアクセスを許可します。Wiki は常に全ユーザーが編集可能なため、読み取りと書き込みアクセスは区別されません。このスコープは他のスコープを含まず、課題が関連付けられているリポジトリへの暗黙的なアクセス権は与えられません。

  • Wiki の表示

  • ページの作成

  • ページの編集

  • Wiki へのプッシュ

  • Wiki のクローン

email

ユーザーの主メール アドレスを表示する権限を付与します。これにより、アドオンや外部アプリケーションへのログイン プロバイダーとして Bitbucket Cloud を使いやすくなります。

webhook

このスコープは、ユーザーがアクセス可能なすべてのリソースに関する既存の webhook サブスクリプションへの読み取りアクセス権を付与します。他のスコープは不要です。webhook 関連の操作ではこのスコープが必要です。

  • アクセス可能な任意のリポジトリ、ワークスペース、またはスニペットに関する Webhook サブスクリプションの一覧表示

  • webhook サブスクリプションの作成、更新、または削除

つまり、クライアントはリポジトリ foo/bar に関するすべての既存の webhook サブスクリプションを一覧表示できます (ユーザーがこのリポジトリへのアクセス権を持っていることが前提です)。このスコープには追加の repository スコープは不要です。

同様に、リポジトリの課題トラッカーに関する既存の webhook サブスクリプションも issue スコープなしで取得できます。必要なのは webhook スコープのみです。

ただし、issue:created の webhook を作成する場合は、webhook スコープと issue スコープの両方を保持している必要があります。

 

アクセス トークンでリポジトリのクローンを作成する

アドオンは自身の SSH キーをアップロードしてクローンすることはできないため、HTTPS を介して安全にクローンするために、アクセス トークンを Basic HTTP 認証の資格情報として使用できます。

1 $ git clone https://x-token-auth:{access_token}@bitbucket.org/user/repo.git

ユーザー名の代替としてリテラル文字列 x-token-auth が必要です。

このプロセスは GitHub と似ていますが、GitHub はユーザー名フィールドに実際のトークンを挿入する点がわずかに異なります。

最終更新日 2020年12月 1日)
次でキャッシュ 9:05 PM on Oct 21, 2021 |

その他のヘルプ