Microsoft.Identity.Web에서 인증서를 사용합니다.

Microsoft. Identity.Web은 기밀 클라이언트 애플리케이션에 대한 클라이언트 비밀에 대한 보안 대안으로 인증서 기반 인증을 지원합니다. 인증서는 비대칭 암호화를 사용하므로 프라이빗 키 소유자만 인증할 수 있습니다.

이 문서에서는 다양한 원본에서 인증서 자격 증명을 구성하고, 앱에 등록하고, 프로덕션 환경에서 관리합니다.

인증서를 사용하는 이유

작동 방식

1. 프라이빗 키를 사용하여 X.509 인증서를 생성하거나 가져옵니다.
2. 인증서의 공개 키(또는 지문)를 Microsoft Entra 앱 등록에 등록합니다.
3. 런타임에 Microsoft. Identity.Web은 구성된 원본에서 인증서(프라이빗 키 포함)를 로드합니다.
4. 라이브러리는 프라이빗 키를 사용하여 Microsoft Entra ID에 보내는 클라이언트 어설션에 서명하여 토큰을 가져옵니다.

인증서 원본

Microsoft. Identity.Web은 여러 원본에서 인증서 로드를 지원합니다.

ClientCertificates 배열에서 인증서 자격 증명을 구성하려면 AzureAd (또는 AzureAdB2C) 구성 섹션을 사용하십시오. 회전 시나리오에 대해 여러 인증서를 지정할 수 있습니다. Microsoft. Identity.Web은 찾은 첫 번째 유효한 인증서를 사용합니다.

Azure Key Vault(권장)

Azure Key Vault 프로덕션의 인증서에 권장되는 소스입니다. 중앙 집중식 관리, 액세스 제어, 감사 및 자동 회전 기능을 제공합니다.

Configuration

인증서 구성을 appsettings.json에 추가합니다.

