Share via

자습서: Azure Key Vault를 사용하여 Azure Cosmos DB 자격 증명 저장 및 사용

  • 아티클

적용 대상: NoSQL MongoDB Cassandra Gremlin 테이블

Important

Azure Cosmos DB에 액세스하는 데 권장되는 방법은 시스템이 할당한 관리 ID를 사용하는 것입니다. 관리 ID 솔루션과 인증서 기반 솔루션이 사용자의 요구를 충족하지 않는 경우, 이 문서의 Azure 키 자격 증명 모음 솔루션을 사용하세요.

Azure Cosmos DB를 데이터베이스로 사용하는 경우 SDK, API 엔드포인트 및 기본 또는 보조 키를 사용하여 데이터베이스, 컨테이너 및 항목에 연결합니다.

엔드포인트 URI 및 중요한 읽기-쓰기 키는 애플리케이션 코드 또는 구성 파일 내에 직접 저장하지 않는 것이 좋습니다. 이 데이터는 호스트 내의 환경 변수에서 읽는 것이 좋습니다. Azure App Service에서 앱 설정을 사용하면 개발자가 안전하지 않은 일반 텍스트 방식으로 이러한 자격 증명을 저장할 필요 없이 Azure Cosmos DB 계정에 런타임 자격 증명을 삽입할 수 있습니다.

Azure Key Vault는 자격 증명에 대한 Azure App Service 관리형 액세스 권한과 같은 서비스를 제공하면서 이러한 자격 증명을 안전하게 저장할 수 있도록 하여 이 모범 사례를 더 반복합니다. Azure App Service는 Azure Key Vault에서 자격 증명을 안전하게 읽고 해당 자격 증명을 실행 중인 애플리케이션에 삽입합니다.

이 모범 사례를 통해 개발자는 개발 중에 Azure Cosmos DB 에뮬레이터 또는 무료로 Azure Cosmos DB 사용해 보기와 같은 도구에 대한 자격 증명을 저장할 수 있습니다. 그런 다음, 운영 팀은 런타임에 올바른 프로덕션 설정이 삽입되도록 할 수 있습니다.

이 자습서에서는 다음을 하는 방법을 알아볼 수 있습니다.

  • Azure Key Vault 인스턴스 만들기
  • 키 자격 증명 모음에 비밀로 Azure Cosmos DB 자격 증명 추가
  • Azure App Service 리소스 만들기, 등록 및 "키 읽기" 권한 부여
  • App Service 리소스에 키 자격 증명 모음 비밀 삽입

참고 항목

이 자습서 및 샘플 애플리케이션은 Azure Cosmos DB for NoSQL 계정을 사용합니다. 다른 API를 사용하여 동일한 여러 단계를 수행할 수 있습니다.

필수 조건

시작하기 전에: Azure Cosmos DB 자격 증명 가져오기

시작하기 전에 기존 계정의 자격 증명을 가져옵니다.

  1. 기존 Azure Cosmos DB for NoSQL 계정의 Azure Portal 페이지로 이동합니다.

  2. Azure Cosmos DB for NoSQL 계정 페이지에서 키 탐색 메뉴 옵션을 선택합니다.

    Screenshot of an Azure Cosmos DB SQL API account page. The Keys option is highlighted in the navigation menu.

  3. URI 및 기본 키 필드의 값을 기록합니다. 이러한 값은 이 자습서의 뒷부분에서 사용합니다.

    Screenshot of Keys page with various credentials for an Azure Cosmos DB SQL API account.

Azure Key Vault 리소스 만들기

먼저 NoSQL 자격 증명에 대한 API를 저장할 새 키 자격 증명 모음을 만듭니다.

  1. Azure Portal에 로그인합니다.

  2. 리소스 만들기 > 보안 > Key Vault를 선택합니다.

  3. 키 자격 증명 모음 만들기 페이지에서 다음 정보를 입력합니다.

    설정 설명
    구독 이 Azure Cosmos 계정에 사용하려는 Azure 구독을 선택합니다.
    리소스 그룹 리소스 그룹을 선택하거나 새로 만들기를 선택한 후, 새 리소스 그룹에 고유한 이름을 입력합니다.
    Key Vault 이름 키 자격 증명 모음의 전역적으로 고유한 이름을 입력합니다.
    지역 Azure Cosmos DB 계정을 호스트할 지리적 위치를 선택합니다. 데이터에 가장 빨리 액세스할 수 있도록 사용자와 가장 가까운 위치를 사용합니다.
    가격 책정 계층 표준을 선택합니다.

  4. 나머지 설정은 기본값으로 둡니다.

  5. 검토 + 만들기를 선택합니다.

  6. 제공한 설정을 검토한 다음, 만들기를 선택합니다. 계정을 만드는 데 몇 분이 걸립니다. 포털 페이지에 배포가 완료됨이 표시될 때까지 기다린 다음, 계속 진행합니다.

