Azure API Management에서 관리 되는 id 사용Use managed identities in Azure API Management

이 문서에서는 Azure API Management 인스턴스에 대 한 관리 되는 id를 만드는 방법과 다른 리소스에 액세스 하는 방법을 보여 줍니다.This article shows you how to create a managed identity for an Azure API Management instance and how to access other resources. Azure Active Directory (Azure AD)에서 생성 된 관리 되는 id를 사용 하면 API Management 인스턴스가 Azure Key Vault 같은 다른 Azure AD 보호 리소스에 쉽고 안전 하 게 액세스할 수 있습니다.A managed identity generated by Azure Active Directory (Azure AD) allows your API Management instance to easily and securely access other Azure AD-protected resources, such as Azure Key Vault. Azure에서이 id를 관리 하므로 암호를 프로 비전 하거나 회전할 필요가 없습니다.Azure manages this identity, so you don't have to provision or rotate any secrets. 관리 id에 대 한 자세한 내용은 Azure 리소스에 대 한 관리 되는 Id 란?을 참조 하세요.For more information about managed identities, see What are managed identities for Azure resources?.

두 가지 유형의 id를 API Management 인스턴스에 부여할 수 있습니다.You can grant two types of identities to an API Management instance:

  • 시스템 할당 id 는 서비스에 연결 되며, 서비스가 삭제 되 면 삭제 됩니다.A system-assigned identity is tied to your service and is deleted if your service is deleted. 서비스에는 시스템 할당 id가 하나만 있을 수 있습니다.The service can have only one system-assigned identity.
  • 사용자 할당 id 는 서비스에 할당할 수 있는 독립 실행형 Azure 리소스입니다.A user-assigned identity is a standalone Azure resource that can be assigned to your service. 서비스에는 사용자가 할당 된 id가 여러 개 있을 수 있습니다.The service can have multiple user-assigned identities.

시스템 할당 관리 id 만들기Create a system-assigned managed identity

Azure portalAzure portal

Azure Portal에서 관리 되는 id를 설정 하려면 먼저 API Management 인스턴스를 만든 후 기능을 사용 하도록 설정 합니다.To set up a managed identity in the Azure portal, you'll first create an API Management instance and then enable the feature.

  1. 평소처럼 포털에서 API Management 인스턴스를 만듭니다.Create an API Management instance in the portal as you normally would. 포털에서 찾습니다.Browse to it in the portal.

  2. 관리 id를 선택 합니다.Select Managed identities.

  3. 시스템 할당 됨 탭에서 상태켜기로 전환 합니다.On the System assigned tab, switch Status to On. 저장을 선택합니다.Select Save.

    시스템 할당 관리 id 사용을 위한 선택 항목

Azure PowerShellAzure PowerShell

참고

이 문서는 새 Azure PowerShell Az 모듈을 사용하도록 업데이트되었습니다.This article has been updated to use the new Azure PowerShell Az module. AzureRM 모듈은 적어도 2020년 12월까지 버그 수정을 수신할 예정이므로 계속 사용하셔도 됩니다.You can still use the AzureRM module, which will continue to receive bug fixes until at least December 2020. 새 Az 모듈 및 AzureRM 호환성에 대한 자세한 내용은 새 Azure PowerShell Az 모듈 소개를 참조하세요.To learn more about the new Az module and AzureRM compatibility, see Introducing the new Azure PowerShell Az module. Az 모듈 설치 지침은 Azure PowerShell 설치를 참조하세요.For Az module installation instructions, see Install Azure PowerShell.

다음 단계에서는 API Management 인스턴스를 만들고 Azure PowerShell를 사용 하 여 id를 할당 하는 과정을 안내 합니다.The following steps walk you through creating an API Management instance and assigning it an identity by using Azure PowerShell.

  1. 필요한 경우 Azure PowerShell 가이드의 지침을 사용 하 여 Azure PowerShell를 설치 합니다.If needed, install Azure PowerShell by using the instructions in the Azure PowerShell guide. 그런 다음 Connect-AzAccount 를 실행 하 여 Azure에 대 한 연결을 만듭니다.Then run Connect-AzAccount to create a connection with Azure.

  2. 다음 코드를 사용 하 여 인스턴스를 만듭니다.Use the following code to create the instance. API Management 인스턴스와 Azure PowerShell를 사용 하는 방법에 대 한 자세한 예제는 API Management PowerShell 샘플을 참조 하세요.For more examples of how to use Azure PowerShell with an API Management instance, see API Management PowerShell samples.

    # 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
    
  3. 기존 인스턴스를 업데이트 하 여 id를 만듭니다.Update an existing instance to create the identity:

    # 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 템플릿Azure Resource Manager template

