.NET용 앱 인증 클라이언트 라이브러리 - 버전 1.6.0

아티클
04/03/2023

참고

Microsoft.Azure.Services.AppAuthentication 이 사용 중지되었으며 더 이상 지원되거나 유지 관리되지 않습니다. .NET, Java, TypeScript 및 Python에 사용할 수 있는 Azure ID 클라이언트 라이브러리 로 대체됩니다. 마이그레이션하는 방법에 대한 정보는 Azure IdentityAppAuthentication to Azure.Identity 마이그레이션 지침에서 찾을 수 있습니다.

서비스 주체를 사용하여 Azure 서비스에 인증하려면 공유 비밀 또는 인증서인 Azure AD(Azure Active Directory) 자격 증명이 필요합니다.

이러한 자격 증명을 관리하는 것은 어려울 수 있습니다. 자격 증명을 원본 또는 구성 파일에 포함하여 앱에 번들로 묶는 것이 좋습니다. .NET 라이브러리에 대한 Microsoft.Azure.Services.AppAuthentication은 이 문제를 단순화합니다. 개발자의 자격 증명을 사용하여 로컬 개발 동안 인증합니다. 나중에 Azure에 솔루션이 배포되면 라이브러리는 애플리케이션 자격 증명으로 자동으로 전환됩니다. Azure AD 자격 증명을 만들거나 개발자 간에 자격 증명을 공유할 필요가 없으므로 로컬 개발 중에 개발자 자격 증명을 사용하는 것이 더 안전합니다.

라이브러리는 Microsoft.Azure.Services.AppAuthentication 인증을 자동으로 관리하므로 자격 증명이 아닌 솔루션에 집중할 수 있습니다. Microsoft Visual Studio, Azure CLI 또는 Azure AD 통합 인증을 사용하여 로컬 개발을 지원합니다. 관리 ID를 지원하는 Azure 리소스에 배포된 라이브러리는 Azure 리소스용 관리 ID를 자동으로 사용합니다. 코드 또는 구성을 변경할 필요가 없습니다. 또한 라이브러리는 관리 ID를 사용할 수 없거나 로컬 개발 중에 개발자의 보안 컨텍스트를 확인할 수 없는 경우 Azure AD 클라이언트 자격 증명을 직접 사용할 수 있습니다.

소스 코드 | 패키지(nuget) | Azure Active Directory 설명서

필수 구성 요소

Visual Studio 2019 또는 Visual Studio 2017 v15.5.
Visual Studio용 앱 인증 확장은 Visual Studio 2017 업데이트 5에 대한 별도의 확장으로 사용할 수 있으며 업데이트 6 이상에서 제품과 함께 제공됩니다. 업데이트 6 이상을 사용하면 Visual Studio 설치 관리자 내에서 Azure 개발 도구를 선택하여 앱 인증 확장의 설치를 확인할 수 있습니다.

라이브러리 사용

.NET 애플리케이션의 경우 Microsoft.Azure.Services.AppAuthentication 패키지를 통해 관리 ID를 사용하는 것이 가장 간단한 방법입니다. 시작 방법은 다음과 같습니다.

도구>NuGet 패키지 관리자>솔루션용 NuGet 패키지 관리를 선택하여 Microsoft.Azure.Services.AppAuthentication 및 Microsoft.Azure.KeyVault NuGet 패키지에 대한 참조를 프로젝트에 추가합니다.

아래 예제와 같이 AzureServiceTokenProvider를 사용하여 Azure 클라이언트에 대한 액세스 토큰 요청을 간소화합니다.

using Microsoft.Azure.Services.AppAuthentication;
using Microsoft.Azure.KeyVault;
using System.Data.SqlClient

// Use AzureServiceTokenProvider’s built-in callback for KeyVaultClient
var azureServiceTokenProvider = new AzureServiceTokenProvider();
var kv = new KeyVaultClient(new KeyVaultClient.AuthenticationCallback(azureServiceTokenProvider.KeyVaultTokenCallback));

// Request an access token for SqlConnection
sqlConnection = new SqlConnection(YourConnectionString)) 
{ 
    sqlConnection.AccessToken = await azureServiceTokenProvider.GetAccessTokenAsync("https://database.windows.net"); 
    sqlConnection.Open(); 
}

스레드로부터 안전한 AzureServiceTokenProvider 클래스는 메모리에 토큰을 캐시하고 만료 직전 Azure AD 토큰을 검색합니다. 즉, 메서드를 호출 GetAccessTokenAsync 하기 전에 토큰의 만료를 검사 필요가 없습니다.

GetAccessTokenAsync 메서드는 리소스 식별자가 필요합니다. Microsoft Azure 서비스에 대한 자세한 내용은 Azure 리소스에 대한 관리 ID란?을 참조하세요.

로컬 개발 인증

로컬 개발의 경우 Azure 서비스에 인증하고 사용자 지정 서비스에 인증하는 두 가지 기본 인증 시나리오 가 있습니다.

Azure 서비스에 인증

로컬 머신은 Azure 리소스에 대한 관리 ID를 지원하지 않습니다. 따라서 Microsoft.Azure.Services.AppAuthentication 라이브러리가 개발자 자격 증명을 사용하여 로컬 개발 환경에서 실행됩니다. Azure에 솔루션이 배포되면 라이브러리가 관리 ID를 사용하여 OAuth 2.0 클라이언트 자격 증명 부여 흐름으로 전환합니다. 이 방법은 동일한 코드를 걱정 없이 로컬 및 원격으로 테스트할 수 있습니다.

로컬 개발의 경우 AzureServiceTokenProvider는 Visual Studio, Azure CLI(명령줄 인터페이스) 또는 Azure AD 통합 인증을 사용하여 토큰을 페치합니다. 각 옵션을 순차적으로 시도하여 라이브러리가 성공하는 첫 번째 옵션을 사용합니다. 작동하는 옵션이 없는 경우 자세한 정보와 함께 AzureServiceTokenProviderException 예외가 throw됩니다.

Visual Studio를 사용하여 인증

Visual Studio를 사용하여 인증하려면 다음을 수행합니다.

Visual Studio에 로그인하고 도구>옵션을 사용하여 옵션을 엽니다.
Azure 서비스 인증을 선택하고 로컬 개발을 위한 계정을 선택한 다음 확인을 선택합니다.

토큰 공급자 파일과 관련된 오류와 같이 Visual Studio를 사용하는 데 문제가 발생하는 경우 이전 단계를 주의 깊게 검토합니다.

개발자 토큰을 다시 인증해야 할 수 있습니다. 이렇게 하려면 도구>옵션을 선택한 다음 , Azure 서비스 인증을 선택합니다. 선택한 계정 아래에서 다시 인증 링크를 찾습니다. 링크를 선택하여 인증합니다.

Azure CLI를 사용하여 인증

로컬 개발에 Azure CLI를 사용하려면 버전 Azure CLI v2.0.12 이상이 있어야 합니다.

Azure CLI을 사용하려면 다음을 수행합니다.

Windows 작업 표시줄에서 Azure CLI를 검색하여 Microsoft Azure 명령 프롬프트를 엽니다.
Azure Portal 로그인: az login을 사용하여 Azure에 로그인합니다.
az account get-access-token --resource https://vault.azure.net를 입력하여 액세스를 확인합니다. 오류가 발생하면 올바른 버전의 Azure CLI가 올바르게 설치되었는지 검사.

