Bamboo OAuth 2.0 provider API

このページの内容

お困りですか?

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

コミュニティに質問

Bamboo Data Center and Server 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 Bamboo, see Configuring 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.

On this page:

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

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

We don’t support Implicit Grant and Resource Owner Password Credentials flows, as they will be deprecated in the next version of the OAuth specification.

これらのフローの仕組みに関する詳細は、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 を使用する

For production environments, use HTTPS for the redirect_uri parameter. This is important as OAuth 2.0 bases its security on the transport layer. For more info, see the OAuth 2.0 RFC and the OAuth 2.0 Threat Model RFC.

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

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

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

パラメーター

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

パラメーター説明 必須
redirect_uriURL that the user will be redirected to after authorizing the request.はい
client_idClient ID received from Bamboo after registering your application.はい
response_time認可コード。はい
scopeScopes that define application’s permissions to the user account. For more info, see Scopes.はい
code_challengesha256 の場合は、擬似コード BASE64URL-ENCODE(SHA256(ASCII(code_verifier))) によってこれを生成します。

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

はい
code_challenge_methodCan be plain or sha256 depending on how the code_challenge was generated.はい
code_verifierHigh-entropy cryptographic random string using the unreserved characters: [A-Z] / [a-z] / [0-9] / "-" / "." / "_" / "~".  Must be between 43-127 characters. For more info, see section 4.1 of RFC7636.はい
stateAn optional parameter, which value can't be predicted. It'll be used by the client to maintain state between the request and callback. It should also be used as a CSRF token. It can be generated in a similar manner to code_verifier.いいえ

はじめる前に

  • Register your application in Bamboo by creating an incoming. During registration, you can enable proper scopes to limit the range of resources that the application can access. After creating the link, you should receive the OAuth Client ID and Client secret — make sure to keep these secure. For more info, see Configuring an incoming link.
  • Before starting the flow, generate state (optional), code_verifier, code_challenge, and code_challenge_method.

手順

  1. Request authorization code by redirecting the user to the /rest/oauth2/latest/authorize page with the following query parameters:

    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

    This is the consent screen that asks the user to approve the application’s request to access their account with the scopes specified in scope. The user is then redirected to the URL specified in redirect_uri. The redirect includes the authorization code. For example:

    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. With the authorization code returned from the previous request, you can request an access_token, with any HTTP client. The following example uses 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

    Example response:

    {
     "access_token": "eyJhbGciOiJIUzI1NiJ9.eyJpZCI6IjNmMTQ3NTUzYjg3OTQ2Y2FhMWJhYWJkZWQ0MzgwYTM4In0.EDnpBl0hd1BQzIRP--xEvyW1F6gDuiFranQCvi98b2c",
     "token_type": "bearer",
     "expires_in": 7200,
     "refresh_token": "eyJhbGciOiJIUzI1NiJ9.eyJpZCI6ImMwZTMxYmZjYTI2NWI0YTkwMzBiOGM2OTJjNWIyMTYwIn0.grHOsso3B3kaSxNd0QJfj1H3ayjRUuA75SiEt0usmiM",
     "created_at": 1607635748
    }
  3. To retrieve a new access_token, use the refresh_token parameter.

    Refresh tokens may be used even after the access_token itself expires.

    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

    This request:

    • invalidates the existing access_token and refresh_token

    • sends new tokens in the response

    Example response:

    {
      "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 returned access token. For more info, see Accessing the Bamboo API with the access token.

認可コード

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

パラメーター

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

パラメーター説明 必須
redirect_uriURL that the user will be redirected to after authorizing the request.はい
client_idClient ID received from Bamboo after registering your application.はい
response_type認可コード。はい
scopeScopes that define application’s permissions to the user account. For more info, see Scopes.はい
stateAn optional parameter, which value can't be predicted. It'll be used by the client to maintain state between the request and callback. It should also be used as a CSRF token.いいえ

はじめる前に

  • Register your application in Bamboo by creating an incoming. During registration, you can enable proper scopes to limit the range of resources that the application can access. After creating the link, you should receive the OAuth Client ID and Client secret — make sure to keep these secure. For more info, see Configuring an incoming link.

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

手順

  1. Request the authorization code by redirecting the user to the /oauth/authorize page with the following query parameters:

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

    This is the consent screen that asks the user to approve the application’s request to access their account with the scopes specified in scope. The user is then redirected to the URL specified in redirect_uri. The redirect includes the authorization code, like in the following example:

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

  2. With the authorization code (response_type) returned from the previous request, you can request an access_token, with any HTTP client. The following example uses Ruby’s 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

    Example response:

    {
     "access_token": "eyJhbGciOiJIUzI1NiJ9.eyJpZCI6IjNmMTQ3NTUzYjg3OTQ2Y2FhMWJhYWJkZWQ0MzgwYTM4In0.EDnpBl0hd1BQzIRP--xEvyW1F6gDuiFranQCvi98b2c",
     "token_type": "bearer",
     "expires_in": 7200,
     "refresh_token": "eyJhbGciOiJIUzI1NiJ9.eyJpZCI6ImMwZTMxYmZjYTI2NWI0YTkwMzBiOGM2OTJjNWIyMTYwIn0.grHOsso3B3kaSxNd0QJfj1H3ayjRUuA75SiEt0usmiM",
     "created_at": 1607635748
    }
  3. To retrieve a new access_token, use the refresh_token parameter.

    Refresh tokens may be used even after the access_token itself expires.

    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

    This request:

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

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

    Example response:

    {
      "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 returned access token. For more info, see Accessing the Bamboo API with the access token.

Accessing the Bamboo API with the access token

To access the Bamboo API with the previously returned access token, put the token in the Authorization header. For example:

curl --header "Authorization: Bearer OAUTH2-TOKEN" "https://atlassian.example.com:8085/bamboo/rest/api/latest/plan/{projectKey}-{buildKey}"

スコープ

scope パラメーターは両方のフローで必須です。これによって、アプリケーションが承認ユーザーからリクエストできる権限スコープを指定できます。どのスコープを選択しても、実際の権限は常にそのユーザーが実際に実行できる操作に制限されます。

ここでは、scope パラメーターの値として、リクエストで使用できるスコープ キーを説明します。

範囲説明
READThe access token will only have permissions to read the same data that the associated user normally has access to in Bamboo.
TRIGGERThe access token will have permissions to start the same builds and deploy the same environments that the associated user normally can.
USERThe access token will have the same set permissions as the associated users (including Administrator permissions, if the associated user has them).


最終更新日 2022 年 11 月 30 日

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

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