Uso de la autenticación de Microsoft Entra para la puerta de enlace autohospedada

SE APLICA A: Desarrollador | Premium

La puerta de enlace autohospedada de Azure API Management necesita conectividad con su instancia de API Management basada en la nube asociada para notificar el estado, comprobar y aplicar actualizaciones de configuración y enviar métricas y eventos.

Además de usar un token de acceso de puerta de enlace (clave de autenticación) para conectarse con su instancia de API Management basada en la nube, puede habilitar la puerta de enlace autohospedada para autenticarse en su instancia de nube asociada mediante una aplicación de Microsoft Entra. Con la autenticación de Microsoft Entra, puede configurar tiempos de expiración más largos para secretos y usar pasos estándar para administrar y rotar secretos en Active Directory.

Información general sobre el escenario

La API de configuración de puerta de enlace autohospedada puede comprobar el control de acceso basado en rol (RBAC) de Azure para determinar quién tiene permisos para leer la configuración de la puerta de enlace. Después de crear una aplicación de Microsoft Entra con esos permisos, la puerta de enlace autohospedada se puede autenticar en la instancia de API Management mediante la aplicación.

Para habilitar la autenticación de Microsoft Entra, complete los pasos siguientes:

Cree dos roles personalizados para:
- Permitir que la API de configuración obtenga acceso a la información de RBAC del cliente
- Concesión de permisos para leer la configuración de la puerta de enlace autohospedada
Conceder acceso de RBAC a la identidad administrada de la instancia de API Management
Creación de una aplicación de Microsoft Entra y concesión de acceso para leer la configuración de la puerta de enlace
Implementación de la puerta de enlace con nuevas opciones de configuración

Prerrequisitos

Una instancia de API Management en el nivel de servicio Desarrollador o Premium. Si es necesario, complete el siguiente inicio rápido: Creación de una instancia de Azure API Management.
Aprovisione un recurso de puerta de enlace en la instancia.
Habilite una identidad administrada asignada por el sistema en la instancia.
Imagen de contenedor de puerta de enlace autohospedada de versión 2.2 o posterior

Notas de limitaciones

Solo se admite la identidad administrada asignada por el sistema.

Creación de roles personalizados

Cree los dos roles personalizados siguientes que se asignan en pasos posteriores. Puede usar los permisos enumerados en las siguientes plantillas JSON para crear los roles personalizados mediante Azure Portal, la CLI de Azure, Azure PowerShell u otras herramientas de Azure.

Al configurar los roles personalizados, actualice la propiedad AssignableScopes con los valores de ámbito adecuados para el directorio, como una suscripción en la que se despliega la instancia de API Management.

Rol de servicio de validador de acceso de API de configuración de API Management

{
  "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}"
  ]
}

Rol lector de configuración de puerta de enlace de 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}"
  ]
}

Agregar asignación de roles

Asignación del rol de servicio de validador de acceso de API de configuración de API Management

Asigne el rol de servicio de validador de acceso de API de configuración de API Management a la identidad administrada de la instancia de API Management. Para obtener pasos detallados para asignar un rol, consulte Asignación de roles de Azure mediante el portal.

Ámbito: el grupo de recursos o la suscripción en el que se implementa la instancia de API Management.
Rol: rol de servicio de validador de acceso de API de configuración de API Management
Asignación de acceso a: identidad administrada de la instancia de API Management

Asignar el rol de lector de configuración de API Management Gateway

Paso 1: Registrar la aplicación Microsoft Entra

Cree una nueva aplicación de Microsoft Entra. Para conocer los pasos, consulte Creación de una aplicación de Microsoft Entra y un principal de servicio para acceder a recursos. La aplicación de Microsoft Entra usará esta aplicación para autenticarse en la instancia de API Management.

Generación de un secreto de cliente
Tome nota de los siguientes valores de aplicación para su uso en la sección siguiente al implementar la puerta de enlace autohospedada: id. de aplicación (cliente), identificador de directorio (inquilino) y secreto de cliente.

Paso 2: Asignación de rol de servicio de lector de configuración de puerta de enlace de API Management

Asigne el rol de servicio lector de configuración de API Management Gateway a la aplicación.

Ámbito: la instancia de API Management (o grupo de recursos o suscripción en la que se implementa la aplicación)
Rol: Rol de lector de configuración de API Management Gateway
Asignación de acceso a: Aplicación Microsoft Entra

Implementación de la puerta de enlace autohospedada

Implemente la puerta de enlace autohospedada en Kubernetes y agregue la configuración de registro de aplicaciones de Microsoft Entra al data elemento de las puertas de enlace ConfigMap. En el siguiente archivo de configuración de YAML de ejemplo, la puerta de enlace se denomina mygw y el archivo se denomina mygw.yaml.

Importante

Si sigue las instrucciones de implementación de Kubernetes existentes:

Asegúrese de omitir el paso para almacenar la clave de autenticación predeterminada mediante el kubectl create secret generic comando .
Sustituya el siguiente archivo de configuración básico para el archivo YAML predeterminado que azure Portal genera automáticamente. El siguiente archivo agrega la configuración de Microsoft Entra en lugar de la configuración para usar una clave de autenticación.

---
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

Implemente la puerta de enlace en Kubernetes con el comando siguiente:

kubectl apply -f mygw.yaml

Confirme que la puerta de enlace está en funcionamiento

Ejecute el siguiente comando para comprobar si la implementación se realizó correctamente. Es posible que tarde un poco en crearse todos los objetos y que los pods se inicialicen.
```
kubectl get deployments
```
Debería devolverse.
```
NAME             READY   UP-TO-DATE   AVAILABLE   AGE
<gateway-name>   1/1     1            1           18s
```

Ejecute el siguiente comando para comprobar si los servicios se crearon correctamente. Las direcciones IP y los puertos de servicio serán diferentes.

kubectl get services

Debería devolverse.

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

Vuelva a Azure Portal y seleccione Información general.
Confirme que Status muestra una marca de verificación verde, seguida de un recuento de nodos que coincide con el número de réplicas especificadas en el archivo YAML. Este estado significa que los pods de puerta de enlace autohospedados implementados se comunican correctamente con el servicio de API Management y tienen un "latido" normal.

Sugerencia

Ejecute el kubectl logs deployment/<gateway-name> comando para ver los registros de un pod seleccionado aleatoriamente si hay más de uno.
Ejecute kubectl logs -h para obtener un conjunto completo de opciones de comando, como cómo ver los registros de un pod o contenedor específicos.

Obtenga más información sobre la puerta de enlace autohospedada de API Management.
Obtenga más información sobre las instrucciones para ejecutar la puerta de enlace autohospedada en Kubernetes en producción.
Obtenga información sobre cómo implementar una puerta de enlace autohospedada de API Management en clústeres de Kubernetes habilitados para Azure Arc.

Comentarios

¿Le resultó útil esta página?

Last updated on 2025-10-10