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.

Siga los pasos de la sección Registro de una aplicación en Inicio rápido: Registro de una aplicación en la plataforma de identidad de Microsoft.

Omita la sección URI de redireccionamiento (opcional). No es necesario configurar un URI de redireccionamiento para las API web, ya que ningún usuario inicia sesión de forma interactiva.

Asignar 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. Seleccione la casilla de verificación para habilitar la función de la aplicación.

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.

Agregar un ámbito

Sugerencia

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

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. 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. Vaya a Identidad>Aplicaciones>Registros de aplicaciones y, después, seleccione el registro de aplicaciones de su API.

  4. Seleccione Exponer una API.

  5. Seleccione Agregar, que se encuentra junto a URI de Id. de aplicación, en caso de que no haya configurado ninguno.

    Puede usar el valor predeterminado de api://<application-client-id>, o cualquier otro patrón de identificador URI de aplicación compatible. 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.

  6. Seleccione Agregar un ámbito:

    An app registration's Expose an API pane in the Azure portal

  7. 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. Seleccione Solo administradores para permisos con más privilegios. Administradores y usuarios
    Nombre para mostrar del consentimiento del administrador Breve descripción del propósito del ámbito que solo verán los administradores. Read-only access to Employee records
    Descripción del consentimiento del administrador Descripción más detallada del permiso concedido por el ámbito que solo verán los administradores. Allow the application to have read-only access to all Employee data.
    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. Read-only access to your Employee records
    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. Allow the application to have read-only access to your Employee data.

  8. Establezca Estado en Habilitado y seleccione Agregar ámbito.

  9. (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 Employees.Write.All, siga los pasos de la sección Incorporación de un ámbito y especifique estos valores en el panel Agregar un ámbito:

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 Write access to Employee records
Descripción del consentimiento del administrador Allow the application to have write access to all Employee data.
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)

Establezca Estado en Habilitado y seleccione Agregar ámbito.

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:

Screenshot of the Expose an API pane showing two exposed scopes.

Como se muestra en la imagen, la cadena completa de un ámbito es la concatenación de los valores de URI de id. de aplicación de la API web y Nombre de ámbito 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.

Pasos siguientes

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