Azure API Management 정책에서 명명된 값 사용하기

적용 대상: 모든 API Management 계층

API Management 정책은 게시자가 구성을 통해 API 동작을 변경할 수 있도록 하는 시스템의 강력한 기능입니다. 정책은 API의 요청이나 응답에 따라 순차적으로 실행되는 명령문의 컬렉션입니다. 정책 설명은 리터럴 텍스트 값, 정책 식 및 명명된 값을 사용하여 생성할 수 있습니다.

명명된 값은 각 API Management 인스턴스에 이름/값 쌍의 전체 컬렉션입니다. 컬렉션의 항목 수에는 제한이 없습니다. 명명된 값은 모든 API 구성 및 정책에서 상수 문자열 값 및 비밀을 관리하는 데 사용할 수 있습니다.

값 형식

Type	설명
일반	리터럴 문자열 또는 정책 식
암호	API Management로 암호화된 리터럴 문자열 또는 정책 식
Key vault	Azure Key Vault에 저장된 비밀의 식별자입니다.

일반 값 또는 비밀에는 정책 식이포함될 수 있습니다. 예를 들어, 식은 @(DateTime.Now.ToString()) 현재 날짜 및 시간을 포함하는 문자열을 반환합니다.

명명된 값의 특성에 대한 세부 정보는 API Management REST API 참조를 참조하세요.

키 자격 증명 모음 비밀

비밀 값을 API Management(사용자 지정 비밀)에 암호화된 문자열로 저장하거나 Azure Key Vault에서 비밀을 참조할 수 있습니다.

API Management 보안 향상을 위해 키 자격 증명 모음 비밀을 사용하는 것이 좋습니다.

• 키 자격 증명 모음에 저장된 비밀은 서비스에서 재사용할 수 있습니다.
• 세분화된 액세스 정책을 비밀에 적용할 수 있습니다.
• 키 자격 증명 모음에서 업데이트한 비밀은 API Management에서 자동으로 회전됩니다. 키 자격 증명 모음에서 업데이트 후 명명된 값은 4시간 이내에 API Management에서 업데이트됩니다. Azure Portal 또는 Management REST API를 사용하여 비밀을 수동으로 새로 고칠 수도 있습니다.

참고 항목

API Management는 이 제한을 초과하는 값을 검색할 수 없으므로 Azure Key Vault에 저장된 비밀은 1자에서 4096자 사이여야 합니다.

필수 조건

• 아직 API Management 서비스 인스턴스를 만들지 않은 경우 API Management 서비스 인스턴스 만들기를 참조하세요.

키 자격 증명 모음 통합을 위한 사전 요구 사항

참고 항목

현재 이 기능은 작업 영역에서 사용할 수 없습니다.

• 아직 키 자격 증명 모음이 없으면 새로 만듭니다. 키 자격 증명 모음을 만드는 단계는 빠른 시작: Azure Portal을 사용하여 키 자격 증명 모음 만들기를 참조하세요.

  키 자격 증명 모음을 만들거나 비밀을 키 자격 증명 모음으로 가져오기 위해서는 빠른 시작: Azure Portal을 사용하여 Azure Key Vault에서 비밀 설정 및 검색을 참조하세요.

• API Management 인스턴스에서 시스템 또는 사용자가 할당한 관리 ID를 사용하도록 설정합니다.

키 자격 증명 모음에 대한 액세스 구성

1. 포털에서 키 자격 증명 모음으로 이동합니다.

2. 왼쪽 메뉴에서 액세스 구성을 선택하고 구성된 권한 모델을 기록해 둡니다.

3. 권한 모델에 따라 API Management 관리 ID에 대해 키 자격 증명 모음 액세스 정책 또는 Azure RBAC 액세스를 구성합니다.

   키 자격 증명 모음 액세스 정책을 추가하려면:
   

   1. 왼쪽 메뉴에서 액세스 정책을 선택합니다.
   2. 액세스 정책 페이지에서 + 만들기를 선택합니다.
   3. 권한 탭의 비밀 권한에서 가져오기 및 나열을 선택한 후 다음을 선택합니다.
   4. 보안 주체 탭에서 보안 주체를 선택하고, 관리 ID의 리소스 이름을 검색한 후, 다음을 선택합니다. 시스템이 할당한 ID를 사용하는 경우 보안 주체는 API Management 인스턴스의 이름입니다.
   5. 다음을 다시 선택합니다. 검토 + 만들기 탭에서 만들기를 선택합니다.

   Azure RBAC 액세스를 구성하려면:
   

   1. 왼쪽 메뉴에서 액세스 제어(IAM)를 선택합니다.
   2. 액세스 제어(IAM) 페이지에서 역할 할당 추가를 선택합니다.
   3. 역할 탭에서 Key Vault 인증서 사용자를 선택합니다.
   4. 멤버 탭에서 관리 ID>+ 멤버 선택을 선택합니다.
   5. 관리 ID 선택 페이지에서 시스템이 할당한 관리 ID 또는 API Management 인스턴스와 연결된 사용자가 할당한 관리 ID를 선택한 다음, 선택을 선택합니다.
   6. 검토 + 할당을 선택합니다.

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를 설정할 때 네트워크 구성을 참조하세요.

