Bitbucket OAuth 2.0 provider API

このページの内容

お困りですか?

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

コミュニティに質問

Bitbucket Data Center provides APIs to allow external services to access resources on a user’s behalf with the OAuth 2.0 protocol.

If you already have an integration that you’d like to add to Bitbucket, see Configure an incoming link for detailed steps. If not, this page will help you understand the details of our OAuth 2.0 implementation so you can create such an integration.

サポート対象の OAuth 2.0 フロー

次の OAuth 2.0 フローがサポート対象です。

Implicit Grant と Resource Owner Password Credentials のフローは、次の OAuth 仕様バージョンで非推奨になるためサポート対象外です。

これらのフローの仕組みに関する詳細は、OAuth RFC をご確認ください。フローを理解して、自分に適したフローを選択するのに役立ちます。

セキュリティに関する推奨事項

ここでは、セキュリティ向上の方法に関する推奨事項をいくつか説明します。

CSRF 攻撃を防止する

To protect redirect-based flows, the OAuth specification recommends the use of “One-time use CSRF tokens carried in the state parameter, which are securely bound to the user agent” using the state query parameter, with each request to the /rest/oauth2/latest/authorize endpoint. This can prevent CSRF attacks.

本番環境で HTTPS を使用する

本番環境には、redirect uri に HTTPS を使用します。OAuth 2.0 のセキュリティがトランスポート層に基づいているため、これは重要になります。詳細については「OAuth 2.0 RFC」と「OAuth 2.0 脅威モデル RFC」をご確認ください。

同じ理由で、本番環境のベース URL にも HTTPS を義務付けています。関連するシステム プロパティを有効にすることで、ステージングまたは開発の各環境に安全ではない URI とベース URL を使用できます。

Proof Key for Code Exchange (PKCE) を含む認可コード

このフローによって、公開クライアント上でアクセス トークンに対するクライアント認証情報の OAuth 交換を安全に実行できます。次のステップとパラメーターでは、このフローの実装について説明しています。

パラメーター

このフローで使用するパラメーターは次のとおりです。

パラメーター説明 必須
redirect_uriリクエストの承認後にユーザーがリダイレクトされる URL。はい
client_idClient ID received from Bitbucket after registering your application.はい
response_time

認可コード。

はい
scopeユーザー アカウントに対してアプリケーションの権限を定義するスコープ。詳細については「スコープ」をご確認くださいはい
code_challenge
  • sha256 の場合は、擬似コード BASE64URL-ENCODE(SHA256(ASCII(code_verifier))) によってこれを生成します。

  • plain の場合、これは生成された code_verifier の可能性があります。

はい
code_challenge_methodcode_challenge が生成された方法に応じて、plain または sha256 になります。はい
code_verifier予約されていない文字を用いるハイエントロピー暗号ランダム文字列: [A-Z] / [a-z] / [0-9] / "-" / "." / "_" / "~"。43 ~ 127 文字にする必要があります。詳細については RFC をご確認くださいはい
state予測できない値。リクエストとコールバックの間のステータスを維持するために、クライアントによって使用されます。CSRF トークンとしても使用する必要があります。code_verifier と同様の方法で生成できます。いいえ

はじめる前に

  • Register your application in Bitbucket by creating an incoming link in application links. During registration, you can enable proper scopes to limit the range of resources which the application can access. After creating the link, you should receive the OAuth credentials: Client ID and Client secret - keep them secure. For more info, see Configure an incoming link.

  • フローを開始する前に、state (オプション)、code_verifiercode_challengecode_challenge_method を生成します。

手順

1. 次のクエリ パラメーターによって、/rest/oauth2/latest/authorize ページにユーザーをリダイレクトすることで認可コードをリクエストします。

curl https://atlassian.example.com/rest/oauth2/latest/authorize?client_id=CLIENT_ID&redirect_uri=REDIRECT_URI&response_type=code&state=STATE&scope=SCOPE&code_challenge=CODE_CHALLENGE&code_challenge_method=S256

これは、scope で指定されたスコープでアカウントにアクセスするアプリケーションのリクエストの承認をユーザーに求める同意画面です。ユーザーは、redirect_uri で指定された URL にリダイレクトされます。リダイレクトには、次の例で示すような認可コードが含まれます。

https://atlassian.example.com/plugins/servlet/oauth2/consent?client_id=CLIENT_ID&redirect_uri=REDIRECT_URI&response_type=code&scope=SCOPE&state=STATE&code_challenge_method=CODE_CHALLENGE_METHOD&code_challenge=CODE_CHALLENGE


