앱을 Atlas App Connections와 통합하기

주요 개념

위임된 액세스

애플리케이션 은 그 자체가 아닌 Atlas user 대신하여 작동합니다. 사용자 자신의 조직 역할과 프로젝트 권한에 따라 성공하는 작업이 결정됩니다. 사용자가 조치 수행할 수 없는 경우 애플리케이션 도 사용자를 대신하여 작업을 수행할 수 없습니다.

조직 위임 설정

각 Atlas 조직 타사 앱 연결 허용 여부를 제어합니다. 사용자가 애플리케이션 승인하더라도 특정 조직 에 대한 작업은 해당 조직 에서 타사 앱 연결을 활성화한 경우에만 성공합니다. 기존 조직에서는 위임이 기본값 으로 비활성화되어 있습니다. 사용자는 여러 조직에 속할 수 있으므로 각 조직의 위임 설정에 따라 사용자의 조직 일부에서는 단일 권한 부여 성공할 수 있고, 다른 조직에서는 실패할 수 있습니다.

코드 교환용 증명 키(PKCE)

OAuth 2.1 권한 부여 코드 플로우에 대한 보안 확장으로, 권한 부여 코드 가로채기 공격으로부터 보호합니다. PKCE는 클라이언트 임의의 code_verifier를 생성하고, 여기서 code_challenge을 도출한 다음, 권한 부여 요청 과 함께 과제 보내도록 요구합니다. 그런 다음 클라이언트 권한 부여 코드를 토큰으로 교환할 때 원본 code_verifier를 전송하여 요청 이 시작되었음을 증명합니다.

흐름 개요

클릭하여 확대

이 흐름은 세 단계로 진행됩니다.

1. 애플리케이션 은 PKCE 코드 검증자와 과제 생성하고 사용자를 Atlas 권한 부여 엔드포인트로 리디렉션하고 사용자는 동의 화면에서 액세스 승인합니다.

2. 애플리케이션 은 권한 부여 코드를 액세스 토큰 및 새로 고침 토큰으로 교환합니다.

3. 애플리케이션 은 액세스 토큰을 사용하여 Atlas 관리 API 호출하고 새로 고침 토큰을 사용하여 만료되기 전에 새 액세스 토큰을 얻습니다.

1단계: 권한 부여 요청