Azure CLI가 기본 디렉터리에 설치되지 않은 경우 Azure CLI의 경로를 찾을 수 없는 오류 보고가 AzureServiceTokenProvider 표시될 수 있습니다. AzureCLIPath 환경 변수를 사용하여 Azure CLI 설치 폴더를 정의합니다. AzureServiceTokenProvider는 필요한 경우 AzureCLIPath 환경 변수에 지정된 디렉터리를 Path 환경 변수에 추가합니다.
여러 계정을 사용하여 Azure CLI에 로그인했거나 계정이 여러 구독에 액세스할 수 있는 경우 사용할 구독을 지정해야 합니다. az account set --subscription 명령을 입력합니다.

이 명령은 실패한 경우에만 출력을 생성합니다. 현재 계정 설정을 확인하려면 명령을 az account list입력합니다.

Azure AD 인증을 사용하여 인증

Azure AD 인증을 사용하려면 다음을 확인합니다.

온-프레미스 Active Directory Azure AD 동기화됩니다. 자세한 내용은 Azure Active Directory를 사용하는 하이브리드 ID란?을 참조하세요.
코드가 도메인에 가입된 컴퓨터에서 실행되고 있습니다.

사용자 지정 서비스에 인증

Azure 서비스를 사용하면 사용자와 애플리케이션에 모두 액세스할 수 있으므로 서비스에서 Azure 서비스를 호출하는 경우 이전 단계가 작동합니다.

사용자 지정 서비스를 호출하는 서비스를 만들 경우 로컬 개발 인증에 Azure AD 클라이언트 자격 증명을 사용합니다. 두 가지 옵션 중이 있습니다.

서비스 주체를 사용하여 Azure에 로그인:
1. 서비스 주체를 생성합니다. 자세한 내용은 Azure CLI을 사용하여 Azure 서비스 주체 만들기를 참조하세요.
2. Azure CLI를 사용하여 다음 명령을 사용하여 로그인합니다.
```
az login --service-principal -u <principal-id> --password <password> --tenant <tenant-id> --allow-no-subscriptions
```
  서비스 주체에 구독에 대한 액세스 권한이 없을 수 있으므로 --allow-no-subscriptions 인수를 사용합니다.
환경 변수를 사용하여 서비스 주체 세부 사항을 지정합니다. 자세한 내용은 서비스 주체를 사용하여 애플리케이션 실행을 참조하세요.

Azure AzureServiceTokenProvider 에 로그인한 후 는 서비스 주체를 사용하여 로컬 개발을 위한 토큰을 검색합니다.

이 방법은 로컬 개발에만 적용됩니다. Azure에 솔루션이 배포되면 라이브러리가 관리 ID 인증으로 전환됩니다.

관리 ID 또는 사용자 할당 ID를 사용하여 애플리케이션 실행

Azure App Service 또는 활성화된 관리 ID를 사용하는 Azure VM에서 코드를 실행하는 경우 라이브러리는 자동으로 관리 ID를 사용합니다. 코드를 변경할 필요는 없지만 관리 ID에는 액세스하려는 리소스에 대한 권한이 있어야 합니다. 예를 들어 관리 ID가 키 자격 증명 모음의 비밀에 액세스하려면 액세스 정책이 필요합니다.

또는 사용자 할당 ID를 사용하여 인증할 수 있습니다. 사용자 할당 ID에 대한 자세한 내용은 Azure 리소스에 대한 관리 ID 정보를 참조하세요. 사용자 할당 ID로 인증하려면 연결 문자열에서 사용자 할당 ID의 클라이언트 ID를 지정해야 합니다. 연결 문자열은 연결 문자열 지원에 지정됩니다.

서비스 주체를 사용하여 애플리케이션 실행

인증할 Azure AD 클라이언트 자격 증명을 만들어야 할 수 있습니다. 이 상황은 다음 예제에서 발생할 수 있습니다.

코드가 로컬 개발 환경에서 실행되지만 개발자의 ID 아래에서는 실행되지 않습니다. 예를 들어 Service Fabric은 로컬 개발에 NetworkService 계정을 사용합니다.
로컬 개발 환경에서 코드가 실행되고 사용자 지정 서비스에 인증하므로 개발자 ID를 사용할 수 없습니다.
코드는 azure 리소스에 대한 관리 ID(예: Azure Batch)를 아직 지원하지 않는 Azure 컴퓨팅 리소스에서 실행되고 있습니다.

서비스 주체를 사용하여 애플리케이션을 실행하는 세 가지 기본 방법이 있습니다. 서비스 주체를 사용하려면 먼저 서비스 주체를 만들어야 합니다. 자세한 내용은 Azure CLI을 사용하여 Azure 서비스 주체 만들기를 참조하세요.

로컬 키 저장소의 인증서를 사용하여 Azure AD 로그인

Azure CLI az ad sp create-for-rbac 명령을 사용하여 서비스 주체 인증서를 만듭니다.
```
az ad sp create-for-rbac --create-cert
```
이 명령은 홈 디렉터리에 저장된 .pem 파일(프라이빗 키)을 만듭니다. 명령을 사용하여 .pem 파일을 PFX 인증서로 변환합니다.
```
openssl pkcs12 -export -in test.pem -out test.pfx
```
AzureServicesAuthConnectionString이라는 환경 변수를 다음 값으로 설정합니다.
```
RunAs=App;AppId={AppId};TenantId={TenantId};CertificateThumbprint={Thumbprint};
      CertificateStoreLocation={CertificateStore}
```
{AppId}, {TenantId} 및 {Thumbprint}를 1단계에서 생성된 값으로 바꿉니다. 배포 계획에 따라 {CertificateStore} 를 LocalMachine' 또는 CurrentUser로 바꿉 있습니다.
애플리케이션을 실행합니다.

공유 비밀 자격 증명을 사용하여 Azure AD 로그인

--sdk-auth 매개 변수와 함께 Azure CLI az ad sp create-for-rbac 명령을 사용하여 암호로 서비스 주체 인증서를 만듭니다.
```
az ad sp create-for-rbac --sdk-auth
```
AzureServicesAuthConnectionString이라는 환경 변수를 다음 값으로 설정합니다.
```
RunAs=App;AppId={AppId};TenantId={TenantId};AppKey={ClientSecret}
```
{AppId}, {TenantId} 및 {ClientSecret}을 1단계에서 생성된 값으로 바꿉니다.
애플리케이션을 실행합니다.

모두가 올바로 설정되면 더 이상 코드를 변경할 필요가 없습니다. AzureServiceTokenProvider는 환경 변수 및 인증서를 사용하여 Azure AD에 인증합니다.

Key Vault 인증서를 사용하여 Azure AD 로그인

이 옵션을 사용하면 서비스 주체의 클라이언트 인증서를 Key Vault 저장하고 서비스 주체 인증에 사용할 수 있습니다. 다음 시나리오에 이 옵션을 사용할 수 있습니다.

명시적 서비스 주체를 사용하여 인증하고 서비스 주체 자격 증명을 키 자격 증명 모음에 안전하게 유지하려는 로컬 인증. 개발자 계정에는 키 자격 증명 모음에 대한 액세스 권한이 있어야 합니다.
명시적 자격 증명을 사용하고 서비스 주체 자격 증명을 키 자격 증명 모음에 안전하게 유지하려는 Azure의 인증입니다. 테넌트 간 시나리오에 이 옵션을 사용할 수 있습니다. 관리 ID는 키 자격 증명 모음에 대한 액세스 권한이 있어야 합니다.

관리 ID 또는 개발자 ID에는 Key Vault 클라이언트 인증서를 검색할 수 있는 권한이 있어야 합니다. AppAuthentication 라이브러리는 검색된 인증서를 서비스 주체의 클라이언트 자격 증명으로 사용합니다.

서비스 주체 인증에 클라이언트 인증서를 사용하려면 다음을 수행합니다.

서비스 주체 인증서를 만들고 Key Vault 자동으로 저장합니다. Azure CLI az ad sp create-for-rbac --keyvault <keyvaultname> --cert <certificatename> --create-cert --skip-assignment 명령을 사용합니다.
```
az ad sp create-for-rbac --keyvault <keyvaultname> --cert <certificatename> --create-cert --skip-assignment
```
인증서 식별자는 형식의 URL입니다. https://<keyvaultname>.vault.azure.net/secrets/<certificatename>
이 연결 문자열에서 을 인증서 식별자로 바꿉 {KeyVaultCertificateSecretIdentifier} 있습니다.
```
RunAs=App;AppId={TestAppId};KeyVaultCertificateSecretIdentifier={KeyVaultCertificateSecretIdentifier}
```
instance 경우 키 자격 증명 모음을 myKeyVault라고 하고 myCert라는 인증서를 만든 경우 인증서 식별자는 다음과 같습니다.
```
RunAs=App;AppId={TestAppId};KeyVaultCertificateSecretIdentifier=https://myKeyVault.vault.azure.net/secrets/myCert
```

연결 문자열 지원

기본적으로 는 AzureServiceTokenProvider 토큰을 검색하기 위해 다음 인증 방법을 시도합니다.

프로세스를 제어하려면 AzureServiceTokenProvider 생성자에 전달되거나 AzureServicesAuthConnectionString 환경 변수에 지정된 연결 문자열을 사용합니다. 다음과 같은 옵션이 지원됩니다.

연결 문자열 옵션	시나리오	의견
`RunAs=Developer;DeveloperTool=AzureCli`	로컬 개발	`AzureServiceTokenProvider` 에서는 AzureCli를 사용하여 토큰을 가져옵니다.
`RunAs=Developer;DeveloperTool=VisualStudio`	로컬 개발	`AzureServiceTokenProvider` 는 Visual Studio를 사용하여 토큰을 가져옵니다.
`RunAs=CurrentUser`	로컬 개발	.NET Core에서는 지원되지 않습니다. `AzureServiceTokenProvider`는 Azure AD 통합 인증을 사용하여 토큰을 가져옵니다.
`RunAs=App`	Azure 리소스에 대한 관리 ID	`AzureServiceTokenProvider` 는 관리 ID를 사용하여 토큰을 가져옵니다.
`RunAs=App;AppId={ClientId of user-assigned identity}`	Azure 리소스에 대한 사용자 할당 ID	`AzureServiceTokenProvider` 는 사용자 할당 ID를 사용하여 토큰을 가져옵니다.
`RunAs=App;AppId={TestAppId};KeyVaultCertificateSecretIdentifier={KeyVaultCertificateSecretIdentifier}`	사용자 지정 서비스 인증	`KeyVaultCertificateSecretIdentifier` 는 인증서의 비밀 식별자입니다.
`RunAs=App;AppId={AppId};TenantId={TenantId};CertificateThumbprint={Thumbprint};CertificateStoreLocation={LocalMachine or CurrentUser}`	서비스 주체	`AzureServiceTokenProvider`는 인증서를 사용하여 Azure AD에서 토큰을 가져옵니다.
`RunAs=App;AppId={AppId};TenantId={TenantId};CertificateSubjectName={Subject};CertificateStoreLocation={LocalMachine or CurrentUser}`	서비스 주체	`AzureServiceTokenProvider`는 인증서를 사용하여 Azure AD에서 토큰을 가져옵니다.
`RunAs=App;AppId={AppId};TenantId={TenantId};AppKey={ClientSecret}`	서비스 주체	`AzureServiceTokenProvider`는 암호를 사용하여 Azure AD에서 토큰을 가져옵니다.

샘플

실행 중인 라이브러리를 Microsoft.Azure.Services.AppAuthentication 보려면 다음 코드 샘플을 참조하세요.

AppAuthentication 문제 해결

로컬 개발 중 일반적인 문제

Azure CLI가 설치되지 않았거나, 로그인하지 않았거나, 최신 버전이 없습니다.

az account get-access-token을 실행하여 Azure CLI에 토큰이 표시되는지 확인합니다. 이러한 프로그램을 찾을 수 없다고 표시되면 최신 버전의 Azure CLI를 설치합니다. 로그인하라는 메시지가 표시될 수 있습니다.

AzureServiceTokenProvider에서 Azure CLI에 대한 경로를 찾을 수 없습니다.

AzureServiceTokenProvider는 기본 설치 위치에서 Azure CLI를 찾습니다. Azure CLI를 찾을 수 없는 경우 환경 변수 AzureCLIPath를 Azure CLI 설치 폴더로 설정합니다. AzureServiceTokenProvider는 Path 환경 변수에 환경 변수를 추가합니다.

여러 계정을 사용하여 Azure CLI에 로그인했거나, 동일한 계정이 여러 테넌트의 구독에 액세스할 수 있거나, 로컬 개발 중에 호출을 시도할 때 액세스 거부 오류가 발생합니다.

Azure CLI를 사용하여 기본 구독을 사용하려는 계정이 있는 구독으로 설정합니다. 구독은 액세스하려는 리소스와 동일한 테넌트( az account set --subscription [subscription-id])에 있어야 합니다. 출력이 표시되지 않으면 성공했습니다. 이제 az account list를 사용하여 올바른 계정이 기본값인지 확인합니다.

환경 전반의 일반적인 문제

무단 액세스, 액세스 거부됨, 액세스 사용할 수 없음 또는 유사한 오류

사용된 보안 주체가 액세스하려는 리소스에 대한 액세스 권한이 없습니다. 사용자 계정 또는 App Service MSI "기여자" 액세스 권한을 리소스에 부여합니다. 로컬 컴퓨터에서 샘플을 실행 중인지 아니면 Azure에서 App Service 배포하는지에 따라 달라집니다. 키 자격 증명 모음과 같은 일부 리소스에는 사용자, 앱 및 그룹과 같은 보안 주체에 대한 액세스 권한을 부여하는 데 사용하는 자체 액세스 정책 도 있습니다.

Azure App Service 배포할 때 발생하는 일반적인 문제

관리 ID가 App Service 설정되지 않음

Kudu 디버그 콘솔을 사용하여 MSI_ENDPOINT 및 MSI_SECRET 환경 변수를 확인합니다. 이러한 환경 변수가 없으면 App Service 관리 ID가 사용하도록 설정되지 않습니다.

IIS를 사용하여 로컬로 배포할 때 발생하는 일반적인 문제

IIS에서 앱을 디버깅할 때 토큰을 검색할 수 없습니다.

기본적으로 AppAuth는 IIS의 다른 사용자 컨텍스트에서 실행됩니다. 따라서 개발자 ID를 사용하여 액세스 토큰을 검색할 수 있는 액세스 권한이 없습니다. 다음 두 단계를 사용하여 사용자 컨텍스트에서 실행되도록 IIS를 구성할 수 있습니다.

웹앱이 현재 사용자 계정으로 실행되도록 애플리케이션 풀을 구성합니다. 자세한 내용은 여기를 참조하세요.
"setProfileEnvironment"를 "True"로 구성합니다. 자세한 내용은 여기를 참조하세요.
- %windir%\System32\inetsrv\config\applicationHost.config
- "setProfileEnvironment"를 검색합니다. "False"로 설정된 경우 "True"로 변경합니다. 없는 경우 processModel 요소(/configuration/system.applicationHost/applicationPools/applicationPoolDefaults/processModel/@setProfileEnvironment)에 특성으로 추가하고 "True"로 설정합니다.
Azure 리소스에 대한 관리 ID에 대해 자세히 알아보세요.
Azure AD 인증 시나리오에 대해 자세히 알아보기.

다음을 통해 공유