Azure API Management의 관리 ID 사용

이 문서에서는 Azure API Management 인스턴스에 대한 관리 ID를 만드는 방법과 이를 사용하여 다른 리소스에 액세스하는 방법을 보여 줍니다. Azure AD(Azure Active Directory)에서 생성된 관리 ID를 사용하면 API Management 인스턴스에서 Azure Key Vault처럼 Azure AD로 보호되는 다른 리소스에 쉽고 안전하게 액세스할 수 있습니다. Azure에서 이 ID를 관리하므로 어떤 비밀도 프로비전하거나 회전할 필요가 없습니다. 관리 ID에 대한 자세한 내용은 Azure 리소스용 관리 ID란?을 참조하세요.

두 가지 유형의 ID를 API Management 인스턴스에 부여할 수 있습니다.

  • 시스템 할당 ID는 서비스에 연결되어 있어 해당 서비스를 삭제하면 이 ID도 삭제됩니다. 서비스에는 시스템 할당 ID가 하나만 있을 수 있습니다.
  • 사용자 할당 ID는 서비스에 할당할 수 있는 독립 실행형 Azure 리소스입니다. 서비스에는 여러 사용자 할당 ID가 있을 수 있습니다.

참고

관리 ID는 Azure 구독이 호스트되는 Azure AD 테넌트에 한정됩니다. 구독이 다른 디렉터리로 이동되면 업데이트되지 않습니다. 구독이 이동된 경우 ID를 다시 만들고 구성해야 합니다.

시스템에서 할당한 관리 ID 만들기

Azure portal

Azure Portal에서 관리 ID를 설정하려면 먼저 API Management 인스턴스를 만든 다음, 기능을 사용하도록 설정합니다.

  1. 평소처럼 포털에서 API Management 인스턴스를 만듭니다. 포털에서 찾아봅니다.

  2. 왼쪽 메뉴의 보안 아래에서 관리 ID를 선택합니다.

  3. 시스템 할당 탭에서 상태켜기로 바꿉니다. 저장을 선택합니다.

    Selections for enabling a system-assigned managed identity

Azure PowerShell

참고

이 문서에서는 Azure와 상호 작용하는 데 권장되는 PowerShell 모듈인 Azure Az PowerShell 모듈을 사용합니다. Az PowerShell 모듈을 시작하려면 Azure PowerShell 설치를 참조하세요. Az PowerShell 모듈로 마이그레이션하는 방법에 대한 자세한 내용은 Azure PowerShell을 AzureRM에서 Az로 마이그레이션을 참조하세요.

다음 단계에서는 API Management 인스턴스를 만들고 Azure PowerShell을 사용하여 ID를 할당하는 과정을 안내합니다.

  1. 필요한 경우 Azure PowerShell 가이드의 지침에 따라 Azure PowerShell을 설치합니다. 그런 다음, Connect-AzAccount를 실행하여 Azure와 연결합니다.

  2. 다음 코드를 사용하여 시스템 할당 관리 ID로 인스턴스를 만듭니다. API Management 인스턴스에서 Azure PowerShell을 사용하는 방법에 대한 예제는 API Management PowerShell 샘플을 참조하세요.

    # Create a resource group.
    New-AzResourceGroup -Name $resourceGroupName -Location $location
    
    # Create an API Management Consumption Sku service.
    New-AzApiManagement -ResourceGroupName $resourceGroupName -Name consumptionskuservice -Location $location -Sku Consumption -Organization contoso -AdminEmail contoso@contoso.com -SystemAssignedIdentity
    

기존 인스턴스를 업데이트하여 ID를 만들 수도 있습니다.

# Get an API Management instance
$apimService = Get-AzApiManagement -ResourceGroupName $resourceGroupName -Name $apiManagementName

# Update an API Management instance
Set-AzApiManagement -InputObject $apimService -SystemAssignedIdentity

Azure Resource Manager 템플릿

리소스 정의에 다음 속성을 포함하여 시스템 할당 ID로 API Management 인스턴스를 만들 수 있습니다.

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

이 속성에 의해 Azure에서 API Management 인스턴스에 대한 ID를 만들어서 관리합니다.

예를 들어 전체 Azure Resource Manager 템플릿은 다음과 같이 보일 수 있습니다.

{
    "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
    "contentVersion": "0.9.0.0",
    "resources": [{
        "apiVersion": "2021-08-01",
        "name": "contoso",
        "type": "Microsoft.ApiManagement/service",
        "location": "[resourceGroup().location]",
        "tags": {},
        "sku": {
            "name": "Developer",
            "capacity": "1"
        },
        "properties": {
            "publisherEmail": "admin@contoso.com",
            "publisherName": "Contoso"
        },
        "identity": {
            "type": "systemAssigned"
        }
    }]
}

인스턴스가 생성되면 다음과 같은 추가 속성이 있습니다.

"identity": {
    "type": "SystemAssigned",
    "tenantId": "<TENANTID>",
    "principalId": "<PRINCIPALID>"
}

tenantId 속성은 ID가 속한 Azure AD 테넌트를 식별합니다. principalId 속성은 인스턴스의 새 ID에 대한 고유 식별자입니다. Azure AD 내에서 서비스 주체는 사용자가 API Management 인스턴스에 지정한 이름과 동일한 이름을 갖습니다.

참고

API Management 인스턴스에는 시스템 할당 ID와 사용자 할당 ID 둘 다가 동시에 있을 수 있습니다. 이 경우에 type 속성이 SystemAssigned,UserAssigned가 됩니다.

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

API Management가 Key Vault의 비밀 및 인증서에 액세스하는 데 필요한 다음 구성을 참조하세요.

Key Vault 액세스 정책 구성

포털을 사용하여 액세스 정책을 구성하려면 다음을 수행합니다.

  1. Azure Portal에서 키 자격 증명 모음으로 이동합니다.
  2. 설정 > 액세스 정책 > + 액세스 정책 추가를 선택합니다.
  3. 비밀 권한을 선택한 다음 가져오기목록을 선택합니다.
  4. 보안 주체 선택을 선택하고, 관리 ID의 리소스 이름을 선택합니다. 시스템이 할당한 ID를 사용하는 경우 보안 주체는 API Management 인스턴스의 이름입니다.
  5. 추가를 선택합니다.

Key Vault 방화벽에 대한 요구 사항

키 자격 증명 모음에서 Key Vault 방화벽을 사용하도록 설정한 경우 추가 요구 사항은 다음과 같습니다.

  • 키 자격 증명 모음에 액세스하려면 API Management 인스턴스의 시스템 할당 관리 ID를 사용해야 합니다.

  • Key Vault 방화벽에서 신뢰할 수 있는 Microsoft 서비스가 이 방화벽을 우회하도록 허용 옵션을 사용하도록 설정합니다.

  • Azure API Management에 추가할 인증서 또는 비밀을 선택하는 동안 로컬 클라이언트 IP 주소가 키 자격 증명 모음에 일시적으로 액세스할 수 있는지 확인합니다. 자세한 내용은 Azure Key Vault 네트워킹 설정 구성을 참조하세요.

    구성을 완료한 후 키 자격 증명 모음 방화벽에서 클라이언트 주소를 차단할 수 있습니다.

가상 네트워크 요구 사항

API Management 인스턴스가 가상 네트워크에 배포된 경우 다음 네트워크 설정도 구성합니다.

  • API Management 서브넷에서 Azure Key Vault에 대한 서비스 엔드포인트를 사용하도록 설정합니다.
  • AzureKeyVault 및 AzureActiveDirectory 서비스 태그에 대한 아웃바운드 트래픽을 허용하도록 NSG(네트워크 보안 그룹) 규칙을 구성합니다.

자세한 내용은 VNet에서 Azure API Management를 설정할 때 네트워크 구성을 참조하세요.

시스템 할당 ID 사용의 지원되는 시나리오

Azure Key Vault에서 API Management 인스턴스에 대한 사용자 지정 TLS/SSL 인증서 가져오기

