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

For obtaining access/bearer tokens, we support three of RFC-6749's grant flows, plus a custom Bitbucket flow for exchanging JWT tokens for access tokens. Note that Resource Owner Password Credentials Grant (4.3) is no longer supported. Check out our OAuth 2.0 developer documentation for more details.

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

コンシューマーの作成

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

画面上部のナビゲーションバーからアバター (自身のプロファイル) を選択します。
[Recent workspaces (最近使用したワークスペース)] で、コンシューマーを使用してアクセスするワークスペースを選択するか、[すべてのワークスペース] でワークスペースを見つけて開きます。
上部のナビゲーションバーにある [設定] (歯車アイコン ) を選択します。
[設定] ドロップダウンメニューから [ワークスペース設定] を選択します。
サイドバーの [アプリと機能] で [OAuth コンシューマー] を選択します。
[コンシューマーを追加] ボタンをクリックします。
システムは次の情報をリクエストします。
名前: コンシューマーの表示名。これはアカウント内で固有である必要があります。入力は必須です。
説明: 任意で、コンシューマーの実行内容の説明を追加します。
コールバック URL: OAuth 2.0 コンシューマーでは必須です。
リクエストの作成時に、コールバック URL をリクエストに含めることができます。
- リクエストに URL を含める場合、コンシューマーで構成された URL と同じものを追加する必要があります。したがって、コンシューマーのコールバック URL が example.com/add-on の場合、リクエスト内の URL は example.com/add-on/function などのようにする必要があります。
- リクエストに URL を含めない場合、リダイレクト先はコンシューマーのコールバック URL になります。
URL: ご愛用のアプリケーションに関する詳細情報を確認できる、任意の URL です。
[保存] をクリックします。キーとシークレットが生成されます。
コンシューマー名を選択して、コンシューマー用に生成されたキーとシークレット値を表示します。

アクセストークン

For obtaining access/bearer tokens, we support three of RFC-6749's grant flows, plus a custom Bitbucket flow for exchanging JWT tokens for access tokens through the following URL's:

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

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

Resource Owner Password Credentials Grant (4.3) is no longer supported. Check out our OAuth 2.0 developer documentation for more details.

許可の種類

認可コードの付与

本格的な 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 はクライアント / コンシューマーに存在しているスコープ以外のスコープがパラメーターに含まれていないことを確認します。追加のスコープがリクエストされている場合は失敗しますが、既存のスコープの一部への要求は生成されるアクセストークンには影響しません。

For a list of available scopes and details of the access they grant, visit Atlassian Developer: Bitbucket Cloud Reference — Scopes.

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

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

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

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

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

コンシューマーを削除する

上部のナビゲーションバーにある [設定] ( のアイコン) を選択します。
[設定] ドロップダウンメニューの [Bitbucket 管理] で [ワークスペース設定] を選択します。
左側のサイドバーにある [アプリと機能] から [OAuth コンシューマー] を選択します。
削除したいコンシューマーエントリーの右側にあるを選択します。
[削除] を選択します。これにより、そのコンシューマーにリンクされている既存のトークンもすべて削除されます。

If you need to delete a consumer because its credential has been compromised, follow the procedure outlined in App security incident management guidelines for Marketplace Partners.

OAuth コンシューマーの例
コンシューマーによる OAuth ライブラリの使用方法の例をご覧ください。

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

正確ではなかった明確ではなかった関係なかった

さらにヘルプが必要ですか?

アトラシアンコミュニティをご利用ください。

コミュニティに質問