Configurar el administrador de credenciales: acceso delegado por un usuario a una API de back-end

  • Artículo

SE APLICA A: todos los niveles de API Management

Este artículo le guía por los pasos de alto nivel para configurar y usar una conexión administrada que concede a los usuarios o grupos delegados de Microsoft Entra permisos delegados a una API de OAuth 2.0 de back-end. Siga estos pasos para escenarios en los que una aplicación cliente (o bot) necesite acceder a los recursos en línea protegidos por back-end en nombre de un usuario autenticado (por ejemplo, comprobar correos electrónicos o realizar un pedido).

Información general del escenario

Nota:

Este escenario solo se aplica a los proveedores de credenciales configurados con el tipo de concesión del código de autorización.

En este caso, configure una conexión administrada que permita a una aplicación cliente (o bot) acceder a una API de back-end en nombre de un usuario o grupo de Microsoft Entra. Por ejemplo, puede tener una aplicación web estática que tenga acceso a una API de GitHub de back-end y a la que quiera acceder a datos específicos del usuario que ha iniciado sesión. En el siguiente diagrama, se ilustra este caso.

Diagrama que muestra el flujo de proceso para los permisos delegados por el usuario.

  • El usuario debe autorizar a la aplicación a acceder a los recursos protegidos en su nombre y autorizar a la aplicación, el usuario debe autenticar su identidad
  • Para realizar operaciones en nombre de un usuario, la aplicación llama al servicio back-end externo, como Microsoft Graph o GitHub
  • Cada servicio externo tiene una manera de proteger esas llamadas, por ejemplo, con un token de usuario que identifica de forma única al usuario
  • Para proteger la llamada al servicio externo, la aplicación debe pedir al usuario que inicie sesión para poder adquirir el token del usuario
  • Como parte de la configuración, un proveedor de credenciales se registra mediante el administrador de credenciales en la instancia de API Management. Contiene información sobre el proveedor de identidades que se va a utilizar, junto con un identificador de cliente y un secreto de OAuth válidos, los ámbitos de OAuth que se van a habilitar y cualquier otros metadatos de conexión que requiera ese proveedor de identidades.
  • Además, se crea una conexión y se usa para ayudar a iniciar sesión del usuario y obtener el token de usuario para que se pueda administrar

Requisitos previos

  • Acceder a un inquilino de Microsoft Entra en el que tenga permisos para crear un registro de aplicación y conceder el consentimiento del administrador para los permisos de aplicación. Más información

    Si desea crear su propio inquilino de desarrollador, puede registrarse en el Programa para desarrolladores de Microsoft 365.

  • Uno o varios usuarios o grupos del inquilino para delegar permisos.

  • Instancia de API Management en ejecución. Si fuera necesario, cree una instancia de Azure API Management.

  • Una API de OAuth 2.0 de back-end a la que desea acceder en nombre del usuario o grupo.

Paso 1: Aprovisionamiento de la entidad de servicio del plano de datos de Azure API Management

Debe aprovisionar la entidad de servicio del plano de datos de Azure API Management para conceder a los usuarios o grupos los permisos delegados necesarios. Siga los pasos siguientes para aprovisionar el servicio principal con Azure PowerShell.

  1. Inicie sesión en Azure PowerShell.

  2. Si el módulo AzureAD aún no está instalado, instálelo con el siguiente comando:

    Install-Module -Name AzureAD -Scope CurrentUser -Repository PSGallery -Force

  3. Conéctese a su inquilino con el siguiente comando:

    Connect-AzureAD -TenantId "<YOUR_TENANT_ID>"

  4. Si se le solicita, inicie sesión con las credenciales de la cuenta de administrador del inquilino.

  5. Aprovisione la entidad de servicio del plano de datos de Azure API Management con el siguiente comando:

    New-AzureADServicePrincipal -AppId c8623e40-e6ab-4d2b-b123-2ca193542c65 -DisplayName "Azure API Management Data Plane"

Paso 2: Creación de un registro de aplicaciones de Microsoft Entra

Cree una aplicación Microsoft Entra ID para la delegación de usuarios y conceda los permisos adecuados para leer la conexión en API Management.

  1. Inicie sesión en Azure Portal con una cuenta con permisos suficientes en el inquilino.
  2. En Servicios de Azure, busque Microsoft Entra ID.
  3. En el menú de la izquierda, seleccione Registros de aplicaciones y luego + Nuevo registro.
  4. En la página Registrar una aplicación, escriba la configuración de registro de aplicación:
    1. En Nombre, escriba un nombre significativo que se mostrará a los usuarios de la aplicación, como UserPermissions.
    2. En Tipos de cuenta compatibles, seleccione una opción que se adapte a su escenario, por ejemplo, Cuentas de este directorio organizativo solo (inquilino único).
    3. Establezca el URI de redirección en Web e introduzca https://www.postman-echo.com/get.
  5. En el menú izquierdo, seleccione Permisos de API y, después, + Agregar un permiso.
    1. Seleccione la pestaña de las API que mi organización usa, escriba Plano de datos de Azure API Management y selecciónelo.
    2. En Permisos, seleccione Authorizations.Read y, a continuación, seleccione Agregar permisos.
  6. En el menú de la izquierda, seleccione Información general. En la página Información general, busque el valor de Id. de aplicación (cliente) y regístrelo para usarlo en el último paso.
  7. En el menú de la izquierda, seleccione Certificados y secretos y, después, + Nuevo secreto de cliente.
    1. Escriba una Descripción.
    2. Seleccione una opción para Expiración.
    3. Seleccione Agregar.
    4. Copie el valor del secreto del cliente antes de salir de la página. La necesitará en otro paso más adelante.