API Management 인스턴스의 시스템 할당 ID를 사용하여 Azure Key Vault에 저장된 사용자 지정 TLS/SSL 인증서를 검색할 수 있습니다. 그런 다음, API Management 인스턴스의 사용자 지정 도메인에 이러한 인증서를 할당할 수 있습니다. 다음 고려 사항을 염두에 두십시오.

  • 비밀의 콘텐츠 형식은 application/x-pkcs12이어야 합니다.
  • 비밀을 포함하는 Key Vault 인증서 비밀 엔드포인트를 사용합니다.

중요

인증서의 개체 버전을 제공하지 않으면 API Management가 Key Vault에서 업데이트된 후 4시간 이내에 최신 버전의 인증서를 자동으로 가져옵니다.

다음 예제에서는 다음 단계를 포함하는 Azure Resource Manager 템플릿을 보여줍니다.

  1. 관리 ID를 사용하여 API Management 인스턴스를 만듭니다.
  2. Azure Key Vault 인스턴스의 액세스 정책을 업데이트하고 API Management 인스턴스가 비밀을 가져올 수 있도록 허용합니다.
  3. Key Vault 인스턴스의 인증서를 통해 사용자 지정 도메인 이름을 설정하여 API Management 인스턴스를 업데이트합니다.
{
    "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
    "contentVersion": "1.0.0.0",
    "parameters": {
        "publisherEmail": {
            "type": "string",
            "minLength": 1,
            "metadata": {
                "description": "The email address of the owner of the service"
            }
        },
        "publisherName": {
            "type": "string",
            "defaultValue": "Contoso",
            "minLength": 1,
            "metadata": {
                "description": "The name of the owner of the service"
            }
        },
        "sku": {
            "type": "string",
            "allowedValues": ["Developer",
            "Standard",
            "Premium"],
            "defaultValue": "Developer",
            "metadata": {
                "description": "The pricing tier of this API Management instance"
            }
        },
        "skuCount": {
            "type": "int",
            "defaultValue": 1,
            "metadata": {
                "description": "The instance size of this API Management instance."
            }
        },
        "keyVaultName": {
            "type": "string",
            "metadata": {
                "description": "Name of the vault"
            }
        },
        "proxyCustomHostname1": {
            "type": "string",
            "metadata": {
                "description": "Gateway custom hostname."
            }
        },
        "keyVaultIdToCertificate": {
            "type": "string",
            "metadata": {
                "description": "Reference to the Key Vault certificate. https://contoso.vault.azure.net/secrets/contosogatewaycertificate."
            }
        }
    },
    "variables": {
        "apiManagementServiceName": "[concat('apiservice', uniqueString(resourceGroup().id))]",
        "apimServiceIdentityResourceId": "[concat(resourceId('Microsoft.ApiManagement/service', variables('apiManagementServiceName')),'/providers/Microsoft.ManagedIdentity/Identities/default')]"
    },
    "resources": [{
        "apiVersion": "2021-08-01",
        "name": "[variables('apiManagementServiceName')]",
        "type": "Microsoft.ApiManagement/service",
        "location": "[resourceGroup().location]",
        "tags": {
        },
        "sku": {
            "name": "[parameters('sku')]",
            "capacity": "[parameters('skuCount')]"
        },
        "properties": {
            "publisherEmail": "[parameters('publisherEmail')]",
            "publisherName": "[parameters('publisherName')]"
        },
        "identity": {
            "type": "systemAssigned"
        }
    },
    {
        "type": "Microsoft.KeyVault/vaults/accessPolicies",
        "name": "[concat(parameters('keyVaultName'), '/add')]",
        "apiVersion": "2015-06-01",
        "dependsOn": [
            "[resourceId('Microsoft.ApiManagement/service', variables('apiManagementServiceName'))]"
        ],
        "properties": {
            "accessPolicies": [{
                "tenantId": "[reference(variables('apimServiceIdentityResourceId'), '2015-08-31-PREVIEW').tenantId]",
                "objectId": "[reference(variables('apimServiceIdentityResourceId'), '2015-08-31-PREVIEW').principalId]",
                "permissions": {
                     "secrets": ["get", "list"]
                }
            }]
        }
    },
    {
        "apiVersion": "2017-05-10",
        "name": "apimWithKeyVault",
        "type": "Microsoft.Resources/deployments",
        "dependsOn": [
        "[resourceId('Microsoft.ApiManagement/service', variables('apiManagementServiceName'))]"
        ],
        "properties": {
            "mode": "incremental",
            "templateLink": {
                "uri": "https://raw.githubusercontent.com/solankisamir/arm-templates/master/basicapim.keyvault.json",
                "contentVersion": "1.0.0.0"
            },
            "parameters": {
                "publisherEmail": { "value": "[parameters('publisherEmail')]"},
                "publisherName": { "value": "[parameters('publisherName')]"},
                "sku": { "value": "[parameters('sku')]"},
                "skuCount": { "value": "[parameters('skuCount')]"},
                "proxyCustomHostname1": {"value" : "[parameters('proxyCustomHostname1')]"},
                "keyVaultIdToCertificate": {"value" : "[parameters('keyVaultIdToCertificate')]"}
            }
        }
    }]
}

