APIスコープ用のツールを更新する

PagerDuty REST APIは、ユーザーが PagerDutyプラットフォームのオブジェクトやワークフローにプログラムでアクセスするための 200 以上のエンドポイントを提供します。チームはこれらの APIを活用して、環境のユーザー、チーム、サービス、その他のコンポーネントの作成と管理を合理化します。

これまで、REST APIへのアクセスはAPIキーを介して認可および認証されてきました。これらのキーは Web UIで管理され、アカウント内のオブジェクトへのオール・オア・ナッシングのアクセスを提供するため、多くのチームにとってはAPI範囲が広すぎるため、PagerDuty Engineeringは、OAuth2.0 トークン。

PagerDuty REST APIの各オブジェクトには少なくとも 1 つのスコープreadがあり、多くのオブジェクトにはwriteもあります。アカウント内の他のすべての機能にもアクセスできることを心配することなく、アプリが正しく動作するために必要なアクセス権のみを持つようにアプリを調整できます。

現在APIキーを使用しているユーザーは、当面は引き続き機能します (将来の EOLに注目してください) が、Scoped OAuthに移行すると、チームがアクセスを管理し、最小特権の原則を遵守するのに役立ちます。

APIスコープの紹介ビデオについては、YouTubeチャンネルのこのビデオをご覧ください。

アプリをセットアップする

スコープを使用してAPIアクセスを設定するときに最初に気づく変更は、アクセスがアプリ経由で管理されることです。これらは、「統合」メニューの「APIアクセスキー」セクションでは管理されません。代わりに「アプリの登録」（以前は「開発者モード」と呼ばれていました）に進み、アプリの構成プロセスを続行することをお勧めします。これらの設定は、アカウントの管理者と所有者に限定されています。

アプリが作成されると、スコープ指定された OAuthを追加するオプションが表示されます。

スコープ付き OAuthをサポートするアプリの場合、次のダイアログでは、このアプリのアクセスから派生したトークンで使用できるオブジェクトを選択できます。ユースケースに応じて、必要なだけ選択できます。

[保存] をクリックすると、このアプリアクセス用のトークンをプロビジョニングするために使用されるクライアント IDとクライアントシークレットという 2 つの重要な情報を含むポップオーバーウィンドウが表示されます。

これらはトークンをプロビジョニングするために必要となるため、証明書、パスワード、またはシークレットに使用するボールトまたは他の場所またはアプリに保存します。

スコープの検索

上記のスクリーンキャプチャからわかるように、APIを介してアクセスされるオブジェクトに応じて、トークンに必要となる可能性のあるスコープが多数あります。

幸いなことに、APIドキュメントが更新され、すべてのオブジェクトエンドポイントに必要なスコープが含まれています。各タイプのリクエストには、スコープと、リクエストに読み取りアクセスと書き込みアクセスが必要かどうかを含むメモが付いています。ただし、大まかに言うと、情報のリストや取得に使用される GETメソッドを使用するリクエストには読み取りアクセスのみが必要ですが、PUT、POST、および DELETEリクエストには書き込みアクセスが必要です。

トークンのリクエスト

アプリの作成時に受け取った資格情報を使用してhttps://identity.pagerduty.com/oauth/tokenから要求されます。リクエストの形式は、ここのAPIドキュメントにあります。その他の必須データは、地域 (米国または EU) とサブドメイン (youraccount.pagerduty.com) です。リクエストする各トークンは、有効なスコープを指定する必要があります。

curl -i --request POST \

  https://identity.pagerduty.com/oauth/token \

  --header "Content-Type: application/x-www-form-urlencoded" \

  --data-urlencode "grant_type=client_credentials" \

  --data-urlencode "client_id={CLIENT_ID}" \

  --data-urlencode "client_secret={CLIENT_SECRET}" \

  --data-urlencode "scope=as_account-us.companysubdomain incidents.read services.read"

トークンに含まれるスコープは、組織が希望するトークンの管理方法に応じて、アプリに含まれるスコープの完全なセットにすることも、それらのスコープのサブセットにすることもできます。トークンは JSONドキュメントで返されます。

