Bitbucket Cloud の REST API 連携および Atlassian Connect for Bitbucket アドオンは OAuth 2.0 を使用して Bitbucket のリソースにアクセスできます。
OAuth 2.0
アクセス トークン/ベアラー トークンを取得するために、RFC-6749 の 3 つの付与フローと、JWT トークンをアクセス トークンと交換するためのカスタム Bitbucket フローがサポートされています。Resource Owner Password Credentials Grant (4.3) はサポートされなくなりましたので、ご注意ください。詳細については、OAuth 2.0 開発者向けドキュメントをご確認ください。
このセクションでは、コンシューマーを登録して 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 です。
[保存] をクリックします。キーとシークレットが生成されます。
コンシューマー名を選択して、コンシューマー用に生成されたキーとシークレット値を表示します。
アクセス トークン
アクセス トークン/ベアラー トークンを取得するために、RFC-6749 の 3 つの付与フローと、次の URL を介して JWT トークンをアクセス トークンと交換するカスタム Bitbucket フローがサポートされています。
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 に従って次のいずれかの方法でリクエストでアクセス トークンを使用できます (以降は推奨順で記載)。
リクエスト ヘッダーで送信: Authorization: Bearer {access_token}
(application/x-www-form-urlencoded) の POST の本文に access_token={access_token} として含める
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 はクライアント / コンシューマーに存在しているスコープ以外のスコープがパラメーターに含まれていないことを確認します。追加のスコープがリクエストされている場合は失敗しますが、既存のスコープの一部への要求は生成されるアクセス トークンには影響しません。
利用可能なスコープのリストと、付与されるアクセス権の詳細については、「Atlassian Developer: Bitbucket Cloud リファレンス — スコープ」を参照してください。
アクセス トークンでリポジトリのクローンを作成する
アドオンは自身の SSH キーをアップロードしてクローンすることはできないため、HTTPS を介して安全にクローンするために、アクセス トークンを Basic HTTP 認証の資格情報として使用できます。
1
$ git clone https://x-token-auth:{access_token}@bitbucket.org/user/repo.git
ユーザー名の代替としてリテラル文字列 x-token-auth が必要です。
このプロセスは GitHub と似ていますが、GitHub はユーザー名フィールドに実際のトークンを挿入する点がわずかに異なります。
