자체 호스팅 게이트웨이에 토큰 인증 사용

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

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

이 문서에서는 기본 토큰 기반 인증 방법을 사용하여 자체 호스팅 게이트웨이를 인증하도록 설정하는 방법을 보여 줍니다. 이 방법은 액세스 토큰 및 엔드포인트 URL을 사용하여 자체 호스팅 게이트웨이와 API Management 인스턴스 간에 보안 통신을 설정합니다. 다른 인증 옵션은 자체 호스팅 게이트웨이 인증 옵션을 참조하세요.

필수 조건

• 개발자 또는 프리미엄 서비스 계층의 API Management 인스턴스입니다. 필요한 경우 다음 빠른 시작을 완료합니다. Azure API Management 인스턴스를 만듭니다.
• 인스턴스의 게이트웨이 리소스 입니다.
• AKS(Azure Kubernetes Service) 클러스터 또는 Kubernetes 클러스터.
• 자체 호스팅 게이트웨이 컨테이너 이미지 버전 2.0 이상

액세스 토큰 생성

API Management에서 게이트웨이 리소스를 프로비전하면 기본 인증 토큰이 자동으로 생성됩니다. 토큰을 검색하려면 다음을 수행합니다.

1. Azure Portal에서 API Management 인스턴스로 이동합니다.
2. 배포 및 인프라>게이트웨이를 선택합니다.
3. 목록에서 게이트웨이를 선택합니다.
4. 게이트웨이 페이지에서 설정>배포를 선택합니다.
5. 토큰 값을 복사합니다. 이 토큰을 사용하여 자체 호스팅 게이트웨이를 API Management 인스턴스에 인증합니다.
6. 다음 섹션에서 복사하고 사용할 환경에 대한 배포 스크립트를 선택하여 토큰 인증을 사용하여 게이트웨이를 배포합니다.

중요합니다

• 액세스 토큰을 안전하게 유지합니다. 이 토큰은 게이트웨이 구성에 대한 액세스 권한을 부여합니다. 소스 제어에 커밋하거나 공개적으로 노출하지 마세요.
• 액세스 토큰은 정의된 수명을 가지고 있으며 주기적으로 회전해야 합니다. 토큰이 거의 만료되었거나 만료되었을 때 알림을 받도록 시스템 이벤트를 구독할 수 있습니다. 자세한 내용은 이 문서의 뒷부분에 나오는 섹션을 참조하세요.

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

기본 토큰 인증을 사용하여 Kubernetes와 같은 컨테이너화된 환경에 자체 호스팅 게이트웨이를 배포합니다.

헬름

Helm 차트를 사용하여 토큰 인증을 사용하여 자체 호스팅 게이트웨이를 배포할 수 있습니다.

명령에서 다음 값을 helm install 실제 값으로 바꿉다.

• <gateway-name>: Azure API Management 인스턴스 이름
• <gateway-url>: 게이트웨이의 URL 형식 https://<gateway-name>.configuration.azure-api.net
• <gateway-key>: 귀하의 액세스 토큰

필수 구성 요소 및 세부 정보는 Helm을 사용하여 API Management 자체 호스팅 게이트웨이 배포를 참조하세요.

helm install --name azure-api-management-gateway azure-apim-gateway/azure-api-management-gateway \
             --set gateway.configuration.uri='<gateway-url>' \
             --set gateway.auth.key='<gateway-key>'

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

1. 다음 명령을 실행하여 게이트웨이 Pod가 정상적으로 실행 중인지 확인하십시오. Pod의 이름은 사용자마다 다를 것입니다.

   kubectl get pods
   NAME                                           READY     STATUS    RESTARTS   AGE
   azure-api-management-gateway-59f5fb94c-s9stz   1/1       Running   0          1m
   

2. 다음 명령을 실행하여 게이트웨이 서비스가 실행 중인지 확인합니다. 서비스 이름과 IP 주소는 서로 다릅니다.

   kubectl get services
   NAME                           TYPE        CLUSTER-IP      EXTERNAL-IP   PORT(S)               AGE
   azure-api-management-gateway   ClusterIP   10.0.229.55     <none>        8080/TCP,8081/TCP     1m
   

3. Azure Portal로 돌아가서 배포한 게이트웨이 노드가 정상 상태를 보고하고 있는지 확인합니다.

팁 (조언)

kubectl logs <gateway-pod-name> 명령을 사용하여 자체 호스팅 게이트웨이 로그의 스냅샷을 봅니다.

YAML (야믈)

다음 샘플 YAML 구성은 토큰 인증을 사용하여 Kubernetes에 배포하는 데 필요한 구성 요소 및 설정을 보여 줍니다.

중요합니다

Azure Portal에 제공된 배포 스크립트를 사용하여 설치하는 단계는 YAML을 사용하여 Kubernetes에 자체 호스팅 게이트웨이 배포를 참조하세요.

비고

자리 표시자 값을 실제 구성으로 교체해야 합니다.

