Compartir por

Protección de API

Cuando proteges tu API, te centras en la autorización como desarrollador. Para llamar a la API del recurso, las aplicaciones deben adquirir autorización de aplicación. El recurso refuerza la autorización. En este artículo, obtendrá información sobre los procedimientos recomendados para lograr sus objetivos de confianza cero . Se describe cómo proteger tu API mediante el registro, la definición de permisos y consentimiento, y la aplicación de medidas de acceso.

Registro de la API protegida

Para proteger la API con el identificador de Microsoft Entra (Id. de Microsoft Entra), registre la API. A continuación, puede administrar las API registradas. En Microsoft Entra ID, una API es una aplicación con una configuración de registro de aplicaciones específica que la define como un recurso o UNA API a la que puede acceder otra aplicación. En el Centro de administración de Microsoft Entra, los desarrolladores de identidad de Microsoft y los registros de aplicaciones son API que se encuentran en el inquilino, ya sea como API de línea de negocio o servicios de proveedores de Software como Servicio (SaaS), que tienen API que Microsoft Entra ID protege.

Durante el registro, se define cómo las aplicaciones que llaman hacen referencia a la API y sus permisos delegados y de aplicación. Un registro de aplicaciones puede representar una solución que tenga aplicaciones cliente y API. Sin embargo, en este artículo se aborda el escenario en el que un recurso independiente expone una API.

Normalmente, una API no realiza la autenticación ni solicita directamente autorización. La API valida un token que presenta la aplicación que llama. Las API no tienen inicios de sesión interactivos, por lo que no es necesario registrar la configuración, como el URI de redireccionamiento o el tipo de aplicación. Las API obtienen sus tokens de las aplicaciones que llaman a esas API, no interactuando con el identificador de Entra de Microsoft. Para las API web, use tokens de acceso de OAuth2 para la autorización. Las API web validan los tokens de portador para autorizar a los autores de llamadas. No acepte ID tokens como prueba de autorización.

De forma predeterminada, el identificador de Microsoft Entra agrega User.Read a los permisos de API de cualquier registro de aplicación nuevo. Quite este permiso para la mayoría de las API web. Microsoft Entra ID solo requiere permisos de API cuando una API llama a otra API. Si la API no llama a otra API, quite el permiso User.Read al registrar su API.

Necesita un identificador único para su API, conocido como URI de identificación de la aplicación, que las aplicaciones cliente solicitan permiso para llamar a su API. El URI del identificador de aplicación debe ser único en todos los inquilinos de Microsoft Entra. Puede usar api://<clientId> (la sugerencia predeterminada en el portal), donde <clientId> es el identificador de aplicación de la API registrada.

Para proporcionar a los desarrolladores que están llamando a su API un nombre más fácil de usar, puede utilizar la dirección de su API como el URI de identificación de la aplicación. Por ejemplo, puede usar https://API.yourdomain.com donde yourdomain.com es un dominio de publicador configurado en la entidad de Microsoft Entra. Microsoft valida que tiene la propiedad del dominio para que pueda usarla como identificador único de la API. No es necesario tener código en esta dirección. La API puede ser donde quiera que sea, pero se recomienda usar la https dirección de la API como URI del identificador de aplicación.

Definición de permisos delegados con privilegios mínimos

Si las aplicaciones que tienen usuarios van a llamar a la API, defina al menos un permiso delegado (consulte Agregar un ámbito en el registro de la aplicación Exponer una API).

Las API que proporcionan acceso a los almacenes de datos de la organización pueden atraer la atención de actores incorrectos que desean acceder a esos datos. En lugar de tener solo un permiso delegado, diseñe los permisos con el principio de confianza cero del acceso con privilegios mínimos en mente. Puede ser difícil entrar en un modelo con privilegios mínimos más adelante si todas las aplicaciones cliente comienzan con acceso con privilegios completos.

A menudo, los desarrolladores caen en un patrón de uso de un solo permiso como acceso como usuario o suplantación de usuario (la cual es una frase común pero técnicamente inexacta). Los permisos únicos como estos solo permiten el acceso con privilegios completos a la API.