{
  "AzureAd": {
    "Instance": "https://login.microsoftonline.com/",
    "TenantId": "your-tenant-id",
    "ClientId": "your-client-id",

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

Key Vault 액세스 정책 설정

애플리케이션의 ID에는 Key Vault 인증서를 읽을 수 있는 권한이 있어야 합니다. 이를 부여하는 방법은 자격 증명 모음 액세스 정책 모델을 사용하는지 또는 Azure 역할 기반 액세스 제어(RBAC)을 사용하는지에 따라 달라집니다.

옵션 1: 금고 액세스 정책

az keyvault set-policy \
  --name your-keyvault-name \
  --object-id <app-or-managed-identity-object-id> \
  --certificate-permissions get list \
  --secret-permissions get

옵션 2: AZURE RBAC

Key Vault 인증서 사용자 역할을 애플리케이션의 ID에 할당합니다.

az role assignment create \
  --role "Key Vault Certificate User" \
  --assignee <app-or-managed-identity-object-id> \
  --scope /subscriptions/<sub-id>/resourceGroups/<rg>/providers/Microsoft.KeyVault/vaults/<vault-name>

관리 ID를 사용하여 Key Vault 액세스

앱이 Azure(App Service, Azure Functions, Azure Kubernetes Service, VM)에서 실행되면 관리 ID를 사용하여 Key Vault 인증합니다. 이렇게 하면 금고 자체에 접근하기 위해 자격 증명이 필요하지 않습니다.

시스템 할당 관리 ID

앱에 시스템 할당 관리 ID를 사용하도록 설정한 경우 Microsoft. Identity.Web은 자동으로 DefaultAzureCredential 사용하여 Key Vault 인증합니다. 항목 이외의 ClientCertificates 추가 구성은 필요하지 않습니다.

{
  "AzureAd": {
    "Instance": "https://login.microsoftonline.com/",
    "TenantId": "your-tenant-id",
    "ClientId": "your-client-id",

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

사용자가 할당한 관리 ID

사용자가 할당한 관리 ID의 경우 Key Vault 인증서 설명자에 ManagedIdentityClientId 지정합니다.

{
  "AzureAd": {
    "Instance": "https://login.microsoftonline.com/",
    "TenantId": "your-tenant-id",
    "ClientId": "your-client-id",

    "ClientCertificates": [
      {
        "SourceType": "KeyVault",
        "KeyVaultUrl": "https://your-keyvault-name.vault.azure.net",
        "KeyVaultCertificateName": "your-certificate-name",
        "ManagedIdentityClientId": "user-assigned-managed-identity-client-id"
      }
    ]
  }
}

인증서 저장소에서(Windows 전용)

Windows Windows 인증서 저장소에서 인증서를 로드할 수 있습니다. 이는 온-프레미스 또는 IIS 호스팅 배포에 일반적입니다.

지문 인식으로

SHA-1 지문으로 인증서를 식별하는 데 사용합니다 StoreWithThumbprint .

{
  "AzureAd": {
    "Instance": "https://login.microsoftonline.com/",
    "TenantId": "your-tenant-id",
    "ClientId": "your-client-id",

    "ClientCertificates": [
      {
        "SourceType": "StoreWithThumbprint",
        "CertificateStorePath": "CurrentUser/My",
        "CertificateThumbprint": "A1B2C3D4E5F6A1B2C3D4E5F6A1B2C3D4E5F6A1B2"
      }
    ]
  }
}

식별된 이름별

StoreWithDistinguishedName를 사용하여 주체 이름으로 인증서를 식별하십시오.

{
  "AzureAd": {
    "Instance": "https://login.microsoftonline.com/",
    "TenantId": "your-tenant-id",
    "ClientId": "your-client-id",

    "ClientCertificates": [
      {
        "SourceType": "StoreWithDistinguishedName",
        "CertificateStorePath": "CurrentUser/My",
        "CertificateDistinguishedName": "CN=MyAppCertificate"
      }
    ]
  }
}

인증서 저장소 위치

다음 표에는 일반적인 인증서 저장소 경로 및 액세스하는 데 필요한 권한이 나와 있습니다.

파일 경로에서

디스크의 (PKCS#12) 파일에서 .pfx 직접 인증서를 로드할 수 있습니다.

Configuration

인증서 파일 경로와 암호를 appsettings.json에 추가하십시오.

{
  "AzureAd": {
    "Instance": "https://login.microsoftonline.com/",
    "TenantId": "your-tenant-id",
    "ClientId": "your-client-id",

    "ClientCertificates": [
      {
        "SourceType": "Path",
        "CertificateDiskPath": "/path/to/certificate.pfx",
        "CertificatePassword": "your-certificate-password"
      }
    ]
  }
}

dotnet user-secrets set "AzureAd:ClientCertificates:0:CertificatePassword" "your-password"

export AzureAd__ClientCertificates__0__CertificatePassword="your-password"

Base64로 인코딩된 값에서

인증서를 Base64로 인코딩된 문자열로 제공할 수 있습니다. 이 방법은 환경 변수, Kubernetes 비밀 또는 CI/CD 파이프라인 변수를 통해 인증서를 삽입할 때 유용합니다.

Configuration

Base64로 인코딩된 인증서 값을 다음 사항에 추가합니다 appsettings.json.

{
  "AzureAd": {
    "Instance": "https://login.microsoftonline.com/",
    "TenantId": "your-tenant-id",
    "ClientId": "your-client-id",

    "ClientCertificates": [
      {
        "SourceType": "Base64Encoded",
        "Base64EncodedValue": "MIIKcQIBAzCCCi0GCSqGSIb3DQEHAaCCCh4Egg..."
      }
    ]
  }
}

Base64 값 생성

.pfx 파일을 Base64 문자열로 변환합니다.

PowerShell:

$certBytes = [System.IO.File]::ReadAllBytes("path/to/certificate.pfx")
$base64 = [System.Convert]::ToBase64String($certBytes)
$base64 | Set-Clipboard  # Copies to clipboard

Bash:

base64 -w 0 path/to/certificate.pfx

Kubernetes 비밀과 함께 사용

Base64로 인코딩된 인증서를 Kubernetes 비밀에 저장하고 환경 변수에 매핑합니다.

apiVersion: v1
kind: Secret
metadata:
  name: app-cert-secret
type: Opaque
data:
  AzureAd__ClientCertificates__0__Base64EncodedValue: <base64-encoded-pfx>

배포에서 해당 시크릿을 참조하세요:

env:
  - name: AzureAd__ClientCertificates__0__SourceType
    value: "Base64Encoded"
  - name: AzureAd__ClientCertificates__0__Base64EncodedValue
    valueFrom:
      secretKeyRef:
        name: app-cert-secret
        key: AzureAd__ClientCertificates__0__Base64EncodedValue

CI/CD 파이프라인에서 사용

Azure DevOps 또는 GitHub Actions Base64로 인코딩된 인증서를 비밀 변수로 저장한 다음 런타임에 환경 변수로 설정합니다.

GitHub Actions 예제:

env:
  AzureAd__ClientCertificates__0__SourceType: "Base64Encoded"
  AzureAd__ClientCertificates__0__Base64EncodedValue: ${{ secrets.APP_CERTIFICATE_BASE64 }}

Azure DevOps 예제:

variables:
  AzureAd__ClientCertificates__0__SourceType: "Base64Encoded"
  AzureAd__ClientCertificates__0__Base64EncodedValue: $(AppCertificateBase64)

C# 코드에서 인증서 구성

JSON 구성 외에도 CredentialDescriptionMicrosoft.Identity.Abstractions 클래스를 사용하여 프로그래밍 방식으로 인증서 자격 증명을 구성할 수 있습니다.

도우미 메서드

클래스는 CredentialDescription 각 인증서 원본 유형에 대한 정적 도우미 메서드를 제공합니다.

using Microsoft.Identity.Abstractions;

// From Azure Key Vault
var kvCredential = CredentialDescription.FromKeyVault(
    "https://your-keyvault-name.vault.azure.net",
    "your-certificate-name");

// From certificate store (by thumbprint)
var thumbprintCredential = CredentialDescription.FromCertificateStore(
    "CurrentUser/My",
    thumbprint: "A1B2C3D4E5F6A1B2C3D4E5F6A1B2C3D4E5F6A1B2");

// From certificate store (by distinguished name)
var dnCredential = CredentialDescription.FromCertificateStore(
    "CurrentUser/My",
    distinguishedName: "CN=MyAppCertificate");

// From file path
var pathCredential = CredentialDescription.FromCertificatePath(
    "/path/to/certificate.pfx",
    "your-certificate-password");

// From Base64-encoded string
var base64Credential = CredentialDescription.FromBase64String(
    "MIIKcQIBAzCCCi0GCSqGSIb3DQEHAaCCCh4Egg...");

ASP.NET Core에서 사용

인증을 구성할 때 자격 증명 설명을 직접 전달합니다.

builder.Services.AddAuthentication(OpenIdConnectDefaults.AuthenticationScheme)
    .AddMicrosoftIdentityWebApp(options =>
    {
        options.Instance = "https://login.microsoftonline.com/";
        options.TenantId = "your-tenant-id";
        options.ClientId = "your-client-id";
        options.ClientCredentials = new[]
        {
            CredentialDescription.FromKeyVault(
                "https://your-keyvault-name.vault.azure.net",
                "your-certificate-name")
        };
    });

개발을 위해 자체 서명된 인증서 만들기

로컬 개발 및 테스트의 경우 자체 서명된 인증서를 만들 수 있습니다. 프로덕션 환경에서 자체 서명된 인증서를 사용하지 마세요.

PowerShell 사용(Windows)

다음 명령을 실행하여 자체 서명된 인증서를 만들고, 내보내고, 지문을 표시합니다.

$cert = New-SelfSignedCertificate `
  -Subject "CN=MyDevCertificate" `
  -CertStoreLocation "Cert:\CurrentUser\My" `
  -KeyExportPolicy Exportable `
  -KeySpec Signature `
  -KeyLength 2048 `
  -KeyAlgorithm RSA `
  -HashAlgorithm SHA256 `
  -NotAfter (Get-Date).AddYears(2)

# Export the .pfx file (with private key)
$password = ConvertTo-SecureString -String "YourPassword123!" -Force -AsPlainText
Export-PfxCertificate -Cert $cert -FilePath ".\MyDevCertificate.pfx" -Password $password

# Export the .cer file (public key only — for app registration)
Export-Certificate -Cert $cert -FilePath ".\MyDevCertificate.cer"

# Display the thumbprint
Write-Host "Thumbprint: $($cert.Thumbprint)"

OpenSSL 사용(플랫폼 간)

다음 명령을 실행하여 인증서를 생성하고, 파일로 .pfx 패키지하고, 지문을 표시합니다.

# Generate a self-signed certificate and private key
openssl req -x509 -newkey rsa:2048 \
  -keyout key.pem -out cert.pem \
  -days 730 -nodes \
  -subj "/CN=MyDevCertificate"

# Package into a .pfx file
openssl pkcs12 -export \
  -out MyDevCertificate.pfx \
  -inkey key.pem -in cert.pem \
  -passout pass:YourPassword123!

# Get the thumbprint
openssl x509 -in cert.pem -noout -fingerprint -sha1

.NET CLI 사용

개발 HTTPS 인증서를 파일로 내보냅니다..pfx

dotnet dev-certs https --export-path ./MyDevCertificate.pfx --password YourPassword123!

Microsoft Entra ID 인증서 등록

인증서를 만들거나 가져온 후에는 Microsoft Entra ID 앱 등록에 공개 키를 등록해야 합니다.

Azure 포털 사용

1. Azure 포털로 이동하여 Microsoft Entra ID>앱 등록 이동합니다.
2. 애플리케이션을 선택합니다.
3. 인증서 및 비밀>인증서>인증서 업로드를 선택합니다.
4. .cer 또는 .pem 업로드합니다. 프라이빗 키가 포함된 파일을 업로드 .pfx 하지 마세요.
5. 업로드 후 표시되는 지문 값을 확인합니다. 구성에 필요할 수 있습니다.

Azure CLI 사용

az ad app credential reset \
  --id <application-client-id> \
  --cert @/path/to/certificate.pem \
  --append

플래그는 --append 기존 자격 증명을 제거하지 않고 인증서를 추가합니다.

Microsoft Graph PowerShell 사용

$certData = [System.IO.File]::ReadAllBytes(".\MyDevCertificate.cer")
$base64Cert = [System.Convert]::ToBase64String($certData)

$keyCredential = @{
    type = "AsymmetricX509Cert"
    usage = "Verify"
    key = [System.Convert]::FromBase64String($base64Cert)
    displayName = "MyAppCertificate"
}

Update-MgApplication -ApplicationId <app-object-id> -KeyCredentials @($keyCredential)

인증서 회전

인증서 회전은 만료되는 인증서를 만료되기 전에 새 인증서로 대체하여 중단 없는 서비스를 보장합니다.

전략: 겹치는 인증서

권장되는 방법은 겹치는 유효 기간을 사용합니다.

1. 현재 인증서가 만료되기 전에 새 인증서를 생성합니다(예: 30~60일 전).
2. 기존 인증서와 함께 Microsoft Entra 앱 등록에 새 인증서 등록합니다. Microsoft Entra ID 등록된 인증서로 서명된 토큰을 허용합니다.
3. 애플리케이션의 인증서 원본(Key Vault, 인증서 저장소 등)에 새 인증서를 배포합니다.
4. 새 인증서를 가리키도록 구성을 업데이트합니다(필요한 경우).
5. 모든 인스턴스가 새 인증서를 사용하는지 확인한 후 앱 등록에서 이전 인증서를 제거합니다.

구성의 여러 인증서

Microsoft. Identity.Web은 여러 인증서 지정을 지원합니다. 라이브러리는 순서대로 시도하고 첫 번째 유효한 인증서를 사용합니다.

{
  "AzureAd": {
    "ClientCertificates": [
      {
        "SourceType": "KeyVault",
        "KeyVaultUrl": "https://your-keyvault.vault.azure.net",
        "KeyVaultCertificateName": "new-cert-2026"
      },
      {
        "SourceType": "KeyVault",
        "KeyVaultUrl": "https://your-keyvault.vault.azure.net",
        "KeyVaultCertificateName": "current-cert-2025"
      }
    ]
  }
}

Azure Key Vault 사용한 자동 회전

Azure Key Vault 자동 인증서 갱신을 지원합니다. 자동 회전을 사용하도록 설정하는 경우:

1. Key Vault 만료 전에 새 인증서 버전을 생성합니다.
2. Microsoft. Identity.Web은 최신 버전을 자동으로 선택합니다(다음 인증서 페치).
3. 이전 인증서 버전은 만료될 때까지 유효한 상태로 유지됩니다.

Key Vault 자동 회전을 구성하려면 다음을 수행합니다.

az keyvault certificate set-attributes \
  --vault-name your-keyvault-name \
  --name your-certificate-name \
  --policy @rotation-policy.json

인증서 오류 문제 해결

이 섹션에서는 일반적인 오류 메시지 및 해당 솔루션을 나열합니다.

일반 오류

인증서를 찾을 수 없습니다

오류 메시지:

System.Security.Cryptography.CryptographicException: The certificate cannot be found.

가능한 원인 및 해결 방법:

Key Vault 액세스 거부됨

오류 메시지:

Azure.RequestFailedException: The user, group or application '...' does not have certificates get permission on key vault '...'

솔루션:

• get인증서와 비밀 모두에 대한 액세스 정책이 권한을 부여했는지 확인합니다.
• Azure RBAC를 사용하는 경우 ID에 Key Vault 인증서 사용자 역할이 있는지 확인합니다.
• 관리 ID의 경우 ID가 활성화되어 있고 정책에 올바른 개체 ID가 사용되는지 확인합니다.

인증서 프라이빗 키에 액세스할 수 없음

오류 메시지:

System.Security.Cryptography.CryptographicException: Keyset does not exist.

솔루션:

• Windows/IIS에서 애플리케이션 풀 ID에 프라이빗 키에 대한 read 액세스 권한이 있는지 확인합니다. 인증서 MMC 스냅인을 사용하여 프라이빗 키 관리를 통해 액세스 권한을 부여합니다.
• Linux에서 .pfx 파일에 적절한 파일 권한이 있는지 chmod 600 확인합니다.
• 인증서를 프라이빗 키(Export-PfxCertificate 또는 openssl pkcs12 -export)로 내보낼 수 있는지 확인합니다.

인증서 만료

오류 메시지:

AADSTS700027: Client assertion contains an invalid signature. The key was expired.

솔루션:

• 인증서의 유효 기간을 확인합니다 openssl x509 -in cert.pem -noout -dates.
• 새 인증서를 생성하고 앱 등록과 애플리케이션의 구성을 모두 업데이트합니다.
• 향후 만료 문제를 방지하기 위해 인증서 회전을 구현합니다. 인증서 회전을 참조하세요.

잘못된 인증서 암호

오류 메시지:

System.Security.Cryptography.CryptographicException: The specified network password is not correct.

솔루션:

• CertificatePassword이(가) .pfx 파일을 내보낼 때 사용된 암호와 일치하는지 확인합니다.
• 환경 변수를 사용하는 경우 인코딩 문제(후행 줄 바꿈, 특수 문자)를 검토하세요.
• 알려진 암호를 사용하여 인증서를 다시 내보냅니다.

진단 검사 목록

인증서 인증이 작동하지 않는 경우 다음 검사 목록을 사용합니다.

• [ ] 인증서 유효성 — 인증서의 유효 기간 내에 있나요? NotBefore 및 NotAfter 날짜를 확인하세요.
• [ ] 앱 등록 - 인증서의 공개 키가 올바른 앱 등록에 업로드되었나요?
• [ ] 지문 일치 - 구성의 지문이 앱 등록의 인증서와 일치하나요?
• [ ] 프라이빗 키 액세스 - 애플리케이션 프로세스에서 인증서의 프라이빗 키를 읽을 수 있나요?
• [ ] Key Vault 권한 — Key Vault 원본의 경우 ID에 certificates/get 및 secrets/get 권한이 있나요?
• [ ] 구성 섹션 - 인증서 구성이 올바른 섹션(AzureAd 또는 AzureAdB2C)인가요?
• [ ] NuGet 패키지 — Microsoft.Identity.Web 최신 상태입니까? 이전 버전에서는 특정 인증서 원본 유형에 대한 지원이 부족할 수 있습니다.

로그 기록 활성화

자세한 진단 정보를 얻으려면 MSAL 로깅을 사용하도록 설정합니다.

builder.Services.AddMicrosoftIdentityWebAppAuthentication(builder.Configuration, "AzureAd")
    .EnableTokenAcquisitionToCallDownstreamApi()
    .AddInMemoryTokenCaches();

builder.Logging.AddFilter("Microsoft.Identity", LogLevel.Debug);

인증서 로드, 클라이언트 어설션 생성 및 토큰 획득에 대한 메시지에 대한 로그를 검토합니다.

관련 콘텐츠

• 자격 증명 개요
• 인증서 없는 인증 - 관리 ID 및 워크로드 ID 페더레이션
• 클라이언트 비밀 - 기밀 앱에 대한 대체 자격 증명 유형
• 토큰 암호 해독 - 토큰 암호 해독에 인증서 사용
• 로깅 및 진단