2. 前のリクエストから返された認可 code によって、任意の HTTP クライアントで access_token をリクエストできます。次の例では curl を使用します。

curl -X POST https://atlassian.example.com/rest/oauth2/latest/token?client_id=CLIENT_ID&client_secret=CLIENT_SECRET&code=CODE&grant_type=authorization_code&redirect_uri=REDIRECT_URI&code_verifier=CODE_VERIFIER

レスポンスの例

{
 "access_token": "eyJhbGciOiJIUzI1NiJ9.eyJpZCI6IjNmMTQ3NTUzYjg3OTQ2Y2FhMWJhYWJkZWQ0MzgwYTM4In0.EDnpBl0hd1BQzIRP--xEvyW1F6gDuiFranQCvi98b2c",
 "token_type": "bearer",
 "expires_in": 7200,
 "refresh_token": "eyJhbGciOiJIUzI1NiJ9.eyJpZCI6ImMwZTMxYmZjYTI2NWI0YTkwMzBiOGM2OTJjNWIyMTYwIn0.grHOsso3B3kaSxNd0QJfj1H3ayjRUuA75SiEt0usmiM",
 "created_at": 1607635748
}


3. 新しい access_token を取得するには、refresh_token パラメーターを使用します。リフレッシュ トークンは、access_token そのものの有効期限が切れた後でも使用できます。次のリクエストは次のとおりです。

  • 既存の access_tokenrefresh_token を無効にします。

  • レスポンスで新しいトークンを送信します。

curl -X POST https://atlassian.example.com/rest/oauth2/latest/token?client_id=CLIENT_ID&client_secret=CLIENT_SECRET&refresh_token=REFRESH_TOKEN&grant_type=refresh_token&redirect_uri=REDIRECT_URI

レスポンスの例

{
  "access_token": "eyJhbGciOiJIUzI1NiJ9.eyJpZCI6ImJmZjg4MzU5YTVkNGUyZmQ3ZmYwOTEwOGIxNjg4MDA0In0.BocpI91mpUzWskyjxHp57hnyl8ZcHehGJwmaBsGJEMg",
  "token_type": "bearer",
  "expires_in": 7200,
  "refresh_token": "eyJhbGciOiJIUzI1NiJ9.eyJpZCI6Ijg1NjQ1YjA1NGJiYmZkNjVmMDNkMzliYzM0YzQ4MzZjIn0.4MSMIG46zjB9QCV-qCCglgojM5dL7_E2kcqmiV46YQ4",
  "created_at": 1628711391
}

You can now make requests to the API with the access token. For more info, see Access Bitbucket API with access token below.

認可コード

このフローによって、公開クライアント上でアクセス トークンに対するクライアント認証情報の OAuth 交換を安全に実行できます。

パラメーター

このフローで使用するパラメーターは次のとおりです。

パラメーター説明 必須
redirect_uriリクエストの承認後にユーザーがリダイレクトされる URL。はい
client_idClient ID received from Bitbucket after registering your application.はい
response_type認可コード。はい
scopeユーザー アカウントに対してアプリケーションの権限を定義するスコープ。詳細については「スコープ」をご確認くださいはい
state予測できない値。リクエストとコールバックの間のステータスを維持するために、クライアントによって使用されます。CSRF トークンとしても使用する必要があります。いいえ

はじめる前に

  • Register your application in Bitbucket by creating an incoming link in application links. During registration, you can enable proper scopes to limit the range of resources which the application can access. After creating the link, you should receive the OAuth credentials: Client ID and Client secret - keep them secure. For more info, see Configure an incoming link.

  • オプションの state パラメーターを使用する場合は、フローを開始する前に生成します。

手順

1. 次のクエリ パラメーターによって /oauth/authorize ページにユーザーをリダイレクトすることで、認可コードをリクエストします。

curl https://atlassian.example.com/rest/oauth2/latest/authorize?client_id=CLIENT_ID&redirect_uri=REDIRECT_URI&response_type=code&state=STATE&scope=SCOPE

これは、scope で指定されたスコープでアカウントにアクセスするアプリケーションのリクエストの承認をユーザーに求める同意画面です。ユーザーは、redirect_uri で指定された URL にリダイレクトされます。リダイレクトには、次の例で示すような認可コードが含まれます。

https://atlassian.example.com/plugins/servlet/oauth2/consent?client_id=CLIENT_ID&redirect_uri=REDIRECT_URI&response_type=code&scope=SCOPE&state=STATE

