Microsoft.Identity.Web와 클라이언트 시크릿 사용

클라이언트 암호는 애플리케이션이 Microsoft ID 플랫폼 토큰을 요청할 때 해당 ID를 증명하는 데 사용하는 문자열 값입니다. Microsoft. Identity.Web은 기밀 클라이언트 애플리케이션에 대한 여러 자격 증명 유형 중 하나로 클라이언트 비밀을 지원합니다.

자격 증명 유형 선택

기밀 클라이언트 애플리케이션은 Microsoft ID 플랫폼 인증하기 위한 자격 증명이 필요합니다. Microsoft. Identity.Web은 ClientCredentials 구성 섹션을 통해 다음 자격 증명 형식을 지원합니다.

클라이언트 비밀은 Microsoft Entra ID 앱에 등록된 간단한 문자열입니다. 가장 쉽게 설정할 수 있는 자격 증명 유형이지만 다음과 같은 중요한 보안 제한 사항도 있습니다.

• 소스 코드, 로그 또는 구성 파일에서 실수로 노출될 수 있습니다.
• 만료 날짜가 있으며 수동으로 회전해야 합니다.
• 그들은 비밀을 아는 것 외에 발신자 신원의 암호화된 증거를 제공하지 않습니다.

appsettings.json 클라이언트 암호 구성

클라이언트 암호를 구성하려면 ClientCredentials 파일의 AzureAd 섹션에 appsettings.json 배열을 추가하십시오.

{
  "AzureAd": {
    "Instance": "https://login.microsoftonline.com/",
    "TenantId": "YOUR_TENANT_ID",
    "ClientId": "YOUR_CLIENT_ID",
    "ClientCredentials": [
      {
        "SourceType": "ClientSecret",
        "ClientSecret": "YOUR_SECRET_VALUE"
      }
    ]
  }
}

배열은 ClientCredentials 여러 항목을 지원합니다. Microsoft. Identity.Web은 각 자격 증명이 성공할 때까지 순서대로 시도하며 이는 비밀 회전 시나리오에 유용합니다.

개발을 위한 비밀 저장

이 섹션에서는 로컬 개발 중에 소스 코드에서 비밀 값을 유지하는 방법을 설명합니다.

.NET 사용자 비밀

로컬 개발 중에 비밀을 저장하는 데 권장되는 방법은 Secret Manager 도구입니다. 사용자 비밀은 프로젝트 트리 외부에 중요한 데이터를 저장하므로 소스 제어에 실수로 커밋되지 않습니다.

1. 프로젝트의 사용자 시크릿을 초기화합니다.

   dotnet user-secrets init
   

2. 클라이언트 비밀 값을 설정합니다.

   dotnet user-secrets set "AzureAd:ClientCredentials:0:ClientSecret" "your-secret-value"
   

3. 비밀이 저장되었는지 확인합니다.

   dotnet user-secrets list
   

사용자 비밀은 Development 환경에서 WebApplication.CreateBuilder() 또는 Host.CreateDefaultBuilder()을(를) 사용할 때 자동으로 로드됩니다.

appsettings.json 실제 비밀 값이 없는 구조를 포함해야 합니다.

{
  "AzureAd": {
    "Instance": "https://login.microsoftonline.com/",
    "TenantId": "YOUR_TENANT_ID",
    "ClientId": "YOUR_CLIENT_ID",
    "ClientCredentials": [
      {
        "SourceType": "ClientSecret"
      }
    ]
  }
}

환경 변수

환경 변수를 사용하여 클라이언트 암호를 제공할 수도 있습니다. .NET 구성은 __(이중 밑줄) 구분 기호를 사용하는 환경 변수를 구성 계층 구조에 자동으로 매핑합니다. 셸에 대한 변수를 설정합니다.

$env:AzureAd__ClientCredentials__0__ClientSecret = "your-secret-value"

export AzureAd__ClientCredentials__0__ClientSecret="your-secret-value"

환경 변수가 값 appsettings.json보다 우선하므로 구성 파일의 비밀 값을 비우거나 생략할 수 있습니다.

더 높은 환경에 대한 비밀 저장

스테이징, QA 또는 공유 환경의 경우 Azure Key Vault 구성 원본으로 사용합니다. 이 방법은 감사, 액세스 정책 및 자동 회전 기능을 제공하면서 구성 파일 및 환경 변수에서 비밀을 유지합니다.

구성 원본으로 Azure Key Vault 추가

