Compartir vía

Inicio rápido: Configuración de una aplicación para exponer una API web

  • Artículo

En este inicio rápido se registrará una API web en la plataforma de identidad de Microsoft y se agrega un ámbito para exponerla a las aplicaciones cliente. Al registrar su API web y exponerla a través de ámbitos, asignando un propietario y una función de aplicación, puede proporcionar acceso basado en permisos a sus recursos a usuarios autorizados y aplicaciones cliente que acceden a su API.

Requisitos previos

Registro de la API web

El acceso a API requiere configurar los ámbitos y roles de acceso. Si quiere exponer sus API web de aplicaciones de recursos a aplicaciones cliente, configure los roles y ámbitos de acceso de la API. Si quiere que una aplicación cliente pueda acceder a una API web, configure permisos de acceso a la API en el registro de la aplicación. Para proporcionar acceso con ámbito a los recursos de la API web, primero debe registrar la API en la plataforma de identidad de Microsoft.

  1. Inicie sesión en el Centro de administración de Microsoft Entra como Administrador de aplicaciones en la nube.
  2. Si tiene acceso a varios inquilinos, use el icono Configuración en el menú superior para cambiar al inquilino que contiene el registro de la aplicación desde el menú Directorios y suscripciones.
  3. Realice los pasos descritos en registrar una aplicación y omita la sección URI de redirección (opcional). No es necesario configurar un URI de redireccionamiento para las API web, ya que ningún usuario inicia sesión de forma interactiva.

Asignación de propietario de la aplicación

  1. En el registro de la aplicación, en Administrar, seleccione Propietarios y Agregar propietarios.
  2. En la nueva ventana, busque y seleccione los propietarios que desea asignar a la aplicación. Los propietarios seleccionados aparecen en el panel derecho. Una vez hecho, confirme con Seleccionar. Los propietarios de la aplicación aparecerán ahora en la lista del propietario.

Nota:

Asegúrese de que tanto la aplicación de API como la aplicación a la que desea agregar permisos tienen un propietario; de lo contrario, la API no aparecerá al solicitar permisos de API.

Asignar rol de aplicación

  1. En el registro de la aplicación, en Administrar, seleccione Roles de la aplicación y Crear rol de aplicación.

  2. A continuación, especifique los atributos del rol de aplicación en el panel Crear rol de aplicación. Para este tutorial, puede usar los valores de ejemplo o especificar los suyos propios.

    Campo Description Ejemplo
    Nombre para mostrar Nombre del rol de aplicación Registros de empleados
    Tipos de miembros permitido Especifica si el rol de aplicación se puede asignar a usuarios o grupos o aplicaciones Aplicaciones
    Valor Valor que se muestra en la notificación "roles" de un token Employee.Records
    Descripción Una descripción más detallada de la función de la aplicación Las aplicaciones tienen acceso a los registros de empleados

  3. Active la casilla para habilitar el rol de aplicación y, a continuación, seleccione Aplicar.

Agregar un ámbito

Sugerencia

Los pasos de este artículo pueden variar ligeramente en función del portal desde donde comienza.

Con la API web registrada y asignado un rol de aplicación y un propietario, puede agregar alcances al código de la API para que pueda proporcionar permiso granular a los consumidores.

El código de las aplicaciones cliente solicita permiso para realizar operaciones definidas por la API web; para ello, pasa un token de acceso junto con sus solicitudes al recurso protegido (la API web). A continuación, la API web realiza la operación solicitada solo si el token de acceso que recibe contiene los ámbitos necesarios para la operación.

