Atlas App Connections とアプリの統合

重要な概念

委任されたアクセス

アプリケーションは、自分自身ではなく、Atlas ユーザーの代わりに動作します。ユーザー自身の組織ロールとプロジェクト権限によって、成功する操作が決まります。ユーザーがアクションを実行できない場合、アプリケーションはユーザーに代わってそれを実行できません。

組織の削除設定

各 Atlas組織が、サードパーティアプリ接続を許可するかどうかを制御します。ユーザーがアプリケーションを認可 している場合でも、特定の組織に対する操作は、その組織でサードパーティのアプリ接続が有効になっている場合にのみ成功します。既存の組織では、削除はデフォルトで無効になっています。ユーザーは複数の組織に属することができるため、各組織の委任設定に応じて、1 つの認可がユーザーの一部の組織では成功し、他の組織では失敗する可能性があります。

コード交換の証明キー（PKCE）

OAuth 2.1 認証コード フローへのセキュリティ拡張機能で、認可コードのインターセプト攻撃から保護します。 PKCE では、クライアントがランダムな code_verifier を生成し、それから code_challenge を生成し、認可リクエストとともにチャレンジを送信する必要があります。その後、クライアントはトークンの認可コードを交換するときに元の code_verifier を送信することで、リクエストを発信したことを証明します。

フローの概要

クリックして拡大します

このフローは、次の 3 つの手順で進みます。

1. アプリケーションは PKCE コード検証子とチャレンジを生成し、ユーザーを Atlas認可エンドポイントにリダイレクトし、ユーザーは同意画面でアクセスを承認します。

2. アプリケーションにより、アクセス トークンとリフレッシュ トークンの認可コードが交換されます。

3. アプリケーションはアクセス トークンを使用して Atlas Administration API を呼び出し、リフレッシュ トークンを使用して有効期限が切れる前に新しいアクセス トークンを取得します。

ステップ 1: 認可リクエスト

次のパラメータを使用して、ユーザーを Atlas認可エンドポイント（https://cloud.mongodb.com/oauth/authorize）に誘導します。アプリケーションがこのエンドポイントを提示する方法を制御します。これは、既存のウィンドウ内の リダイレクト 、 新しい ブラウザウィンドウ、またはポップアップです。

前述の表のパラメーターのみを送信します。認可エンドポイントには resource パラメーターが必要ないため、OAuth 2.1 仕様でパラメーターが定義されていても、認可リクエストから省略します。

次の例では、読みやすくするためにURLを複数行分割します。 1 行だけで送信します。

https://cloud.mongodb.com/oauth/authorize
  ?response_type=code
  &client_id=<YOUR_CLIENT_ID>
  &redirect_uri=https://yourapp.example.com/callback
  &code_challenge=<CODE_CHALLENGE>
  &code_challenge_method=S256
  &state=<RANDOM_STATE_VALUE>

ステップ 2: トークン交換

Atlas トークン エンドポイントに POSTリクエストを送信して、トークンの認可コードを交換します。

POST https://authorize.mongodb.com/tokens

リクエストの例 :

curl --request POST \
  --url https://authorize.mongodb.com/tokens \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data 'grant_type=authorization_code' \
  --data 'code=<AUTHORIZATION_CODE>' \
  --data 'code_verifier=<CODE_VERIFIER>' \
  --data 'redirect_uri=https://yourapp.example.com/callback' \
  --data 'client_id=<YOUR_CLIENT_ID>' \
  --data 'client_secret=<YOUR_CLIENT_SECRET>'

応答には、次のものが含まれます。

ステップ 3: アクセス トークンを更新する

アクセス トークンの有効期間は短いです（現在は 10 分）。有効期限が切れた後に Atlas Administration API を呼び出す前に、リフレッシュ トークンを新しいアクセス トークンに交換します。

curl --request POST \
  --url https://authorize.mongodb.com/tokens \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data 'grant_type=refresh_token' \
  --data 'refresh_token=<YOUR_REFRESH_TOKEN>' \
  --data 'client_id=<YOUR_CLIENT_ID>' \
  --data 'client_secret=<YOUR_CLIENT_SECRET>'

レスポンスでは常に新しい access_token と新しい refresh_token が返されます。前の更新トークンはすぐに無効化されます。保存されている値の両方を常に置き換えてください。

権限と組織削除設定

特定の Atlas組織に対する操作は、次の両方に当てはまる場合にのみ成功します。