Declare ámbitos de privilegios mínimos para que las aplicaciones no sean vulnerables a riesgos o se usen para realizar una tarea que nunca ha pensado. Defina los varios ámbitos en permisos de API. Por ejemplo, separe los ámbitos de lectura y actualización de datos y considere la posibilidad de ofrecer permisos de solo lectura. El acceso de escritura incluye privilegios para las operaciones de creación, actualización y eliminación. Un cliente nunca debería requerir acceso de escritura solo para datos de lectura.

Tenga en cuenta los permisos de acceso estándar y completo cuando la API funciona con datos confidenciales. Restrinja las propiedades confidenciales para que un permiso estándar no permita el acceso (por ejemplo, Resource.Read). A continuación, implemente un permiso de acceso completo (por ejemplo, Resource.ReadFull) que devuelva propiedades e información confidencial.

Evalúe siempre los permisos que solicite para asegurarse de que busca el conjunto de privilegios mínimos absolutos para realizar el trabajo. Evite solicitar permisos de privilegios mayores. En su lugar, cree un permiso individual para cada escenario principal. Consulte la referencia de permisos de Microsoft Graph para obtener buenos ejemplos de este enfoque. Localice y use solo el número correcto de permisos para satisfacer sus necesidades.

Como parte de las definiciones de ámbito, decida si el intervalo de operaciones que se puede realizar con un ámbito determinado requiere el consentimiento del administrador.

Como diseñador de API, puede proporcionar instrucciones sobre qué ámbitos pueden requerir de forma segura solo el consentimiento del usuario. Sin embargo, los administradores de inquilinos pueden configurar un inquilino para que todos los permisos requieran el consentimiento del administrador. Si define un ámbito como requerir consentimiento del administrador, el permiso siempre requiere el consentimiento del administrador.

Al decidir sobre el consentimiento del usuario o del administrador, tiene estas consideraciones principales:

  • Si la gama de operaciones relativas al permiso afecta a más de un solo usuario. Si el permiso permite al usuario elegir a qué aplicación solo puede acceder a su propia información, puede que el consentimiento del usuario sea adecuado. Por ejemplo, el usuario puede dar su consentimiento para elegir su aplicación preferida para el correo electrónico. Sin embargo, si las operaciones detrás del permiso implican más de un solo usuario (como ver perfiles de usuario completos de otros usuarios), defina ese permiso como requerir el consentimiento del administrador.

  • Si el rango de operaciones detrás del permiso tiene un alcance amplio. Por ejemplo, un ámbito amplio es cuando un permiso permite a una aplicación cambiar todo en un inquilino o hacer algo que podría ser irreversible. Un ámbito amplio indica que necesita consentimiento del administrador en lugar de consentimiento del usuario.

Erre en el lado conservador y requiera consentimiento del administrador si está en duda. Describir claramente y concisamente las consecuencias del consentimiento en las cadenas de permisos. Supongamos que la persona que lee las cadenas de descripción no está familiarizado con las API o el producto.

Evite agregar las API a los permisos existentes de una manera que cambie la semántica del permiso. La sobrecarga de permisos existentes diluye el razonamiento sobre el que los clientes concedieron previamente el consentimiento.

Definición de permisos de aplicación

Al desarrollar aplicaciones que no están destinadas a usuarios, no tiene un usuario a quien pueda pedir un nombre de usuario y una contraseña o autenticación multifactor (MFA). Si las aplicaciones sin usuarios (como cargas de trabajo, servicios y demonios) llaman a tu API, define permisos de aplicación específicos para tu API. Al definir un permiso de aplicación, use un rol de aplicación en lugar de usar ámbitos.

Al igual que con los permisos delegados, proporciona permisos de aplicación pormenorizados para que las cargas de trabajo que llaman a la API puedan seguir el acceso con privilegios mínimos y alinearse con los principios de confianza cero. Evite publicar solo un rol de aplicación (permiso de aplicación) y un ámbito (permiso delegado) o exponer todas las operaciones a cada cliente.

Las cargas de trabajo se autentican con credenciales de cliente y solicitan un token con el .default ámbito , como se muestra en el código de ejemplo siguiente.

// With client credentials flows the scopes is ALWAYS of the shape "resource/.default", as the 
// application permissions need to be set statically (in the portal or by PowerShell), 
// and then granted by a tenant administrator
string[] scopes = new string[] { "https://kkaad.onmicrosoft.com/webapi/.default" };
 
