インテグレーションのための OAuth

Join the Beta!

Datadog Developer Platform は現在ベータ版です。アクセス権をお持ちでない場合は、apps@datadoghq.com までご連絡ください。

概要

OAuth の仕組みにより、ユーザーはサードパーティインテグレーションに対し、スコープを特定した形でユーザーの Datadog データへのアクセスを許可することができます。この認証により、インテグレーションは Datadog にデータをプッシュしたり、Datadog からデータをプルしたりすることが可能になります。例えば、ユーザーがインテグレーションに対し Datadog モニターへの読み取りアクセスを許可した場合、インテグレーションはユーザーのモニターデータを直接読み取って、抽出することができます。

Datadog における OAuth の実装の詳細については、Datadog OAuth2 のドキュメントをご覧ください。

インテグレーションで OAuth を使用する

OAuth の仕組みにより、Datadog をご利用のお客様は、数回のクリック操作で簡単かつセキュアにサードパーティプラットフォームを認証することができます。API キーやアプリキーを直接どこかに入力する必要はありません。既存のインテグレーションで OAuth を利用することも、新規のインテグレーション開発の一環として OAuth を構成することも可能です。

OAuth を利用してインテグレーションをビルドする際は、アプリケーションがアクセスする必要のあるデータの正確なスコープを選択でき、ユーザーは要求された詳細なスコープに対するアクセス権を付与することができます。任意のスコープはサポートされていませんが、ユーザーが承認した場合、インテグレーションにより要求された全てのスコープがアクセス可能となります。

OAuth を使ったインテグレーションの構築

ここでは、Marketplace または Integrations ページのタイルを使って新規のインテグレーションをビルドする方法をご説明します。既存のインテグレーションをもとにビルドする場合や、新規のインテグレーションをビルドして、いずれかのページの既存のタイルに追加したい場合は、既存のオファーに OAuth を追加するをご覧ください。

テンプレートからアプリを作成する

  1. Datadog Developer Platform に移動して、+New App をクリックします。

    インテグレーション用の OAuth クライアントそれぞれについて、アプリを作成する必要があります。インテグレーションが公開されると、Datadog がこのアプリをインテグレーションに紐付けます。

  2. Blank App を選択して、アプリの名前を追加します。

  3. 作成をクリックします。

  4. Basic Information タブで、詳細ビューに表示される情報を入力します。

  5. OAuth クライアントの公開準備が整ったら、Mark Stable ボタンをクリックします。

  6. 保存をクリックします。

OAuth クライアントを作成する

OAuth クライアントはアプリケーションのコンポーネントで、ユーザーがアプリケーションに対し、自身の Datadog データへのアクセスを許可することが可能になります。クライアントがアクセス権を取得するには、適切なアクセストークンが必要です。

  1. Features の OAuth & Permissions タブに移動し、Create OAuth Client をクリックします。

    インテグレーション用に作成する OAuth クライアントは、クライアント ID とクライアントシークレットを提供する機密クライアントです。この段階で作成するクライアントはクライアントの非公開バージョンで、その資格情報を使ってテストを行うことができます。このクライアントの公開バージョンが作成された際には、新しい資格情報が付与されます。この資格情報は、クライアント作成後は二度と表示されないため、必ず安全な場所に保管してください。

  2. 名前、説明、リダイレクト先の URI、オンボーディング用 URL などのクライアント情報を入力します。

  3. スコープを検索して、Requested 欄のチェックボックスを選択することで、OAuth クライアントのスコープの構成を行います。

    スコープとは、顧客の Datadog アカウント内でアプリがアクセス可能なデータの種類を決定するものです。これにより、インテグレーションが必要なスコープにアクセスすることができます。スコープは必要に応じて後で追加できますので、ご自身のユースケースで必要とされる最低限のスコープのみを要求するようにしてください。

    Datadog にデータを送信するには、api_keys_write スコープを選択する必要があります。これは、インテグレーションパートナーにのみ認められる非公開のスコープで、ユーザーに代わって API キーを作成することが可能になり、このキーを使ってデータを Datadog に送信することができます。

  4. Save Changes をクリックします。

  5. OAuth クライアントを作成してスコープを割り当てた後は、OAuth を通じて利用可能なエンドポイントを利用して、インテグレーションに OAuth PKCE プロトコルを実装し、認可コードの付与フローを完成させ、インテグレーションコードの記述を開始することができます。

    認可コード付与フローでは、認可コードとリフレッシュトークンを受け取った後、認可コードをアクセストークンと交換します。アクセストークンは、Datadog からプルしたいデータにアクセスするために利用できます。

    Datadog で使用する OAuth プロトコルの実装に関する詳細については、Datadog OAuth2 をご覧ください。また、インテグレーションのビルドと公開に関する詳細については、インテグレーション開発者用ドキュメントをご覧ください。

  6. OAuth プロトコルのテストを行います。クライアントの詳細ページにある Test Authorization をクリックすると、オンボーディング用 URL にリダイレクトされ、顧客がたどる認可フローが開始されます。

    クライアントが公開されるまでは、お客様の Datadog オーガニゼーションのメンバーのみがテスト中にクライアントを認可できます。

  7. OAuth が正しく機能しているかどうかを検証するために、リクエストのヘッダーにトークンを設定して、marketplace_create_api エンドポイントにリクエストを送信します。

    このリクエストが成功した場合は、API キーが返されます。API キーは、ユーザーに代わって Datadog にデータを送信する際に使用できるよう、セキュリティに配慮して保存する必要があります。最初のリクエストに対する応答が返された後は、この API キーの値に再度アクセスすることはできません。

  8. US1 以外の Datadog アカウントから認可を要求して、OAuth クライアントが複数の Datadog サイトで機能することを確認します。

    • 別のサイトのサンドボックスアカウントへのアクセス権がない場合は、marketplace@datadog.com までご連絡ください。
    • Developer Platform で作成したアプリに移動して右上の歯車アイコンをクリックし、Export App Manifest をクリックして、オリジナルの Datadog サイトのアカウントからアプリのマニフェストをエクスポートします。
    • 新しい Datadog サイトのアカウントで Developer Platform に移動して、手順 2 でエクスポートしたアプリのマニフェストをインポートします。
    • マニフェストのインポートが完了したら、OAuth & Permissions タブに移動して、OAuth クライアントとそのクライアント ID およびクライアントシークレットを確認します。この資格情報を使って、このサイトからの認可をテストします。

  9. 他にもアクセスを要求したスコープがある場合は、そちらのテストを行います。