Key Vault에 Azure Cosmos DB 액세스 키 추가

이제 Azure Cosmos DB 자격 증명을 키 자격 증명 모음에 비밀로 저장합니다.

  1. 리소스로 이동을 선택하여 Azure Key Vault 리소스 페이지로 이동합니다.

  2. Azure Key Vault 리소스 페이지에서 비밀 탐색 메뉴 옵션을 선택합니다.

  3. 메뉴에서 생성/가져오기를 선택합니다.

    Screenshot of the Generate/Import option in a key vault menu.

  4. 비밀 만들기 페이지에서 다음 정보를 입력합니다.

    설정 설명
    업로드 옵션 수동
    이름 cosmos-endpoint
    비밀 값 이 자습서의 앞부분에서 복사한 URI를 입력합니다.

    Screenshot of the Create a secret dialog in the Azure portal with details for an URI secret.

  5. 만들기를 선택하여 새 cosmos-endpoint 비밀을 만듭니다.

  6. 메뉴에서 생성/가져오기를 다시 선택합니다. 비밀 만들기 페이지에서 다음 정보를 입력합니다.

    설정 설명
    업로드 옵션 수동
    이름 cosmos-readwrite-key
    비밀 값 이 자습서의 앞부분에서 복사한 PRIMARY KEY를 입력합니다.

    Screenshot of the Create a secret dialog in the Azure portal with details for a PRIMARY KEY secret.

  7. 만들기를 선택하여 새 cosmos-readwrite-key 비밀을 만듭니다.

  8. 비밀이 만들어지면 비밀 페이지 내 비밀 목록에서 해당 비밀을 확인합니다.

    Screenshot of the list of secrets for a key vault.

  9. 각 키를 선택하고 최신 버전을 선택한 다음, 비밀 식별자를 복사합니다. 이 자습서의 뒷부분에서 cosmos-endpoint 및 cosmos-readwrite-key 비밀에 이 식별자를 사용합니다.

    팁

    비밀 식별자는 https://<key-vault-name>.vault.azure.net/secrets/<secret-name>/<version-id> 형식입니다. 예를 들어 키 자격 증명 모음의 이름이 msdocs-key-vault인 경우 키 이름은 cosmos-readwrite-key이고, 83b995e363d947999ac6cf487ae0e12e인 경우 버전입니다. 그러면 비밀 식별자는 https://msdocs-key-vault.vault.azure.net/secrets/cosmos-readwrite-key/83b995e363d947999ac6cf487ae0e12e가 됩니다.

    Screenshot of a secret identifier for a key vault secret named cosmos-readwrite-key.

Azure Key Vault를 사용하여 Azure Web App 만들기 및 등록

이 섹션에서는 Azure Key Vault를 사용하여 새 Azure Web App을 만들고, 샘플 애플리케이션을 배포한 다음, 웹앱의 관리 ID를 등록합니다.

  1. cosmos-db-nosql-dotnet-sample-web-environment-variables 템플릿을 사용하여 새 GitHub 리포지토리를 만듭니다.

  2. Azure Portal에서 리소스 만들기 > 웹 > 웹앱을 선택합니다.

  3. 웹앱 만들기 페이지의 기본 사항 탭에서 다음 정보를 입력합니다.

    설정 설명
    구독 이 Azure Cosmos 계정에 사용하려는 Azure 구독을 선택합니다.
    리소스 그룹 리소스 그룹을 선택하거나 새로 만들기를 선택한 후, 새 리소스 그룹에 고유한 이름을 입력합니다.
    이름 웹앱의 전역적으로 고유한 이름을 입력합니다.
    게시 코드를 선택합니다.
    런타임 스택 .NET 6(LTS)를 선택합니다.
    운영 체제 Windows를 선택합니다.
    지역 Azure Cosmos DB 계정을 호스트할 지리적 위치를 선택합니다. 데이터에 가장 빨리 액세스할 수 있도록 사용자와 가장 가까운 위치를 사용합니다.

  4. 나머지 설정은 기본값으로 둡니다.

  5. 다음: 배포를 선택합니다.

  6. 배포 탭에서 다음 정보를 입력합니다.

    설정 설명
    지속적인 배포 사용을 선택합니다.
    GitHub 계정 권한 부여를 선택합니다. GitHub 계정 권한 부여 프롬프트에 따라 새로 만든 GitHub 리포지토리를 읽을 수 있는 권한을 Azure에 부여합니다.
    조직 새 GitHub 리포지토리의 조직을 선택합니다.
    리포지토리 새 GitHub 리포지토리의 이름을 선택합니다.
    Branch 기본을 선택합니다.

  7. 검토 + 만들기를 선택합니다.

  8. 제공한 설정을 검토한 다음, 만들기를 선택합니다. 계정을 만드는 데 몇 분이 걸립니다. 포털 페이지에 배포가 완료됨이 표시될 때까지 기다린 다음, 계속 진행합니다.

  9. 웹 애플리케이션이 웹앱에 처음 배포될 때까지 몇 분 정도 더 기다려야 할 수 있습니다. Azure Web App 리소스 페이지에서 찾아보기를 선택하여 앱의 기본 상태를 확인합니다.

    Screenshot of the web application in it's default state without credentials.

  10. ID 탐색 메뉴 옵션을 선택합니다.

  11. ID 페이지에서 시스템이 할당한 관리 ID에 대해 켜기를 선택한 다음, 저장을 선택합니다.

    Screenshot of system-assigned managed identity being enabled from the Identity page.

