Atlas 앱 Connections와 앱 통합

주요 개념

위임된 액세스

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

조직 위임 설정

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

코드 교환의 증명 키(PKCE)

OAuth 2.1에 대한 보안 확장 권한 부여 코드 가로채기 공격으로부터 보호하는 권한 부여 코드 흐름입니다. PKCE를 사용하려면 클라이언트가 임의의 code_verifier를 생성하고, 이로부터 code_challenge를 도출한 다음, 권한 부여 요청과 함께 과제를 전송해야 합니다. 그런 다음 클라이언트는 권한 부여 코드를 토큰으로 교환할 때 원본 code_verifier을(를) 보내 자신이 요청을 시작했음을 증명합니다.

흐름 개요

클릭하여 확대

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

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

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

3. 애플리케이션은 액세스 토큰을 사용하여 Atlas Administration 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 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 Owner는 Organization Settings > App Connections에서 이 설정을 구성합니다. 이러한 설정에 대해 자세히 알아보려면 Atlas 앱 연결 개요를 참조하세요.

• 권한을 부여하는 사용자는 해당 조직 또는 프로젝트 내에서 작업에 필요한 역할을 가지고 있습니다.

사용자가 이미 애플리케이션을 승인한 후 조직에 대해 위임이 비활성화되면 해당 조직을 대상으로 하는 API 호출은 403 Forbidden 응답을 반환합니다.

권한 부여가 완료되었다고 해서 Atlas Administration API 호출이 성공하는 것은 아닙니다. Atlas는 권한 부여 시 한 번이 아니라 모든 요청 시 조직의 위임 설정과 사용자의 역할을 평가하므로 OAuth 흐름과 동의 화면은 깔끔하게 완료될 수 있지만 요청은 여전히 403 Forbidden을(를) 반환할 수 있습니다.

조직 액세스 확인

권한 부여 후 GET /api/atlas/v2/orgs을 호출하여 애플리케이션이 작업을 수행할 수 있는 조직을 확인합니다. Atlas는 삼자 앱 연결을 허용하는 조직만 반환합니다. 따라서 빈 목록은 사용자가 속한 조직 중 어떤 조직도 이를 활성하지 않았음을 의미합니다.

빈 목록은 실패가 아니라 설정 단계입니다. 사용자에게 Organization Owner에게 조직에 대한 앱 연결을 활성화하도록 요청하고 Atlas 앱 연결 개요를 참조하도록 안내하세요. 사용자의 자격 증명과 동의가 유효하므로 빈 목록을 권한 부여 또는 인증 오류로 표시하지 마세요.

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

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

• 클러스터를 생성하려면 사용자는 대상 프로젝트에 대해 Project Owner 또는 Project Cluster Creator 역할이 있어야 합니다.

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

애플리케이션이 사용자를 대신하여 조직을 만들 때, 새 조직은 아직 제3자 앱 연결을 허용하지 않습니다. 이를 활성화하는 것은 수동 단계입니다. 조직을 허용 목록에 추가하려면 MongoDB에 문의하세요. 그때까지는 사용자가 애플리케이션에 권한을 부여했더라도 애플리케이션이 조직에 대해 작업을 수행할 수 없습니다.

차단 및 필터 엔드포인트

위임된 액세스는 대부분의 Atlas Administration API 엔드포인트에 적용되지만, Atlas는 권한 부여 사용자의 권한과 관계없이 일부 엔드포인트를 다르게 처리합니다.

차단된 엔드포인트는 권한을 부여하는 사용자에게 일반적으로 작업을 허용하는 역할이 있는 경우에도 403 Forbidden 응답을 반환합니다. Atlas는 페더레이션 및 SSO(Single Sign-On) 구성을 읽고 수정하는 페더레이션 설정 엔드포인트를 차단합니다. 자격 증명 공급자 구성은 페더레이션의 모든 조직에서 공유되므로 이에 대한 위임된 액세스는 귀하의 애플리케이션을 승인하지 않은 조직을 노출하거나 방해할 수 있습니다.

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

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

Organization Owner는 Organization Settings > App Connections에서 옵트인합니다. 자세한 내용은 권한 및 조직 위임 설정을 참조하세요.

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

제어 편 대 데이터 편

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

Atlas 클러스터의 데이터에 액세스하려면 Atlas Administration API를 통해 클러스터 연결 문자열을 조회하고 데이터베이스 사용자 및 MongoDB 드라이버 또는 shell을 사용하여 연결하세요. 연결 문자열과 데이터베이스 자격 증명은 OAuth Bearer token과 별개입니다.

취소는 컨트롤 플레인과 데이터 플레인 액세스에 다르게 영향을 미칩니다. 데이터 플레인 효과를 참조하세요.

데이터베이스 사용자 생성

인증 사용자의 Bearer token을 사용하여 Atlas Administration 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(Advanced Encryption Standard)-256 또는 동급의 암호화를 사용하여 저장된 모든 연결 문자열을 암호화합니다. 설정 파일, 환경 변수 저장소 또는 데이터베이스에 연결 문자열을 일반 텍스트로 저장하지 마십시오.

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

• 클라이언트 비밀. client_secret은(는) 비밀번호와 동일합니다. 비밀 관리자에 저장하고 노출된 것으로 의심되는 경우 교체하십시오.

연결 문자열 처리

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

• 가능한 경우 연결 문자열을 장기간 저장하기보다는 필요할 때 조회하세요.

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

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

토큰 및 비밀 저장

• 토큰이나 비밀 정보를 소스 제어에 커밋하지 마세요.

• 액세스 토큰, 새로 고침 토큰 또는 클라이언트 비밀을 기록하지 마십시오. 애플리케이션이 디버깅을 위해 Atlas Administration API 요청을 기록하는 경우 Authorization 헤더를 수정하십시오.

• secrets manager의 비밀에 대한 액세스 권한을 해당 비밀이 필요한 서비스로만 제한하세요.

• client_secret을(를) 주기적으로, 그리고 침해가 의심되는 경우 즉시 교체하세요. OAuth 애플리케이션과 관련된 비밀을 교체하려면 MongoDB에 문의하세요.

청구 취소 트리거

다음 조치 중 하나를 통해 취소할 수 있습니다.

• Atlas UI(User Settings > Connected Apps)에서 사용자가 액세스 권한을 취소 합니다.

• Organization Owner가 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을(를) 반환하므로, 성공 응답은 토큰이 존재했다는 증거가 아니라 더 이상 사용할 수 없다는 확인으로 간주해야 합니다.

컨트롤 플레인 효과

취소 조치가 얼마나 빨리 적용되는지는 액세스를 취소하는 주체에 따라 다라집니다.

• Organization Owner가 타사 앱 연결을 제한하는 경우: 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 파트너 팀에 문의하세요.