API Management 인스턴스는 ID를 사용하여 리소스 정의에 다음 속성을 포함하는 방법으로 만들 수 있습니다.You can create an API Management instance with an identity by including the following property in the resource definition:

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

이 속성에 의해 Azure에서 API Management 인스턴스에 대한 ID를 만들어서 관리합니다.This property tells Azure to create and manage the identity for your API Management instance.

예를 들어 전체 Azure Resource Manager 템플릿은 다음과 같이 보일 수 있습니다.For example, a complete Azure Resource Manager template might look like the following:

{
    "$schema": "https://schema.management.azure.com/schemas/2014-04-01-preview/deploymentTemplate.json#",
    "contentVersion": "0.9.0.0",
    "resources": [{
        "apiVersion": "2019-01-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"
        }
    }]
}

인스턴스가 생성 되 면 다음과 같은 추가 속성이 있습니다.When the instance is created, it has the following additional properties:

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

tenantId속성은 id가 속하는 AZURE AD 테 넌 트를 식별 합니다.The tenantId property identifies what Azure AD tenant the identity belongs to. principalId속성은 인스턴스의 새 id에 대 한 고유 식별자입니다.The principalId property is a unique identifier for the instance's new identity. Azure AD 내에서 서비스 주체는 API Management 인스턴스에 제공한 이름과 동일 합니다.Within Azure AD, the service principal has the same name that you gave to your API Management instance.

참고

API Management 인스턴스에는 시스템 할당 id와 사용자 할당 id가 동시에 있을 수 있습니다.An API Management instance can have both system-assigned and user-assigned identities at the same time. 이 경우 type 속성은 SystemAssigned,UserAssigned 입니다.In this case, the type property would be SystemAssigned,UserAssigned.

지원되는 시나리오Supported scenarios

Azure Key Vault에서 API Management 인스턴스에 대 한 사용자 지정 TLS/SSL 인증서를 가져옵니다.Obtain a custom TLS/SSL certificate for the API Management instance from Azure Key Vault

API Management 인스턴스의 시스템 할당 id를 사용 하 여 Azure Key Vault에 저장 된 사용자 지정 TLS/SSL 인증서를 검색할 수 있습니다.You can use the system-assigned identity of an API Management instance to retrieve custom TLS/SSL certificates stored in Azure Key Vault. 그런 다음 API Management 인스턴스의 사용자 지정 도메인에 이러한 인증서를 할당할 수 있습니다.You can then assign these certificates to custom domains in the API Management instance. 다음 고려 사항을 염두에 두십시오.Keep these considerations in mind:

  • 비밀의 콘텐츠 형식은 application/x pkcs12이어야 합니다.The content type of the secret must be application/x-pkcs12.
  • 비밀을 포함 하는 Key Vault 인증서 비밀 끝점을 사용 합니다.Use the Key Vault certificate secret endpoint, which contains the secret.

중요

인증서의 개체 버전을 제공 하지 않으면 API Management는 Key Vault에서 업데이트 된 후 4 시간 이내에 최신 버전의 인증서를 자동으로 가져옵니다.If you don't provide the object version of the certificate, API Management will automatically obtain the newer version of the certificate within four hours after it's updated in Key Vault.

다음 예제에서는 다음 단계를 포함하는 Azure Resource Manager 템플릿을 보여줍니다.The following example shows an Azure Resource Manager template that contains the following steps:

  1. 관리 id를 사용 하 여 API Management 인스턴스를 만듭니다.Create an API Management instance with a managed identity.
  2. Azure Key Vault 인스턴스의 액세스 정책을 업데이트하고 API Management 인스턴스가 비밀을 가져올 수 있도록 허용합니다.Update the access policies of an Azure Key Vault instance and allow the API Management instance to obtain secrets from it.
  3. Key Vault 인스턴스의 인증서를 통해 사용자 지정 도메인 이름을 설정하여 API Management 인스턴스를 업데이트합니다.Update the API Management instance by setting a custom domain name through a certificate from the Key Vault instance.
{
    "$schema": "https://schema.management.azure.com/schemas/2015-01-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": "Proxy 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": "2019-01-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"]
                }
            }]
        }
    },
    {
        "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')]"}
            }
        }
    }]
}

API Management id를 사용 하 여 백 엔드에 인증Authenticate to the back end by using an API Management identity

시스템이 할당 한 id를 사용 하 여 인증 관리 id 정책을 통해 백 엔드에 인증할 수 있습니다.You can use the system-assigned identity to authenticate to the back end through the authentication-managed-identity policy.

사용자 할당 관리 ID 만들기Create a user-assigned managed identity

참고

사용자 할당 관리 id를 최대 10 개까지 API Management 인스턴스를 연결할 수 있습니다.You can associate an API Management instance with up to 10 user-assigned managed identities.

Azure portalAzure portal

포털에서 관리 id를 설정 하려면 먼저 API Management 인스턴스를 만든 후 기능을 사용 하도록 설정 합니다.To set up a managed identity in the portal, you'll first create an API Management instance and then enable the feature.

  1. 평소처럼 포털에서 API Management 인스턴스를 만듭니다.Create an API Management instance in the portal as you normally would. 포털에서 찾습니다.Browse to it in the portal.

  2. 관리 id를 선택 합니다.Select Managed identities.

  3. 사용자 할당 됨 탭에서 추가를 선택 합니다.On the User assigned tab, select Add.

  4. 이전에 만든 id를 검색 하 여 선택 합니다.Search for the identity that you created earlier and select it. 추가를 선택합니다.Select Add.

    사용자 할당 관리 id 사용을 위한 선택 항목

Azure PowerShellAzure PowerShell

참고

이 문서는 새 Azure PowerShell Az 모듈을 사용하도록 업데이트되었습니다.This article has been updated to use the new Azure PowerShell Az module. AzureRM 모듈은 적어도 2020년 12월까지 버그 수정을 수신할 예정이므로 계속 사용하셔도 됩니다.You can still use the AzureRM module, which will continue to receive bug fixes until at least December 2020. 새 Az 모듈 및 AzureRM 호환성에 대한 자세한 내용은 새 Azure PowerShell Az 모듈 소개를 참조하세요.To learn more about the new Az module and AzureRM compatibility, see Introducing the new Azure PowerShell Az module. Az 모듈 설치 지침은 Azure PowerShell 설치를 참조하세요.For Az module installation instructions, see Install Azure PowerShell.

다음 단계에서는 API Management 인스턴스를 만들고 Azure PowerShell를 사용 하 여 id를 할당 하는 과정을 안내 합니다.The following steps walk you through creating an API Management instance and assigning it an identity by using Azure PowerShell.

  1. 필요한 경우 Azure PowerShell 가이드의 지침을 사용 하 여 Azure PowerShell를 설치 합니다.If needed, install the Azure PowerShell by using the instructions in the Azure PowerShell guide. 그런 다음 Connect-AzAccount 를 실행 하 여 Azure에 대 한 연결을 만듭니다.Then run Connect-AzAccount to create a connection with Azure.

  2. 다음 코드를 사용 하 여 인스턴스를 만듭니다.Use the following code to create the instance. API Management 인스턴스와 Azure PowerShell를 사용 하는 방법에 대 한 자세한 예제는 API Management PowerShell 샘플을 참조 하세요.For more examples of how to use Azure PowerShell with an API Management instance, see API Management PowerShell samples.

    # 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
    
  3. 서비스에 id를 할당 하도록 기존 서비스를 업데이트 합니다.Update an existing service to assign an identity to the service:

    # 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 템플릿Azure Resource Manager template

