EAP documentation: Jira OAuth 2.0 provider API

Jira (Data Center と Server) は、OAuth 2.0 プロトコルによってユーザーの代わりに外部サービスがリソースにアクセスできるようにする API を提供します。

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

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

• Authorization code with Proof Key for Code Exchange (PKCE)

• 認可コード

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

For more information on how these flows work, see OAuth RFC. This should help you understand the flows and choose the right one for you.

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

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

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. 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.

For the same reason, we also enforce HTTPS for the base URL of production environments. 

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

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

パラメーター

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

はじめる前に

• Register your application in Jira 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. 

• Before starting the flow, generate the state (optional), code_verifier, code_challenge, and code_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

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&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

レスポンスの例

{
 "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_token と refresh_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 Jira API with access token below.

認可コード

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

パラメーター

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

はじめる前に

• Register your application in Jira 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. 

• オプションの 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

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

レスポンスの例

{
 "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. This request:

• 既存の access_token と refresh_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 Jira API with access token below.

アクセス トークンで Jira API にアクセスする

The access token allows you to make requests to the API on behalf of a user. You can put the token in the Authorization header:

curl --header "Authorization: Bearer OAUTH2-TOKEN" "https://atlassian.example.com/rest/api/latest/issue/JRA-9"

スコープ

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: