자체 호스팅 게이트웨이에 Microsoft Entra 인증 사용

적용 대상: 개발자 | 프리미엄

Azure API Management 자체 호스팅 게이트웨이 는 상태 보고, 구성 업데이트 확인 및 적용, 메트릭 및 이벤트 전송을 위해 연결된 클라우드 기반 API Management 인스턴스와의 연결이 필요합니다.

게이트웨이 액세스 토큰(인증 키)을 사용하여 클라우드 기반 API Management 인스턴스와 연결하는 것 외에도 Microsoft Entra 앱을 사용하여 자체 호스팅 게이트웨이가 연결된 클라우드 인스턴스에 인증하도록 설정할 수 있습니다. Microsoft Entra 인증을 사용하면 비밀에 대해 더 긴 만료 시간을 구성하고 표준 단계를 사용하여 Active Directory에서 비밀을 관리하고 회전할 수 있습니다.

시나리오 개요

자체 호스팅 게이트웨이 구성 API는 Azure RBAC(역할 기반 액세스 제어)를 확인하여 게이트웨이 구성을 읽을 권한이 있는 사용자를 확인할 수 있습니다. 이러한 권한으로 Microsoft Entra 앱을 만든 후 자체 호스팅 게이트웨이는 앱을 사용하여 API Management 인스턴스에 인증할 수 있습니다.

Microsoft Entra 인증을 사용하도록 설정하려면 다음 단계를 완료합니다.

다음 두 가지 사용자 지정 역할을 만듭니다.
- 구성 API가 고객의 RBAC 정보에 액세스할 수 있도록 허용
- 자체 호스팅 게이트웨이 구성을 읽을 수 있는 권한 부여
API Management 인스턴스의 관리 ID에 대한 RBAC 액세스 권한 부여
Microsoft Entra 앱을 만들고 게이트웨이 구성을 읽을 수 있는 액세스 권한을 부여합니다.
새 구성 옵션을 사용하여 게이트웨이 배포

필수 조건

개발자 또는 프리미엄 서비스 계층의 API Management 인스턴스입니다. 필요한 경우 다음 빠른 시작을 완료합니다. Azure API Management 인스턴스를 만듭니다.
인스턴스에서 게이트웨이 리소스 를 프로비전합니다.
인스턴스에서 시스템 할당 관리 ID 를 사용하도록 설정합니다.
자체 호스팅 게이트웨이 컨테이너 이미지 버전 2.2 이상

제한 사항 참고 사항

시스템 할당 관리 ID만 지원됩니다.

사용자 지정 역할 만들기

이후 단계에서 할당된 다음 두 개의 사용자 지정 역할을 만듭니다. 다음 JSON 템플릿에 나열된 사용 권한을 사용하여 Azure Portal, Azure CLI, Azure PowerShell 또는 기타 Azure 도구를 사용하여 사용자 지정 역할을 만들 수 있습니다.

사용자 지정 역할을 구성할 때 API Management 인스턴스가 배포된 구독과 같이 디렉터리에 대한 적절한 범위 값으로 AssignableScopes 속성을 업데이트합니다.

API Management 구성 API 액세스 유효성 검사기 서비스 역할

{
  "Description": "Can access RBAC permissions on the API Management resource to authorize requests in Configuration API.",
  "IsCustom": true,
  "Name": "API Management Configuration API Access Validator Service Role",
  "Permissions": [
    {
      "Actions": [
        "Microsoft.Authorization/*/read"
      ],
      "NotActions": [],
      "DataActions": [],
      "NotDataActions": []
    }
  ],
  "NotDataActions": [],
  "AssignableScopes": [
    "/subscriptions/{subscriptionID}"
  ]
}

API Management 게이트웨이 구성 읽기 권한자 역할