1. 필요한 NuGet 패키지를 설치합니다.

   dotnet add package Azure.Extensions.AspNetCore.Configuration.Secrets
   

2. 구성 경로에 매핑되는 이름으로 Azure Key Vault 클라이언트 비밀을 저장합니다. 구분 기호로 (이중 대시)를 사용합니다 -- .

   az keyvault secret set \
     --vault-name "your-keyvault-name" \
     --name "AzureAd--ClientCredentials--0--ClientSecret" \
     --value "your-secret-value"
   

3. Program.cs 구성 원본으로 Key Vault 추가합니다. 다음 코드는 표준 구성 API를 통해 해당 비밀을 사용할 수 있도록 Key Vault 등록합니다.

   var builder = WebApplication.CreateBuilder(args);
   
   builder.Configuration.AddAzureKeyVault(
       new Uri("https://your-keyvault-name.vault.azure.net/"),
       new DefaultAzureCredential());
   

Key Vault 비밀 이름 AzureAd--ClientCredentials--0--ClientSecretAzureAd:ClientCredentials:0:ClientSecret 구성 경로에 자동으로 매핑됩니다.

Azure 포털에서 클라이언트 암호 만들기

Microsoft Entra ID 애플리케이션에 대한 클라이언트 암호를 등록하려면 다음 단계를 수행합니다.

1. Microsoft Entra 관리 센터 로그인합니다.
2. Identity>Applications>앱 등록로 이동합니다.
3. 목록에서 애플리케이션을 선택합니다.
4. 왼쪽 메뉴에서 인증서 및 비밀을 선택합니다.
5. 클라이언트 비밀 탭을 선택합니다.
6. 새 클라이언트 암호를 선택합니다.
7. 클라이언트 비밀 추가 창에서 다음을 수행합니다.
   • 비밀에 대한 설명을 입력합니다(예: "개발 비밀").
   • 만료 기간을 선택합니다. 사용 가능한 옵션에는 180일, 365일, 730일 또는 사용자 지정 날짜가 포함됩니다.
   • 추가를 선택합니다.
8. 비밀 값을 즉시 복사합니다. 값은 한 번만 표시되며 페이지에서 벗어나면 검색할 수 없습니다.

비밀 만료 및 회전 관리

클라이언트 비밀은 최대 수명을 가지며 생성 중에 지정된 날짜에 만료됩니다. 애플리케이션 중단을 방지하기 위해 비밀 회전을 계획합니다.

만료 관리

• 앱 등록의 인증서 및 비밀 페이지에서 만료 열을 확인합니다.
• 자격 증명이 만료되기 전에 경고를 수신하도록 Microsoft Entra 권장 사항을 설정합니다.

회전 전략

배열을 ClientCredentials 사용하여 가동 중지 시간 0 회전을 지원합니다.

1. Azure 포털에서 새 클라이언트 비밀을 만듭니다.

2. 배열의 추가 항목으로 새 비밀을 추가합니다 ClientCredentials . 새 비밀을 먼저 배치하여 이전 비밀 앞에 시도합니다.

   {
     "AzureAd": {
       "ClientCredentials": [
         {
           "SourceType": "ClientSecret",
           "ClientSecret": "[NEW_SECRET_REFERENCE]"
         },
         {
           "SourceType": "ClientSecret",
           "ClientSecret": "[OLD_SECRET_REFERENCE]"
         }
       ]
     }
   }
   

3. 업데이트된 구성을 배포합니다. Microsoft. Identity.Web은 첫 번째 자격 증명을 시도하고 첫 번째 자격 증명이 실패하면 두 번째 자격 증명으로 돌아갑니다.

4. 새 비밀이 작동하는지 확인한 후 구성과 Azure 포털 모두에서 이전 비밀을 제거합니다.

프로덕션 자격 증명으로 마이그레이션

프로덕션 환경에 배포하기 전에 클라이언트 비밀에서 보다 안전한 자격 증명 유형으로 마이그레이션합니다.

인증서 기반 인증

인증서는 암호화 ID 증명을 제공하며 프로덕션에 권장되는 자격 증명 유형입니다. 다음 구성은 Key Vault 인증서를 검색합니다.

{
  "AzureAd": {
    "ClientCredentials": [
      {
        "SourceType": "KeyVault",
        "KeyVaultUrl": "https://your-keyvault-name.vault.azure.net",
        "KeyVaultCertificateName": "your-certificate-name"
      }
    ]
  }
}

자세한 단계는 Microsoft.Identity.Web과 함께 인증서 사용하기를 참조하세요.