• <namespace-name>: 사용자의 Kubernetes 네임스페이스
• <service-name>.configuration.azure-api.net: API Management 구성 엔드포인트
• <gateway-name>: 게이트웨이 이름
• <configuration-token>: 액세스 토큰

---
apiVersion: v1
kind: Secret
metadata:
  name: apim-access-token
  namespace: <namespace-name>
type: Opaque
stringData:
  config.service.auth.key: "<configuration-token>"
---
apiVersion: v1
kind: ConfigMap
metadata:
  name: apim-gateway-env
  namespace: <namespace-name>
data:
  gateway.name: <gateway-name>
  config.service.auth: key
  config.service.endpoint: https://<service-name>.configuration.azure-api.net
  telemetry.logs.std.level: info
---
apiVersion: apps/v1
kind: Deployment
metadata:
  name: apim-gateway
  namespace: <namespace-name>
spec:
  replicas: 1
  selector:
    matchLabels:
      app: apim-gateway
  template:
    metadata:
      labels:
        app: apim-gateway
    spec:
      containers:
      - name: apim-gateway
        image: mcr.microsoft.com/azure-api-management/gateway:v2
        ports:
        - name: http
          containerPort: 8080
          protocol: TCP
        - name: https
          containerPort: 8081
          protocol: TCP
        readinessProbe:
          failureThreshold: 3
          httpGet:
            path: /internal-status-0123456789abcdef
            port: http
            scheme: HTTP
          periodSeconds: 5
          successThreshold: 1
          timeoutSeconds: 1
        resources:
          limits:
            cpu: "2"
            memory: 2Gi
          requests:
            cpu: "2"
            memory: 2Gi
        envFrom:
        - configMapRef:
            name: apim-gateway-env
        - secretRef:
            name: apim-access-token
---
apiVersion: v1
kind: Service
metadata:
  name: apim-gateway-loadbalancer
  namespace: <namespace-name>
spec:
  type: LoadBalancer
  selector:
    app: apim-gateway
  ports:
  - name: http
    port: 80
    protocol: TCP
    targetPort: 8080
  - name: https
    port: 443
    protocol: TCP
    targetPort: 8081

ConfigMap은 게이트웨이의 인증 및 연결 설정을 정의합니다.

• config.service.auth: key - 토큰 기반 인증을 메서드로 지정합니다.
• config.service.endpoint - API 관리 구성 엔드포인트 URL
• gateway.name - API Management 인스턴스의 게이트웨이 리소스 이름

Kubernetes에 배포

YAML 구성을 파일(예 apim-access-token.yaml: )에 저장하고 Kubernetes 클러스터에 배포합니다.

kubectl apply -f apim-access-token.yaml

배포 확인:

kubectl get pods -n <namespace-name>
kubectl logs -n <namespace-name> <pod-name>

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

1. 다음 명령을 실행하여 배포가 성공했는지 확인합니다. 모든 개체를 만들고 Pod를 초기화하는 데 약간의 시간이 걸릴 수 있습니다.

   kubectl get deployments
   

   반환해야 합니다.

   NAME             READY   UP-TO-DATE   AVAILABLE   AGE
   <gateway-name>   1/1     1            1           18s
   

2. 다음 명령을 실행하여 서비스가 성공적으로 만들어졌는지 확인합니다. 서비스 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
   

3. Azure Portal로 돌아가서 게이트웨이의 개요 탭을 선택합니다.

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

팁 (조언)

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

토큰 회전 및 관리

액세스 토큰의 수명은 정의되어 있습니다. 토큰이 만료되면 게이트웨이는 API Management 인스턴스에 대한 연결을 끊습니다.

토큰을 회전하려면 다음을 수행합니다.

1. Azure Portal에서 API Management 인스턴스로 이동합니다.
2. 배포 및 인프라>게이트웨이를 선택합니다.
3. 게이트웨이를 선택합니다.
4. 배포 탭에서 토큰 다시 생성을 선택합니다.
5. 새 토큰을 복사합니다.
6. Kubernetes 비밀을 새 토큰으로 업데이트합니다.

kubectl patch secret apim-access-token -n <namespace-name> -p '{"data":{"config.service.auth.key":"'$(echo -n "<new-token>" | base64)'"}}' --type=merge

토큰 만료에 대한 Event Grid 이벤트

API Management는 자체 호스팅 게이트웨이 액세스 토큰이 만료되거나 만료되는 경우 시스템 이벤트를 생성합니다. 이러한 이벤트를 구독하여 배포된 게이트웨이가 연결된 API Management 인스턴스를 사용하여 항상 인증할 수 있는지 확인합니다. 자세한 내용은 Event Grid 원본으로 Azure API Management를 참조하세요.

관련 콘텐츠

• API Management 자체 호스팅 게이트웨이에 대해 자세히 알아봅니다.
• 프로덕션 환경에서 Kubernetes에서 자체 호스팅 게이트웨이를 실행하기 위한 지침에 대해 자세히 알아봅니다.
• Microsoft Entra 워크로드 ID 인증과 비교합니다.
• 클라이언트 비밀을 사용하여 Microsoft Entra 인증과 비교합니다.