API Management 인스턴스는 ID를 사용하여 리소스 정의에 다음 속성을 포함하는 방법으로 만들 수 있습니다.You can create an API Management instance with an identity by including the following property in the resource definition:

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

사용자 할당 형식을 추가 하면 인스턴스에 지정 된 사용자 할당 id를 사용 하도록 Azure에 지시 합니다.Adding the user-assigned type tells Azure to use the user-assigned identity specified for your instance.

예를 들어 전체 Azure Resource Manager 템플릿은 다음과 같이 보일 수 있습니다.For example, a complete Azure Resource Manager template might look like the following:

{
    "$schema": "https://schema.management.azure.com/schemas/2014-04-01-preview/deploymentTemplate.json#",
    "contentVersion": "0.9.0.0",
    "resources": [{
        "apiVersion": "2019-12-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'))]"
        ]
    }]
}

서비스를 만들면 다음과 같은 추가 속성이 있습니다.When the service is created, it has the following additional properties:

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

principalId속성은 AZURE AD 관리에 사용 되는 id의 고유 식별자입니다.The principalId property is a unique identifier for the identity that's used for Azure AD administration. clientId속성은 런타임 호출 중에 사용할 id를 지정 하는 데 사용 되는 응용 프로그램의 새 id에 대 한 고유 식별자입니다.The clientId property is a unique identifier for the application's new identity that's used for specifying which identity to use during runtime calls.

참고

API Management 인스턴스에는 시스템 할당 id와 사용자 할당 id가 동시에 있을 수 있습니다.An API Management instance can have both system-assigned and user-assigned identities at the same time. 이 경우 type 속성은 SystemAssigned,UserAssigned 입니다.In this case, the type property would be SystemAssigned,UserAssigned.

지원되는 시나리오Supported scenarios

사용자 할당 id를 사용 하 여 백 엔드 인증Authenticate to the back end by using a user-assigned identity

사용자 할당 id를 사용 하 여 인증 관리 id 정책을 통해 백 엔드에 인증할 수 있습니다.You can use the user-assigned identity to authenticate to the back end through the authentication-managed-identity policy.

ID 제거Remove an identity

포털이 생성 된 것과 동일한 방식으로 포털 또는 Azure Resource Manager 템플릿을 통해 기능을 사용 하지 않도록 설정 하 여 시스템 할당 id를 제거할 수 있습니다.You can remove a system-assigned identity by disabling the feature through the portal or the Azure Resource Manager template in the same way that it was created. 사용자 할당 ID는 개별 제거할 수 있습니다.User-assigned identities can be removed individually. 모든 id를 제거 하려면 id 유형을로 설정 "None" 합니다.To remove all identities, set the identity type to "None".

이런 방식으로 시스템 할당 ID를 제거하면 Azure AD에서도 삭제됩니다.Removing a system-assigned identity in this way will also delete it from Azure AD. 시스템 할당 id는 API Management 인스턴스가 삭제 될 때 Azure AD 에서도 자동으로 제거 됩니다.System-assigned identities are also automatically removed from Azure AD when the API Management instance is deleted.

Azure Resource Manager 템플릿을 사용 하 여 모든 id를 제거 하려면이 섹션을 업데이트 합니다.To remove all identities by using the Azure Resource Manager template, update this section:

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

중요

Key Vault에서 사용자 지정 SSL 인증서를 사용 하 여 API Management 인스턴스를 구성 하 고 관리 되는 id를 사용 하지 않도록 설정 하려고 하면 요청이 실패 합니다.If an API Management instance is configured with a custom SSL certificate from Key Vault and you try to disable a managed identity, the request will fail.

Azure Key Vault 인증서에서 인라인 인코딩된 인증서로 전환 하 고 관리 되는 id를 사용 하지 않도록 설정 하 여 스스로 차단을 해제할 수 있습니다.You can unblock yourself by switching from an Azure Key Vault certificate to an inline encoded certificate, and then disabling the managed identity. 자세한 내용은 사용자 지정 도메인 이름 구성을 참조하세요.For more information, see Configure a custom domain name.

다음 단계Next steps

Azure 리소스에 대 한 관리 id에 대해 자세히 알아보세요.Learn more about managed identities for Azure resources: