Compartir a través de

Acceso seguro a productos y API con aplicaciones de Microsoft Entra

SE APLICA A: Desarrollador | Básico | Estándar | Premium

API Management ahora admite el acceso integrado basado en aplicaciones de OAuth 2.0 a las API de producto mediante el flujo de credenciales de cliente. Esta característica permite a los administradores de API registrar aplicaciones de id. de Microsoft Entra, lo que simplifica el acceso seguro a la API para los desarrolladores mediante la autorización de OAuth 2.0.

Nota:

Las aplicaciones se encuentran actualmente en versión preliminar limitada. Para registrarse, rellene este formulario.

Con esta característica:

  • Los administradores de API establecen una propiedad de producto para habilitar el acceso basado en aplicaciones.
  • Los administradores de API registran aplicaciones cliente en el identificador de Microsoft Entra para limitar el acceso a productos específicos.
  • Con el flujo de credenciales de cliente de OAuth 2.0, los desarrolladores o las aplicaciones obtienen tokens que pueden incluir en las solicitudes de API.
  • La puerta de enlace de API valida los tokens presentados en las solicitudes de API para autorizar el acceso a las API del producto.

Prerrequisitos

  • Una instancia de API Management implementada en el nivel Premium, Estándar, Básico o Desarrollador . Si necesita implementar una instancia, consulte Creación de una instancia del servicio API Management.

  • Al menos un producto de la instancia de API Management, con al menos una API asignada.

    • El producto debe estar en estado Publicado para que los desarrolladores puedan acceder a él a través del portal para desarrolladores.
    • Para las pruebas, puede usar el producto starter predeterminado y la API echo que se agrega a él.
    • Si desea crear un producto, consulte Creación y publicación de un producto.

  • Permisos suficientes en el entorno de Microsoft Entra para asignar el rol Administrador de Aplicaciones, que requiere al menos el rol Administrador de Roles con Privilegios.

  • Opcionalmente, agregue uno o varios usuarios en la instancia de API Management.

Configuración de una identidad administrada

  1. Habilite una identidad administrada asignada por el sistema para API Management en la instancia de API Management.

  2. Asigne la identidad al rol RBAC de Administrador de aplicaciones en Microsoft Entra ID. Para asignar el rol:

    1. Inicie sesión en el portal y vaya a Microsoft Entra ID.
    2. En el menú de la izquierda, seleccione Administrar>roles y administradores.
    3. Seleccione Administrador de aplicaciones.
    4. En el menú de la izquierda, seleccione Administrar>asignaciones>+ Agregar asignaciones.
    5. En la página Agregar asignaciones , busque la identidad administrada de la instancia de API Management por nombre (el nombre de la instancia de API Management). Seleccione la identidad administrada y, a continuación, seleccione Agregar.

Habilitación del acceso basado en aplicaciones para el producto

Siga estos pasos para habilitar el acceso basado en aplicaciones para un producto. Un producto debe tener habilitada esta configuración para asociarse a una aplicación cliente en pasos posteriores.

En el ejemplo siguiente se usa el producto Starter , pero se elige cualquier producto publicado que tenga al menos una API asignada.

  1. Inicie sesión en el portal y vaya a la instancia de API Management.
  2. En el menú de la izquierda, en API, seleccione Productos.
  3. Elija el producto que desea configurar, como el producto starter .
  4. En el menú izquierdo, en Producto, seleccione Propiedades.
  5. En la sección Acceso basado en aplicaciones, habilite la configuración del token de OAuth 2.0 (más seguro).
  6. Opcionalmente, habilite la opción Clave de suscripción . Si habilita el acceso basado en aplicaciones y un requisito de suscripción, la puerta de enlace de API Management puede aceptar un token de OAuth 2.0 o una clave de suscripción para acceder a las API del producto.
  7. Haga clic en Guardar.

Captura de pantalla de la habilitación del acceso basado en aplicaciones en el portal.

Sugerencia

También puede habilitar la configuración del token de OAuth 2.0 al crear un nuevo producto.

Al habilitar el acceso basado en aplicaciones, se crea una aplicación empresarial de back-end en microsoft Entra ID para representar el producto. El identificador de la aplicación back-end se muestra en la página Propiedades del producto.

Captura de pantalla de la configuración de la aplicación del producto en el portal.

Nota:

Este identificador de aplicación se establece como el valor audiencia al crear una aplicación cliente para acceder al producto. Use también este valor al generar un token para llamar a la API del producto.

(Opcional) Puede revisar la configuración de la aplicación del producto en Microsoft Entra ID.

Opcionalmente, revise la configuración de la aplicación empresarial de back-end creada en el identificador de Entra de Microsoft para representar el producto.

La aplicación se denomina con el siguiente formato: APIMProductApplication<product-name>. Por ejemplo, si el nombre del producto es Starter, el nombre de la aplicación es APIMProductApplicationStarter. La aplicación tiene definido un rol de aplicación .

Para revisar la configuración de la aplicación en Registros de aplicaciones:

  1. Inicie sesión en el portal y vaya a Microsoft Entra ID>Manage>Registros de aplicaciones.
  2. Seleccione Todas las aplicaciones.
  3. Busque y seleccione la aplicación creada por API Management.
  4. En el menú izquierdo, en Administrar, seleccione Roles de aplicación.
  5. Confirme el rol de aplicación establecido por Azure API Management, como se muestra en la captura de pantalla siguiente:

Recorte de pantalla de los roles de aplicación en el portal.

Registro de la aplicación cliente para acceder al producto

Ahora registre una aplicación cliente que limite el acceso a uno o varios productos.

  • Un producto debe tener habilitado el acceso basado en la aplicación para asociarse a una aplicación cliente.
  • Cada aplicación cliente tiene un único usuario (propietario) en la instancia de API Management. Un propietario puede acceder a las API del producto a través de la aplicación.
  • Un producto se puede asociar a más de una aplicación cliente.

  1. Inicie sesión en el portal y vaya a la instancia de API Management.

  2. En el menú de la izquierda, en API, seleccione Aplicaciones>+ Registrar aplicación.

  3. En la página Registrar una aplicación , escriba la siguiente configuración de la aplicación:

    • Name: Escriba un nombre para la aplicación.
    • Propietario: seleccione el propietario de la aplicación en la lista desplegable de usuarios de la instancia de API Management.
    • Conceder acceso a los productos seleccionados: seleccione uno o varios productos en la instancia de API Management que se habilitaron anteriormente para el acceso basado en aplicaciones.
    • Descripción: opcionalmente, escriba una descripción.

    Captura de pantalla de la configuración de la aplicación en el portal.

  4. Seleccione Registrar.

La aplicación se agrega a la lista de aplicaciones de la página Aplicaciones . Seleccione la aplicación para ver los detalles, como el identificador de cliente. Necesita este identificador para generar un token para llamar a la API del producto.

Sugerencia

  • Después de crear una aplicación, puede asociarla a otros productos. Seleccione la aplicación en la página Aplicaciones y, a continuación, seleccione Detalles>productos>+ Agregar producto.
  • También puede crear o asociar una aplicación editando un producto desde la página Productos .

Generación de secretos de cliente

Se debe generar un secreto de cliente para que la aplicación cliente use el flujo de credenciales de cliente de OAuth 2.0. El secreto es válido durante un año, pero se puede volver a generar en cualquier momento.

  1. En la página Aplicaciones , seleccione la aplicación que creó.

  2. En la página Información general de la aplicación, junto a Secreto de cliente, seleccione Agregar secreto.

  3. En la página Nuevo secreto de cliente , seleccione Generar.

    Se genera un secreto de cliente y se muestra en el campo Secreto de cliente. Asegúrese de copiar el valor del secreto y almacenarlo de forma segura. No podrá recuperarlo de nuevo después de cerrar la página.

  4. Selecciona Cerrar.

(Opcional) Revisar la configuración de la aplicación cliente en Microsoft Entra ID

Opcionalmente, revise la configuración de la aplicación cliente en microsoft Entra ID.

La aplicación se denomina con el siguiente formato: APIMApplication<product-name>. Por ejemplo, si el nombre del producto es Starter, el nombre de la aplicación es similar a APIMApplicationStarter.

Para revisar la configuración de la aplicación en Registros de aplicaciones:

  1. Inicie sesión en el portal y vaya a Microsoft Entra ID>Manage>Registros de aplicaciones.

  2. Seleccione Todas las aplicaciones.

  3. Busque y seleccione la aplicación cliente creada por API Management.

  4. En el menú izquierdo, en Administrar, seleccione Permisos de API.

  5. Confirme que la aplicación tiene permisos para acceder a la aplicación o las aplicaciones del producto back-end.

    Por ejemplo, si la aplicación cliente concede acceso al producto Starter , la aplicación tiene permisos Product.Starter.All para acceder a la aplicación APIMProductApplicationStarter .

    Captura de pantalla de los permisos de API en el portal.

Creación de un token y uso con la llamada API

Después de habilitar el acceso basado en aplicaciones para un producto y registrar una aplicación cliente, un desarrollador o una aplicación puede generar un token para llamar a las API del producto. El token debe incluirse en el Authorization encabezado de una solicitud.

Por ejemplo, un desarrollador o una aplicación pueden ejecutar los siguientes scripts de Azure PowerShell para llamar a la aplicación cliente para generar un token y, a continuación, usar el token para llamar a una API de producto en API Management.

Precaución

Los scripts siguientes son ejemplos solo con fines de prueba. En producción, use un método seguro para almacenar y recuperar el secreto de cliente.

Llamada a la aplicación cliente para generar el token

# Replace placeholder values with your own values.

$clientId = "00001111-aaaa-2222-bbbb-3333cccc4444" # Client (application) ID of client application
$clientSecret = "******" # Retrieve secret of client application in developer portal
$scopeOfOtherApp = "api://55556666-ffff-7777-aaaa-8888bbbb9999/.default" # Value of Audience in product properties
$tenantId = "aaaabbbb-0000-cccc-1111-dddd2222eeee" # Directory (tenant) ID in Microsoft Entra ID

$body = @{
    grant_type    = "client_credentials"
    client_id     = $clientId
    client_secret = $clientSecret
    scope         = $scopeOfOtherApp
}
$response = Invoke-RestMethod -Method Post -Uri "https://login.microsoftonline.com/$tenantId/oauth2/v2.0/token" -ContentType "application/x-www-form-urlencoded" -Body $body
$token = $response.access_token

Llamada a la API de producto mediante el token

El token generado en el paso anterior se usa para llamar a una API de producto. El token se pasa en el encabezado Authorization de la solicitud. La instancia de API Management valida el token y autoriza el acceso a la API.

En el script siguiente se muestra una llamada de ejemplo a la API echo.

# Gatewate endpoint to call. Update with URI of API operation you want to call.
$uri = "https://<gateway-hostname>/echo/resource?param1=sample"
$headers = @{
   "Authorization" = "Bearer $token"  # $token is the token generated in the previous script.
}
$body = @{
    "hello" = "world"
} | ConvertTo-Json -Depth 5

$getresponse = Invoke-RestMethod -Method Post -Uri $uri -ContentType "application/x-www-form-urlencoded" -Headers $headers -Body $body
Write-Host "Response:"
$getresponse | ConvertTo-Json -Depth 5

Contenido relacionado