Microsoft 토큰 암호 해독을 구성합니다. Identity.Web

이 문서에서는 Microsoft.Identity.Web에서 토큰 해독 인증서를 구성하여 애플리케이션이 Microsoft ID 플랫폼에서 암호화된 토큰을 해독할 수 있는 방법을 설명합니다.

기본적으로 Microsoft ID 플랫폼 서명되었지만 암호화되지 않은 JWT로 토큰(ID 토큰, SAML 토큰)을 발급합니다. 토큰을 가로채는 모든 중개자가 해당 클레임을 읽을 수 있습니다. 중요한 클레임을 처리하거나 엄격한 규정 준수 환경에서 작동하는 애플리케이션의 경우 Microsoft ID 플랫폼 토큰 암호화 지원합니다. 사용하도록 설정하면 ID 플랫폼은 애플리케이션에 등록된 공개 키를 사용하여 토큰 페이로드를 암호화합니다. 해당 프라이빗 키를 보유하는 애플리케이션만 토큰의 암호를 해독하고 읽을 수 있습니다.

토큰 암호화 작동 방식

퍼블릭/프라이빗 키 쌍을 사용하여 인증서를 생성합니다.
Microsoft Entra ID 앱 등록에 public 키(.cer 파일)를 업로드합니다.
Microsoft ID 플랫폼 애플리케이션에 대한 토큰을 발급하면 공개 키를 사용하여 토큰을 암호화합니다.
애플리케이션은 프라이빗 키를 사용하여 클레임을 처리하기 전에 토큰의 암호를 해독합니다.

암호화는 2 계층 체계를 사용합니다. 토큰 페이로드는 공개 키를 사용하여 래핑(암호화)되는 대칭 콘텐츠 암호화 키로 암호화됩니다. Microsoft Entra RSA-OAEP 및 RSA-OAEP-256 키 래핑 알고리즘을 지원합니다.

토큰 암호 해독을 구성할 시기 결정

애플리케이션이 다음 조건 중 하나를 충족하는 경우 토큰 암호 해독을 구성합니다.

암호화된 SAML 토큰을 받 습니다. SAML 기반 Single Sign-On을 사용하고 규정 준수 또는 규정상의 이유로 암호화된 SAML 어설션이 필요한 엔터프라이즈 애플리케이션입니다.
암호화된 ID 토큰을 받습니다 . 중요한 클레임(그룹 멤버 자격, 사용자 지정 클레임)이 전송 중에 읽지 않도록 보호하기 위해 ID 토큰 암호화를 옵트인하는 웹 애플리케이션입니다.
높은 보안 환경에서 작동합니다 . 토큰 기밀성이 정책에 따라 위임되는 정부, 금융 또는 의료 시나리오의 애플리케이션입니다.

메모

토큰 암호화는 선택 사항입니다. 대부분의 애플리케이션은 필요하지 않습니다. 특정 요구 사항이 있는 경우에만 토큰 암호화를 사용하도록 설정합니다. 이는 운영 복잡성(인증서 관리, 회전)을 추가하고 문제 해결을 더 어렵게 만들기 때문입니다.

필수 구성 요소 충족

토큰 암호 해독을 구성하기 전에 다음 요구 사항을 확인합니다.

프라이빗 키가 있는 X.509 인증서 - .pfx(PKCS#12) 형식의 인증서가 필요하거나 애플리케이션(Azure Key Vault, 인증서 저장소 또는 파일 시스템)에 액세스할 수 있는 위치에 저장해야 합니다. 프라이빗 키는 토큰의 암호를 해독하는 데 필요합니다.
토큰 암호화에 대해 구성된 앱 등록 - Microsoft Entra ID 앱 등록에 인증서의 공개 키를 업로드합니다. 이 문서의 뒷부분에서 암호 해독 인증서 등록 을 참조하세요.
Microsoft.Identity.Web 2.1.0 이상 - TokenDecryptionCredentials 구성 속성은 Microsoft.Identity.Web 2.1.0 이상에서 사용할 수 있습니다.

appsettings.json 토큰 암호 해독 구성

Microsoft. Identity.Web은 TokenDecryptionCredentials 구성 섹션에서 AzureAd 배열을 사용합니다. 이 배열은 ClientCredentials 동일한 자격 증명 설명 형식을 따르므로 Azure Key Vault, 인증서 저장소, 파일 경로 또는 Base64로 인코딩된 문자열에서 암호 해독 인증서를 로드할 수 있습니다.

기본 구성 설정

다음 예제에서는 Azure Key Vault 암호 해독 인증서를 로드하는 최소 구성을 보여 줍니다.

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

    "TokenDecryptionCredentials": [
      {
        "SourceType": "KeyVault",
        "KeyVaultUrl": "https://mykeyvault.vault.azure.net",
        "KeyVaultCertificateName": "MyCertificate"
      }
    ]
  }
}

