Przeczytaj w języku angielskim

Udostępnij za pośrednictwem

Używanie uwierzytelniania firmy Microsoft Entra dla bramy hostowanej samodzielnie

  • Artykuł
  • 11.04.2025

DOTYCZY: Developer | Premium

Brama samoobsługowa usługi Azure API Management wymaga łączności ze skojarzonym wystąpieniem usługi API Management opartym na chmurze na potrzeby raportowania stanu, sprawdzania i stosowania aktualizacji konfiguracji oraz wysyłania metryk i zdarzeń.

Oprócz używania tokenu dostępu bramy (klucza uwierzytelniania) do nawiązywania połączenia z wystąpieniem usługi API Management opartym na chmurze, można umożliwić bramie samodzielnie hostowanej uwierzytelnianie w jej skojarzonym wystąpieniu chmurowym, korzystając z aplikacji Microsoft Entra. Dzięki uwierzytelnianiu firmy Microsoft Entra można skonfigurować dłuższe czasy wygaśnięcia dla wpisów tajnych i używać standardowych kroków do zarządzania wpisami tajnymi i obracania ich w usłudze Active Directory.

Omówienie scenariusza

Interfejs API konfiguracji lokalnie hostowanej bramy może sprawdzić Azure RBAC, aby określić, kto ma uprawnienia do odczytu konfiguracji bramy. Po utworzeniu aplikacji Microsoft Entra z tymi uprawnieniami brama hostowana lokalnie może uwierzytelnić się w usłudze API Management przy użyciu aplikacji.

Aby włączyć uwierzytelnianie firmy Microsoft Entra, wykonaj następujące kroki:

  1. Utwórz dwie role niestandardowe w celu:
    • Zezwalanie interfejsowi API konfiguracji na dostęp do informacji o kontroli dostępu opartej na rolach klienta
    • Udzielenie uprawnień do odczytu konfiguracji bramy samodzielnie hostowanej
  2. Udzielanie dostępu RBAC do tożsamości zarządzanej wystąpienia usługi API Management
  3. Utwórz aplikację Microsoft Entra i przyznaj jej dostęp do odczytu konfiguracji bramy
  4. Wdrażanie bramy przy użyciu nowych opcji konfiguracji

Wymagania wstępne

Uwagi dotyczące ograniczeń

  • Obsługiwana jest tylko tożsamość zarządzana przypisana przez system.

Tworzenie ról niestandardowych

Utwórz następujące dwie role niestandardowe przypisane w kolejnych krokach. Możesz użyć uprawnień wymienionych w poniższych szablonach JSON, aby utworzyć role niestandardowe przy użyciu witryny Azure Portal, interfejsu wiersza polecenia platformy Azure, programu Azure PowerShell lub innych narzędzi platformy Azure.

Podczas konfigurowania ról niestandardowych zaktualizuj AssignableScopes właściwość, używając odpowiednich wartości zakresu dla Twojego katalogu, takich jak subskrypcja, w której wdrożono instancję usługi API Management.

Rola usługi walidatora dostępu do interfejsu API w konfiguracji zarządzania 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}"
  ]
}

Rola czytelnika konfiguracji bramy usługi 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}"
  ]
}

Dodawanie przypisań ról

Przypisanie roli usługowej walidatora dostępu do interfejsu API w konfiguracji zarządzania API

Przypisz rolę usługi sprawdzania poprawności dostępu interfejsu API konfiguracji usługi API Management do tożsamości zarządzanej wystąpienia usługi API Management. Aby uzyskać szczegółowe instrukcje przypisywania roli, zobacz Przypisywanie ról platformy Azure przy użyciu portalu.

  • Zakres: grupa zasobów lub subskrypcja, w której wdrożono wystąpienie usługi API Management
  • Rola: Rola usługi walidatora dostępu API w konfiguracji zarządzania API
  • Przypisywanie dostępu do: Tożsamość zarządzana wystąpienia usługi API Management

Przypisz rolę Czytelnika konfiguracji bramy zarządzania API

Krok 1. Rejestrowanie aplikacji Microsoft Entra

Utwórz nową aplikację Firmy Microsoft Entra. Aby uzyskać instrukcje, zobacz Create a Microsoft Entra application and service principal that can access resources (Tworzenie aplikacji i jednostki usługi firmy Microsoft, która może uzyskiwać dostęp do zasobów). Ta aplikacja będzie używana przez samohostowalną bramę do uwierzytelniania w wystąpieniu usługi Zarządzania API.

  • Wygeneruj tajny klucz klienta
  • Zanotuj następujące wartości aplikacji do użycia w następnej sekcji podczas wdrażania bramy hostowanej samodzielnie: identyfikator aplikacji (klienta), identyfikator katalogu (dzierżawy) i klucz klienta.

Krok 2. Przypisywanie roli usługi Czytelnik konfiguracji bramy w zarządzaniu API

Przypisz aplikacji rolę usługi Czytelnika konfiguracji bramy API Management.

  • Zakres: instancja usługi API Management (lub grupa zasobów albo subskrypcja, gdzie jest wdrażana)
  • Rola: Odczytywacz konfiguracji bramy dla usługi zarządzania API
  • Przypisywanie dostępu do: Aplikacja Microsoft Entra

Wdrażanie bramy hostowanej samodzielnie

Wdróż bramę hostowaną samodzielnie na platformie Kubernetes, dodając ustawienia rejestracji aplikacji Microsoft Entra do data elementu bram ConfigMap. W poniższym przykładowym pliku konfiguracji YAML brama nosi nazwę mygw , a plik ma nazwę mygw.yaml.

Ważne

Jeśli śledzisz istniejące wskazówki dotyczące wdrażania Kubernetes:

  • Pamiętaj, aby pominąć krok przechowywania domyślnego klucza uwierzytelniania przy użyciu kubectl create secret generic polecenia .
  • Zastąp następujący podstawowy plik konfiguracji domyślnym plikiem YAML wygenerowany dla Ciebie w witrynie Azure Portal. Poniższy plik dodaje konfigurację firmy Microsoft Entra zamiast konfiguracji w celu użycia klucza uwierzytelniania.
---
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

Wdróż bramę na platformie Kubernetes za pomocą następującego polecenia:

kubectl apply -f mygw.yaml

Upewnij się, że brama jest uruchomiona

  1. Uruchom następujące polecenie, aby sprawdzić, czy wdrożenie zakończyło się pomyślnie. Tworzenie wszystkich obiektów i inicjalizacja zasobników może zająć trochę czasu.

    kubectl get deployments

    Powinno zostać zwrócone

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

  2. Uruchom następujące polecenie, aby sprawdzić, czy usługi zostały pomyślnie utworzone. Adresy IP i porty usługi będą inne.

    kubectl get services

    Powinno zostać zwrócone

    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. Wróć do witryny Azure Portal i wybierz pozycję Przegląd.

  4. Upewnij się, że Status pokazuje zielony znacznik wyboru, a następnie liczba węzłów jest zgodna z liczbą replik określonych w pliku YAML. Ten stan oznacza, że wdrożone zasobniki własnego, hostowanego lokalnie, gatewaya pomyślnie komunikują się z usługą API Management i mają regularne "heartbeat". Zrzut ekranu przedstawiający stan własnego, hostowanego lokalnie, gatewaya w portalu.

Porada

  • Uruchom polecenie kubectl logs deployment/<gateway-name>, aby wyświetlić dzienniki z losowo wybranego zasobnika, gdy istnieje więcej niż jeden.
  • Uruchom polecenie kubectl logs -h , aby uzyskać pełny zestaw opcji poleceń, takich jak wyświetlanie dzienników dla określonego zasobnika lub kontenera.

Powiązana zawartość