概要
このページでは、機密クライアントを作成した後、アプリケーションに OAuth プロトコルをエンドツーエンドで実装する方法を順を追って説明しています。
OAuth プロトコルの実装
Datadog Partner Sandbox アカウント内の Developer Platform で OAuth クライアントを作成し、設定します。
ユーザーがインテグレーションをインストールした後、インテグレーションタイルの Configure タブにある Connect Accounts ボタンをクリックしてアカウントを接続することができます。
ユーザーがこのボタンをクリックすると、OAuth クライアント作成プロセスの一部として提供した onboarding_url に誘導されます。このページは、プラットフォームのサインインページであるべきです。
ユーザーがサインインしたら、適切な URL パラメーターを指定して OAuth2 Authorization エンドポイントにリダイレクトします。この URL パラメーターには、アプリケーションで生成した code_challenge パラメーターが追加されています。
code_challenge パラメーターの導出方法については、 PKCE のセクションを参照してください。アプリケーションは、ステップ 5 のトークンリクエストのために code_verifier を保存する必要があります。
- この GET リクエストのURLを作成するには、
onboarding_url へのリダイレクトで提供されるsite クエリパラメーターを使用します。 - このパラメーターは、ユーザーが Datadog インテグレーションタイルから認可を開始する場合にのみ提供されます。ユーザーが外部から認可を開始することを選択した場合のオプションについては、 サードパーティロケーションからの認可の開始セクションを参照してください。
site クエリパラメータは、認証ユーザーがいる Datadog サイト と、そのユーザーが使用しているであろうサブドメインを提供し、Authorize エンドポイントへの GET リクエストの URL を構築するために必要です。<site>/oauth2/v1/authorize?... 。
ユーザーが Authorize をクリックすると、Datadog は認可エンドポイントに POST リクエストを作成します。ユーザーは、OAuth クライアントを設定する際に、クエリコンポーネントの認可パラメータ ー code で指定した redirect_uri にリダイレクトされます。
redirect_uri から、Datadog トークンエンドポイントに POST リクエストを行い、ステップ 4 の認可コード、ステップ 3 の code_verifier 、OAuth クライアント ID、クライアントシークレットを含むようにします。
- この POST リクエストの URL を作成するには、
redirect_uri へのリダイレクトで提供されるdomain クエリパラメーターを使用します。 - これは、トークンのエンドポイントへの POST リクエストの URL を作成するために必要です。
https://api.<domain>/oauth2/v1/token
成功すると、レスポンス本文で access_token と refresh_token を受け取ります。アプリケーションには、You may now close this tab というメッセージを含む確認ページが表示されるはずです。
Datadog API エンドポイントを呼び出すには、リクエストの認可ヘッダーの一部として access_token を使用します: headers = {"Authorization": "Bearer {}".format(access_token)}
- 注*: API エンドポイントは、Datadog サイトごとに異なります。例えば、ユーザーが EU リージョンにいる場合、Events エンドポイントは
https://api.datadoghq.eu/api/v1/events ですが、US1 のユーザーの場合、Events エンドポイントは https://api.datadoghq.com/api/v1/events です。 - これらの API コールでは
domain クエリパラメーターを直接使用して、正しいエンドポイントにアクセスできるようにしてください。例えば、Events エンドポイントを呼び出すには、リクエスト URL を https://api.<domain>/api/v1/events とします。 - エンドポイントによっては API キーが必要な場合があります。これはステップ 8 で作成されます。
API Key Creation エンドポイントを呼び出し、Datadog ユーザーの代わりにデータを送信するための API キーを生成します。
API_KEYS_WRITE スコープがクライアントに追加されていない場合、このステップは失敗します。このエンドポイントでは、一度だけ表示される API キーを生成し、ユーザーが Datadog アカウント内で削除しない限り、再生成することはできません。この値は安全なデータベースまたは場所に保存してください。
OAuth クライアントの作成、テスト、公開については、Datadog インテグレーションのための OAuth を参照してください。
サードパーティロケーションからの認可の開始
ユーザーは、インテグレーションタイルの Connect Accounts をクリックすることで、Datadog の認証プロセスを開始することができます。ユーザーが Datadog の Connect Accounts をクリックすると、ユーザーの Datadog サイト に関する情報がリダイレクトで onboarding_url と redirect_uri に送信されます。ユーザーの Datadog サイトは、ユーザーの代理で API コールを行い、認証コードを受け取るために必要です。ユーザーが インテグレーションの外部ウェブサイト から認証を開始する場合、ユーザーのサイト情報は提供されません。
さらに、ユーザーが Datadog インテグレーションタイルから認可を開始する場合、要求されたすべてのスコープに対応する権限を持っていることが必要です。インテグレーションタイル以外の場所から認可を開始した場合、必要なすべての権限を持たないユーザーが認可を完了することがあります (ただし、インテグレーションタイルに戻ったときに適切な権限で再認可するよう促されます)。
Datadog は、パートナーが自社のプラットフォームからではなく、Datadog から認可を開始するようユーザーに促すことを推奨しています。
Datadog は、Datadog インテグレーションタイル以外のサードパーティロケーションからの認可をサポートすることを推奨していませんが、この方法を選択する場合は、すべての Datadog サイトでユーザーをサポートできることを確認し、新しい Datadog サイトが作成されるたびにサポートを継続する意思があることを確認する必要があります。これには通常、認可時にユーザーが自分のサイトをプラットフォームに手動で入力する方法を実装することが含まれます。
組織はサブドメインも持っている可能性があることに留意してください。 (例えば、 https://subdomain.datadoghq.com) サブドメインを API コールに含めないようにしてください。そのため、API コールの URL を作成する際、redirect_uri へのリダイレクト時に返される domain のクエリパラメータを使用することをお勧めします。ユーザーが正しいサイトで認証されていることを確認するには、常に US1 の Datadog サイト (app.datadoghq.com) に誘導し、そこから利用する地域を選んでもらうようにします。
PKCE による認可コード付与フロー
OAuth2 プロトコルはいくつかの付与フローをサポートしていますが、PKCE による認可コード付与フローは、ユーザーが一度明示的に同意し、クライアントの資格を安全に保存できる長期的なアプリケーションに推奨する付与タイプです。
この付与タイプでは、アプリケーションが一意の認可コードを安全に取得し、それをアクセストークンと交換することで、Datadog API へのリクエストを行うことができます。認可コードの付与フローは、3 つのステップで構成されています。
- アプリケーションは、一連の Datadog スコープにアクセスするためにユーザーに認可をリクエストします。
- ユーザーが Authorize をクリックすると、アプリケーションは一意の認可コードを取得します。
- アプリケーションは認可コードをアクセストークンに交換し、アクセストークンは Datadog の API にアクセスするために使用されます。
PKCE 拡張機能を使用する
Proof key for code exchange (PKCE) は、OAuth2 の認可コード付与フローを拡張して、OAuth2 クライアントを傍受攻撃から保護するための拡張機能です。攻撃者がフローを傍受し、アプリケーションに返される前の認可コードにアクセスした場合、アクセストークンを取得し、Datadog の API にアクセスすることができます。
このような攻撃を軽減するために、PKCE 拡張機能では、認可リクエストとトークンリクエストをグラントフロー全体で安全に関連付けるために、以下のパラメーターが用意されています。
| パラメーター | 定義 |
|---|
| Code Verifier | 動的に生成される暗号用乱数文字列。 |
| Code Challenge | コードベリファイアの変換。code_challenge は base64url エンコーディングを使用しなければなりません。 |
| Code Challenge Method | code_challenge を code_verifier から導出するために使用するメソッド。code_challenge の計算には SHA-256 を使用しなければなりません。 |
PKCE プロトコルは、以下のアクションを完了することで、認可コードの付与フローとインテグレーションします。
アプリケーションは code_verifier というランダムな文字列を生成し、それに対応する code_challenge を code_challenge_method を用いて導出します。
アプリケーションは Datadog に対して、code_challenge と code_challenge_method のパラメーターで認可リクエストを送信し、認可コードを取得することができます。
アプリケーションはアクセストークンを取得するために、認可コードと code_verifier を指定して Datadog にトークンリクエストを送信します。トークンエンドポイントは code_verifier を code_challenge_method を使って変換し、元の code_challenge の値と比較することで認可コードを検証します。
その他の参考資料
