Contents
Jira Cloud と Server/Data Center の認証方式の概要
Jira の利用形態が クラウド と Server/Data Center で分かれると、推奨される認証手段も大きく異なります。
本セクションではそれぞれの環境で現在サポートされている認証方式を整理し、運用コストやセキュリティ面での違いを把握できるようにします。
- Jira Cloud では API トークンと OAuth 2.0 が唯一公式にサポートされ、Basic 認証は過去の互換性維持目的でのみ利用可能です。
- Server/Data Center は従来通り Basic 認証や LDAP / SAML といった社内認証基盤と併用できますが、トークン管理機能は限定的です。
Cloud が提供する公式認証方式
| 方法 | 取得手段 | 主な利用シーン |
|---|---|---|
| API トークン | Atlassian アカウントの Security ページで作成 | CI/CD、スクリプト実行、サードパーティ連携 |
| OAuth 2.0（認可コードフロー） | 開発者コンソールにアプリ登録 → 認可エンドポイントへリダイレクト | ユーザー操作が必要な Web アプリやプラグイン |
| OAuth 2.0（クライアント資格情報フロー） | クライアント ID/シークレットでトークン取得 | バックエンドバッチ、サービス間連携 |
公式ドキュメント: https://developer.atlassian.com/cloud/jira/platform/authentication/
Server/Data Center が利用できる認証方式
| 方法 | 主な特徴 | 注意点 |
|---|---|---|
| Basic 認証（ユーザー名＋パスワード） | 既存システムとの互換性が高い | パスワードの平文送信リスク、定期的なローテーションが必須 |
| LDAP / SAML 連携 | 社内ディレクトリと統合可能 | 設定・保守コストが発生 |
| 限定的 API トークン（プラグインやアドオン向け） | 権限を絞って利用できる | Cloud と比べて機能が制限的 |
詳細は Atlassian の Server/Data Center 認証ガイドをご参照ください: https://confluence.atlassian.com/adminjiraserver/authentication-938847032.html
Basic 認証の廃止スケジュールと現在サポートされている手段
Atlassian は 2022 年 5 月 に Cloud REST API の Basic 認証を 非推奨 とし、同年末に実際の利用がブロックされました（※完全廃止は 2023 年 12 月）。したがって「2024 年に廃止された」という表記は誤りです。現在 Cloud 環境で使用できる認証手段は API トークン と OAuth 2.0 のみです。
- 非推奨期間（2022‑2023）：Basic 認証は利用可能だったが、警告ヘッダーが付与されました。
- 完全ブロック（2023‑12 以降）：認証エラー (401) が返り、リクエストは失敗します。
公式アナウンス: https://developer.atlassian.com/cloud/jira/platform/basic-auth-for-rest-apis/#deprecation
API トークンの取得・管理と有効期限
取得手順（概要）
- Atlassian アカウントにサインインし、
https://id.atlassian.com/manage-profile/securityにアクセス。 - Create API token をクリックし、トークン名と 必要最小限のスコープ を選択して作成。
- 表示された文字列を直ちにコピーし、環境変数やシークレット管理ツールに保存。
スコープ例（公式ドキュメント参照）
| スコープ | 説明 |
|---|---|
read:jira-work |
課題の閲覧・検索 |
write:jira-work |
課題の作成・更新 |
manage:jira-configuration |
プロジェクトやワークフロー設定へのアクセス |
スコープ一覧: https://developer.atlassian.com/cloud/jira/platform/scopes/
有効期限とリスク
- API トークン自体は無期限（手動で Revoke するまで有効）。
- ただし、トークンが漏洩した場合の影響を最小化するために 定期的なローテーション と 最小権限付与 を推奨します。
- 組織レベルで IP 制限や MFA が有効になっている場合、トークン使用時にもそれらのポリシーが適用されます。
OAuth 2.0 のフローとアクセストークンの有効期限
認可コードフロー（3‑legged）
- アプリはユーザーを Atlassian の同意画面へリダイレクト。
- ユーザーが許可すると 認可コード が返される。
-
認可コードとクライアントシークレットで アクセストークン と リフレッシュトークン を取得。
-
アクセストークンの有効期限は通常 1 時間（環境により 30 分〜2 時間）。
- リフレッシュトークンを使用すれば、バックグラウンドで自動的に新しいアクセストークンを取得できます。
詳細: https://developer.atlassian.com/cloud/jira/platform/oauth-2-authorization-code-grants/
クライアント資格情報フロー（Client Credentials）
- アプリはクライアント ID とシークレットだけでトークンエンドポイントにリクエスト。
-
アクセストークンが返却され、即座に API 呼び出しに使用できる。
-
このフローでは リフレッシュトークン は発行されません。したがって有効期限（デフォルト 1 時間）ごとに新しいトークンを取得するロジックが必要です。
- スコープは アプリ作成時に設定でき、最小権限での利用が推奨されます。
詳細: https://developer.atlassian.com/cloud/jira/platform/oauth-2-client-credentials-grants/
認証方式選択ガイドライン
判断基準表
| 条件 | 推奨認証方式 | 理由 |
|---|---|---|
| ユーザーコンテキストが必要（課題作成・コメント投稿） | OAuth 2.0 認可コードフロー | 個別ユーザー権限をそのまま反映でき、最小権限の原則に適合 |
| バックエンドバッチや CI/CD パイプライン | API トークン または OAuth 2.0 クライアント資格情報フロー | シンプルなヘッダー送信で済む。トークン自動更新が必要ならクレデンシャルフロー |
| 既存のオンプレ認証基盤（LDAP/SAML）を流用したい | Server/Data Center の Basic 認証 + LDAP/SAML | クラウド移行前段階でのレガシーサポート |
| トークンの有効期限管理が必須 | OAuth 2.0（リフレッシュトークン利用） | 有効期限切れによる障害を防げ、定期的なローテーションが自動化しやすい |
セキュアなトークン活用と実装例
共通のベストプラクティス（箇条書き）
- 環境変数またはシークレット管理ツール に保存し、コードにハードコーディングしない。
- 最小権限（Least Privilege） のスコープだけを付与する。例:
read:jira-workだけで課題検索が可能。 - アクセストークンは定期的に更新（OAuth はリフレッシュトークン、API トークンは手動ローテーション）。
- ログ出力時にトークン文字列を除外し、認証エラーだけを記録する。
curl での呼び出し例
|
1 2 3 4 5 6 7 8 9 10 11 |
# API トークンの場合（Bearer 方式） curl -s \ -H "Authorization: Bearer $JIRA_API_TOKEN" \ -H "Accept: application/json" \ https://your-domain.atlassian.net/rest/api/3/project # OAuth アクセストークン（有効期限がある）場合 curl -s \ -H "Authorization: Bearer $JIRA_OAUTH_ACCESS_TOKEN" \ https://your-domain.atlassian.net/rest/api/3/search?jql=project=TEST |
ポイント：
$JIRA_API_TOKEN/$JIRA_OAUTH_ACCESS_TOKENは CI のシークレットストアや Vault から注入してください。
Python (requests) での実装例
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 |
import os, requests # 環境変数から取得（API トークンまたは OAuth アクセストークン） token = os.getenv("JIRA_API_TOKEN") # API トークンの場合 # token = os.getenv("JIRA_OAUTH_ACCESS_TOKEN") # OAuth の場合 headers = { "Authorization": f"Bearer {token}", "Accept": "application/json" } url = "https://your-domain.atlassian.net/rest/api/3/project" resp = requests.get(url, headers=headers) if resp.ok: print("取得したプロジェクト:", resp.json()) else: # 401 → トークン無効、403 → 権限不足 print(f"エラー {resp.status_code}: {resp.text}") |
- セッション再利用：
session = requests.Session()を作成しsession.headers.update(headers)とすれば接続がプールされ、パフォーマンス向上。 - リフレッシュトークンの自動取得（OAuth）:
requests_oauthlib.OAuth2Sessionでauto_refresh_urlとauto_refresh_kwargsを設定すると、期限切れ時に自動的に新しいアクセストークンを取得できます。
トラブルシューティングチェックリスト
| 症状 | 確認項目 |
|---|---|
| 401 Unauthorized | - トークンが正しく環境変数に設定されているか - OAuth の場合、アクセストークンの有効期限切れでないか（リフレッシュトークン使用） |
| 403 Forbidden | - スコープが対象 API に必要な権限を含んでいるか - Jira プロジェクトや課題タイプへのユーザーアクセス権が付与されているか |
| 429 Too Many Requests / 403 IP 制限 | - 組織の IP ホワイトリスト設定を確認し、実行サーバーの IP が許可済みか |
| SSL/TLS エラー | - 社内プロキシ経由の場合は --cacert（curl）や verify=（requests）で社内 CA を指定 |
まとめ ― 主要ポイントだけを押さえる
- Basic 認証は 2022 年に非推奨化、2023 年末に完全ブロック。現在 Cloud では API トークンまたは OAuth 2.0 のみが利用可能です。
- API トークンは無期限だが最小権限で作成し、定期的にローテーションすることがベストプラクティス。
- OAuth 2.0 アクセストークンは通常 1 時間の有効期限を持ち、リフレッシュトークンで自動更新できます。フロー選択は「ユーザーコンテキストが必要か」か「バックエンド処理だけか」で決めます。
- Server/Data Center は引き続き Basic 認証や LDAP/SAML が利用可能ですが、クラウド移行時はトークンベース認証への置換を計画してください。
- セキュリティ対策としては環境変数・Vault での安全な保管、最小スコープ付与、ログにトークンを書き出さないことが重要です。
これらの指針に従って認証方式を設計すれば、Jira の API 利用時に発生しやすい権限・有効期限問題を未然に防ぎ、安定した自動化パイプラインを構築できます。