Compartir vía

API web protegida: Registro de aplicación

  • Artículo

En este artículo se explica cómo registrar una aplicación para una API web protegida.

Para conocer los pasos comunes para registrar una aplicación, consulte Inicio rápido: Registro de una aplicación en la plataforma de identidad de Microsoft.

Versión del token aceptada

La plataforma de identidad de Microsoft puede emitir tokens v1.0 y v2.0. Para obtener más información sobre estos tokens, consulte Tokens de acceso.

La versión del token que puede aceptar la API depende de los tipos de cuenta admitidos que haya seleccionado al crear el registro de aplicación de API web en Azure Portal.

  • Si el valor de Tipos de cuenta admitidos es Cuentas en cualquier directorio organizativo y cuentas personales de Microsoft (como Skype, Xbox, Outlook.com), la versión del token aceptado debe ser v2.0.
  • En caso contrario, la versión del token aceptada puede ser la v1.0.

Después de crear la aplicación, puede determinar o cambiar la versión del token aceptada siguiendo estos pasos:

  1. En el Centro de administración de Microsoft Entra, seleccione la aplicación y, a continuación, seleccione Manifiesto.
  2. Busque la propiedad accessTokenAcceptedVersion en el manifiesto.
  3. El valor especifica a Microsoft Entra la versión del token que acepta la API web.
    • Si el valor es 2, la API web acepta tokens v 2.0.
    • Si el valor es NULL, la API web acepta tokens v1.0.
  4. Si ha cambiado la versión del token, seleccione Guardar.

La API web especifica qué versión del token acepta. Cuando un cliente solicita un token para la API web desde la Plataforma de identidad de Microsoft, el cliente obtiene un token que indica qué versión del token acepta la API web.

URI sin redireccionamiento

Las API web no necesitan registrar ningún URI de redirección porque no hay ningún usuario con la sesión iniciada de forma interactiva.

API expuesta

Otra configuración específica de las API web es la API expuesta y los ámbitos o roles de aplicación expuestos.

Ámbitos y el URI de identificador de aplicación

Normalmente, los ámbitos tienen el formato resourceURI/scopeName. En Microsoft Graph, los ámbitos tienen accesos directos. Por ejemplo, User.Read es un acceso directo de https://graph.microsoft.com/user.read.

Durante el registro de la aplicación, defina estos parámetros:

  • URI del recurso
  • Uno o varios ámbitos
  • Uno o varios roles de aplicación

De forma predeterminada, el portal de registro de aplicación recomienda usar el URI de recurso api://{clientId}. Este URI es único pero no es legible para los humanos. Si cambia el URI, asegúrese de que el nuevo valor sea único. El portal de registro de aplicaciones se asegurará de que use un dominio de editor configurado.

Para las aplicaciones cliente, los ámbitos se muestran como permisos delegados y los roles de aplicación se muestran como permisos de aplicación para la API web.

También aparecen ámbitos en la ventana de consentimiento que se presenta a los usuarios de la aplicación. Por lo tanto, proporcione las cadenas correspondientes que describen el ámbito:

  • Como las ve un usuario.
  • Como las ve un administrador de inquilinos, que puede otorgar consentimiento de administrador.

Un usuario no puede dar su consentimiento a los roles de aplicación (ya que los usa una aplicación que llama a la API web en su propio nombre). Un administrador de inquilinos tendrá que dar su consentimiento a las aplicaciones cliente de la API web que exponen roles de aplicación. Consulte el consentimiento del administrador para obtener más información.

Exponer permisos delegados (ámbitos)

Para exponer permisos delegados, o ámbitos, siga los pasos en Configurar una aplicación para exponer una API web.

Si sigue el escenario de la API web descrito en este conjunto de artículos, use esta configuración:

  • URI del Id. de la aplicación: Acepte el URI de Id. de aplicación propuesto (api://<clientId>) (si se le solicita)
  • Nombre del ámbito: access_as_user
  • Quién puede dar su consentimiento: administradores y usuarios
  • Nombre para mostrar el consentimiento del administrador: acceder a TodoListService como usuario
  • Descripción del consentimiento del administrador: acceder a la API web de TodoListService como usuario
  • Nombre para mostrar el consentimiento del usuario: acceder a TodoListService como usuario
  • Descripción del consentimiento del usuario: acceder a la API web de TodoListService como usuario
  • Estado: Enabled

Sugerencia

En URI de id. de aplicación, tiene la opción de establecer el valor en la autoridad física de la API, por ejemplo https://graph.microsoft.com. Esto puede resultar útil si se conoce la dirección URL de la API a la que se debe llamar.

Si la API de su web es llamada por un servicio o una aplicación demonio

Exponga permisos de aplicación en lugar de permisos delegados si los demonios, servicios u otras aplicaciones no interactivas (por un usuario) deben tener acceso a la API. Dado que las aplicaciones de tipo de servicio y demonio se ejecutan desatendidas y se autentican con su propia identidad, no hay ningún usuario para "delegar" su permiso.

Exposición de los permisos de aplicación (roles de la aplicación)

Para exponer permisos de aplicación, siga los pasos descritos en Incorporación de roles de aplicación a la aplicación.

En el panel Crear rol de aplicación en Tipos de miembros permitidos, seleccione Aplicaciones. O bien, agregue el rol mediante el Editor de manifiestos de aplicación, tal y como se describe en el artículo.

Restricción de tokens de acceso a aplicaciones de clientes específicos

Los roles de aplicación son el mecanismo que usa un desarrollador de aplicaciones para exponer los permisos de aplicación. El código de la API web debe comprobar si hay roles de aplicación en los tokens de acceso que recibe de los autores de llamadas.

Para agregar otra capa de seguridad, un Administrador de inquilinos de Microsoft Entra puede configurar su inquilino para que el plataforma de identidad de Microsoft emita tokens de seguridad solo a las aplicaciones cliente que han aprobado para el acceso a la API.

Para aumentar la seguridad mediante la restricción de la emisión de tokens solo a las aplicaciones cliente que se han asignado roles de aplicación:

  1. En el Centro de administración de Microsoft Entra, seleccione su aplicación en Identidad>Aplicaciones>Registros de aplicaciones.
  2. En la página de Información general de la aplicación, en Aspectos esenciales, busque y seleccione el vínculo de Aplicación administrada en el directorio local para acceder a su página de Información general de la aplicación empresarial.
  3. En Administrar, seleccione Propiedades.
  4. Establezca ¿Asignación requerida? en Sí.
  5. Seleccione Guardar.

Microsoft Entra ID comprobará ahora las asignaciones de roles de aplicación de las aplicaciones cliente que solicitan tokens de acceso para la API web. Si no se ha asignado ningún rol de aplicación a una aplicación cliente, Microsoft Entra ID devuelve un mensaje de error al cliente similar a _invalid_client: AADSTS501051: Application \<application name\> isn't assigned to a role for the \<web API\>_.

Advertencia

NO use los códigos de error AADSTS o las cadenas de mensajes como literales en el código de su aplicación. Los códigos de error "AADSTS" y las cadenas de mensajes de error que devuelve Microsoft Entra ID no se pueden modificar, y Microsoft puede cambiarlos en cualquier momento y sin que el usuario lo sepa. Si toma decisiones de bifurcación en su código en función de los valores de los códigos AADSTS o de las cadenas de mensajes, pone en riesgo la funcionalidad y estabilidad de la aplicación.

Paso siguiente

El siguiente artículo de esta serie es Configuración de código de aplicación.