AuthenticationResult result = null;
try
{
  result = await app.AcquireTokenForClient(scopes)
    .ExecuteAsync();
  Console.WriteLine("Token acquired \n");
}
catch (MsalServiceException ex) when (ex.Message.Contains("AADSTS70011"))
{
  // Invalid scope. The scope has to be of the form "https://resourceurl/.default"
  // Mitigation: change the scope to be as expected
  Console.WriteLine("Scope provided is not supported");
}

Los permisos requieren el consentimiento del administrador cuando no hay ningún usuario delante de la aplicación y cuando el permiso de aplicación habilita una amplia gama de operaciones.

Exigir acceso

Asegúrese de que sus API garanticen el acceso validando e interpretando los tokens de acceso que las aplicaciones solicitantes proporcionan como tokens de portador en el encabezado de autorización de la solicitud https. Aplique el acceso validando tokens, administrando la actualización de metadatos y aplicando ámbitos y roles, tal y como se describe en las secciones siguientes.

Validar tokens

Después de que la API reciba un token, asegúrese de que valida el token. La validación garantiza que el token procede del emisor adecuado y no ha sido alterado ni modificado. Compruebe la firma porque no obtiene el token directamente de Microsoft Entra ID como lo hace con los tokens de ID. Valide la firma después de que la API reciba un token de un origen que no es de confianza en la red.

Dado que hay vulnerabilidades conocidas en torno a la comprobación de firma de token web JSON, use una biblioteca de validación de tokens estándar bien mantenida y establecida. Las bibliotecas de autenticación (como Microsoft.Identity.Web) usan los pasos adecuados y mitigan las vulnerabilidades conocidas.

Opcionalmente, amplíe la validación de tokens. Utilice la reclamación de ID de inquilino (tid) para restringir los inquilinos en los que la API puede obtener un token. Usa las azp y appid reclamaciones para filtrar las aplicaciones que pueden llamar a tu API. Usa la declaración de ID de objeto (oid) para restringir todavía más el acceso a usuarios individuales.

Administrar la actualización de metadatos

Asegúrese siempre de que la biblioteca de validación de tokens administre eficazmente los metadatos necesarios. En este caso, los metadatos son las claves públicas, el par de claves privadas que Microsoft usa para firmar tokens de Microsoft Entra. Cuando las bibliotecas validan estos tokens, obtienen nuestra lista publicada de claves de firma pública desde una dirección de Internet conocida. Asegúrese de que el entorno de hospedaje tenga el tiempo adecuado para obtener esas claves.

Por ejemplo, las bibliotecas más antiguas estaban programadas de manera fija para actualizar esas claves de firma pública cada 24 horas. Tenga en cuenta cuándo Microsoft Entra ID tiene que rotar rápidamente esas claves y las claves que descargó no incluyeron las nuevas rotadas. La API podría estar sin conexión durante un día mientras espera su ciclo de actualización de metadatos. Haga referencia a instrucciones de actualización de metadatos específicas para asegurarse de que obtiene correctamente los metadatos. Si usa una biblioteca, asegúrese de que trata los metadatos dentro de un tiempo razonable.

Imponer ámbitos y roles

Después de validar el token, la API examina las declaraciones del token para determinar cómo debe funcionar.

Para los tokens de permisos delegados, haga que la API inspeccione la notificación de ámbito (scp) para ver lo que la aplicación tiene consentimiento para hacer. Inspeccione los atributos del identificador de objeto (oid) o clave de sujeto (sub) para ver al usuario en cuyo nombre está funcionando la aplicación.

A continuación, compruebe la API para asegurarse de que el usuario también tiene acceso a la operación solicitada. Si la API define roles para asignar a usuarios y grupos, haga que la API compruebe si hay notificaciones de roles en el token y se comporte en consecuencia. Los tokens de permiso de aplicación no tienen un reclamo de ámbito (scp). En su lugar, haga que la API inspeccione la notificación de roles para determinar qué permisos de aplicación recibió la carga de trabajo.

Una vez que la API valida el token y los ámbitos y procesa el identificador de objeto (oid), la clave de asunto (sub) y las reclamaciones de roles, la API puede devolver los resultados.

Pasos siguientes

  • Last updated on