OAuth クライアントを公開する

OAuth クライアントを公開するには、まず integrations-extras または Marketplace GitHub リポジトリで、作成したインテグレーションについてプルリクエストを開く必要があります。

プルリクエストの一環として、README ファイルを更新してください。## Setup 内に uninstallation セクションとして次の指示を記入します (カスタムの指示を追加した場合は併せて記入)。

  • このインテグレーションをアンインストールすると、それ以前に与えられた認可は全て取り消されます。
  • また、API Keys ページでインテグレーション名を検索して、このインテグレーションに紐付けられた全ての API キーが無効になったことを確認してください。

Developer Platform で公開プロセスを開始する方法

  1. General の Publishing タブに移動します。公開フローの手順 1 では、公開済みのクライアント ID とクライアントシークレットを受け取りました。手順 2 では、インテグレーションに関する追加の情報を入力し、以下で使用する公開済みの app_uuid を確認することができます。

    クライアント ID、クライアントシークレット、app_uuid を安全な場所に保存します。

  2. integrations-extras または Marketplace で新規インテグレーションのプルリクエストをオープンする際には、manifest.json ファイルの app_uuid フィールドに公開するのに、この app_uuid の値を使用します。app_uuid の値が一致しない場合、アプリケーションの公開が正しく行われません。既存のインテグレーションがある場合、app_uuid の更新は不要です。

公開済みの OAuth クライアントを直接編集することはできませんので、全てのテストが完了し、準備が整った段階で公開フローを実行してください。OAuth クライアントを更新するには、公開フローを再度実行する必要があります。公開済みクライアントの資格情報は再表示されません。

インテグレーション公開プロセスの詳細については、マーケットプレイスとインテグレーションのドキュメントを参照してください。

既存のオファーに OAuth を追加する

既存のインテグレーションに OAuth クライアントを追加する手順は、上記とほぼ同じですが、いくつかの重要な違いがあります。

UI Extension に接続されていない既存のインテグレーションがある場合

上記の手順に従い、インテグレーションタイルに新しいアンインストール手順を追加するためにプルリクエストを開くことを確認してください。

既存のインテグレーションがある場合は、manifest.json ファイル内の app_uuid を変更する必要はありません。

UI Extension に接続中の既存のインテグレーションがある場合 (同じタイルを共有)

アプリを作成するのではなく、Developer Platform で公開した UI Extension を含むアプリに移動し、残りの手順に従ってください。

インテグレーションの OAuth クライアントを作成し、公開する準備ができたら、アプリの Edit をクリックし、General の下の Publishing タブに移動します。また、新しいアンインストール手順をタイルに追加するために、プルリクエストを開きます。

注: 既存のインテグレーションまたは UI Extension がある場合は、manifest.json ファイル内の app_uuid を変更する必要はありません。

公開されている UI Extension があり、同じタイルにインテグレーションを追加したい場合

アプリを作成するのではなく、Developer Platform で公開した UI Extension を含むアプリに移動し、残りの手順に従ってください。

README、画像フォルダなどの更新を含む、インテグレーションに関する追加情報で既存のタイルを更新するために、プルリクエストを開きます。公開プロセスで、このプルリクエストへのリンクを追加します。

その他の参考資料

お役に立つドキュメント、リンクや記事: