Compartir vía

Autorización de la consola de prueba del portal para desarrolladores mediante la configuración de la autorización de usuarios de OAuth 2.0

  • Artículo

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

Muchas API admiten OAuth 2.0 para proteger la API y garantizar que solo usuarios válidos obtengan acceso y que, además, solo puedan tener acceso a los recursos para los que estén autorizados. Para usar la consola para desarrolladores interactiva de Azure API Management con estas API, el servicio le permite configurar un proveedor externo para la autorización de usuarios de OAuth 2.0.

La configuración de la autorización de usuario de OAuth 2.0 en la consola de prueba del portal para desarrolladores proporciona a los desarrolladores una manera cómoda de adquirir un token de acceso de OAuth 2.0. En la consola de prueba, el token posteriormente se pasa al back-end con la llamada API. La validación de tokens debe configurarse por separado, ya sea mediante una directiva de validación JWTo en el servicio de back-end.

Requisitos previos

En este artículo, se explica cómo configurar una instancia del servicio API Management para que use la autorización de OAuth 2.0 en la consola de prueba del portal para desarrolladores, pero no se muestra cómo configurar un proveedor de OAuth 2.0.

Si todavía no ha creado una instancia de servicio de API Management, consulte Creación de una instancia de servicio de API Management.

Información general de escenario

La configuración de la autorización de usuario OAuth 2.0 en API Management solo permite a la consola de pruebas del portal de desarrolladores (y a la consola de pruebas del portal Azure) como cliente adquirir un token del servidor de autorización. Aunque los proveedores de OAuth 2.0 tienen configuraciones diferentes, los pasos son similares y se precisa la misma información para configurar OAuth 2.0 en la instancia del servicio API Management. En este artículo se muestra un ejemplo en el que se usa Microsoft Entra ID como proveedor de OAuth 2.0.

Estos son los pasos de configuración de alto nivel:

  1. Registre una aplicación (aplicación de back-end) en Microsoft Entra ID para representar la API.

  2. Registre otra aplicación (aplicación cliente) en Microsoft Entra ID que represente una aplicación cliente que necesite llamar a la API (en este caso, la consola de prueba del portal para desarrolladores).

    En Microsoft Entra ID, conceda permisos para que la aplicación cliente llame a la aplicación de back-end.

  3. Configure la consola de prueba del portal para desarrolladores para llamar a una API mediante la autorización de usuarios de OAuth 2.0.

  4. Configure una API para usar la autorización de usuarios de OAuth 2.0.

  5. Agregue una directiva para preautorizar el token de OAuth 2.0 para todas las solicitudes entrantes. Puede usar la directiva validate-jwt para cualquier proveedor de OAuth 2.0.

Esta configuración admite el flujo de OAuth siguiente:

Gráfico de información general para conceptualizar visualmente el flujo siguiente.

  1. El portal para desarrolladores solicita un token de Microsoft Entra ID con las credenciales de la aplicación cliente.

  2. Después de la validación correcta, Microsoft Entra ID emite el token de acceso o actualización.

  3. Un desarrollador (usuario del portal para desarrolladores) realiza una llamada API con el encabezado de autorización.

  4. Microsoft Entra ID valida el token mediante el uso de la directiva validate-jwt en API Management.

  5. En función del resultado de la validación, el desarrollador recibirá la respuesta en el portal para desarrolladores.

Tipos de concesión de autorización

Azure API Management admite los siguientes tipos de concesión (flujos) de OAuth 2.0. Un tipo de concesión hace referencia a una manera de que una aplicación cliente (en este contexto, la consola de prueba del portal para desarrolladores) para obtener un token de acceso a la API de back-end. Puede configurar uno o varios tipos de concesión, en función del proveedor y los escenarios de OAuth 2.0.

A continuación se muestra un resumen de alto nivel. Para obtener más información sobre los tipos de concesión, consulte Marco de autorización de OAuth 2.0 y Tipos de concesión de OAuth.

Tipo de concesión Descripción Escenarios
Código de autorización Intercambios del código de autorización para el token Aplicaciones del lado servidor, como aplicaciones web
Código de autorización + PKCE Mejora del flujo de código de autorización que crea un desafío de código que se envía con la solicitud de autorización Clientes móviles y públicos que no pueden proteger un secreto o token
Implícito (en desuso) Devuelve el token de acceso inmediatamente sin un paso de intercambio de código de autorización adicional. Clientes que no pueden proteger un secreto o token, como aplicaciones móviles y aplicaciones de página única.

