Bitbucket Cloud で OAuth を使用する

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 コンシューマーと呼ばれます。コンシューマーは既存の任意のワークスペースで作成できます。コンシューマーを作成するには、以下を実行します。

  1. 画面上部のナビゲーション バーからアバター (自身のプロファイル) を選択します。

  2. [Recent workspaces (最近使用したワークスペース)] で、コンシューマーを使用してアクセスするワークスペースを選択するか、[すべてのワークスペース] でワークスペースを見つけて開きます。

  3. 上部のナビゲーション バーにある [設定] (歯車アイコン ) を選択します。

  4. [設定] ドロップダウン メニューから [ワークスペース設定] を選択します。

  5. サイドバーの [アプリと機能] で [OAuth コンシューマー] を選択します。

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

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

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

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

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

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

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

  7. [保存] をクリックします。キーとシークレットが生成されます。

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

アクセス トークン

アクセス トークン/ベアラー トークンを取得するために、RFC-6749 の 3 つの付与フローと、次の URL を介して JWT トークンをアクセス トークンと交換するカスタム Bitbucket フローがサポートされています。

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

Resource Owner Password Credentials Grant (4.3) はサポートされなくなりました。詳細については、OAuth 2.0 開発者向けドキュメントをご確認ください。

許可の種類

認可コードの付与

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

利用可能なスコープのリストと、付与されるアクセス権の詳細については、「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 はユーザー名フィールドに実際のトークンを挿入する点がわずかに異なります。

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

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