추가 코드가 필요하지 않습니다. Microsoft. Identity.Web은 TokenDecryptionCredentials 구성을 검색하고, 지정된 인증서를 자동으로 로드하고 토큰 암호 해독을 위해 OpenID Connect 인증 처리기에 등록합니다.

자격 증명 원본 선택

배열은 TokenDecryptionCredentials .와 동일한 소스 형식 ClientCredentials을 지원합니다. 다음 표에서는 각 옵션을 요약합니다.

소스 유형	설명	필수 속성
KeyVault	Azure Key Vault 인증서를 로드합니다. 프로덕션에 권장합니다.	`KeyVaultUrl`, `KeyVaultCertificateName`
StoreWithThumbprint	지문으로 로컬 인증서 저장소에서 로드합니다.	`CertificateStorePath`, `CertificateThumbprint`
StoreWithDistinguishedName	주체 고유 이름으로 로컬 인증서 저장소에서 로드합니다.	`CertificateStorePath`, `CertificateDistinguishedName`
Path	파일 시스템에서 `.pfx` 파일을 로드합니다.	`CertificateDiskPath`, `CertificatePassword`
Base64Encoded	Base64로 인코딩된 `.pfx` 문자열에서 로드합니다(환경 변수에 유용).	`Base64EncodedValue`

Key Vault(프로덕션에 권장)

다음 구성은 Azure Key Vault 암호 해독 인증서를 로드합니다.

{
  "TokenDecryptionCredentials": [
    {
      "SourceType": "KeyVault",
      "KeyVaultUrl": "https://mykeyvault.vault.azure.net",
      "KeyVaultCertificateName": "TokenDecryptionCert"
    }
  ]
}

애플리케이션의 관리 ID 또는 서비스 주체에는 Key Vault 인증서에 대한 Get 및 List 권한이 있어야 합니다.

인증서 저장소(Windows)

다음 구성은 지문으로 Windows 인증서 저장소에서 인증서를 로드합니다.

{
  "TokenDecryptionCredentials": [
    {
      "SourceType": "StoreWithThumbprint",
      "CertificateStorePath": "CurrentUser/My",
      "CertificateThumbprint": "A1B2C3D4E5F6..."
    }
  ]
}

파일 경로

다음 구성은 디스크의 파일에서 인증서를 .pfx 로드합니다.

{
  "TokenDecryptionCredentials": [
    {
      "SourceType": "Path",
      "CertificateDiskPath": "/var/ssl/private/decrypt-cert.pfx",
      "CertificatePassword": "your-certificate-password"
    }
  ]
}

경고

프로덕션 환경에서 appsettings.json 인증서 암호를 저장하지 마세요. 대신 환경 변수, Azure Key Vault 참조 또는 비밀 관리자를 사용합니다.

Base64 인코딩

다음 구성은 Base64로 인코딩된 문자열에서 인증서를 로드합니다.

{
  "TokenDecryptionCredentials": [
    {
      "SourceType": "Base64Encoded",
      "Base64EncodedValue": "MIIJ..."
    }
  ]
}

이 옵션은 환경 변수 또는 CI/CD 파이프라인 비밀을 통해 인증서를 삽입할 때 유용합니다.

여러 암호 해독 인증서 구성

배열에서 TokenDecryptionCredentials 여러 인증서를 지정할 수 있습니다. Microsoft. Identity.Web은 토큰의 암호를 성공적으로 해독할 때까지 각 인증서를 순서대로 시도합니다. 이 기능은 인증서 회전 에 필수적입니다( 인증서 회전 참조).

{
  "TokenDecryptionCredentials": [
    {
      "SourceType": "KeyVault",
      "KeyVaultUrl": "https://mykeyvault.vault.azure.net",
      "KeyVaultCertificateName": "TokenDecryptionCert-New"
    },
    {
      "SourceType": "KeyVault",
      "KeyVaultUrl": "https://mykeyvault.vault.azure.net",
      "KeyVaultCertificateName": "TokenDecryptionCert-Old"
    }
  ]
}

Microsoft Entra ID 암호 해독 인증서 등록

Microsoft ID 플랫폼 애플리케이션에 대한 토큰을 암호화하려면 인증서의 공개 키를 앱 등록에 업로드해야 합니다.

Microsoft Entra 관리 센터 로그인합니다.
Identity>Applications>앱 등록로 이동하여 애플리케이션을 선택합니다.
인증서 및 비밀>인증서>인증서 업로드를 선택합니다.
암호 해독 인증서의 .cer 파일(공개 키만 해당)을 업로드합니다.
업로드한 후 지문 값은 애플리케이션에서 사용하는 인증서와 일치해야 합니다.

애플리케이션에 대한 토큰 암호화 사용

인증서를 업로드한 후 암호화된 토큰을 받도록 애플리케이션을 구성해야 합니다. 이 구성은 현재 Microsoft Graph API 또는 PowerShell을 통해 사용할 수 있습니다.

Microsoft Graph PowerShell 사용:

# Get the key credential ID of the uploaded certificate
$app = Get-MgApplication -Filter "appId eq 'your-client-id'"
$keyId = ($app.KeyCredentials | Where-Object { $_.DisplayName -eq "CN=TokenDecryptionCert" }).KeyId

# Set the token encryption key ID
Update-MgApplication -ApplicationId $app.Id -BodyParameter @{
    "tokenEncryptionKeyId" = $keyId
}

중요합니다

애플리케이션 개체의 tokenEncryptionKeyId 속성은 Microsoft Entra 토큰을 암호화하는 데 사용하는 업로드된 인증서를 식별합니다. 한 번에 하나의 암호화 키만 활성화할 수 있습니다.

암호 해독 인증서 회전

토큰 암호 해독을 위한 인증서 회전에는 가동 중지 시간을 방지하기 위해 신중하고 단계적인 접근 방식이 필요합니다.

회전 단계

새 인증서 생성 - 프라이빗 키를 사용하여 새 X.509 인증서를 만듭니다.
애플리케이션 구성에 새 인증서를 추가 합니다. 기존 인증서와 함께 배열에 TokenDecryptionCredentials 새 인증서를 추가합니다. 배열에서 새 인증서를 먼저 배치합니다.
새 공개 키 업로드 - 새 인증서의 .cer 파일을 Microsoft Entra 앱 등록에 업로드합니다.
애플리케이션 배포 - 애플리케이션이 인증서로 토큰의 암호를 해독할 수 있도록 업데이트된 구성을 배포합니다.
활성 암호화 키 전환 - 새 인증서tokenEncryptionKeyId를 가리키도록 애플리케이션 개체를 업데이트 keyId 합니다.
확인 — 애플리케이션이 새 인증서로 암호화된 토큰의 암호를 성공적으로 해독했는지 확인합니다.
이전 인증서 제거 - 유예 기간(캐시된 토큰이 만료될 수 있도록 24시간 이상) 후에 앱 등록 및 애플리케이션 구성 모두에서 이전 인증서를 제거합니다.

회전 중 구성

회전 창 동안, TokenDecryptionCredentials에는 두 인증서가 모두 포함되어야 합니다.