Paso 3: Configuración de un proveedor de credenciales en API Management

  1. Inicie sesión en el portal y vaya a la instancia de API Management.
  2. En el menú de la izquierda, seleccione Administrador de credenciales, y luego seleccione + Crear.
    Captura de pantalla de la creación de credenciales de API en el portal.
  3. En la página Crear proveedor de credenciales, escriba la configuración del proveedor de credenciales para la API. En este escenario, en Tipo de concesión, debe seleccionar Código de autorización. Obtenga más información consultando Configurar proveedores de credenciales en el administrador de credenciales.
  4. Seleccione Crear.
  5. Cuando se le solicite, revise la dirección URL de redireccionamiento de OAuth que se muestra y seleccione Sí para confirmar que coincide con la dirección URL que escribió en el registro de la aplicación.

Paso 4: Configure una conexión

Después de crear un proveedor de credenciales, puede agregar una conexión al proveedor. En la pestaña Conexión, complete los pasos de la conexión:

  1. Escriba un nombre de conexión y seleccione Guardar.
  2. En Paso 2: Iniciar sesión en la conexión, seleccione el vínculo para iniciar sesión en el proveedor de credenciales. Complete los pasos para autorizar el acceso, y volver a API Management.
  3. En Paso 3: Determine quién tendrá acceso a esta conexión (directiva de acceso), seleccione + Agregar. En función del escenario de delegación, seleccione Usuarios o Grupo.
  4. En la ventana Seleccionar elemento, realice selecciones en el orden siguiente:
    1. En primer lugar, busque uno o varios usuarios (o grupos) para agregar y activar la casilla de selección.
    2. A continuación, en la lista que aparece, busque el registro de la aplicación que creó en una sección anterior.
    3. Después, haga clic en Seleccionar.
  5. Seleccione Completar.

La nueva conexión aparece en la lista de autorizaciones y programa un estado de Conectado. Si desea crear otra conexión para el proveedor de credenciales, complete los pasos anteriores.

Sugerencia

Use el portal para agregar, actualizar o eliminar conexiones a un proveedor de credenciales en cualquier momento. Para obtener más información, consulte Configuración de varias conexiones.

Paso 5: Adquirir un token de acceso de Microsoft Entra ID

Para habilitar el acceso delegado de usuario a la API de back-end, se debe proporcionar un token de acceso para el usuario o grupo delegado en tiempo de ejecución en la directiva de get-authorization-context. Normalmente, esto se realiza mediante programación en la aplicación cliente mediante la Biblioteca de autenticación de Microsoft (MSAL). En esta sección se proporcionan pasos manuales para crear un token de acceso para las pruebas.

  1. Pegue la siguiente dirección URL en el explorador, reemplazando los valores de <tenant-id> y <client-id> por valores del registro de la aplicación Microsoft Entra:

    https://login.microsoftonline.com/<tenant-id>/oauth2/authorize?client_id=<client-id>&response_type=code&redirect_uri=https://www.postman-echo.com/get&response_mode=query&resource=https://azure-api.net/authorization-manager&state=1234`

  2. Cuando se le solicite, inicie sesión. En el cuerpo de la respuesta, copie el valor de código proporcionado (ejemplo: "0.AXYAh2yl…").

  3. Envíe la siguiente solicitud de POST al punto de conexión del token, reemplazando <tenant-id> por el identificador de inquilino e incluyendo el encabezado indicado y los parámetros de cuerpo del registro de la aplicación y el código que copió en el paso anterior.

    POST https://login.microsoftonline.com/<tenant-id>/oauth2/token HTTP/1.1

    Encabezado

    Content-Type: application/x-www-form-urlencoded

    Cuerpo

    grant_type: "authorization_code"
client_id: <client-id>
client_secret: <client-secret>
redirect_uri: <redirect-url> 
code: <code>   ## The code you copied in the previous step

  4. En el cuerpo de la respuesta, copie el valor de access_token proporcionado (ejemplo: eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6IjZqQmZ1...). Pasará este valor en la configuración de directiva en el paso siguiente.

Paso 6: Configuración de la directiva get-authorization-context para la API de back-end

Configure la directiva get-authorization-context para la API de back-end a la que desea acceder en nombre del usuario o grupo. Con fines de prueba, puede configurar la directiva mediante el token de acceso de Microsoft Entra ID para el usuario que obtuvo en la sección anterior.

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

  2. En el menú de la izquierda, seleccione API y, después, seleccione la API de back-end de OAuth 2.0.

  3. Seleccione Todas las operaciones. En la sección Procesamiento de entrada, selecciona el icono del editor de código (</>).

  4. Configure la directiva de get-authorization-context en la sección inbound, estableciendo identity-type en jwt:

    <policies>
    <inbound>
        [...]
        <get-authorization-context provider-id="<credential-provider-id>" authorization-id="<connection-id>" context-variable-name="auth-context" identity-type="jwt" identity="<access-token>" ignore-error="false" />
        [...]
    </inbound> 
</policies>

En la definición de directiva anterior, reemplace:

  • <credential-provider-id> y <connection-id> con el nombre del proveedor de credenciales y la conexión, respectivamente, que configuró en los pasos anteriores.

  • <access-token> con el token de acceso de Microsoft Entra ID que generó en el paso anterior.

Paso 7: Probar la API

  1. En la pestaña Prueba, seleccione una operación que haya configurado.

  2. Seleccione Enviar.

    Una respuesta correcta devuelve datos de usuario de la API de back-end.

Contenido relacionado