App Service 및 Azure Functions에 대한 관리 ID를 사용하는 방법

아티클
09/30/2024

참고 항목

2024년 6월 1일부터, 새로 만들어진 모든 App Service 앱에는 명명 규칙 <app-name>-<random-hash>.<region>.azurewebsites.net을 사용하여 고유한 기본 호스트 이름을 생성할 수 있는 옵션이 제공됩니다. 기존 앱 이름은 변경되지 않은 상태로 유지됩니다.

예: myapp-ds27dh7271aah175.westus-01.azurewebsites.net

자세한 내용은 App Service 리소스의 고유 기본 호스트 이름을 참조하세요.

이 문서에서는 App Service 및 Azure Functions 애플리케이션에 대한 관리 ID를 만드는 방법과 다른 리소스에 액세스하는 데 사용하는 방법을 보여 줍니다.

Important

관리 ID는디렉터리 간 시나리오를 지원하지 않으므로 앱이 구독 또는 테넌트 간에 마이그레이션되는 경우 예상대로 동작하지 않습니다. 이러한 이동 후 관리 ID를 다시 만들려면 구독을 다른 디렉터리로 이동하는 경우 관리 ID가 자동으로 다시 만들어지나요?를 참조하세요. 다운스트림 리소스에도 새 ID를 사용하려면 액세스 정책을 업데이트해야 합니다.

참고 항목

Azure Arc에 배포된 앱에 대해서는 관리 ID를 사용할 수 없습니다.

Microsoft Entra ID의 관리 ID를 사용하면 앱이 Azure Key Vault 등의 다른 Microsoft Entra 보호 리소스에 쉽게 액세스할 수 있습니다. ID는 Azure 플랫폼에서 관리하며 비밀을 프로비전하거나 회전할 필요가 없습니다. Microsoft Entra ID의 관리 ID에 대한 자세한 내용은 Azure 리소스의 관리 ID를 참조하세요.

애플리케이션에 두 가지 형식의 ID를 부여할 수 있습니다.

시스템 할당 ID는 앱에 연결되어 있으며 앱이 삭제되면 삭제됩니다. 앱에는 하나의 시스템 할당 ID만 있을 수 있습니다.
사용자 할당 ID는 앱에 할당할 수 있는 독립 실행형 Azure 리소스입니다. 앱에는 여러 사용자 할당 ID가 있을 수 있으며, 하나의 사용자 할당 ID를 두 개의 App Service 앱과 같은 여러 Azure 리소스에 할당할 수 있습니다.

관리 ID 구성은 슬롯과 관련이 있습니다. 포털에서 배포 슬롯에 대한 관리 ID를 구성하려면 먼저 슬롯으로 이동합니다. Azure Portal에서 Microsoft Entra 테넌트의 웹앱 또는 배포 슬롯에 대한 관리 ID를 찾으려면 테넌트의 개요 페이지에서 직접 검색합니다. 일반적으로 슬롯 이름은 <app-name>/slots/<slot-name>과 비슷합니다.

다음 비디오에서는 App Service에 관리 ID를 사용하는 방법을 보여줍니다.

비디오의 단계도 다음 섹션에 설명되어 있습니다.

시스템 할당 ID 추가

왼쪽 탐색 창의 설정 그룹 아래에 있는 Azure Portal 앱의 설정에 액세스합니다.
ID를 선택합니다.
시스템 할당 탭에서 상태를 켜기로 바꿉니다. 저장을 클릭합니다.

az webapp identity assign 명령을 실행하여 시스템 할당 ID를 만듭니다.

az webapp identity assign --name myApp --resource-group myResourceGroup

App Service의 경우

Set-AzWebApp -AssignIdentity 명령을 실행하여 App Service에 대한 시스템 할당 ID를 만듭니다.

Set-AzWebApp -AssignIdentity $true -Name <app-name> -ResourceGroupName <group-name>

함수의 경우

Update-AzFunctionApp -IdentityType 명령을 실행하여 함수 앱에 대한 시스템 할당 ID를 만듭니다.

Update-AzFunctionApp -Name $functionAppName -ResourceGroupName $resourceGroupName -IdentityType SystemAssigned

Azure Resource Manager 템플릿을 사용하여 Azure 리소스 배포를 자동화할 수 있습니다. App Service 및 Functions에 배포하는 방법에 대한 자세한 내용은 App Service에서 리소스 배포 자동화 및 Azure Functions에서 리소스 배포 자동화를 참조하세요.

모든 Microsoft.Web/sites 유형의 리소스는 ID를 사용하여 리소스 정의에 다음 속성을 포함하는 방법으로 만들 수 있습니다.

"identity": {
    "type": "SystemAssigned"
}

시스템 할당 형식을 추가하면 애플리케이션에 대한 ID를 만들어서 관리하라고 Azure에 알려주는 것입니다.

예를 들어 웹앱의 템플릿은 다음 JSON과 같을 수 있습니다.

{
    "apiVersion": "2022-03-01",
    "type": "Microsoft.Web/sites",
    "name": "[variables('appName')]",
    "location": "[resourceGroup().location]",
    "identity": {
        "type": "SystemAssigned"
    },
    "properties": {
        "name": "[variables('appName')]",
        "serverFarmId": "[resourceId('Microsoft.Web/serverfarms', variables('hostingPlanName'))]",
        "hostingEnvironment": "",
        "clientAffinityEnabled": false,
        "alwaysOn": true
    },
    "dependsOn": [
        "[resourceId('Microsoft.Web/serverfarms', variables('hostingPlanName'))]"
    ]
}

사이트가 생성되면 다음과 같은 추가 속성이 있습니다.

"identity": {
    "type": "SystemAssigned",
    "tenantId": "<tenant-id>",
    "principalId": "<principal-id>"
}

tenantId 속성은 ID가 속한 Microsoft Entra 테넌트를 식별합니다. principalId는 애플리케이션 새 ID의 고유 식별자입니다. Microsoft Entra ID 내에서 서비스 주체는 사용자가 App Service 또는 Azure Functions 인스턴스에 지정한 이름과 동일한 이름을 갖습니다.

템플릿의 이후 단계에서 이러한 속성을 참조해야 하는 경우 다음 예제와 같이 'Full' 플래그를 사용하여 reference()템플릿 함수를 통해 수행할 수 있습니다.

{
    "tenantId": "[reference(resourceId('Microsoft.Web/sites', variables('appName')), '2018-02-01', 'Full').identity.tenantId]",
    "objectId": "[reference(resourceId('Microsoft.Web/sites', variables('appName')), '2018-02-01', 'Full').identity.principalId]",
}

사용자 할당 ID 추가

사용자 할당 ID로 앱을 만들려면 ID를 만든 다음, 앱 구성에 리소스 ID를 추가해야 합니다.

먼저, 사용자 할당 ID 리소스를 만들어야 합니다.

이러한 지침에 따라 사용자 할당 관리 ID 리소스를 만듭니다.
앱 페이지의 왼쪽 탐색 영역에서 설정 그룹으로 아래로 스크롤합니다.
ID를 선택합니다.
사용자 할당>추가를 선택합니다.
이전에 만든 ID를 검색하여 선택한 후 추가를 선택합니다.

추가를 선택하면 앱이 다시 시작됩니다.

사용자 할당 ID를 만듭니다.

az identity create --resource-group <group-name> --name <identity-name>

az webapp identity assign 명령을 실행하여 앱에 ID를 할당합니다.

az webapp identity assign --resource-group <group-name> --name <app-name> --identities <identity-id>

App Service의 경우

App Service에서 사용자 할당 ID 추가는 현재 지원되지 않습니다.

함수의 경우

사용자 할당 ID를 만듭니다.

Install-Module -Name Az.ManagedServiceIdentity -AllowPrerelease
$userAssignedIdentity = New-AzUserAssignedIdentity -Name $userAssignedIdentityName -ResourceGroupName <group-name>

Update-AzFunctionApp -IdentityType UserAssigned -IdentityId 명령을 실행하여 함수에 ID를 할당합니다.

Update-AzFunctionApp -Name <app-name> -ResourceGroupName <group-name> -IdentityType UserAssigned -IdentityId $userAssignedIdentity.Id

모든 Microsoft.Web/sites 형식의 리소스는 <resource-id>를 원하는 ID의 리소스 ID로 바꿔 리소스 정의에 다음 블록을 포함한 ID로 만들 수 있습니다.

"identity": {
    "type": "UserAssigned",
    "userAssignedIdentities": {
        "<resource-id>": {}
    }
}

참고 항목

애플리케이션에는 시스템 할당 ID와 사용자 할당 ID 둘 다 동시에 있을 수 있습니다. 이 경우에 type 속성이 SystemAssigned,UserAssigned가 됩니다.

사용자 할당 형식을 추가하면 Azure에서 애플리케이션에 대해 지정된 사용자 할당 ID를 사용하도록 지시하게 됩니다.

예를 들어 웹앱의 템플릿은 다음 JSON과 같을 수 있습니다.

{
    "apiVersion": "2022-03-01",
    "type": "Microsoft.Web/sites",
    "name": "[variables('appName')]",
    "location": "[resourceGroup().location]",
    "identity": {
        "type": "UserAssigned",
        "userAssignedIdentities": {
            "[resourceId('Microsoft.ManagedIdentity/userAssignedIdentities', variables('identityName'))]": {}
        }
    },
    "properties": {
        "name": "[variables('appName')]",
        "serverFarmId": "[resourceId('Microsoft.Web/serverfarms', variables('hostingPlanName'))]",
        "hostingEnvironment": "",
        "clientAffinityEnabled": false,
        "alwaysOn": true
    },
    "dependsOn": [
        "[resourceId('Microsoft.Web/serverfarms', variables('hostingPlanName'))]",
        "[resourceId('Microsoft.ManagedIdentity/userAssignedIdentities', variables('identityName'))]"
    ]
}

사이트가 생성되면 다음과 같은 추가 속성이 있습니다.

"identity": {
    "type": "UserAssigned",
    "userAssignedIdentities": {
        "<resource-id>": {
            "principalId": "<principal-id>",
            "clientId": "<client-id>"
        }
    }
}

principalId는 Microsoft Entra 관리에 사용되는 ID의 고유 식별자입니다. clientId는 런타임 호출 중 사용할 ID 지정에 사용하는 애플리케이션의 새 ID에 대한 고유 식별자입니다.

대상 리소스 구성

앱 또는 함수의 액세스를 허용하도록 대상 리소스를 구성해야 할 수 있습니다. 예를 들어 Key Vault에 액세스하기 위한 토큰을 요청하는 경우 앱 또는 함수의 관리 ID를 포함하는 액세스 정책도 추가해야 합니다. 그렇지 않으면 유효한 토큰을 사용하는 경우에도 Key Vault에 대한 호출이 거부됩니다. Azure SQL Database에서도 마찬가지입니다. Microsoft Entra 토큰을 지원하는 리소스에 대한 자세한 내용은 Microsoft Entra 인증을 지원하는 Azure 서비스를 참조하세요.

Important

관리 ID에 대한 백 엔드 서비스는 약 24시간 동안 리소스 URI당 캐시를 유지합니다. 즉, 관리 ID의 그룹 또는 역할 멤버 자격에 대한 변경 내용이 적용되는 데 몇 시간이 걸릴 수 있습니다. 현재는 관리 ID의 토큰이 만료되기 전에 강제로 새로 고칠 수 없습니다. 관리 ID의 그룹 또는 역할 멤버 자격을 변경하여 권한을 추가하거나 제거하는 경우, 해당 ID를 사용하는 Azure 리소스에 올바른 액세스 권한이 부여될 때까지 몇 시간 동안 기다려야 할 수 있습니다. 그룹 또는 역할 멤버 자격에 대한 대안은 권한 부여에 관리 ID 사용 제한을 참조하세요.

앱 코드에서 Azure 서비스에 커넥트

앱은 관리 ID를 사용하여 Azure SQL Database, Azure Key Vault 및 Azure Storage와 같은 Microsoft Entra ID로 보호되는 Azure 리소스에 대한 토큰을 가져올 수 있습니다. 이러한 토큰은 애플리케이션의 특정 사용자가 아닌 리소스에 액세스하는 애플리케이션을 나타냅니다.

App Service 및 Azure Functions는 토큰 검색을 위해 내부적으로 액세스할 수 있는 REST 엔드포인트를 제공합니다. REST 엔드포인트는 모든 언어의 일반 HTTP 클라이언트를 사용하여 구현할 수 있는 표준 HTTP GET을 사용하여 앱 내에서 액세스할 수 있습니다. .NET, JavaScript, Java, Python의 경우 Azure ID 클라이언트 라이브러리는 이 REST 엔드포인트에 대한 추상화 기능을 제공하고 개발 환경을 간소화합니다. 다른 Azure 서비스에 연결하는 것은 서비스별 클라이언트에 자격 증명 개체를 추가하는 것만큼 간단합니다.

원시 HTTP GET 요청은 제공된 두 환경 변수를 사용하며 다음 예제와 같습니다.

GET /MSI/token?resource=https://vault.azure.net&api-version=2019-08-01 HTTP/1.1
Host: <ip-address-:-port-in-IDENTITY_ENDPOINT>
X-IDENTITY-HEADER: <value-of-IDENTITY_HEADER>

샘플 응답은 다음과 유사할 수 있습니다.

HTTP/1.1 200 OK
Content-Type: application/json

{
    "access_token": "eyJ0eXAi…",
    "expires_on": "1586984735",
    "resource": "https://vault.azure.net",
    "token_type": "Bearer",
    "client_id": "00001111-aaaa-2222-bbbb-3333cccc4444"
}

이 응답은 Microsoft Entra 서비스 간 액세스 토큰 요청에 대한 응답과 동일합니다. Key Vault에 액세스하려면 자격 증명 모음을 사용하여 클라이언트 연결에 access_token 값을 추가합니다.

참고 항목

Entity Framework Core를 사용하여 Azure SQL 데이터 원본에 연결할 때 관리 ID 연결에 특별한 연결 문자열을 제공하는 Microsoft.Data.SqlClient를 사용하는 것이 좋습니다. 예제는 자습서: 관리 ID를 사용하여 App Service에서 Azure SQL Database 연결 보호를 참조하세요.

.NET 앱 및 함수의 경우 .NET용 Azure ID 클라이언트 라이브러리를 통해 관리 ID를 사용하는 것이 가장 간단한 방법입니다. 자세한 지침은 자습서: 관리 ID를 사용하여 비밀 없이 App Service에서 Azure 데이터베이스에 연결을 참조하세요.

자세한 내용은 클라이언트 라이브러리의 해당 설명서 제목을 참조하세요.

연결된 예제에서는 DefaultAzureCredential을 사용합니다. 동일한 패턴이 Azure(관리 ID 포함) 및 로컬 머신(관리 ID 제외)에서 작동하기 때문에 대부분의 시나리오에 유용합니다.

Node.js 앱 및 JavaScript 함수의 경우 JavaScript용 Azure ID 클라이언트 라이브러리를 통해 관리 ID를 사용하는 것이 가장 간단한 방법입니다. 자세한 지침은 자습서: 관리 ID를 사용하여 비밀 없이 App Service에서 Azure 데이터베이스에 연결을 참조하세요.

자세한 내용은 클라이언트 라이브러리의 해당 설명서 제목을 참조하세요.

JavaScript용 Azure ID 클라이언트 라이브러리의 코드 예제에 대한 자세한 내용은 Azure ID 예제를 참조하세요.

Python 앱 및 함수의 경우 Python용 Azure ID 클라이언트 라이브러리를 통해 관리 ID를 사용하는 것이 가장 간단한 방법입니다. 자세한 지침은 자습서: 관리 ID를 사용하여 비밀 없이 App Service에서 Azure 데이터베이스에 연결을 참조하세요.

자세한 내용은 클라이언트 라이브러리의 해당 설명서 제목을 참조하세요.

Java 앱 및 함수의 경우 Java용 Azure ID 클라이언트 라이브러리를 통해 관리 ID를 사용하는 것이 가장 간단한 방법입니다. 자세한 지침은 자습서: 관리 ID를 사용하여 비밀 없이 App Service에서 Azure 데이터베이스에 연결을 참조하세요.

자세한 내용은 클라이언트 라이브러리의 해당 설명서 제목을 참조하세요.

Java용 Azure ID 클라이언트 라이브러리의 코드 예제에 대한 자세한 내용은 Azure ID 예제를 참조하세요.

다음 스크립트를 사용하여 Azure 서비스의 리소스 URI를 지정하여 로컬 엔드포인트에서 토큰을 검색합니다.

$resourceURI = "https://<AAD-resource-URI-for-resource-to-obtain-token>"
$tokenAuthURI = $env:IDENTITY_ENDPOINT + "?resource=$resourceURI&api-version=2019-08-01"
$tokenResponse = Invoke-RestMethod -Method Get -Headers @{"X-IDENTITY-HEADER"="$env:IDENTITY_HEADER"} -Uri $tokenAuthURI
$accessToken = $tokenResponse.access_token

REST 엔드포인트에 대한 자세한 내용은 REST 엔드포인트 참조를 참조하세요.

ID 제거

시스템 할당 ID를 제거하면 Microsoft Entra ID에서 삭제됩니다. 앱 리소스 자체를 삭제하면 시스템 할당 ID도 Microsoft Entra ID에서 자동으로 제거됩니다.

앱 페이지의 왼쪽 탐색 영역에서 설정 그룹으로 아래로 스크롤합니다.
ID를 선택합니다. 그런 다음, ID 유형에 따라 단계를 수행합니다.
- 시스템 할당 ID: 시스템 할당 탭 내에서 상태를 끄기로 전환합니다. 저장을 클릭합니다.
- 사용자 할당 ID: 사용자 할당 탭을 선택하고 ID에 대한 확인란을 선택한 다음, 제거를 선택합니다. 예를 선택하여 확인합니다.

시스템 할당 ID를 제거하려면 다음을 수행합니다.

az webapp identity remove --name <app-name> --resource-group <group-name>

하나 이상의 사용자 할당 ID를 제거하려면 다음을 수행합니다.

az webapp identity remove --name <app-name> --resource-group <group-name> --identities <identity-id1> <identity-id2> ...

--identities에서 [system]을 지정하여 시스템 할당 ID를 제거할 수도 있습니다.

App Service의 경우

Set-AzWebApp -AssignIdentity 명령을 실행하여 App Service에 대한 시스템 할당 ID를 제거합니다.

Set-AzWebApp -AssignIdentity $false -Name <app-name> -ResourceGroupName <group-name>

함수의 경우

Azure PowerShell에서 모든 ID를 제거하는 방법(Azure Functions만 해당):

# Update an existing function app to have IdentityType "None".
Update-AzFunctionApp -Name $functionAppName -ResourceGroupName $resourceGroupName -IdentityType None

ARM 템플릿에서 모든 ID를 제거하려면 다음을 수행합니다.

"identity": {
    "type": "None"
}

참고 항목

설정할 수 있는 애플리케이션 설정인 WEBSITE_DISABLE_MSI도 있으며 이것은 로컬 토큰 서비스를 비활성화합니다. 그러나 ID는 그대로 두고 도구는 관리 ID를 “켜짐” 또는 “사용”으로 표시합니다. 따라서 이 설정을 사용하지 않는 것이 좋습니다.

REST 엔드포인트 참조

관리 ID가 있는 앱은 다음 두 가지 환경 변수를 정의하여 이 엔드포인트를 사용할 수 있도록 합니다.

IDENTITY_ENDPOINT - 로컬 토큰 서비스의 URL입니다.
IDENTITY_HEADER - SSRF(서버 쪽 요청 위조) 공격을 완화하는 데 사용되는 헤더입니다. 플랫폼에서 값을 회전합니다.

IDENTITY_ENDPOINT는 앱이 토큰을 요청할 수 있는 로컬 URL입니다. 리소스 토큰을 가져오려면 이 엔드포인트에 다음 매개 변수를 포함하여 HTTP GET 요청을 보냅니다.

매개 변수 이름 In 설명

resource 쿼리 토큰을 가져와야 하는 리소스의 Microsoft Entra 리소스 URI입니다. Microsoft Entra 인증 또는 다른 리소스 URI를 지원하는 Azure 서비스 중 하나일 수 있습니다.

api-version 쿼리 사용할 토큰 API의 버전입니다. 2019-08-01을 사용합니다.

X-IDENTITY-HEADER 헤더 IDENTITY_HEADER 환경 변수의 값입니다. 이 헤더는 SSRF(서버 쪽 요청 위조) 공격을 완화하는 데 사용됩니다.

client_id 쿼리 (선택 사항) 사용할 사용자 할당 ID의 클라이언트 ID입니다. principal_id, mi_res_id 또는 object_id를 포함하는 요청에 사용할 수 없습니다. 모든 ID 매개 변수(client_id, principal_id, object_id 및 mi_res_id)가 생략될 경우 시스템 할당 ID가 사용됩니다.

principal_id 쿼리 (선택 사항) 사용할 사용자 할당 ID의 보안 주체 ID입니다. object_id는 대신 사용할 수 있는 별칭입니다. client_id, mi_res_id 또는 object_id를 포함하는 요청에 사용할 수 없습니다. 모든 ID 매개 변수(client_id, principal_id, object_id 및 mi_res_id)가 생략될 경우 시스템 할당 ID가 사용됩니다.

mi_res_id 쿼리 (선택 사항) 사용할 사용자 할당 ID의 Azure 리소스 ID입니다. principal_id, client_id 또는 object_id를 포함하는 요청에 사용할 수 없습니다. 모든 ID 매개 변수(client_id, principal_id, object_id 및 mi_res_id)가 생략될 경우 시스템 할당 ID가 사용됩니다.

매개 변수 이름	In	설명
resource	쿼리	토큰을 가져와야 하는 리소스의 Microsoft Entra 리소스 URI입니다. Microsoft Entra 인증 또는 다른 리소스 URI를 지원하는 Azure 서비스 중 하나일 수 있습니다.
api-version	쿼리	사용할 토큰 API의 버전입니다. `2019-08-01`을 사용합니다.
X-IDENTITY-HEADER	헤더	IDENTITY_HEADER 환경 변수의 값입니다. 이 헤더는 SSRF(서버 쪽 요청 위조) 공격을 완화하는 데 사용됩니다.
client_id	쿼리	(선택 사항) 사용할 사용자 할당 ID의 클라이언트 ID입니다. `principal_id`, `mi_res_id` 또는 `object_id`를 포함하는 요청에 사용할 수 없습니다. 모든 ID 매개 변수(`client_id`, `principal_id`, `object_id` 및 `mi_res_id`)가 생략될 경우 시스템 할당 ID가 사용됩니다.
principal_id	쿼리	(선택 사항) 사용할 사용자 할당 ID의 보안 주체 ID입니다. `object_id`는 대신 사용할 수 있는 별칭입니다. client_id, mi_res_id 또는 object_id를 포함하는 요청에 사용할 수 없습니다. 모든 ID 매개 변수(`client_id`, `principal_id`, `object_id` 및 `mi_res_id`)가 생략될 경우 시스템 할당 ID가 사용됩니다.
mi_res_id	쿼리	(선택 사항) 사용할 사용자 할당 ID의 Azure 리소스 ID입니다. `principal_id`, `client_id` 또는 `object_id`를 포함하는 요청에 사용할 수 없습니다. 모든 ID 매개 변수(`client_id`, `principal_id`, `object_id` 및 `mi_res_id`)가 생략될 경우 시스템 할당 ID가 사용됩니다.

Important

사용자 할당 ID에 대한 토큰을 가져오려고 시도하는 경우 선택적 속성 중 하나를 포함해야 합니다. 그러지 않으면 토큰 서비스는 시스템 할당 ID에 대한 토큰을 가져오려고 시도하는데 이는 존재 여부가 불분명합니다.

다음을 통해 공유

App Service 및 Azure Functions에 대한 관리 ID를 사용하는 방법

시스템 할당 ID 추가

App Service의 경우

함수의 경우

사용자 할당 ID 추가

App Service의 경우

함수의 경우

대상 리소스 구성

앱 코드에서 Azure 서비스에 커넥트

ID 제거

App Service의 경우

함수의 경우

REST 엔드포인트 참조

다음 단계

피드백

추가 리소스