{
  "TokenDecryptionCredentials": [
    {
      "SourceType": "KeyVault",
      "KeyVaultUrl": "https://mykeyvault.vault.azure.net",
      "KeyVaultCertificateName": "TokenDecryptionCert-2026"
    },
    {
      "SourceType": "KeyVault",
      "KeyVaultUrl": "https://mykeyvault.vault.azure.net",
      "KeyVaultCertificateName": "TokenDecryptionCert-2025"
    }
  ]
}

팁 (조언)

Azure Key Vault 자동 회전 기능을 Key Vault 이벤트 알림과 결합하여 애플리케이션 재배포를 트리거하여 인증서 회전을 자동화합니다.

토큰 암호 해독 문제 해결

다음 지침을 사용하여 일반적인 토큰 암호 해독 문제를 진단하고 해결합니다.

토큰 암호 해독 실패

증상: 애플리케이션이 토큰을 SecurityTokenDecryptionFailedException 처리할 때 401/500 오류를 던지거나 반환합니다.

일반적인 원인:

원인	해결 방법
인증서를 찾을 수 없습니다	인증서가 구성된 위치(Key Vault, 저장 또는 파일 경로)에 있는지 확인합니다. 애플리케이션에 액세스하는 데 필요한 권한이 있는지 확인합니다.
잘못된 인증서	애플리케이션 구성의 인증서 지문이 앱 등록에 업로드된 인증서와 일치하는지 확인합니다.
`tokenEncryptionKeyId` 설정되지 않음	Microsoft Entra 애플리케이션 개체에서 `tokenEncryptionKeyId` 속성을 설정합니다. 이 속성이 없으면 ID 플랫폼은 토큰을 암호화하지 않습니다.

누락된 프라이빗 키

증상:CryptographicException: The certificate key is not accessible 또는 InvalidOperationException: Certificate does not have a private key.

원인 및 해결 방법:

프라이빗 키 없이 내보낸 인증서 - 인증서 .pfx 를 형식으로 다시 내보내고 내보내는 동안 프라이빗 키를 포함해야 합니다.
Key Vault 액세스 정책 — Azure Key Vault 사용하는 경우 애플리케이션의 ID에 < Get Certificates 및 Secrets 권한이 있는지 확인합니다. 프라이빗 키는 Key Vault 비밀로 저장됩니다.
저장소 권한 인증 — Windows 애플리케이션 풀 ID 또는 서비스 계정에 프라이빗 키에 대한 읽기 권한이 있는지 확인합니다. 인증서 저장소 MMC 스냅인에서 프라이빗 키 관리 옵션을 사용합니다.

알고리즘 불일치

증상:SecurityTokenDecryptionFailedException 지원되지 않는 알고리즘을 나타내는 메시지와 함께

원인 및 해결 방법:

지원되지 않는 키 유형 - Microsoft Entra 토큰 암호화에 대한 RSA 인증서를 지원합니다. 인증서가 EC/ECDSA가 아닌 RSA 키 쌍을 사용하는지 확인합니다.
키 크기가 너무 작 습니다. 2048비트 이상의 키 크기를 사용합니다. 2048비트보다 작은 RSA 키는 거부될 수 있습니다.
Algorithm은 지원되지 않습니다 - Microsoft Entra 키 래핑에 RSA-OAEP 사용합니다. 인증서 및 애플리케이션 인프라가 이 알고리즘을 지원하는지 확인합니다.

암호화된 토큰이 발급되지 않음

증상: 토큰 암호 해독을 구성한 경우에도 애플리케이션은 암호화되지 않은 토큰을 받습니다.

원인 및 해결 방법:

tokenEncryptionKeyId 구성되지 않음 - Microsoft Graph 통해 이 속성을 명시적으로 설정해야 합니다. 인증서만 업로드하는 것만으로는 충분하지 않습니다.
앱 등록에서 인증서가 만료됨 - 앱 등록 에 업로드된 인증서가 만료되지 않았는지 확인합니다. 필요한 경우 새 인증서를 업로드합니다.
액세스 토큰은 암호화되지 않습니다 . 토큰 암호화는 ID 토큰 및 SAML 토큰 에만 적용됩니다. Microsoft Entra 액세스 토큰은 인증서로 암호화되지 않습니다.