{

  "access_token": "pdus+xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",

  "scope": "as_account-us.companysubdomain incidents.read services.read",

  "token_type": "bearer",

  "expires_in": 2592000

}

これらのトークンには有効期限があります。これは、無期限のAPIキーからの大きな変更です。トークンは 30 日ごとにローテーションする必要があります。

さらに、リポジトリスキャナを使用する人々がトークンがチェックインされていないことを確認できるように、各 PagerDutyトークンは「pd+」で始まり、トークンが簡単に識別できるようにpdus+またはpdeu+のいずれかになります。

トークンが作成されたら、それをどのように配布および管理するかはユーザー次第です。トークンは Web UIにはリストされず、プラットフォーム上でも入手できません。アプリページ内から、アプリに関連付けられたすべてのトークンを取り消すことができますが、個々のトークンを取り消すことはできません。

トークンの使用

カスタムスクリプト経由でAPIにアクセスしている場合は、新しいトークンを使用するためにいくつかの更新を行う必要があります。

httpsリクエストを行うためにcurlや wgetなどのコマンドラインツールを使用するシェルスクリプトの場合は、Authorizationヘッダーを更新する必要があります。

--header "Authorization: Bearer $TOKEN"

同様に、Postman などのツールでは、Authorizationを Bearerトークンに設定する必要があります。Postmanでこれを行う方法の詳細については、Postmanのドキュメントを参照してください。

PagerDutyのAPIのさまざまなクライアントライブラリのいずれかを使用している場合は、それらのプロジェクトのドキュメントを確認して、コードの変更が必要かどうかを判断してください。たとえば、pdpyrasでは、OAuth2.0トークン専用のセッションコンストラクターが使用できます。

# REST API v2 with an OAuth2 access token:

session_oauth = pdpyras.APISession(OAUTH_TOKEN, auth_type='oauth2')

使用しているプログラミング言語によっては、より高度なソリューションや OAuth2.0トークンのサポートが利用できる場合があります。開発者サイトのドキュメントには、いくつかの言語のサンプルコードも含まれています。

トークンとアプリの管理

アプリとトークンの粒度をどのように設計するかは、あなたと組織のセキュリティ要件次第です。始めるのに役立ついくつかの推奨方法があります。

トークンのプロビジョニング者

スコープ付き OAuthトークンには 30 日間の有効期限があるため、PagerDuty APIにプログラムでアクセスするチームが多数ある組織では、クライアント IDとクライアントシークレットを個々のチームと共有し、独自のトークンをプロビジョニングできるようにすることが容易になる可能性があります。管理者は、チームまたはアプリケーションの種類ごとにアプリを作成して、APIにアクセスできるユーザーとオブジェクトを制御することを選択できます。

小規模なチーム、またはリソースへのアクセスをより詳細に制御する必要があるチームは、クライアント IDとクライアントシークレットをアカウント管理者に保持し、アカウント管理者がトークンを作成し、安全なストレージ経由でチームに共有することをお勧めします。

完全なスコープのアプリ、限定されたスコープのトークン

さまざまなオブジェクトへのアクセスが必要なユースケースでは、すべてのスコープを含めるようにアプリをプロビジョニングできます。トークンはすべての許可されたスコープのサブセットでリクエストできるため、個々のトークンはクライアントアプリケーションがAPIで使用するものだけに制限できます。

この方法により、PagerDutyアカウントで管理する必要があるアプリの数を減らすことができます。管理者は、チームまたは部門にアプリをプロビジョニングし、より限定された範囲のトークンを提供できます。

試してみてお知らせください

スコープ付き OAuthは現在早期アクセス機能として利用可能であり、2023 年 5 月末にすべてのアカウントで一般利用可能になる予定です。試してみて、ご意見をお聞かせください。https://www.pagerduty.com/early-access/で早期アクセスにサインアップするか、詳細についてはアカウントチームにお問い合わせください。質問がある場合は、コミュニティフォーラムに参加することもできます。

カテゴリー：ベストプラクティス

タグ：

新着情報

カテゴリ

タグ

BLOGAPIスコープ用のツールを更新する