En primer lugar, siga estos pasos para crear un ámbito de ejemplo denominado Employees.Read.All:

  1. Seleccione Exponer una API.

  2. En la parte superior de la página, seleccione Agregar junto a URI de identificador de aplicación. Este valor predeterminado es api://<application-client-id>. El URI de identificación de aplicación actúa como prefijo de los ámbitos a los que se hará referencia en el código de la API y debe ser único globalmente. Seleccione Guardar.

  3. Seleccione Agregar un ámbito:

    Panel de exposición de una API durante el registro de una aplicación en Azure Portal

  4. A continuación, especifique los atributos del ámbito en el panel Agregar un ámbito. Para este tutorial, puede usar los valores de ejemplo o especificar los suyos propios.

    Campo Description Ejemplo
    Nombre de ámbito Nombre del ámbito. Una convención de nomenclatura típica es resource.operation.constraint. Employees.Read.All
    ¿Quién puede dar el consentimiento? Si los usuarios pueden dar su consentimiento a este ámbito o si se requiere el consentimiento del administrador. Solo administradores deben usarse para permisos con privilegios superiores. Administradores y usuarios
    Nombre para mostrar del consentimiento del administrador Breve descripción del propósito del ámbito que solo verán los administradores. Acceso de solo lectura a los registros del empleado
    Descripción del consentimiento del administrador Descripción más detallada del permiso concedido por el ámbito que solo verán los administradores. Permitir que la aplicación tenga acceso de solo lectura a todos los datos del empleado.
    Nombre para mostrar del consentimiento del usuario Descripción breve del propósito del ámbito. Se muestra a los usuarios solo si establece Quién puede dar el consentimiento en Administradores y usuarios. Acceso de solo lectura a los registros del empleado
    Descripción del consentimiento del usuario Descripción más detallada del permiso concedido por el ámbito. Se muestra a los usuarios solo si establece Quién puede dar el consentimiento en Administradores y usuarios. Permitir que la aplicación tenga acceso de solo lectura a los datos del empleado.
    State Si el ámbito está habilitado o deshabilitado. Habilitado

  5. Selecciona la opción Agregar un ámbito.

  6. (Opcional) Para eliminar la solicitud de consentimiento por parte de los usuarios de su aplicación en los ámbitos que ha definido, puede preautorizar a la aplicación cliente para que acceda a su API web. Debe preautorizar únicamente a las aplicaciones cliente en las que confíe, ya que los usuarios no tendrán la oportunidad de rechazar el consentimiento.

    1. En Aplicaciones cliente autorizadas, seleccione Agregar una aplicación cliente
    2. Escriba el valor de Id. de aplicación (cliente) de la aplicación cliente que desea preautorizar. Por ejemplo, el de una aplicación web que ha registrado previamente.
    3. En Ámbitos autorizados, seleccione los ámbitos en que desea suprimir la solicitud de consentimiento y, después, seleccione Agregar aplicación.

    Si ha seguido este paso opcional, la aplicación cliente será ya una aplicación cliente preautorizada (PCA) y no se pedirá a los usuarios su consentimiento al iniciar sesión en ella.

A continuación, agregue otro ámbito de ejemplo denominado Employees.Write.All para el que solo los administradores puedan dar su consentimiento. Los ámbitos que requieren el consentimiento del administrador se suelen usar para proporcionar acceso a operaciones de mayor privilegio y, a menudo, los usan aplicaciones cliente que se ejecutan como servicios back-end o demonios que no inician sesión de forma interactiva.

Para agregar el ámbito de ejemplo de Employees.Write.All, siga los pasos descritos en la sección Agregar un ámbito y especifique estos valores en el panel Agregar un ámbito. Seleccione Agregar ámbito cuando haya terminado:

Campo Valor de ejemplo
Nombre de ámbito Employees.Write.All
¿Quién puede dar el consentimiento? Solo administradores
Nombre para mostrar del consentimiento del administrador Acceso de escritura a registros de empleados
Descripción del consentimiento del administrador Permitir que la aplicación tenga acceso de escritura a todos los datos del empleado.
Nombre para mostrar del consentimiento del usuario Ninguno (deje este campo en blanco)
Descripción del consentimiento del usuario Ninguno (deje este campo en blanco)
State Habilitado

Verificación de los ámbitos expuestos

Si ha agregado correctamente los dos ámbitos de ejemplo descritos en las secciones anteriores, aparecerán en el panel Exponer una API del registro de la aplicación de API web, de forma similar a la siguiente imagen:

Captura de pantalla del panel Exponer una API que muestra dos ámbitos expuestos.

La cadena completa del ámbito es la concatenación de la URI de identificador de aplicación de la API web y el nombre del ámbito Nombre del ámbito. Por ejemplo, si el identificador URI de aplicación de la API web es https://contoso.com/api y el nombre del ámbito es Employees.Read.All, el ámbito completo es:

https://contoso.com/api/Employees.Read.All

Uso de los ámbitos expuestos

En el siguiente artículo de esta serie, configurará el registro de una aplicación cliente con acceso a su API web y los ámbitos que haya definido mediante los pasos de este artículo.

Una vez que el registro de una aplicación cliente tenga permiso para acceder a la API web, se puede emitir un token de acceso de OAuth 2.0 para el cliente mediante la plataforma de identidad. Cuando el cliente llama a la API web, presenta un token de acceso cuya demanda de ámbito (scp) se establece en los permisos especificados en el registro de la aplicación cliente.

Puede exponer ámbitos adicionales posteriormente si es necesario. Tenga en cuenta que la API web puede exponer varios ámbitos asociados a varias operaciones. El recurso puede controlar el acceso a la API web en tiempo de ejecución, mediante la evaluación de las notificaciones de ámbito (scp) del token de acceso de OAuth 2.0 recibido.

Paso siguiente

Ahora que ha expuesto su API web mediante la configuración de sus ámbitos, configure el permiso para acceder a esos ámbitos en el registro de la aplicación cliente.

Configuración de una aplicación para acceder a una API web