PagerDuty REST APIは、ユーザーがPagerDutyプラットフォーム内のオブジェクトやワークフローにプログラムでアクセスするための200以上のエンドポイントをご提供します。チームはこれらのAPIを活用し、ユーザー、チーム、サービス、その他環境のコンポーネントの作成と管理を効率化します。
これまで、REST API へのアクセスはAPIキーを介して認可・認証されてきました。これらのキーはWeb UIで管理され、アカウント内のオブジェクトにオール・オア・ナッシングでアクセスできるため、多くのチームにとっては寛容すぎるものでした。そこでPagerDuty Engineeringは、OAuth2.0 Tokensで使うAPIスコープの総合セットを作ることに取り組んでいます。
PagerDuty REST APIの各オブジェクトには少なくとも１つのスコープであるreadがあり、多くのオブジェクトにはwriteもあります。アプリがアカウントの他の全てにアクセスできるかどうかを心配することなく、正しく動作するために必要なアクセスだけを持つように調整できるようになります。
現在APIキーを使っている人は、当分の間APIキーを使い続けることができます（将来的には廃止される可能性があるのでご注意ください）が、Scoped OAuthに移行することで、チームがアクセスを管理し、最小特権の原則を守ることができます。
API スコープの紹介ビデオについては、YouTubeチャンネルのこのビデオをご覧ください。
アプリをセットアップする
スコープによるAPIアクセスを設定する際に最初に気付くのは、アクセスがアプリで管理されるようになったことでしょう。これらは、「Integrations」メニューの「API Access Keys」セクションで管理することはできません。代わりに「App Registration」（以前は「Developer Mode」として知られていました）にアクセスし、アプリの設定プロセスを進める必要があります。これらの設定は、アカウントの管理者と所有者に限定されています。
アプリを作成する際に、Scoped OAuthを追加するオプションがあります：
Scoped OAuthをサポートするアプリの場合、次のダイアログで、このアプリのアクセスに由来するTokenが使えるようにするオブジェクトを選択できます。ユースケースに応じて、必要なだけ選択できます：
Saveをクリックすると、このアプリアクセス用のトークンをプロビジョニングするために使用されるClient IDとClient Secretという２つの重要な情報を含むポップオーバーウィンドウが表示されます。
トークンのプロビジョニングに必要なので、証明書やパスワード、シークレットに使っている金庫などの場所やアプリに保管しておきましょう。
スコープの検索
上記の画面キャプチャーから分かるように、APIを介してアクセスされるオブジェクトに応じて、トークンが必要とする可能性のあるスコープが多数存在することになります。
幸いなことに、 APIドキュメントが更新され、全てのオブジェクトエンドポイントに必要なスコープが含まれています。各タイプのリクエストには、スコープと、リクエストに読み取りアクセスと書き込みアクセスが必要かどうかを含むメモが付いています。大まかには、情報の一覧表示や取得に使われるGETメソッドによるリクエストは読み取りアクセスのみ、PUT、POST、DELETEリクエストは書き込みアクセスが必要です。
トークンのリクエスト
アプリ内のScoped Clientに関連付けられたトークンは、アプリの作成時に受け取った認証情報を使用して、https://identity.pagerduty.com/oauth/token から要求されます。リクエストの形式は、こちらのAPIドキュメントに記載されています。その他の必要なデータは、地域（USまたは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
トークンが作成されたら、それをどのように配布・管理するかはユーザー次第です。トークンはWeb UIにはリストされず、プラットフォーム上でも入手できません。アプリページ内から、アプリに関連付けられた全てのトークンを取り消すことができますが、個々のトークンを取り消すことはできません。
トークンの使用
カスタムスクリプト経由で API にアクセスしている場合は、新しいトークンを使用するためにいくつかの更新を行う必要があります。
curlやwgeなどのコマンドラインツールを使ってhttpsリクエストを行うシェルスクリプトの場合、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トークンのサポートが利用可能な場合があります。 また、開発者サイトのドキュメントには、複数の言語用のサンプルコードが含まれています。
トークンとアプリの管理
アプリとトークンの粒度をどのように設計するかは、あなたと組織のセキュリティー要件次第です。始めるのに役立ついくつかの推奨方法があります。
トークンのプロビジョニングをするのは？
Scoped OAuthトークンは30日間の有効期限があるため、PagerDuty APIにプログラムでアクセスするチームが多い組織では、Client IDとClient Secret 各チームと共有し、各自でトークンを用意するほうが簡単でしょう。管理者は、チームやアプリケーションの種類ごとにアプリを作成し、誰がAPIにアクセスし、どのオブジェクトにアクセスできるかを制御できます。
小規模なチームや、リソースへのアクセスをより詳細に管理する必要がある場合は、Client IDとClient Secretをアカウント管理者に保持させ、管理者がトークンを作成し、安全なストレージを介してチームに共有するとよいでしょう。
完全なスコープのアプリ、限定されたスコープのトークン
多くの異なるオブジェクトへのアクセスが必要となるユースケースの場合、全てのコープを含めるようにアプリをプロビジョニングできます。トークンは、許可された全てのスコープのサブセットで要求できるため、個々のトークンは、クライアントアプリケーションがAPIで使うものだけに制限できます。
この方法により、PagerDutyアカウントで管理する必要があるアプリの数を減らすことができます。管理者は、チームまたは部門にアプリをプロビジョニングし、より限定された範囲のトークンを提供できます。
ぜひお試しください
Scoped OAuthは、現在アーリーアクセス機能として提供されており、2023年5月末には全てのアカウントで一般利用できるようになる予定です。ぜひお試しの上、ご意見をお聞かせください。https://pagerduty.digitalstacks.net/free-trial-2/?from-blog からアーリーアクセスにお申込みいただくか、担当者までお問い合わせください。コミュニティーフォーラムに参加して質問することもできます。
この記事はPagerDuty社のウェブサイトで公開されているものをDigital Stacksが日本語に訳したものです。無断複製を禁じます。原文はこちらです。
カテゴリー ：ベストプラクティス