Azure Web App 앱 설정으로 Azure Key Vault 비밀 삽입

마지막으로 키 자격 증명 모음에 저장된 비밀을 웹앱 내 앱 설정에 삽입합니다. 그러면 앱 설정이 자격 증명을 일반 텍스트로 저장하지 않고 런타임에 애플리케이션에 자격 증명을 삽입합니다.

  1. Azure Portal에서 키 자격 증명 모음 페이지로 돌아갑니다. 탐색 메뉴에서 액세스 정책을 선택합니다.

  2. 액세스 정책 페이지의 메뉴에서 만들기를 선택합니다.

    Screenshot of the Create option in the Access policies menu.

  3. 액세스 정책 만들기 페이지의 권한 탭에서 비밀 권한 섹션의 가져오기 옵션을 선택합니다. 다음을 선택합니다.

    Screenshot of the Get permission enabled for Secret permissions.

  4. 보안 주체 탭에서 이 자습서의 앞부분에서 만든 웹앱의 이름을 선택합니다. 새로 만들기를 선택합니다.

    Screenshot of a web app managed identity assigned to a permission.

    참고 항목

    이 예제 스크린샷에서 웹앱의 이름은 msdocs-dotnet-web입니다.

  5. 다음을 다시 선택하여 애플리케이션 탭을 건너뜁니다. 검토 + 만들기 탭에서 제공한 설정을 검토한 다음 만들기를 선택합니다.

  6. Azure Portal의 웹앱 페이지로 돌아갑니다. 탐색 메뉴에서 구성을 선택합니다.

  7. 구성 페이지에서 새 애플리케이션 설정을 선택합니다. 애플리케이션 설정 추가/편집 대화 상자에서 다음 정보를 입력합니다.

    설정 Description
    이름 CREDENTIALS__ENDPOINT
    Key 이 자습서의 앞부분에서 만든 키 자격 증명 모음에서 cosmos-endpoint 비밀의 비밀 식별자를 가져옵니다. 식별자를 @Microsoft.KeyVault(SecretUri=<secret-identifier>) 형식으로 입력합니다.

    팁

    환경 변수에 단일 밑줄 대신 이중 밑줄(__) 값이 있는지 확인합니다. 이중 밑줄은 .NET이 모든 플랫폼에서 지원하는 키 구분 기호입니다. 자세한 내용은 환경 변수 구성을 참조하세요.

    참고 항목

    예를 들어 비밀 식별자가 https://msdocs-key-vault.vault.azure.net/secrets/cosmos-endpoint/69621c59ef5b4b7294b5def118921b07일 경우 참조는 @Microsoft.KeyVault(SecretUri=https://msdocs-key-vault.vault.azure.net/secrets/cosmos-endpoint/69621c59ef5b4b7294b5def118921b07)가 됩니다.

    Screenshot of the Add/Edit application setting dialog with a new app setting referencing a key vault secret.

  8. 확인을 선택하여 새 앱 설정을 유지합니다.

  9. 새 애플리케이션 설정을 다시 선택합니다. 애플리케이션 설정 추가/편집 대화 상자에서 다음 정보를 입력한 후 확인을 선택합니다.

    설정 Description
    이름 CREDENTIALS__KEY
    Key 이 자습서의 앞부분에서 만든 키 자격 증명 모음에서 cosmos-readwrite-key 비밀의 비밀 식별자를 가져옵니다. 식별자를 @Microsoft.KeyVault(SecretUri=<secret-identifier>) 형식으로 입력합니다.

  10. 구성 페이지로 돌아가서 저장을 선택하여 웹앱의 앱 설정을 업데이트합니다.

    Screenshot of the Save option in the Configuration page's menu.

  11. 웹앱이 새 앱 설정으로 다시 시작될 때까지 몇 분 정도 기다립니다. 이때 새 앱 설정은 키 자격 증명 모음 참조임을 나타내야 합니다.

    Screenshot of the Key vault Reference designation on two app settings in a web app.

  12. 탐색 메뉴에서 개요를 선택합니다. 찾아보기를 선택하여 채워진 자격 증명이 있는 앱을 확인합니다.

    Screenshot of the web application with valid Azure Cosmos DB for NoSQL account credentials.

다음 단계