Por lo general, no se recomienda debido a los riesgos inherentes que conlleva devolver el token de acceso en el redireccionamiento HTTP sin confirmación de que lo recibe el cliente.
Contraseña del propietario del recurso Solicita credenciales de usuario (nombre de usuario y contraseña), normalmente mediante un formulario interactivo. Para su uso con aplicaciones de alta confianza.

Solo se debe usar cuando no se puedan usar otros flujos más seguros.
Credenciales de cliente Autentica y autoriza una aplicación en lugar de un usuario. Aplicaciones de máquina a máquina que no requieren permisos de un usuario concreto para acceder a datos, como las CLI, los demonios o los servicios que se ejecutan en el back-end

Consideraciones de seguridad

Tenga en cuenta cómo el tipo de concesión genera un token, el ámbito del token y cómo se podría exponer ese token. Un actor malintencionado podría usar un token en peligro para acceder a recursos adicionales dentro del ámbito del token.

Al configurar la autorización de usuario de OAuth 2.0 en la consola de prueba del portal para desarrolladores:

  • Limite el ámbito del token al mínimo necesario para que los desarrolladores prueben las API. Limite el ámbito a la consola de prueba o a las API afectadas. Los pasos para configurar el ámbito del token dependen del proveedor de OAuth 2.0.

    En función de los escenarios, puede configurar ámbitos de token más o menos restrictivos para otras aplicaciones cliente que cree para acceder a las API de back-end.

  • Tenga especial cuidado si habilita el flujo de credenciales de cliente. La consola de prueba del portal para desarrolladores, cuando se trabaja con el flujo de credenciales de cliente, no solicita credenciales. Un token de acceso podría exponerse accidentalmente a desarrolladores o usuarios anónimos de la consola del desarrollador.

Realizar un seguimiento de la información clave

A lo largo de este tutorial, se le pedirá que registre información clave para hacer referencia a ella más adelante sobre:

  • Id. de la aplicación de back-end (cliente): GUID de la aplicación que representa la API de back-end
  • Ámbitos de la aplicación de back-end: uno o varios ámbitos que puede crear para acceder a la API. El formato del ámbito es api://<Backend Application (client) ID>/<Scope Name> (por ejemplo, api://1764e900-1827-4a0b-9182-b2c1841864c2/Read)
  • Id. de la aplicación cliente (cliente): GUID de la aplicación que representa el portal para desarrolladores
  • Valor del secreto de la aplicación cliente: GUID que actúa como secreto para la interacción con la aplicación cliente en Microsoft Entra ID

Registro de aplicaciones en el servidor de OAuth

Tendrá que registrar dos aplicaciones en el proveedor de OAuth 2.0: una representa la API de back-end que se va a proteger y la otra representa la aplicación cliente que llama a la API (en este caso, la consola de prueba del portal para desarrolladores).

A continuación se muestran los pasos de ejemplo que usan Microsoft Entra ID como proveedor de OAuth 2.0. Para obtener detalles sobre el registro de aplicaciones, vea Inicio rápido: Configuración de una aplicación para exponer las API web.

Registro de una aplicación en Microsoft Entra ID para representar la API

  1. En Azure Portal, busque y seleccione Registros de aplicaciones.

  2. Seleccione Nuevo registro.

  3. Cuando aparece la página Registrar una aplicación, escriba la información de registro de la aplicación:

    • En la sección Nombre, escriba un nombre significativo para la aplicación, que se mostrará a los usuarios de la aplicación, por ejemplo, backend-app.
    • En la sección Tipos de cuenta admitidos, seleccione una opción que se ajuste a su escenario.

  4. Deje vacía la sección URI de redireccionamiento. Más adelante, agregará un identificador URI de redireccionamiento generado en la configuración de OAuth 2.0 en API Management.

  5. Seleccione Registrar para crear la aplicación.

  6. En la página Información general de la aplicación, busque el valor de Id. de aplicación (cliente) y regístrelo para usarlo más tarde.

  7. En la sección Administrar del menú lateral, seleccione Exponer una API y configure el URI del id. de aplicación con el valor predeterminado. Anote este valor para más adelante.

  8. Seleccione el botón Agregar un ámbito para mostrar la página Agregar un ámbito:

    1. Escriba un Nombre de ámbito para un ámbito compatible con la API (por ejemplo, Files.Read).
    2. En ¿Quién puede dar el consentimiento?, haga una selección para su escenario, como Administradores y usuarios. Seleccione Solo administradores para escenarios con privilegios más elevados.
    3. Escriba un Nombre para mostrar del consentimiento del administrador y una Descripción del consentimiento del administrador.
    4. Asegúrese de seleccionar el estado del ámbito Habilitado.

  9. Seleccione el botón Agregar ámbito para crear el ámbito.

  10. Repita los dos pasos anteriores para agregar todos los ámbitos que admita la API.

  11. Cuando se creen los ámbitos, anótelos para usarlos en un paso posterior.

Registro de otra aplicación en Microsoft Entra ID que represente una aplicación cliente

Registre todas las aplicaciones cliente que llamen a la API como aplicación en Microsoft Entra ID.

  1. En Azure Portal, busque y seleccione Registros de aplicaciones.

  2. Seleccione Nuevo registro.

  3. Cuando aparece la página Registrar una aplicación, escriba la información de registro de la aplicación:

    • En la sección Nombre, escriba un nombre significativo para la aplicación, que se mostrará a los usuarios de la aplicación, por ejemplo, client-app.
    • En la sección Tipos de cuenta admitidos, seleccione una opción que se ajuste a su escenario.

  4. En la sección URI de redirección, seleccione Web y deje el campo de dirección URL vacío por ahora.

  5. Seleccione Registrar para crear la aplicación.

  6. En la página Información general de la aplicación, busque el valor de Id. de aplicación (cliente) y regístrelo para usarlo más tarde.

  7. Cree un secreto de cliente para esta aplicación que se usará en un paso posterior.

    1. En la sección Administrar del menú lateral, seleccione Certificados y secretos.
    2. En Secretos de cliente, seleccione +Nuevo secreto de cliente.
    3. En Agregar un secreto de cliente, escriba la Descripción y elija cuándo debe caducar la clave.
    4. Seleccione Agregar.

Cuando se cree el secreto, anote el valor de clave para usarlo en un paso posterior. No se puede volver a acceder al secreto en el portal.

Concesión de permisos en Microsoft Entra ID

Ahora que ha registrado dos aplicaciones que representan la API y la consola de prueba, conceda permisos para que la aplicación cliente pueda llamar a la aplicación back-end.

  1. En Azure Portal, busque y seleccione Registros de aplicaciones.

  2. Seleccione la aplicación cliente. En el menú lateral, seleccione Permisos de API.

  3. Seleccione + Agregar un permiso.

  4. En Seleccionar una API, seleccione Mis API y busque y seleccione la aplicación de back-end.

  5. Seleccione Permisos delegados y, a continuación, seleccione los permisos apropiados para la aplicación de back-end.

  6. Seleccione Agregar permisos.

Opcionalmente:

  1. Vaya a la página Permisos de API de la aplicación cliente.

  2. Seleccione Conceder el consentimiento del administrador para <nombre-inquilino> y así conceder el consentimiento en nombre de todos los usuarios de este directorio.

Configuración de un servidor de autorización OAuth 2.0 en API Management

  1. Vaya a la instancia de API Management en Azure Portal.

  2. En la opción Portal para desarrolladores del menú lateral, seleccione OAuth 2.0 y OpenID Connect.

  3. En la pestaña OAuth 2.0, seleccione + Agregar.

    Menú OAuth 2.0

  4. Escriba un nombre y una descripción opcional en los campos Nombre y Descripción.

    Nota

    Estos campos sirven para identificar el servidor de autorización OAuth 2.0 en el servicio API Management. Sus valores no proceden del servidor de OAuth 2.0.

  5. Escriba la URL de la página de registro de cliente; por ejemplo, https://contoso.com/login. Esta página es donde los usuarios pueden crear y administrar sus cuentas, si el proveedor de OAuth 2.0 admite la administración de cuentas de usuario. La página varía en función del proveedor de OAuth 2.0 usado.

    Si el proveedor de OAuth 2.0 no tiene configurada la administración de usuarios de las cuentas, especifique aquí una dirección URL de marcador de posición, por ejemplo, la dirección URL de su empresa o una URL como http://localhost.

    Nuevo servidor de OAuth 2.0

  6. La siguiente sección del formulario contiene la configuración de Authorization grant types (Tipos de concesión de autorización), Authorization endpoint URL (URL del punto de conexión de autorización) y Authorization request method (Método de solicitud de autorización).

    • Seleccione uno o varios tipos de concesión de autorización deseados. En este ejemplo, seleccione Código de autorización (valor predeterminado). Más información

    • Escriba la URL del extremo de autorización. La dirección URL del punto de conexión se puede obtener en la página Puntos de conexión de uno de los registros de la aplicación. Para una aplicación de un solo inquilino en Microsoft Entra ID, esta dirección URL será similar a una de las siguientes, donde {aad-tenant} se reemplaza por el identificador de su inquilino de Microsoft Entra.

      Se recomienda usar el punto de conexión v2; sin embargo, API Management admite puntos de conexión v1 y v2.

      https://login.microsoftonline.com/{aad-tenant}/oauth2/v2.0/authorize (v2)

      https://login.microsoftonline.com/{aad-tenant}/oauth2/authorize (v1)

    • El Método de solicitud de autorización especifica cómo se envía la solicitud de autorización al servidor OAuth 2.0. Seleccione POST.

    Especificar la configuración de autorización

  7. Especifique los valores de URL de punto de conexión del token, Métodos de autenticación del cliente, Método de envío del token de acceso y Ámbito predeterminado.

    • Escriba la URL de punto de conexión del token. Para una aplicación de un solo inquilino en Microsoft Entra ID, será similar a una de las siguientes, donde {aad-tenant} se reemplaza por el identificador de su inquilino de Microsoft Entra. Use la misma versión del punto de conexión (v2 o v1) que eligió anteriormente.

      https://login.microsoftonline.com/{aad-tenant}/oauth2/v2.0/token (v2)

      https://login.microsoftonline.com/{aad-tenant}/oauth2/token (v1)

    • Si usa puntos de conexión v1, agregue un parámetro de cuerpo:
      * Nombre: recurso.
      * Valor: el valor de id. de aplicación (cliente) de la aplicación de back-end.

    • Si usa puntos de conexión v2:
      * Especifique el ámbito de la aplicación de back-end que creó en el campo Ámbito predeterminado.
      * Establezca el valor de la propiedad accessTokenAcceptedVersion en 2 en el manifiesto de aplicación de los registros tanto de la aplicación de back-end como de la aplicación cliente.

    • Acepte la configuración predeterminada de Métodos de autenticación de cliente y Método de envío de tokens de acceso.

  8. En Credenciales de cliente, escriba el Id. de cliente y el Secreto del cliente que obtuvo en los procesos de creación y configuración de la aplicación cliente.

  9. Tras especificar los valores de Id. de cliente y el Secreto del cliente, se genera el valor de URI de redirección para el código de autorización. Este identificador URI se usa para configurar el identificador URI de redirección en la configuración del servidor de OAuth 2.0.

    En el portal para desarrolladores, el sufijo del URI tiene el formato siguiente:

    • /signin-oauth/code/callback/{authServerName} para el flujo de concesión de código de autorización
    • /signin-oauth/implicit/callback para el flujo de concesión implícita

    Agregar credenciales de cliente para el servicio OAuth 2.0

    Copie el identificador URI de redirección adecuado en la página Autenticación del registro de la aplicación cliente. En el registro de la aplicación, seleccione Autenticación>+ Agregar una plataforma>Web y, a continuación, escriba el URI de redirección.

  10. Si Authorization grant types (Tipos de concesión de autorización) se establece en Resource owner password (Contraseña de propietario de recursos), las credenciales se especifican con la sección Resource owner password credentials (Credenciales de contraseña de propietario de recursos). De no ser así, puede dejarse en blanco.

  11. Seleccione Crear para guardar la configuración del servidor de autorización OAuth 2.0 de API Management.

  12. Vuelva a publicar el portal para desarrolladores.

    Importante

    Al realizar cambios relacionados con OAuth 2.0, asegúrese de volver a publicar el portal para desarrolladores después de cada modificación como cambios pertinentes (por ejemplo, cambio de ámbito); de lo contrario, no se puede propagar al portal y, posteriormente, usarse para probar las API.

Configuración de una API para usar la autorización de usuarios OAuth 2.0

Después de guardar la configuración del servidor OAuth 2.0, configure una o varias API para que usen esta configuración.

Importante

  • La configuración de la configuración de autorización de usuario de OAuth 2.0 para una API permite a API Management adquirir un token del servidor de autorización al usar la consola de prueba en el portal para desarrolladores o Azure Portal. La configuración del servidor de autorización también se agrega a la definición y la documentación de la API.
  • Para la autorización de OAuth 2.0 en tiempo de ejecución, la aplicación cliente debe adquirir y presentar el token y debe configurar la validación de tokens en API Management o la API de back-end. Para obtener un ejemplo, consulte Protección de cualquier API en Azure API Management mediante la autorización de OAuth 2.0 con Microsoft Entra ID.

  1. Seleccione la API en el menú API Management de la izquierda.

  2. Seleccione el nombre de la API deseada y haga clic en la pestaña Configuración. Desplácese hasta la sección Seguridad y, a continuación, seleccione OAuth 2.0.

  3. Seleccione el Servidor de autorización que quiera en la lista desplegable y haga clic en Guardar.

    Configuración del servidor de autorización OAuth 2.0

Portal para desarrolladores: prueba de la autorización de usuarios OAuth 2.0

Tras configurar el servidor de autorización OAuth 2.0 y las API para que usen dicho servidor, puede probarlo. Para ello, vaya al portal para desarrolladores y llame a una API.

  1. Haga clic en Portal para desarrolladores en el menú superior de la página Introducción de la instancia de Azure API Management.

  2. Vaya a cualquier operación de la API en el portal para desarrolladores.

  3. Seleccione Probar para acceder a la Consola para desarrolladores.

  4. Tenga en cuenta el nuevo elemento de la sección Autorización correspondiente al servidor de autorización que acaba de agregar.

  5. Seleccione el Código de autorización de la lista desplegable de autorización.

    Seleccione la autorización del código de autorización

  6. Cuando se le solicite, inicie sesión en el inquilino de Microsoft Entra.

    • Si ya ha iniciado sesión con la cuenta, es posible que no se le indique nada.

  7. Al iniciar sesión correctamente, un encabezado Authorization se agregará a la solicitud con un token de acceso de Microsoft Entra ID. A continuación se muestra un token de ejemplo abreviado (codificado en Base64):

    Authorization: Bearer eyJ0eXAiOi[...]3pkCfvEOyA

  8. Configure los valores deseados para los parámetros restantes y seleccione Enviar para llamar a la API.

Configurar una directiva de validación de JWT para autorizar previamente las solicitudes

En la configuración realizada hasta ahora, API Management no valida el token de acceso. Solo pasa el token en el encabezado de autorización a la API de back-end.

Para preautorizar las solicitudes configure una directiva validate-jwt para validar el token de acceso de cada solicitud entrante. Si una solicitud no tiene un token válido, API Management lo bloquea.

Cuando se agrega la siguiente directiva de ejemplo a la sección de la directiva <inbound>, se comprueba el valor de la notificación de audiencia en un token de acceso obtenido de Microsoft Entra ID que se presenta en el encabezado Authorization. Devuelve un error si el token no es válido. Configure esta directiva en un ámbito de directiva adecuado para su escenario.

  • En la dirección URL openid-config, el valor aad-tenant es el identificador de inquilino en Microsoft Entra ID. Busque este valor en Azure Portal, por ejemplo, en la página Información general del recurso de Microsoft Entra. En el ejemplo que se muestra se dan por hecho una aplicación de Microsoft Entra de un solo inquilino y un punto de conexión de configuración v2.
  • El valor de claim es el identificador de cliente de la aplicación de back-end que registró en Microsoft Entra ID.
<validate-jwt header-name="Authorization" failed-validation-httpcode="401" failed-validation-error-message="Unauthorized. Access token is missing or invalid.">
    <openid-config url="https://login.microsoftonline.com/{aad-tenant}/v2.0/.well-known/openid-configuration" />
    <audiences>
        <audience>{audience-value - (ex:api://guid)}</audience>
    </audiences>
    <issuers>
        <issuer>{issuer-value - (ex: https://sts.windows.net/{tenant id}/)}</issuer>
    </issuers>
    <required-claims>
        <claim name="aud">
            <value>{backend-app-client-id}</value>
        </claim>
    </required-claims>
</validate-jwt>

Nota:

La dirección URL openid-config anterior corresponde al punto de conexión v2. En cuanto al punto de conexión v1 openid-config, use https://login.microsoftonline.com/{aad-tenant}/.well-known/openid-configuration.

Para información sobre cómo configurar directivas, consulte el artículo sobre edición o establecimiento de directivas. Consulte la referencia validate-jwt para obtener más personalización en las validaciones de JWT. Para validar un JWT proporcionado por el servicio Microsoft Entra, API Management también proporciona la directiva validate-azure-ad-token.

Contenido relacionado