2. 前のリクエストから返された認可コード (response_type) によって、任意の HTTP クライアントで access_token をリクエストできます。次の例では Ruby の rest-client を使用します。

curl -X POST https://atlassian.example.com/rest/oauth2/latest/token?client_id=CLIENT_ID&client_secret=CLIENT_SECRET&code=CODE&grant_type=authorization_code&redirect_uri=REDIRECT_URI

レスポンスの例

{
 "access_token": "eyJhbGciOiJIUzI1NiJ9.eyJpZCI6IjNmMTQ3NTUzYjg3OTQ2Y2FhMWJhYWJkZWQ0MzgwYTM4In0.EDnpBl0hd1BQzIRP--xEvyW1F6gDuiFranQCvi98b2c",
 "token_type": "bearer",
 "expires_in": 7200,
 "refresh_token": "eyJhbGciOiJIUzI1NiJ9.eyJpZCI6ImMwZTMxYmZjYTI2NWI0YTkwMzBiOGM2OTJjNWIyMTYwIn0.grHOsso3B3kaSxNd0QJfj1H3ayjRUuA75SiEt0usmiM",
 "created_at": 1607635748
}

3. 新しい access_token を取得するには、refresh_token パラメーターを使用します。リフレッシュ トークンは、access_token そのものの有効期限が切れた後でも使用できます。このリクエストは次のとおりです。

  • 既存の access_tokenrefresh_token を無効にします。

  • レスポンスで新しいトークンを送信します。

curl -X POST https://atlassian.example.com/rest/oauth2/latest/token?client_id=CLIENT_ID&client_secret=CLIENT_SECRET&refresh_token=REFRESH_TOKEN&grant_type=refresh_token&redirect_uri=REDIRECT_URI

レスポンスの例

{
  "access_token": "eyJhbGciOiJIUzI1NiJ9.eyJpZCI6ImJmZjg4MzU5YTVkNGUyZmQ3ZmYwOTEwOGIxNjg4MDA0In0.BocpI91mpUzWskyjxHp57hnyl8ZcHehGJwmaBsGJEMg",
  "token_type": "bearer",
  "expires_in": 7200,
  "refresh_token": "eyJhbGciOiJIUzI1NiJ9.eyJpZCI6Ijg1NjQ1YjA1NGJiYmZkNjVmMDNkMzliYzM0YzQ4MzZjIn0.4MSMIG46zjB9QCV-qCCglgojM5dL7_E2kcqmiV46YQ4",
  "created_at": 1628711391
}

You can now make requests to the API with the access token returned. For more info, see Access Bitbucket API with access token below.

Access Bitbucket API with access token

アクセス トークンによって、ユーザーに代わって API にリクエストできます。認証ヘッダーにトークンを次のように入れられます。

curl --header "Authorization: Bearer OAUTH2-TOKEN" "https://atlassian.example.com/rest/api/latest/projects/PROJECT_KEY/repos"

スコープ

The scope parameter is required in both flows. It allows you to specify the permission scopes your application can request from the authorizing user. Note that regardless of which scopes you choose, the actual permissions will always be capped at what the user can actually do.

Here you can find the scope keys you can use in your requests, as values of the scope parameter:

スコープ キー説明
No scope / PUBLIC_REPOS

View public projects and repositories

View projects and repositories that are publicly accessible, including pulling code and cloning repositories.

ACCOUNT_WRITE

Update user account

Update the user account settings.

REPO_READ

View projects and repositories

View projects and repositories the user account can view, including pulling code, cloning, and forking repositories. Create and comment on pull requests.

REPO_WRITE

Update projects and repositories

Update projects and repositories the user account can change, including pushing code and merging pull requests.

REPO_ADMIN

Administer repositories

Perform administrative functions on repositories and pull requests the user account can change, including deleting pull requests and updating repository settings and permissions.

PROJECT_ADMIN

プロジェクトの管理

Perform administrative functions on projects, repositories, and pull requests the user account can change, including creating new repositories and updating project settings and permissions.

ADMIN_WRITE

Administer Bitbucket

Perform most administrative functions on the entire Bitbucket instance, excluding functions such as backups, imports, and infrastructure settings which are limited to system administrators.

SYSTEM_ADMIN

Administer Bitbucket system

Perform all administrative functions on the entire Bitbucket instance, including functions such as backups, imports, and infrastructure settings.

最終更新日 2024 年 9 月 24 日

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

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