Azure Key Vault에서 명명된 값 저장 및 관리

시스템 할당 관리 ID를 사용하여 Azure Key Vault에 액세스하여 API Management 정책에서 사용할 비밀을 저장하고 관리할 수 있습니다. 자세한 내용은 Azure API Management 정책에서 명명된 값 사용을 참조하세요.

API Management ID를 사용하여 백 엔드에 인증

시스템 할당 ID를 사용하여 인증 관리 ID 정책을 통해 백 엔드 서비스에 인증할 수 있습니다.

시스템 할당 관리 ID를 사용하여 IP 방화벽 뒤에 있는 Azure 리소스에 연결

API Management는 다음 리소스에 대한 신뢰할 수 있는 Microsoft 서비스입니다. 이를 통해 서비스는 방화벽 뒤에 있는 다음 리소스에 연결할 수 있습니다. 해당 리소스 인스턴스에 대한 시스템 할당 관리 ID에 적절한 Azure 역할을 명시적으로 할당한 후 인스턴스의 액세스 범위는 관리 ID에 할당된 Azure 역할에 해당합니다.

Azure 서비스 링크
Azure Key Vault Trusted-access-to-azure-key-vault
Azure Storage Trusted-access-to-azure-storage
Azure Service Bus Trusted-access-to-azure-service-bus
Azure Event Hub Trused-access-to-azure-event-hub

사용자 할당 관리 ID 만들기

참고

사용자 할당 관리 ID를 최대 10개까지 API Management 인스턴스를 연결할 수 있습니다.

Azure portal

포털에서 관리 ID를 설정하려면 먼저 API Management 인스턴스를 만들고 사용자 할당 ID를 만듭니다. 그런 다음, 기능을 사용하도록 설정합니다.

  1. 평소처럼 포털에서 API Management 인스턴스를 만듭니다. 포털에서 찾아봅니다.

  2. 왼쪽 메뉴의 보안 아래에서 관리 ID를 선택합니다.

  3. 사용자 할당 탭에서 추가를 클릭합니다.

  4. 이전에 만든 ID를 검색하고 이를 선택합니다. 추가를 선택합니다.

    Selections for enabling a user-assigned managed identity

Azure PowerShell

참고

이 문서에서는 Azure와 상호 작용하는 데 권장되는 PowerShell 모듈인 Azure Az PowerShell 모듈을 사용합니다. Az PowerShell 모듈을 시작하려면 Azure PowerShell 설치를 참조하세요. Az PowerShell 모듈로 마이그레이션하는 방법에 대한 자세한 내용은 Azure PowerShell을 AzureRM에서 Az로 마이그레이션을 참조하세요.