• 組織ではサードパーティアプリ接続が有効になっています。組織の所有者は、この設定をOrganization Settings >App Connections で構成します。 。これらの設定の詳細については、「 Atlas アプリ接続の概要 」を参照してください。

• 認可ユーザーには、その組織またはプロジェクト内での操作に必要なロールがあります。

ユーザーがすでにアプリケーションを承認した後に組織の削除が無効になっている場合、その組織を対象とするAPI呼び出しは 403 Forbidden 応答を返します。

認可が完了しても、Atlas Administration API呼び出しの成功は保証されません。 Atlas は組織の削除設定とユーザーのロールを、認可時に 1 回ではなく、すべてのリクエストで評価するため、リクエストは引き続き 403 Forbidden を返しても、OAuth フローと同意画面は正常に完了できます。

組織のアクセスの確認

アプリケーションが操作できる組織を確認するには、認可後に GET /api/atlas/v2/orgs を呼び出します。 Atlas では、サードパーティのアプリ接続を許可している組織のみが返されるため、空のリストでは、ユーザーが属する組織でそれが有効になっていないことを意味します。

空のリストはセットアップ ステップであり、失敗ではありません。組織のアプリ接続を有効にして点。ユーザーの認証情報と同意は有効であるため、空のリストを認可または認証エラーとして表示することは避けてください。

委任されたアクセスには認可ユーザー独自の権限が付与されるため、書込み (write) 操作はそのユーザーのロールによっても異なります。一般的なプロビジョニング操作には次のロールが必要です。

• プロジェクトを作成するには、ユーザーにOrganization Owner またはOrganization Project Creator ロールが必要です。

• クラスターを作成するには、ターゲットプロジェクトでProject Owner またはProject Cluster Creator ロールが必要です。

Organization Memberロールのみを持つユーザーはアクセスできるリソースを読み取ることができますが、書込み操作は403 Forbidden を返します。エラー処理で必要なロールに名前を付けて、ユーザーが正しいロールをリクエストできるようにします。利用可能なすべてのロールの詳細については、「 Atlas ユーザーロール 」を参照してください。

アプリケーションがユーザーに代わって組織を作成した場合、新しい組織ではサードパーティのアプリ接続はまだ許可されません。これらを有効にするには手動の手順であり、 MongoDBに連絡して組織を許可リスト作成してください。それまでは、ユーザーがアプリケーションを 承認していても 、アプリケーションは組織で動作できません。

ブロックおよびフィルタリングされたエンドポイント

委任されたアクセスはほとんどの Atlas Administration APIエンドポイントに到達しますが、Atlas は、認可ユーザーの権限に関係なく、一部のエンドポイントの処理は異なります。

ブロックされたエンドポイントは、認可ユーザーが通常操作を許可するロールを持っている場合でも、 403 Forbidden応答を返します。 Atlas は、フェデレーションとシングル サインオン（SSO）構成を読み取りおよび変更するフェデレーション設定エンドポイントをブロックします。 ID プロバイダーの構成はフェデレーション内のすべての組織間で共有されるため、アクセスが委任されると、アプリケーションが認可されていない組織が公開されたり、中断されたりする可能性があります。

フィルタリングされたエンドポイントは 呼び出しを受け入れますが、サードパーティのアプリ接続をオプトインしている組織に基づいて、表示や変更できる内容が制限されます。アプリケーションはそれらの組織のみにアクセスでき、Atlas はオプトインしていない組織のリソースへのアクセスをブロックします。

ユーザーがアクセスできるすべての組織、プロジェクト、または クラスター を一覧表示するエンドポイントは、サードパーティアプリ接続を許可する組織のみを返します。リソースを作成するリクエストの場合、Atlas は対象組織を検証し、その組織がオプトインしていない場合は呼び出しを拒否します。

組織所有者は、Organization Settings >App Connections からオプトインします。 。詳細については、「 権限と組織削除設定 」を参照してください。

Atlas は、時間の経過とともに追加のエンドポイントをブロックまたはフィルタリングして委任されたアクセスのために使用される場合があります。

Control Plane と Data Plane

Atlas Administration API はコントロールプレーンにアクセスします。組織、プロジェクト、クラスター、ユーザーなどの Atlas リソースを作成、構成、および管理できます。データプレーンへの直接アクセス（データベース内のドキュメントの読み取りまたは書込み）は提供されません。

Atlas クラスター内のデータにアクセスするには、 Atlas Administration APIからクラスター接続文字列を取得し、データベースユーザーとMongoDBドライバーまたはシェルを使用して接続します。接続文字列とデータベースの認証情報は、OAuth Bearer トークンとは別です。