관리 ID(인증서 없는)

Azure 호스트되는 애플리케이션의 경우 관리 ID는 자격 증명을 완전히 관리할 필요가 없습니다. 다음 구성에서는 사용자 할당 관리 ID를 사용합니다.

{
  "AzureAd": {
    "ClientCredentials": [
      {
        "SourceType": "SignedAssertionFromManagedIdentity",
        "ManagedIdentityClientId": "YOUR_MANAGED_IDENTITY_CLIENT_ID"
      }
    ]
  }
}

자세한 단계는 Microsoft.Identity.Web의 Certificateless 인증을 참조하십시오.

마이그레이션 검사 목록

• [ ] 새 자격 증명(인증서 또는 관리 ID)을 생성하거나 프로비전합니다.
• [ ] 새 자격 증명 유형을 사용하도록 애플리케이션 구성을 업데이트합니다.
• [ ] 스테이징 환경에서 새 자격 증명을 테스트합니다.
• [ ] 프로덕션에 배포합니다.
• [ ] Azure 포털에서 이전 클라이언트 비밀을 제거합니다.
• [ ] 이전 비밀 없이 애플리케이션이 올바르게 작동하는지 확인합니다.

일반적인 보안 실수 방지

클라이언트 비밀로 작업할 때 다음과 같은 안티패턴 및 권장 대안을 검토합니다.

일반적인 오류 해결 방법

이 섹션에서는 클라이언트 비밀을 구성할 때 발생할 수 있는 자주 발생하는 오류에 대해 설명합니다.

잘못된 클라이언트 암호

오류:AADSTS7000215: Invalid client secret provided.

가능한 원인:

• 비밀 값이 잘못 복사되었습니다. 비밀 값은 복사/붙여넣기 작업 중에 잘리는 특수 문자를 포함할 수 있습니다.
• 다른 앱 등록을 위해 비밀이 ClientId에 설정된 것과 다르게 만들어졌습니다.
• 구성 경로가 올바르지 않으며 애플리케이션에서 비밀 값을 읽지 않습니다.

해결 방법:

1. Azure 포털에서 새 클라이언트 비밀을 만들고 전체 값을 신중하게 복사합니다.

2. 구성에서 ClientId 및 TenantId이 비밀이 생성된 앱 등록과 일치하는지 확인합니다.

3. 중단점 또는 로그 문을 추가하여 구성이 올바르게 로드되었는지 확인합니다.

   // For debugging only — remove before committing
   var config = builder.Configuration.GetSection("AzureAd:ClientCredentials:0:ClientSecret").Value;
   Console.WriteLine($"Secret loaded: {!string.IsNullOrEmpty(config)}");
   

만료된 클라이언트 암호

오류:AADSTS7000222: The provided client secret keys for app '{app-id}' are expired.

해결 방법:

1. Microsoft Entra 관리 센터 앱 등록으로 이동합니다.
2. 인증서 및 비밀>에서 만료 날짜를 확인합니다.
3. 새 비밀을 만들고 애플리케이션 구성을 업데이트합니다.
4. 포털에서 만료된 비밀을 삭제합니다.

구성에서 비밀을 찾을 수 없음

증상: 비밀 값이 문제를 일으켜 애플리케이션이 NullReferenceException 오류를 발생시키거나 null 인증에 실패합니다.

가능한 원인:

• 사용자 비밀은 프로젝트에 대해 초기화되지 않습니다.
• 환경 변수 이름이 예상 구성 경로와 일치하지 않습니다.
• Key Vault 구성 원본으로 구성되지 않습니다.
• 애플리케이션은 사용자 비밀이 로드되지 않는 비개발 환경에서 실행됩니다.

해결 방법:

1. UserSecretsId 태그를 .csproj 파일에서 확인하여 사용자 비밀이 초기화되었는지 확인합니다.
2. 를 실행 dotnet user-secrets list하여 비밀이 설정되었는지 확인합니다.
3. 구성 경로가 정확히 일치하는지 확인합니다 AzureAd:ClientCredentials:0:ClientSecret.
4. 개발 환경 외부에서 실행되는 경우 적절한 구성 원본(환경 변수 또는 Key Vault)을 사용할 수 있는지 확인합니다.

관련 콘텐츠

• Microsoft.Identity.Web을 사용한 인증서
• 인증서 없는 인증
• 토큰 캐시 개요
• ASP.NET Core 개발 시 앱 비밀의 안전한 저장
• ASP.NET Core의 Azure Key Vault 구성 공급자