다음 매개변수를 사용하여 사용자를 Atlas 권한 부여 엔드포인트(https://cloud.mongodb.com/oauth/authorize)로 안내합니다. 애플리케이션 이 엔드포인트를 표시하는 방법(기존 창 내 리디렉션, 새 브라우저 창 또는 팝업)을 제어합니다.

앞의 표에 있는 매개변수만 전송합니다. 권한 부여 엔드포인트에는 resource 매개변수가 필요하지 않으므로 OAuth 2.1 사양에 정의되어 있더라도 권한 부여 요청 에서 이를 생략하세요.

다음 예시 가독성을 위해 URL 여러 줄로 나누습니다. 다음과 같이 한 줄로 전송합니다.

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 관리 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 관리 API 호출의 성공이 보장되는 것은 아닙니다. Atlas 권한 부여 시점에 한 번이 아닌 모든 요청 에서 조직의 위임 설정과 사용자의 역할을 평가하므로 요청이 여전히 403 Forbidden을 반환하는 동안 OAuth 흐름 및 동의 화면이 깨끗하게 완료될 수 있습니다.

조직 액세스 확인

권한 부여 후 GET /api/atlas/v2/orgs를 호출하여 애플리케이션 이 어떤 조직에서 조치를 취할 수 있는지 확인합니다. Atlas 타사 앱 연결을 허용하는 조직만 반환하므로 목록이 비어 있으면 사용자가 속한 조직에서 타사 앱 연결을 허용한 조직 없다는 의미입니다.

빈 목록은 설정 단계이며 실패가 아닙니다. 사용자에게 조직 소유자에게 조직 에 대한 앱 연결을 활성화 하도록 요청하고 Atlas App Connections Overview( Atlas 앱 연결 개요)를 가리키도록 요청하라는 메시지를 점 . 사용자의 자격 증명 과 동의가 유효하므로 빈 목록을 권한 부여 또는 인증 오류로 표시하지 않도록 합니다.

위임된 액세스 는 권한 부여하는 사용자의 고유한 권한을 수반하므로 쓰기 (write) 작업도 해당 사용자의 역할에 따라 달라집니다. 일반적인 프로비저닝 작업에는 다음과 같은 역할이 필요합니다.

• 프로젝트 생성하려면 사용자에게 Organization Owner 또는 Organization Project Creator 역할 필요합니다.

• 클러스터 생성하려면 사용자에게 대상 프로젝트 에서 Project Owner 또는 Project Cluster Creator 역할 필요합니다.

Organization Member 역할 만 가진 사용자는 액세스 이 있는 리소스를 읽을 수 있지만 쓰기 (write) 작업은 403 Forbidden를 반환합니다. 오류 처리에서 필요한 역할 의 이름을 지정하여 사용자가 올바른 역할 요청 수 있도록 합니다. 사용 가능한 모든 역할에 대해 학습 Atlas 사용자 역할을 참조하세요.

애플리케이션 에서 사용자를 대신하여 조직 만드는 경우 새 조직 아직 타사 앱 연결을 허용하지 않습니다. 이를 활성화하는 것은 수동 단계입니다. 조직 허용 목록에 추가하려면 MongoDB 문의 . 그때까지는 사용자가 애플리케이션 승인했더라도 애플리케이션 조직 에 영향을 미칠 수 없습니다.

차단 및 필터링된 엔드포인트

위임된 액세스 대부분의 Atlas 관리 API 엔드포인트에 도달하지만, Atlas 권한 부여 사용자의 권한에 관계없이 일부 엔드포인트를 다르게 취급합니다.

차단된 엔드포인트는 권한을 부여하는 사용자가 일반적으로 작업을 허용하는 역할 가지고 있는 경우에도 403 Forbidden 응답을 반환합니다. Atlas 페더레이션 및 싱글 사인온(SSO) 구성을 읽고 수정하는 페더레이션 설정 엔드포인트를 차단합니다. ID 제공자 구성은 페더레이션의 모든 조직 에서 공유되므로 이에 대한 위임된 액세스 애플리케이션 승인한 적이 없는 조직을 노출하거나 중단시킬 수 있습니다.

필터링된 엔드포인트는 호출을 수락하지만 타사 앱 연결을 선택한 조직에 따라 보거나 변경할 수 있는 항목을 제한합니다. 애플리케이션 해당 조직에만 연결할 수 있으며, Atlas 옵트인하지 않은 조직 의 리소스에 대한 액세스 차단합니다.

사용자가 액세스 할 수 있는 모든 조직, 프로젝트 또는 클러스터 나열하는 엔드포인트와 같이 여러 조직에 걸쳐 있는 엔드포인트는 타사 앱 연결을 허용하는 조직만 반환합니다. 리소스를 생성하는 요청의 경우 Atlas 대상 조직 유효성을 검사하고 해당 조직 옵트인하지 않은 경우 호출을 거부합니다.

조직 소유자가 Organization Settings > App Connections. 자세한 학습 은 권한 및 조직 위임 설정을 참조하세요.

Atlas 시간이 지남에 따라 위임된 액세스 에 대해 추가 엔드포인트를 차단 하거나 필터하다 할 수 있습니다.

컨트롤 플레인 대 데이터 플레인

Atlas 관리 API 조직, 프로젝트, 클러스터, 사용자와 같은 Atlas 리소스를 생성, 구성 및 관리 할 수 있는 컨트롤 플레인 액세스 제공합니다. 직접적인 데이터 플레인 액세스 (데이터베이스의 문서 읽기 또는 쓰기)는 제공하지 않습니다.

Atlas 클러스터의 데이터에 액세스 하려면 Atlas 관리 API 통해 클러스터 연결 문자열 조회 하고 데이터베이스 사용자와 MongoDB 운전자 또는 셸 사용하여 연결합니다. 연결 문자열 과 데이터베이스 자격 증명 은 OAuth 베어러 토큰과 별개입니다.

철회는 컨트롤 플레인과 데이터 플레인 액세스 서로 다른 영향을 미칩니다.데이터 플레인 효과를 참조하세요.

데이터베이스 사용자 생성

권한 부여 사용자의 베어러 토큰을 사용하여 Atlas 관리 API 엔드포인트 POST /api/atlas/v2/groups/{groupId}/databaseUsers를 통해 데이터베이스 사용자를 생성합니다. 사용자는 데이터베이스 사용자 관리 허용하는 프로젝트 역할 보유해야 합니다.

권장 사례

• 데이터베이스 사용자 제한을 준수합니다. Atlas 프로젝트 당 100 데이터베이스 사용자의 기본값 제한을 적용합니다. 각 작업마다 새 사용자를 만드는 대신 가능한 경우 기존 데이터베이스 사용자를 재사용하고, 한도에 도달하지 않도록 더 이상 필요하지 않은 사용자의 프로비저닝을 해제하세요.

• 범위가 지정된 역할을 사용합니다. atlasAdmin 대신 사용 사례 에 필요한 최소 데이터베이스 역할로 데이터베이스 사용자를 생성하세요.

• 더 이상 필요하지 않은 경우 사용자의 프로비저닝을 해제합니다. 사용자가 애플리케이션 에 대한 액세스 취소하는 경우 애플리케이션 에서 사용자를 대신하여 생성한 데이터베이스 사용자를 모두 삭제 . Atlas 액세스 취소될 때 데이터베이스 사용자를 자동으로 제거 하지 않습니다.

• 정의된 예정 에 따라 자격 증명 교체합니다. 애플리케이션 에 데이터베이스 사용자 비밀번호가 저장되는 경우, PATCH /api/atlas/v2/groups/{groupId}/databaseUsers/ {databaseName}/{username} 엔드포인트를 사용하여 정기적으로 비밀번호를 교체하세요.

Atlas 데이터베이스 사용자 비밀번호와 같이 애플리케이션 에서 프로비저닝한 리소스 에 대한 자격 증명 로테이션하는 경우, 자격 증명 직접 업데이트 할 필요 없이 선택적 웹훅을 통해 애플리케이션 에 알릴 수 있습니다. 이는 OAuth client_secret 로테이션과 관련이 없습니다. 이에 대해서는 토큰 및 비밀 저장소를 참조하세요. 웹훅을 구현 하려면 자격 증명 순환 웹훅 구현을 참조하세요.

미사용 자격 증명 암호화

애플리케이션 은 미사용 데이터 암호화됨 해야 하는 여러 범주의 민감한 정보를 처리합니다.

• 연결 문자열. Atlas 연결 문자열에는 내장된 자격 증명 또는 참조 데이터베이스 사용자가 포함되어 있습니다. 고급 암호화 표준(AES)-256 또는 이에 상응하는 암호화 사용하여 저장된 연결 문자열을 암호화합니다. 구성 파일, 환경 변수 저장소 또는 데이터베이스에 연결 문자열을 일반 텍스트로 저장 하지 마세요.

• OAuth 토큰. 새로 고침 토큰은 수명이 긴 자격 자격 증명 입니다. 암호화됨 시크릿 관리자( 예시: HashiCorp Vault, Amazon Web Services (AWS) Secrets 관리자 또는 Azure Key Vault )에 저장합니다. 새로 고침 토큰을 암호화 하지 않고 애플리케이션 데이터베이스 에 저장 하지 마세요.

• 클라이언트 비밀. client_secret은(는) 비밀번호와 동일합니다. 비밀 관리자에 저장했다가 노출이 의심되는 경우 순환시키세요.

연결 문자열 처리

애플리케이션 이 사용자를 대신하여 Atlas 관리 API 에서 연결 문자열을 검색하는 경우:

• 가능한 경우 연결 문자열을 장기간 저장하는 대신 필요한 시점에 검색합니다.

• 애플리케이션 에서 연결 문자열 유지해야 하는 경우, 필요한 항목( 예시: 호스트 이름 및 포트)만 자격 증명 과 별도로 저장 .

• 연결 문자열을 로그 하거나 오류 메시지 또는 스택 추적에 포함하지 마세요.

토큰 및 시크릿 스토리지

• 토큰이나 시크릿을 소스 제어에 커밋 하지 마세요.

• 액세스 토큰, 새로 고침 토큰 또는 클라이언트 비밀을 로그 하지 마세요. 애플리케이션 디버깅을 위해 Atlas 관리 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 관리 API 모든 호출에서 조직의 위임 설정을 확인하므로 해당 조직 대한 요청이 즉시 403 Forbidden을 반환하기 시작합니다.

• 사용자가 애플리케이션의 액세스 취소하는 경우: 새로 고침 토큰은 즉시 무효화되지만 이미 발급된 액세스 토큰은 만료될 때까지 유효합니다. 액세스 토큰은 수명이 짧기 때문에 애플리케이션 최대 10분 동안 계속 성공적인 호출을 할 수 있습니다. 그 후에는 호출이 401 Unauthorized을 반환합니다.

• MongoDB OAuth 클라이언트 삭제합니다: 해지는 애플리케이션 연결된 모든 조직 에서 계단식으로 진행되며, 완료하는 데 최대 15분이 걸립니다.

즉각적인 전파에 의존하기보다는 401 및 403 응답을 사전에 처리하다 하도록 애플리케이션 설계하세요.

데이터 플레인 효과

Atlas 관리 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 제휴하다 팀 문의 클라이언트 다시 활성화합니다.