Jira OAuth 2.0 プロバイダー API
Jira (Data Center と Server) は、OAuth 2.0 プロトコルによってユーザーの代わりに外部サービスがリソースにアクセスできるようにする API を提供します。
Jira に追加する統合が既にある場合は「受信リンクを設定する」で詳しいステップをご確認ください。ない場合は、このページを参照してアトラシアンの OAuth 2.0 実装の詳細を理解すれば、そのような統合を作成できるようになります。
サポート対象の OAuth 2.0 フロー
次の OAuth 2.0 フローがサポート対象です。
Proof Key for Code Exchange (PKCE) を含む認可コード
認可コード
Implicit Grant と Resource Owner Password Credentials のフローは、次の OAuth 仕様バージョンで非推奨になるためサポート対象外です。
これらのフローの仕組みに関する詳細は、OAuth RFC をご確認ください。フローを理解して、自分に適したフローを選択するのに役立ちます。
セキュリティに関する推奨事項
ここでは、セキュリティ向上の方法に関する推奨事項をいくつか説明します。
CSRF 攻撃を防止する
リダイレクト ベースのフローを保護するために、OAuth の仕様では、/rest/oauth2/latest/authorize エンドポイントへの各リクエストとともに、state クエリ パラメーターによる「state パラメーターで伝送されてユーザー エージェントに安全にバインドされる単回使用 CSRF トークン」の使用を推奨しています。これによって、CSRF 攻撃を防げます。
本番環境で 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_id | アプリケーションの登録後に Jira から受け取ったクライアント ID。 | はい |
response_type | 認可コード。 | はい |
scope | ユーザー アカウントに対してアプリケーションの権限を定義するスコープ。詳細については「スコープ」をご確認ください。 | はい |
code_challenge |
| はい |
code_challenge_method | code_challenge が生成された方法に応じて、plain または sha256 になります。 | はい |
code_verifier | 予約されていない文字を用いるハイエントロピー暗号ランダム文字列: [A-Z] / [a-z] / [0-9] / "-" / "." / "_" / "~"。43 ～ 127 文字にする必要があります。詳細については RFC をご確認ください。 | はい |
state | 予測できない値。リクエストとコールバックの間のステータスを維持するために、クライアントによって使用されます。CSRF トークンとしても使用する必要があります。code_verifier と同様の方法で生成できます。 | いいえ |
はじめる前に
アプリケーション リンクに受信リンクを作成することで、Jira にアプリケーションを登録します。登録時に、適切なスコープを有効にして、アプリケーションがアクセスできるリソースの範囲を制限できます。リンクを作成したら OAuth 認証情報 (クライアント ID とクライアント シークレット) を受信するはずですので、その情報は安全に保管してください。詳細については「受信リンクを設定する」をご確認ください。
- フローを開始する前に、
state(オプション)、code_verifier、code_challenge、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これは、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_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
}アクセス トークンによって API にリクエストできるようになりました。詳細については、以下の「アクセス トークンで Jira API にアクセスする」をご確認ください。
認可コード
このフローによって、公開クライアント上でアクセス トークンに対するクライアント認証情報の OAuth 交換を安全に実行できます。
パラメーター
このフローで使用するパラメーターは次のとおりです。
| パラメーター | 説明 | 必須 |
|---|---|---|
redirect_uri | リクエストの承認後にユーザーがリダイレクトされる URL。 | はい |
client_id | アプリケーションの登録後に Jira から受け取ったクライアント ID。 | はい |
response_type | 認可コード。 | はい |
scope | ユーザー アカウントに対してアプリケーションの権限を定義するスコープ。詳細については「スコープ」をご確認ください。 | はい |
state | 予測できない値。リクエストとコールバックの間のステータスを維持するために、クライアントによって使用されます。CSRF トークンとしても使用する必要があります。 | いいえ |
アクセス トークンで Jira API にアクセスする
アクセス トークンによって、ユーザーに代わって API にリクエストできます。認証ヘッダーにトークンを次のように入れられます。
curl --header "Authorization: Bearer OAUTH2-TOKEN" "https://atlassian.example.com/rest/api/latest/issue/JRA-9"スコープ
scope パラメーターは両方のフローで必須です。これによって、アプリケーションが承認ユーザーからリクエストできる権限スコープを指定できます。どのスコープを選択しても、実際の権限は常にそのユーザーが実際に実行できる操作に制限されます。
ここでは、scope パラメーターの値として、リクエストで使用できるスコープ キーを説明します。
スコープ キー | 説明 | 暗黙的なスコープ |
|---|---|---|
| プロジェクトと課題を表示する ダッシュボード、フィルター、添付ファイル、またはコメントといった関連アイテムなど、ユーザーのアカウントで表示できるプロジェクトと課題を表示します。また、ユーザー プロファイルを表示します。 | READ |
| プロジェクトと課題を作成、更新、削除する ダッシュボード、フィルター、添付ファイル、またはコメントといった関連アイテムなど、ユーザーのアカウントで変更できるプロジェクトと課題を作成、更新、削除します。また、ユーザー プロファイルを変更します。 | 読み取り、書き込み |
| Jira の管理 バックアップ、インポート、インフラストラクチャ設定などの機能を除く、システム管理者のみが実行できるほとんどの管理機能を Jira インスタンス全体で実行します。 | 読み取り、書き込み、管理者 |
SYSTEM_ADMIN | Jira システムを管理する バックアップ、インポート、インフラストラクチャ設定など、すべての管理機能を Jira インスタンス全体で実行します。 | 読み取り、書き込み、管理者、システム管理者 |