토큰 암호 해독 및 클라이언트 자격 증명 비교

토큰 암호 해독 자격 증명은 클라이언트 자격 증명과 다른 용도로 사용됩니다. 애플리케이션은 둘 다에 대해 동일한 인증서를 사용하거나 별도의 인증서를 사용할 수 있습니다.

다음 예제에서는 인증 및 토큰 암호 해독 모두에 동일한 Key Vault 인증서를 사용하는 구성을 보여 줍니다.

{
  "AzureAd": {
    "ClientCredentials": [
      {
        "SourceType": "KeyVault",
        "KeyVaultUrl": "https://mykeyvault.vault.azure.net",
        "KeyVaultCertificateName": "AppAuthCert"
      }
    ],
    "TokenDecryptionCredentials": [
      {
        "SourceType": "KeyVault",
        "KeyVaultUrl": "https://mykeyvault.vault.azure.net",
        "KeyVaultCertificateName": "AppAuthCert"
      }
    ]
  }
}

메모

두 가지 용도로 동일한 인증서를 사용하는 경우 인증서는 KeyEncipherment 키 사용을 가져야 하며, KeyExchange 키 사양을 사용해야 하고 Signature를 사용하지 않아야 합니다. 클라이언트 자격 증명에는 KeySpec = Signature 생성된 인증서가 작동하지만, 토큰 복호화에는 실패합니다.

모범 사례 준수

토큰 암호 해독을 구현할 때 이러한 권장 사항을 적용합니다.

Azure Key Vault 사용 — 중앙 집중식 관리, 액세스 제어 및 감사 로깅을 위해 암호 해독 인증서를 Key Vault 저장합니다.

회전 계획 - 토큰 암호화를 배포하기 전에 항상 회전 전략을 갖습니다. 회전 기간 동안 새 인증서와 이전 인증서를 모두 포함합니다.

RSA 2048비트 이상 키 사용 - 인증서가 적절한 보안을 위해 2048비트 이상의 RSA 키를 사용하는지 확인합니다.

모니터 인증서 만료 — 인증서가 만료되기 전에 알리도록 Azure Key Vault 또는 모니터링 시스템에서 경고를 설정합니다.

스테이징 환경에서 테스트 - 프로덕션 환경에서 사용하도록 설정하기 전에 비프로덕션 환경에서 토큰 암호화 및 암호 해독을 확인합니다.

소스 제어에 프라이빗 키를 저장하지 않음 — 인증서 스토리지에 Key Vault, 환경 변수 또는 비밀 관리자를 사용합니다.

순환하는 동안 이전 인증서를 너무 일찍 제거하지 마세요 . 캐시된 토큰이 만료되도록 두 인증서를 24시간 이상 활성 상태로 유지합니다.

암호 해독 인증서를 구성하지 않고 토큰 암호화를 사용하도록 설정하지 마세요 . 암호 해독할 수 없는 경우 애플리케이션에서 토큰을 처리하지 못합니다.

피드백

이 페이지가 도움이 되었나요?

Last updated on 2026-04-29

Microsoft 토큰 암호 해독을 구성합니다. Identity.Web

토큰 암호화 작동 방식

토큰 암호 해독을 구성할 시기 결정

필수 구성 요소 충족

appsettings.json 토큰 암호 해독 구성

기본 구성 설정

자격 증명 원본 선택

Key Vault(프로덕션에 권장)

인증서 저장소(Windows)

파일 경로

Base64 인코딩

여러 암호 해독 인증서 구성

Microsoft Entra ID 암호 해독 인증서 등록

애플리케이션에 대한 토큰 암호화 사용

암호 해독 인증서 회전

회전 단계

회전 중 구성

토큰 암호 해독 문제 해결

토큰 암호 해독 실패

누락된 프라이빗 키

알고리즘 불일치

암호화된 토큰이 발급되지 않음

토큰 암호 해독 및 클라이언트 자격 증명 비교

모범 사례 준수

관련 콘텐츠

피드백

추가 리소스