다음 단계에서는 API Management 인스턴스를 만들고 Azure PowerShell을 사용하여 ID를 할당하는 과정을 안내합니다.

  1. 필요한 경우 Azure PowerShell 가이드의 지침에 따라 Azure PowerShell을 설치합니다. 그런 다음, Connect-AzAccount를 실행하여 Azure와 연결합니다.

  2. 다음 코드를 사용하여 인스턴스를 만듭니다. API Management 인스턴스에서 Azure PowerShell을 사용하는 방법에 대한 예제는 API Management PowerShell 샘플을 참조하세요.

    # Create a resource group.
    New-AzResourceGroup -Name $resourceGroupName -Location $location
    
    # Create a user-assigned identity. This requires installation of the "Az.ManagedServiceIdentity" module.
    $userAssignedIdentity = New-AzUserAssignedIdentity -Name $userAssignedIdentityName -ResourceGroupName $resourceGroupName
    
    # Create an API Management Consumption Sku service.
    $userIdentities = @($userAssignedIdentity.Id)
    
    New-AzApiManagement -ResourceGroupName $resourceGroupName -Location $location -Name $apiManagementName -Organization contoso -AdminEmail admin@contoso.com -Sku Consumption -UserAssignedIdentity $userIdentities
    

기존 서비스를 업데이트하여 서비스에 ID를 할당할 수도 있습니다.

# Get an API Management instance
$apimService = Get-AzApiManagement -ResourceGroupName $resourceGroupName -Name $apiManagementName

# Create a user-assigned identity. This requires installation of the "Az.ManagedServiceIdentity" module.
$userAssignedIdentity = New-AzUserAssignedIdentity -Name $userAssignedIdentityName -ResourceGroupName $resourceGroupName

# Update an API Management instance
$userIdentities = @($userAssignedIdentity.Id)
Set-AzApiManagement -InputObject $apimService -UserAssignedIdentity $userIdentities

Azure Resource Manager 템플릿

API Management 인스턴스는 ID를 사용하여 리소스 정의에 다음 속성을 포함하는 방법으로 만들 수 있습니다.

"identity": {
    "type": "UserAssigned",
    "userAssignedIdentities": {
        "<RESOURCEID>": {}
    }
}

사용자 할당 형식을 추가하면 Azure에서 인스턴스에 대해 지정된 사용자 할당 ID를 사용하도록 지시하는 것입니다.

예를 들어 전체 Azure Resource Manager 템플릿은 다음과 같이 보일 수 있습니다.

{
    "$schema": "https://schema.management.azure.com/schemas/2014-04-01-preview/deploymentTemplate.json#",
    "contentVersion": "0.9.0.0",
    "resources": [{
        "apiVersion": "2021-08-01",
        "name": "contoso",
        "type": "Microsoft.ApiManagement/service",
        "location": "[resourceGroup().location]",
        "tags": {},
        "sku": {
            "name": "Developer",
            "capacity": "1"
        },
        "properties": {
            "publisherEmail": "admin@contoso.com",
            "publisherName": "Contoso"
        },
        "identity": {
            "type": "UserAssigned",
             "userAssignedIdentities": {
                "[resourceId('Microsoft.ManagedIdentity/userAssignedIdentities', variables('identityName'))]": {}
             }
        },
         "dependsOn": [
          "[resourceId('Microsoft.ManagedIdentity/userAssignedIdentities', variables('identityName'))]"
        ]
    }]
}

서비스가 생성되면 다음과 같은 추가 속성이 있습니다.

"identity": {
    "type": "UserAssigned",
    "userAssignedIdentities": {
        "<RESOURCEID>": {
            "principalId": "<PRINCIPALID>",
            "clientId": "<CLIENTID>"
        }
    }
}

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

참고

API Management 인스턴스에는 시스템 할당 ID와 사용자 할당 ID 둘 다가 동시에 있을 수 있습니다. 이 경우에 type 속성이 SystemAssigned,UserAssigned가 됩니다.

사용자 할당 관리 ID 사용의 지원되는 시나리오

Azure Key Vault에서 API Management 인스턴스에 대한 사용자 지정 TLS/SSL 인증서 가져오기

