サービス アカウントの API トークンを管理する
API トークンを使用して、Atlassian Cloud アプリでスクリプトを認証できます。サービス アカウントのトークンを生成し、スクリプトにコピー アンド ペーストします。各組織につき、最大 5 つのサービス アカウントを無料で作成できます。5 つを超えるサービス アカウントが必要な場合は、Atlassian Guard のサブスクリプションを検討してください。
認証に 2 段階認証を使用する場合、スクリプトでは REST API トークンによって認証する必要があります。
サービス アカウントには、ユーザー アカウントと同じ権限とスコープの要件が適用されます。API トークンを設定する前に、サービス アカウントに管理者やサービス デスク チームなどの適切なプロジェクト ロールが割り当てられていることを確認してください。これにより、アカウントがフォームの送信や自動化タスクの実行などのアクションを実行できるようになります。
API トークンとは
API トークンを使用すると、HTTP 基本認証によってスクリプトから Atlassian Cloud アプリの REST API にアクセスできるようになります。
固定長ではなく可変長の API トークンを使用することで、トークンの安全性と信頼性を向上させます。該当するスクリプトに固定長の API トークンが使用されている場合は、可変長を処理できることを確認してください。
API トークンのスコープとは
サービス アカウントの API トークンではスコープが使用されます。スコープは、Atlassian アプリ データに対してトークンによって許可されるアクセス レベルを定義するものです。
API トークンを作成する際には、スコープをどのようにするかを選択します。スコープを選択することで、トークンに特定のアクションの実行権限を付与します。
サービス アカウントでは、API に対して Jira と Confluence のコンテンツの読み取り、書き込み、削除を許可するスコープを選択できます。一般的なスコープには read:jira-work と write:jira-work があります。これらのスコープは、フォーム フィールドの取得と更新、レスポンスの送信、作業項目の作成などのタスクに使用します。
セキュリティのベスト プラクティスとして、スクリプトに必要なスコープのみを選択してください。不明な場合は、スコープのドキュメントを確認してください。
サービス アカウントに必要な権限やスコープがない場合、次のようなエラーが発生する可能性があります。
401 Unauthorized404 Not Found"Issue does not exist or you do not have permission to see it."
一度作成した API トークンのスコープは変更できません。異なるスコープを適用する場合は、新しいトークンを作成する必要があります。
スコープ付き API トークンを作成する
有効期限が無期限の API トークンは、データに関するセキュリティ上のリスクをもたらします。データ セキュリティを強化するため、既定では、API トークンが 1 年で失効するように設定されます。API トークンの作成時に、そのトークンに名前を付けて、有効期限を設定できます。
You must create a service account before you can create a token for the service account.
サービス アカウントの API トークンを作成するには、次の手順に従います。
移動 アトラシアンの管理。組織が複数ある場合は、対象の組織を選択します。
[ディレクトリ] > [サービス アカウント] の順に選択します。
認証情報を作成するサービス アカウントを選択します。
[認証情報の作成] を選択します。
[API トークン] を選択し、[次へ] を選択します。
API トークンにその機能を説明する名前を付けます。API トークンの有効期限を選択します。トークンの有効期限は 1 日から 365 日の間で設定できます。[次へ] を選択します。
スコープを選択して、API トークンによって Jira または Confluence で実行できることを決定します。[次へ] を選択します。
API トークンを確認してから、[作成] を選択します。
[クリップボードにコピー] を選択してから、スクリプトにトークンを貼り付けるか、安全な場所に保存します。
この手順が完了すると、API トークンを復元できなくなります。API トークンを安全に保つためのベスト プラクティスとして、パスワード マネージャーに API トークンを保存することをお勧めします。
API トークンを検証する
API トークンを作成したら、スクリプトに必要なアクセス権限が付与されていることを確認することが重要です。テスト API 呼び出しを行って、トークンに適切なスコープと権限が割り当てられていることを確認します。
リクエストでトークンをテストする
トークンを使用して API リクエストを行う際には、必ず api.atlassian.com で始まるプラットフォーム API ゲートウェイ URL を使用する必要があります。アクセス対象のアプリの API を呼び出すためのリクエストを構築できます。
次の例は、Jira アプリに対するリクエストに使用できる適切な形式の URL です。https://api.atlassian.com/ex/jira/{cloudId}/rest/api/3/project/{project_key}
リクエストを認証する
api.atlassian.com ゲートウェイを必要とする API では、HTTP ヘッダーでベアラー トークン認証または基本認証を使用できます。
使用する HTTP ライブラリの詳細によっては、パスワードをトークンで置き換えることができます。サービス アカウントに対応するメール アドレスであることを確認し、パスワードの代わりに API トークンを使用してください。
たとえば、curl を使用している場合、以下のようにします。
## URLs for API tokens with scopes for Jira
curl -v \
https://api.atlassian.com/ex/jira/{cloudId}/rest/api/3/project \
-H "Authorization: Bearer my-api-token" \
-H "Accept: application/json"
## URLs for API tokens with scopes for Confluence
curl -v \
https://api.atlassian.com/ex/confluence/{cloudId}/wiki/rest/api/space \
-H "Authorization: Bearer my-api-token" \
-H "Accept: application/json"
必要な情報を見つける
上の例では、bot@serviceaccount.atlassian.com はトークンの作成に使用した Atlassian アカウントのメール アドレスです。
Cloud ID は、各 Atlassian Cloud サイト (インスタンス) に割り当てられる一意の識別子です。アプリ開発、管理、特定の管理タスクに使用され、api.atlassian.com を使用して API リクエストを構築するために必要です。Cloud ID は組織 ID とは異なります。組織 ID は、複数の Cloud サイトまたは製品のグループを指します。
Cloud ID を確認するには、次の手順に従います。
admin.atlassian.comに移動します。管理 URL またはレスポンスで
/s/の後にある文字列 (1a11d016-8984-4c3e-b9ab-142dd06acb1bなど) を見つけます。
組織 ID の使用は避けてください。使用すると、404 Not Found などのエラーや API リクエストの失敗につながります。
失敗したリクエストをトラブルシューティングする
次のチェックリストを使用して API トークンを検証し、問題を解決してください。
エンドポイントの形式を確認する
API エンドポイントでクラウド ID を使用していること (組織 ID ではない) を確認してください。
文字列にタイポやスペースが含まれていないことを確認してください。
トークンとアカウントのステータスを確認する
API トークンがアクティブであり、取り消されていないことを確認してください。
サービス アカウントが無効化または停止されていないことを確認してください。
API トークンのスコープを検証する
トークンの有効性、有効期限、適切なエンコーディング (email:token 形式を使用している場合は Base64) を確認してください。
ユース ケースの作成時に適切なスコープ (read、write、admin) が選択されていることを確認してください。どのスコープが必要かわからない場合は、次のページを参照してください。
サービス アカウントのアプリ アクセスを確認する
サービス アカウントがアプリ アクセスを許可する関連グループに含まれていることを確認してください。
通常のユーザー アカウントは機能するがサービス アカウントが機能しない場合は、グループ メンバーシップと権限を比較して相違点を特定できます。
アトラシアンの権限ヘルパーを使用して、サービス アカウントに必要なプロジェクト権限があることを確認してください。
Jira スペースおよび作業項目の権限を確認する
サービス アカウントが正しいスペース ロールに追加されていることを確認してください。
サービス アカウントに対象のアクションの実行に必要な権限が割り当てられていることを確認してください。
Jira の権限ヘルパーを使用して、サービス アカウントが特定の作業項目またはスペースにアクセスできるかどうかを確認します。[スペース設定] > [権限] > [権限ヘルパー] に移動し、サービス アカウントのメールと課題キーを入力します。
API トークンを取り消す
トークンを取り消すと、そのトークンは機能しなくなり、アカウントから完全に削除されます。既存の API トークンを取り消す場合は、新しいトークンに置き換えることができます。トークン取り消しの所要時間は最大 10 分です。
API トークンを取り消すには、次の手順に従います。
移動 アトラシアンの管理。組織が複数ある場合は、対象の組織を選択します。
[ディレクトリ] > [サービス アカウント] の順に選択します。
トークンを取り消すサービス アカウントを選択します。
[認証情報] で、該当するトークンに対して [取り消し] を選択します。
サービス アカウントに関する注意事項
サービス アカウントは、Atlassian Cloud UI へのインタラクティブ ログインには使用できません。
一部の機能 (ID プロバイダー (OKTA など) からのグループ同期など) は、サービス アカウントでは利用できない場合があります。
サービス アカウントには、通常のユーザーと同じ権限とスコープの要件が適用されます。
各組織につき、最大 5 つのサービス アカウントを無料で作成できます。さらに必要な場合は、Atlassian Guard のサブスクリプションを検討してください。
この内容はお役に立ちましたか?