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

아티클
03/05/2024

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

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

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

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

1단계: Microsoft Entra 앱 등록

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

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

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

앱에 API Management 게이트웨이 구성 읽기 권한자 서비스 역할을 할당합니다.

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

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

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

Important

기존 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 파일에 지정된 복제본 수와 일치하는 노드 수가 표시되는지 확인합니다. 이 상태는 배포된 자체 호스팅 게이트웨이 Pod가 API Management 서비스와 성공적으로 통신하고 있으며 "하트비트"가 규칙적이라는 것을 의미합니다.

팁

게이트웨이가 여러 개 있는 경우 kubectl logs deployment/<gateway-name> 명령을 실행하여 임의로 선택한 Pod의 로그를 확인합니다.
명령 옵션 전체 세트에 대해 kubectl logs -h를 실행합니다(예: 특정 Pod 또는 컨테이너에 대한 로그를 보는 방법).

다음 단계

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

다음을 통해 공유