{
  "Description": "Can read self-hosted gateway configuration from Configuration API",
  "IsCustom": true,
  "Name": "API Management Gateway Configuration Reader Role",
  "Permissions": [
    {
      "Actions": [],
      "NotActions": [],
      "DataActions": [
        "Microsoft.ApiManagement/service/gateways/getConfiguration/action"
      ],
      "NotDataActions": []
    }
  ],
  "NotDataActions": [],
  "AssignableScopes": [
    "/subscriptions/{subscriptionID}"
  ]
}

역할 할당 추가

API Management 구성 API 액세스 유효성 검사 서비스 역할을 할당합니다.

API Management 구성 API 액세스 유효성 검사기 서비스 역할을 API Management 인스턴스의 관리 ID에 할당합니다. 역할을 할당하는 자세한 단계는 포털을 사용하여 Azure 역할 할당을 참조하세요.

범위: API Management 인스턴스가 배포되는 리소스 그룹 또는 구독
역할: API 관리 구성 API 접근 검사기 서비스 역할
액세스 권한 할당: API Management 인스턴스의 관리 ID

API Management 게이트웨이 구성 읽기 권한자 역할 할당

1단계: Microsoft Entra 앱 등록

새 Microsoft Entra 앱을 만듭니다. 단계는 리소스에 액세스할 수 있는 Microsoft Entra 애플리케이션 및 서비스 주체 만들기를 참조하세요. Microsoft Entra 앱은 자체 호스팅 게이트웨이에서 API Management 인스턴스에 인증하는 데 사용됩니다.

클라이언트 암호 생성
자체 호스팅 게이트웨이를 배포할 때 다음 섹션에서 사용할 애플리케이션 값을 기록해 둡니다. 애플리케이션(클라이언트) ID, 디렉터리(테넌트) ID 및 클라이언트 암호

2단계: API Management 게이트웨이 구성 읽기 권한자 서비스 역할 할당

API Management 게이트웨이 구성 판독기 서비스 역할을 앱에 할당합니다.

범위: API Management 인스턴스(또는 앱이 배포된 리소스 그룹 또는 구독)
역할: API 관리 게이트웨이 구성 읽기 역할
액세스 권한 할당: Microsoft Entra 앱

자체 호스팅 게이트웨이 배포

자체 호스팅 게이트웨이를 Kubernetes에 배포하고 게이트웨이 요소에 data Microsoft Entra 앱 등록 설정을 추가합니다 ConfigMap. 다음 예제 YAML 구성 파일에서 게이트웨이 이름은 mygw 이고 파일 이름은 지정 mygw.yaml됩니다.

중요합니다

기존 Kubernetes 배포 지침을 따르는 경우:

명령을 사용하여 kubectl create secret generic 기본 인증 키를 저장하는 단계를 생략해야 합니다.
Azure Portal에서 생성하는 기본 YAML 파일로 다음 기본 구성 파일을 대체합니다. 다음 파일은 인증 키를 사용하도록 구성 대신 Microsoft Entra 구성을 추가합니다.

---
apiVersion: v1
kind: ConfigMap
metadata:
  name: mygw-env
  labels:
    app: mygw
data:
  config.service.endpoint: "<service-name>.configuration.azure-api.net"
  config.service.auth: azureAdApp 
  config.service.auth.azureAd.authority: "https://login.microsoftonline.com"  
  config.service.auth.azureAd.tenantId: "<Azure AD tenant ID>" 
  config.service.auth.azureAd.clientId: "<Azure AD client ID>" 
  config.service.auth.azureAd.clientSecret: "<Azure AD client secret>"
  gateway.name: <gateway-id>
---
apiVersion: apps/v1
kind: Deployment
metadata:
  name: mygw
  labels:
    app: mygw
spec:
  replicas: 1
  selector:
    matchLabels:
      app: mygw
  strategy:
    type: RollingUpdate
    rollingUpdate:
      maxUnavailable: 0
      maxSurge: 25%
  template:
    metadata:
      labels:
        app: mygw
    spec:
      terminationGracePeriodSeconds: 60
      containers:
      - name: mygw
        image: mcr.microsoft.com/azure-api-management/gateway:v2
        ports:
        - name: http
          containerPort: 8080
        - name: https
          containerPort: 8081
          # Container port used for rate limiting to discover instances
        - name: rate-limit-dc
          protocol: UDP
          containerPort: 4290
          # Container port used for instances to send heartbeats to each other
        - name: dc-heartbeat
          protocol: UDP
          containerPort: 4291
        readinessProbe:
          httpGet:
            path: /status-0123456789abcdef
            port: http
            scheme: HTTP
          initialDelaySeconds: 0
          periodSeconds: 5
          failureThreshold: 3
          successThreshold: 1
        envFrom:
        - configMapRef:
            name: mygw-env
---
apiVersion: v1
kind: Service
metadata:
  name: mygw-live-traffic
  labels:
    app: mygw
spec:
  type: LoadBalancer
  externalTrafficPolicy: Local
  ports:
  - name: http
    port: 80
    targetPort: 8080
  - name: https
    port: 443
    targetPort: 8081
  selector:
    app: mygw
---
apiVersion: v1
kind: Service
metadata:
  name: mygw-instance-discovery
  labels:
    app: mygw
  annotations:
    azure.apim.kubernetes.io/notes: "Headless service being used for instance discovery of self-hosted gateway"
spec:
  clusterIP: None
  type: ClusterIP
  ports:
  - name: rate-limit-discovery
    port: 4290
    targetPort: rate-limit-dc
    protocol: UDP
  - name: discovery-heartbeat
    port: 4291
    targetPort: dc-heartbeat
    protocol: UDP
  selector:
    app: mygw

다음 명령을 사용하여 Kubernetes에 게이트웨이를 배포합니다.

kubectl apply -f mygw.yaml

게이트웨이가 실행 중인지 확인

다음 명령을 실행하여 배포가 성공했는지 확인합니다. 모든 개체를 만들고 Pod를 초기화하는 데 약간의 시간이 걸릴 수 있습니다.
```
kubectl get deployments
```
반환해야 합니다.
```
NAME             READY   UP-TO-DATE   AVAILABLE   AGE
<gateway-name>   1/1     1            1           18s
```

다음 명령을 실행하여 서비스가 성공적으로 만들어졌는지 확인합니다. 서비스 IP와 포트는 서로 다릅니다.

kubectl get services

반환해야 합니다.

NAME                                TYPE           CLUSTER-IP      EXTERNAL-IP   PORT(S)                      AGE
<gateway-name>-live-traffic         ClusterIP      None            <none>        4290/UDP,4291/UDP   9m1s
<gateway-name>-instance-discovery   LoadBalancer   10.99.236.168   <pending>     80:31620/TCP,443:30456/TCP   9m1s

Azure Portal로 돌아가 서 개요를 선택합니다.
상태가 녹색 확인 표시를 표시한 다음 YAML 파일에 지정된 복제본 수와 일치하는 노드 수를 표시하는지 확인합니다. 이 상태는 배포된 자체 호스팅 게이트웨이의 포드가 API 관리 서비스와 성공적으로 통신하며, 정기적인 "하트비트"를 유지하고 있음을 의미합니다.

팁 (조언)

kubectl logs deployment/<gateway-name> 명령을 실행하여 둘 이상의 Pod 중 임의로 선택된 하나에서 로그를 확인합니다.
kubectl logs -h을(를) 실행하여 특정 Pod 또는 컨테이너에 대한 로그를 보는 방법과 같은 전체 명령 옵션 집합을 확인하십시오.

API Management 자체 호스팅 게이트웨이에 대해 자세히 알아봅니다.
프로덕션 환경에서 Kubernetes에서 자체 호스팅 게이트웨이를 실행하기 위한 지침에 대해 자세히 알아봅니다.
API Management 자체 호스팅 게이트웨이를 Azure Arc 지원 Kubernetes 클러스터에 배포하는 방법에 대해 알아봅니다.

피드백

이 페이지가 도움이 되었나요?

Last updated on 2025-10-10