取り消しは、コントロールプレーンとデータプレーンのアクセスに異なる影響を与えます。 「 データプレーンの影響 」を参照してください。

データベースユーザーの作成

認可ユーザーのベアラー トークンを使用して、Atlas Administration APIエンドポイント POST /api/atlas/v2/groups/{groupId}/databaseUsers からデータベースユーザーを作成します。ユーザーは、データベースユーザー管理を許可するプロジェクトロール を保持している必要があります。

推奨されるプラクティス

• データベースユーザーの制限内にあること。 Atlas100 はプロジェクトごとに データベースユーザーのデフォルト制限を適用します。操作ごとに新しいユーザーを作成する 代わりに、可能な場合は既存のデータベースユーザーを再利用し、 制限に達するのを避ける必要がなくなったユーザーのプロビジョニングを解除します。

• スコープ指定されたロール を使用します。 atlasAdminではなく、ユースケースに必要な最小限のデータベースロールを持つデータベースユーザーを作成します。

• 不要になったユーザーのプロビジョニングを解除します。ユーザーがアプリケーションへのアクセスを取り消す と、アプリケーションがユーザーに代わって作成したデータベースユーザーをすべて削除します。 Atlas は、アクセスが取り消されたときにデータベースユーザーを自動的に削除しません。

• 定義されたスケジュールで認証情報をローテーションします。アプリケーションでデータベースユーザーのパスワードが保存されている場合は、 PATCH /api/atlas/v2/groups/{groupId}/databaseUsers/ {databaseName}/{username}エンドポイントを使用して定期的にローテーションします。

Atlas が、データベースユーザーのパスワードなど、アプリケーションがプロビジョニングされたリソースの認証情報をローテーションする場合は、認証情報を自分で更新する必要はなく、任意の Webhook を介してアプリケーションに通知できます。これは、OAuth のローテーションとは無関係です。詳しくは、「client_secret トークンとシークレット ストレージ 」を参照してください。 Webhook を実装するには、「 認証情報ローテーション Webhook の実装 」を参照してください。

保管時の認証情報の暗号化

アプリケーションは、保管時に暗号化する必要がある機密情報のいくつかのカテゴリを処理します。

• 接続文字列。 Atlas 接続文字列には埋め込み認証情報または参照データベースユーザーが含まれます。高度な暗号化標準（AES）-256 または 同等の暗号化を使用して、保存されている接続文字列を暗号化します。構成ファイル、環境変数ストア、またはデータベースに接続文字列をプレーンテキストで保存しないでください。

• OAuth トークン。リフレッシュ トークンは有効期間が長い認証情報です。これらは暗号化されたシークレット マネージャー（例、 、HashiCorp Vault、 Amazon Web Services （AWS）Secrets Manager、 Azure Key Vault）に保存します。暗号化れていない状態のアプリケーションデータベースにリフレッシュ トークンを保存しないでください。

• クライアントシークレット。あなたの client_secretはパスワードと同じです。このファイルを シークレット マネージャーに保存し、公開されたと思われる場合はローテーションします。

接続文字列の処理

アプリケーションがユーザーに代わって Atlas Administration APIから接続文字列を取得する場合:

• 接続文字列は、可能な場合は長期的に保存するのではなく、必要なときに取得します。

• アプリケーションで接続文字列を保持する必要がある場合は、必要なもの（例、ホスト名とポート）のみを認証情報とは別に保存します。

• 接続文字列をログたり、エラーメッセージやスタックトレースに含めたりしないでください。

トークンとシークレット ストレージ

• ソース管理にトークンまたはシークレットをコミットしないでください。

• アクセス トークン、リフレッシュ トークン、またはクライアントシークレットをログしないでください。アプリケーションがデバッグ用に Atlas Administration APIリクエストを記録する場合は、Authorization ヘッダーを編集します。

• シークレット マネージャー内のシークレットへのアクセスを、必要なサービスのみにスコープ設定します。

• client_secret を定期的に、かつ侵害が発生したと思われる場合はすぐにローテーションします。 OAuthアプリケーションに関連付けられたシークレットをローテーションするには、 MongoDBに問い合わせてください。

失効トリガー

次のいずれかのアクションのいずれかによって取り消しを行うことができます。

• ユーザーが Atlas UIからのアクセスを取り消します（User Settings Connected Apps）。

• 組織所有者は、Organization Settings から組織全体のサードパーティアプリ接続を制限します。

• 組織の最大更新トークン有効期間に達したか、トークンがアイドル有効期間の制限を超えてアイドル状態になっていたため、更新トークンは期限切れになります。

• アプリケーションは、アクセスが不要になると、独自のトークンを取り消します。

アプリケーションからのトークンの取り消し

ユーザーがアプリケーションを自分のインターフェースから切断するか、統合にアクセスが不要になった場合は、トークンを期限切れにするのではなく、トークンを取り消します。失効エンドポイントに POSTリクエストを送信します。

curl --request POST \
  --url https://authorize.mongodb.com/tokens/revoke \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --user '<YOUR_CLIENT_ID>:<YOUR_CLIENT_SECRET>' \
  --data 'token=<REFRESH_OR_ACCESS_TOKEN>' \
  --data 'token_type_hint=refresh_token'

リフレッシュ トークンを取り消すと、そのトークンから発行されたすべてのアクセス トークンも無効になります。エンドポイントはトークンが有効かどうかを確認するために 200 OK を返すため、成功応答はトークンが存在したことを証明するものではなく、トークンが使用できなくなったことを確認するものとして扱います。

コントロールプレーンの影響

取り消しがどの程度有効になるかは、アクセスを取り消すユーザーによって異なります。

• 組織の所有者はサードパーティのアプリ接続を制限します。Atlas Administration API は呼び出しごとに組織の削除設定をチェックするため、その組織に対して403 Forbidden の返却をすぐに開始するようにリクエストします。

• ユーザーがアプリケーションのアクセスを取り消します。リフレッシュ トークンはすぐに無効化されますが、すでに発行されたアクセス トークンは、有効期限が切れるまで有効のままになります。アクセス トークンの有効期間が短いため、アプリケーションは最大10 分間呼び出しに成功し続ける可能性があります。その後、 は401 Unauthorized を返します。

• MongoDB はOAuthクライアントを削除します 15。アプリケーションが接続されているすべての組織にわたって失効のカスケードがあり、完了までに最大 分かかります。

即座の伝達に依存するのではなく、401 と 403 応答を積極的に処理するようにアプリケーションを設計します。

データプレーンの影響

Atlas Administration APIアクセスを取り消しても、既存のデータ プレーン接続はすぐに終了しません。アプリケーションは、OAuth トークンとは独立した認証情報で認証する、作成されたデータベースユーザーを通じてデータプレーンにアクセスします。トークンを取り消しても、これらの認証情報は無効になりません。開いているMongoDBドライバー セッションと接続プール接続は、タイムアウトやアイドルの閉じ、アプリケーションによる明示的な閉じなど、通常の接続ライフサイクル イベントによって閉じられるまでアクティブのままになります。

取り消しでは、アプリケーションで作成されたデータベースユーザーは削除されないため、切断フローの一部としてクリーンアップします。詳細については、「 データベースユーザーのライフサイクル 」を参照してください。

Error Scenarios

OAuth エラー応答

認可およびトークン エンドポイントからのエラーは、標準の OAuth 構造に従います。

{
  "error": "error_code",
  "error_description": "Human-readable explanation"
}

次の表に一般的な error 値を示します。

同じ認可コードが複数回表示される場合、サーバーはコードの中断に対するセキュリティ対策として、その付与に関連付けられているすべてのトークンを無効にします。この問題が発生した場合、ユーザーは最初から再認可する必要があります。

無効化されたクライアント

MongoDB は、インシデント応答や提携するのオフボード例、 登録されたクライアントを無効にすることができます。クライアントが無効になっている間、サーバーは新しい認可フローの開始や新しいトークンの発行を拒否します。

• 認可エンドポイントは、error=access_denied と client is disabled の error_description を持つ redirect_uri にユーザーをリダイレクトします。

• トークン エンドポイントは、invalid_client と同じ説明を持つ 401 を返します。これは、refresh_token を含むすべての付与タイプに適用されるため、アプリケーションは無効になっている間は既存の更新トークンを交換できません。

クライアントが無効化される前に発行されたアクセス トークンは、有効期限が切れるまで有効のままです。クライアントを無効にすると、既存のトークンが無効になるのではなく、新しいトークンがブロックされます。

無効にされたクライアントは、単独では回復できません。 client is disabled をターミナル条件として扱い、再試行を停止し、障害を表示し、 MongoDB提携するチームにクライアントを再度有効にするよう連絡します。