사용자 할당 ID를 사용하여 API Management 인스턴스와 Azure Key Vault 간의 트러스트를 설정할 수 있습니다. 그런 다음, 이 트러스트를 사용하여 Azure Key Vault에 저장된 사용자 지정 TLS/SSL 인증서를 검색할 수 있습니다. 그런 다음, API Management 인스턴스의 사용자 지정 도메인에 이러한 인증서를 할당할 수 있습니다.

중요

키 자격 증명 모음에서 Key Vault 방화벽이 활성화된 경우 사용자 할당 ID를 사용하여 API Management에서 액세스할 수 없습니다. 대신 시스템 할당 ID를 사용할 수 있습니다. Key Vault 방화벽에서 신뢰할 수 있는 Microsoft 서비스가 이 방화벽을 우회하도록 허용 옵션도 사용하도록 설정해야 합니다.

다음 고려 사항을 염두에 두십시오.

  • 비밀의 콘텐츠 형식은 application/x-pkcs12이어야 합니다.
  • 비밀을 포함하는 Key Vault 인증서 비밀 엔드포인트를 사용합니다.

중요

인증서의 개체 버전을 제공하지 않으면 API Management가 Key Vault에서 업데이트된 후 4시간 이내에 최신 버전의 인증서를 자동으로 가져옵니다.

전체 템플릿은 사용자 할당 ID 방식의 Key Vault 기반 SSL을 사용하는 API Management를 참조하세요.

이 서식 파일에서 다음을 배포합니다:

  • API Management 인스턴스
  • Azure 사용자 할당 관리 ID
  • SSL/TLS 인증서를 저장하기 위한 Azure Key Vault

배포를 자동으로 실행하려면 다음 단추를 클릭합니다.

Deploy to Azure

Azure Key Vault에서 명명된 값 저장 및 관리

사용자 할당 관리 ID를 사용하여 Azure Key Vault에 액세스하여 API Management 정책에서 사용할 비밀을 저장하고 관리할 수 있습니다. 자세한 내용은 Azure API Management 정책에서 명명된 값 사용을 참조하세요.

참고

키 자격 증명 모음에서 Key Vault 방화벽이 활성화된 경우 사용자 할당 ID를 사용하여 API Management에서 액세스할 수 없습니다. 대신 시스템 할당 ID를 사용할 수 있습니다. Key Vault 방화벽에서 신뢰할 수 있는 Microsoft 서비스가 이 방화벽을 우회하도록 허용 옵션도 사용하도록 설정해야 합니다.

사용자 할당 ID를 사용하여 백 엔드에 인증

사용자 할당 ID를 사용하여 인증 관리 ID 정책을 통해 백 엔드 서비스에 인증할 수 있습니다.

ID 제거

포털이 생성된 것과 동일한 방식으로 포털 또는 Azure Resource Manager 템플릿을 통해 기능을 사용하지 않도록 설정하여 시스템 할당 ID를 제거할 수 있습니다. 사용자 할당 ID는 개별 제거할 수 있습니다. 모든 ID를 제거하려면 ID 유형을 "None"으로 설정합니다.

이런 방식으로 시스템 할당 ID를 제거하면 Azure AD에서도 삭제됩니다. API Management 인스턴스가 삭제될 때 시스템 할당 ID도 Azure AD에서 자동으로 제거됩니다.

Azure Resource Manager 템플릿을 사용하여 모든 ID를 제거하려면 이 섹션을 업데이트합니다.

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

중요

Key Vault에서 사용자 지정 SSL 인증서를 사용하여 API Management 인스턴스를 구성하고 관리 ID를 사용하지 않도록 설정하려고 하면 요청이 실패합니다.

Azure Key Vault 인증서에서 인라인으로 인코딩된 인증서로 전환한 다음, 관리 ID를 사용하지 않도록 설정하여 스스로 차단을 해제할 수 있습니다. 자세한 내용은 사용자 지정 도메인 이름 구성을 참조하세요.

다음 단계

Azure 리소스의 관리 ID에 대해 자세히 알아보기