명명된 값을 추가 또는 편집하기

API Management에 키 자격 증명 모음 비밀 추가

키 자격 증명 모음 통합을 위한 필수 구성 요소를 참조하세요.

Important

API Management 인스턴스에 키 자격 증명 모음의 비밀을 추가할 때 키 자격 증명 모음의 비밀을 나열할 수 있는 권한이 있어야 합니다.

주의

API Management에서 키 자격 증명 모음 비밀을 사용하는 경우 액세스에 사용하는 비밀, 키 자격 증명 모음 또는 관리 ID를 삭제하지 않도록 주의합니다.

1. Azure Portal에서 API Management 인스턴스로 이동합니다.

2. API에서 명명된 값>+추가를 선택합니다.

3. 이름 식별자를 입력하고 정책에서 속성을 참조하는 데 사용하는 표시 이름을 입력합니다.

4. 값 형식에서 Key Vault를 선택합니다.

5. 키 자격 증명 모음 비밀의 식별자(버전 없음)를 입력하거나, 선택에서 키 자격 증명 모음 비밀을 선택합니다.

   Important

   키 자격 증명 모음 비밀 식별자를 직접 입력하는 경우 버전 정보를 포함해서는 안 됩니다. 이를 포함할 경우 키 자격 증명 모음을 업데이트한 후에 API Management에서 비밀이 자동으로 회전되지 않습니다.

6. 클라이언트 ID에서 시스템 또는 기존 사용자가 할당한 관리 ID를 선택합니다. API Management 서비스에서 관리 ID를 추가 또는 수정하는 방법에 대해 알아봅니다.

   참고 항목

   ID에는 키 자격 증명 모음에서 비밀을 가져오고 나열할 수 있는 권한이 필요합니다. 키 자격 증명 모음에 대한 액세스를 아직 구성하지 않은 경우 API Management는 필수적인 권한을 통해 ID를 자동으로 구성할 수 있도록 메시지를 표시합니다.

7. 하나 이상의 선택적 태그를 추가하여 명명된 값을 구성하고 저장하기를 선택합니다.

8. 만들기를 실행합니다.

   

API Management에 일반 또는 비밀 값 추가

포털

1. Azure Portal에서 API Management 인스턴스로 이동합니다.
2. API에서 명명된 값>+추가를 선택합니다.
3. 이름 식별자를 입력하고 정책에서 속성을 참조하는 데 사용하는 표시 이름을 입력합니다.
4. 값 형식에서 일반 또는 비밀을 선택합니다.
5. 값에 문자열 또는 정책 식을 입력합니다.
6. 하나 이상의 선택적 태그를 추가하여 명명된 값을 구성하고 저장하기를 선택합니다.
7. 만들기를 실행합니다.

명명된 값이 만들어지면 이를 선택하여 편집할 수 있습니다. 표시 이름을 변경하면 해당 명명된 값을 참조하는 모든 정책이 새 표시 이름을 사용하도록 자동으로 업데이트됩니다.

Azure CLI

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

• Azure Cloud Shell에서 Bash 환경을 사용합니다. 자세한 내용은 Azure Cloud Shell의 Bash에 대한 빠른 시작을 참조하세요.

  

• CLI 참조 명령을 로컬에서 실행하려면 Azure CLI를 설치합니다. Windows 또는 macOS에서 실행 중인 경우 Docker 컨테이너에서 Azure CLI를 실행하는 것이 좋습니다. 자세한 내용은 Docker 컨테이너에서 Azure CLI를 실행하는 방법을 참조하세요.

  • 로컬 설치를 사용하는 경우 az login 명령을 사용하여 Azure CLI에 로그인합니다. 인증 프로세스를 완료하려면 터미널에 표시되는 단계를 수행합니다. 다른 로그인 옵션은 Azure CLI를 사용하여 로그인을 참조하세요.

  • 메시지가 표시되면 처음 사용할 때 Azure CLI 확장을 설치합니다. 확장에 대한 자세한 내용은 Azure CLI에서 확장 사용을 참조하세요.

  • az version을 실행하여 설치된 버전과 종속 라이브러리를 찾습니다. 최신 버전으로 업그레이드하려면 az upgrade를 실행합니다.

명명된 값을 추가하려면 az apim nv create 명령을 사용합니다.

az apim nv create --resource-group apim-hello-word-resource-group \
    --display-name "named_value_01" --named-value-id named_value_01 \
    --secret true --service-name apim-hello-world --value test

명명된 값을 만든 후에는 az apim nv update 명령을 사용하여 업데이트할 수 있습니다. 모든 명명된 값을 보려면 az apim nv list 명령을 실행합니다.

az apim nv list --resource-group apim-hello-word-resource-group \
    --service-name apim-hello-world --output table

예제에서 만든 명명된 값의 세부 정보를 보려면 az apim nv show 명령을 실행합니다.

az apim nv show --resource-group apim-hello-word-resource-group \
    --service-name apim-hello-world --named-value-id named_value_01

이 예제는 비밀 값입니다. 이전 명령은 값을 반환하지 않습니다. 값을 확인하려면 az apim nv show-secret 명령을 실행합니다.

az apim nv show-secret --resource-group apim-hello-word-resource-group \
    --service-name apim-hello-world --named-value-id named_value_01

명명된 값을 삭제하려면 az apim nv delete 명령을 사용합니다.

az apim nv delete --resource-group apim-hello-word-resource-group \
    --service-name apim-hello-world --named-value-id named_value_01

명명된 값 사용하기

이 섹션의 예제에서는 다음 표에 표시된 명명된 값을 사용합니다.

속성	값	암호
ContosoHeader	TrackingId	False
ContosoHeaderValue	••••••••••••••••••••••	True
ExpressionProperty	@(DateTime.Now.ToString())	False
ContosoHeaderValue2	This is a header value.	False

정책에서 명명된 값을 사용하기 위해서는 다음 예제와 같이 해당 표시 이름을 이중괄호 쌍 안에 놓습니다(예: {{ContosoHeader}}).

<set-header name="{{ContosoHeader}}" exists-action="override">
  <value>{{ContosoHeaderValue}}</value>
</set-header>

이 예제에서 ContosoHeader는 set-header 정책의 헤더 이름으로 사용되고, ContosoHeaderValue는 해당 헤더의 값으로 사용됩니다. API Management 게이트웨이에 대한 요청이나 응답 중에 이 정책을 평가하는 경우 {{ContosoHeader}} 및 {{ContosoHeaderValue}}가 해당 값으로 바뀝니다.

명명된 값은 위 예제에 표시된 대로 전체 특성 또는 요소 값으로 사용될 수 있지만 다음 예제와 같이 리터럴 텍스트 식의 일부로 삽입되거나 결합될 수도 있습니다.

<set-header name = "CustomHeader{{ContosoHeader}}" ...>

또한 명명된 값은 정책 식을 포함할 수 있습니다. 다음 예제에서는 ExpressionProperty 식이 사용됩니다.

<set-header name="CustomHeader" exists-action="override">
    <value>{{ExpressionProperty}}</value>
</set-header>

이 정책을 평가할 때 {{ExpressionProperty}}은 해당 값 @(DateTime.Now.ToString())로 바뀝니다. 이 값은 정책 식이므로 식이 계산되고 정책이 계속 실행됩니다.

범위에 명명된 값이 포함된 정책이 있는 작업을 호출하여 Azure portal 또는 개발자 포털에서 테스트할 수 있습니다. 다음 예제에서는 명명된 값이 있는 이전 두 예제 set-header 정책으로 작업이 호출되었습니다. 응답에 명명된 값이 있는 정책을 사용하여 구성된 두 개의 사용자 지정 헤더가 포함되어 있습니다.

명명된 값이 있는 이전의 두 샘플 정책이 포함된 호출에 대한 아웃바운드 API 추적을 살펴보면 명명된 값이 삽입된 두 개의 set-header 정책과 정책 식이 포함된 명명된 값에 대한 정책 식 평가를 확인할 수 있습니다.

문자열 보간은 명명된 값과 함께 사용할 수도 있습니다.

<set-header name="CustomHeader" exists-action="override">
    <value>@($"The URL encoded value is {System.Net.WebUtility.UrlEncode("{{ContosoHeaderValue2}}")}")</value>
</set-header>

CustomHeader의 값은 The URL encoded value is This+is+a+header+value.입니다.

주의

정책이 Azure Key Vault의 비밀을 참조하는 경우 API 요청 추적에 사용하도록 설정된 구독에 대한 액세스 권한이 있는 사용자에게 Key Vault 값이 표시됩니다.

정책 식은 명명된 값에 포함할 수 있지만, 다른 명명된 값은 포함할 수 없습니다. 명명된 값 참조가 포함된 텍스트가 Text: {{MyProperty}}와 같은 값에 사용되는 경우 해당 참조는 확인되지 않고 바뀌지 않습니다.

명명된 값 삭제하기

명명된 값을 삭제하려면 이름을 선택하고 바로 가기 메뉴(...)에서 삭제를 선택합니다.

Important

API Management 정책에서 명명된 값을 참조하는 경우 이를 사용하는 모든 정책에서 명명된 값을 제거할 때까지 해당 값을 삭제할 수 없습니다.

다음 단계

• 정책 작업에 대한 자세한 정보
  • API Management의 정책
  • 정책 참조
  • 정책 식