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. 左下のアバターから、[Bitbucket settings] をクリックします。
  2. 左側のナビゲーションから [OAuth] をクリックします。[コンシューマーの追加] ボタンをクリックします。
    システムは次の情報をリクエストします。

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

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

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

    • If you do include the URL in a request it must be appended to the same URL configured in the consumer. So if your consumer callback URL is example.com/add-on the URL in your request must be something similar to example.com/add-on/function.

    • リクエストに URL を含めない場合、リダイレクト先はコンシューマーのコールバック URL になります。
    URL ご利用のアプリケーションについての詳細情報を確認できる、任意の URL。
  3. [保存] をクリックします。
    システムによってキーとシークレットが生成されます。
  4. コンシューマー名を選択して、コンシューマー用に生成されたキーシークレット値を表示します。

Access tokens

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

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

許可の種類

認可コードの付与

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

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

The callback includes the ?code={} query parameter that you can swap for an access token:

$ 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

That will redirect to the callback URL with a fragment containing the access token (#access_token={token}&token_type=bearer) where your page's JavaScript can pull it out of the URL.

リクエストの作成

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

  1. Send it in a request header: Authorization: Bearer {access_token}
  2. Include it in a (application/x-www-form-urlencoded) POST body as access_token={access_token}
  3. Put in the query string of a non-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

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

  • すべてのメール アドレスの閲覧
  • language
  • 場所
  • website
  • 氏名
  • SSH キー
  • ユーザー グループ
account:write

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

  • 認可しているユーザーのアカウントの削除
  • ユーザーのグループの管理
  • ユーザーのメール アドレスの操作
  • ユーザー名、表示名、アバターの変更
team

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

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

Grants (implies) the team scope and adds the ability to manage the teams on which the authorizing user is an administrator.

  • チームの管理権限
repository

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

  • リポジトリのソース コードへのアクセス
  • clone over https://
  • API を使用したファイルへのアクセス
  • リポジトリのコンテンツの zip アーカイブのダウンロード
  • すべてのリポジトリでの課題トラッカーの表示および使用権限 (作成済みの課題、コメント、投票など)
  • すべてのリポジトリでの Wiki の表示および使用権限 (ページの作成/編集)
repository:write

Grants (implies) the repository scope and adds write access to all the repositories to which the authorizing user has access. No distinction is made between public or private repos. This scope alone does not give access to the pull requests API.

  • https 経由でのプッシュ アクセス
  • リポジトリのフォーク
repository:admin

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

  • コミッター マッピングの表示および操作
  • デプロイ キーの一覧表示および編集
  • リポジトリの削除権限
  • リポジトリ権限の表示および編集
  • ブランチ権限の表示および編集
  • 課題トラッカーのインポートおよびエクスポート
  • 課題トラッカーの有効化および無効化
  • 課題トラッカーのバージョン、マイルストーン、およびコンポーネントの一覧表示および編集
  • Wiki の有効化および無効化
  • 既定のレビュワーの一覧表示および編集
  • リポジトリ リンク (Jira / Bamboo / Custom) の一覧表示および編集
  • リポジトリの web hook の一覧表示および編集
  • リポジトリ所有権の譲渡の開始
pullrequest

Grants read access to pull requests and the ability to collaborate on a specific pull request through comments, tasks, and approvals. This scope implies repository, giving read access to the pull request's destination repository.

  • プル リクエストの閲覧および一覧表示
  • タスクの作成および解決
pullrequest:write

Grants (implies) the  pullrequest scope and adds the ability to create, merge and decline pull requests. This scope also implies repository:write, giving write access to the pull request's destination repository. This is necessary to facilitate merging.

  • プル リクエストのマージ
  • プル リクエストの却下
  • プルリクエストの作成
  • プル リクエストへのコメント
  • プル リクエストの承認
snippet

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

  • 任意のスニペットの表示
  • スニペット コメントの作成
snippet:write

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

  • スニペットの編集
  • スニペットの削除
issue

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

  • 課題の表示、一覧表示、および検索
  • 新しい課題の作成
  • 課題にコメントする
  • 課題のウォッチ
  • 課題への投票
issue:write

Grants (implies) the issue scope and adds the ability to transition and delete issues. This scope does not imply any other scopes and does not give implicit access to the repository to which the issue is attached.

  • 課題のトランジション
  • 課題の削除

wiki

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

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

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

  • アクセス可能なリポジトリ、ユーザー、チーム、またはスニペットに関する webhook サブスクリプションの一覧表示
  • webhook サブスクリプションの作成、更新、または削除

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

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

However, to create a webhook for issue:created, the client will need to have both the webhook and the issue scope.


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

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

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

The literal string x-token-auth as a substitute for username is required.

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



最終更新日 2018 年 8 月 21 日

この内容はお役に立ちましたか?

はい
いいえ
この記事についてのフィードバックを送信する
Powered by Confluence and Scroll Viewport.