Compartir a través de

Protección de API

  • Artículo

Cuando usted, como desarrollador, protege una API, debe centrarse en la autorización. Para llamar a la API del recurso, las aplicaciones deben adquirir una autorización de la aplicación. El propio recurso debe aplicar la autorización. En este artículo, obtendrá información sobre los procedimientos recomendados para proteger la API mediante el registro, la definición de permisos y el consentimiento y la aplicación del acceso para lograr los objetivos de Confianza cero.

Registro de la API protegida

Para proteger la API con Microsoft Entra ID, primero tiene que registrar la API, después de lo cual podrá 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 se puede autorizar que acceda otra aplicación. En el Centro de administración Microsoft Entra, Microsoft Identity Developer, los registros de aplicaciones, son API que se encuentran en el inquilino en forma de API de línea de negocio o servicios de proveedores SaaS que tienen API que protege Microsoft Entra ID.

Durante el registro, definirá cómo las aplicaciones que llaman hacen referencia a la API y a sus delegados y permisos 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 Microsoft Entra ID. 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 las llamadas. No acepte tokens de identidad como prueba de permiso.

De forma predeterminada, Microsoft Entra ID 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 la API.

Necesita un identificador único para la API, conocido como URI de identificador de aplicación, que las aplicaciones cliente que necesitan acceder a la API solicitan permiso para llamar a la 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 id. de aplicación de la API registrada.

Para proporcionar a los desarrolladores que llaman a la API un nombre más descriptivo, puede usar la dirección de la API como URI del id. de aplicación. Por ejemplo, puede usar https://API.yourdomain.com, donde yourdomain.com debe ser un dominio de publicador configurado en el inquilino de Microsoft Entra. Microsoft comprueba 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 estar donde quiera, pero es recomendable usar la dirección HTTPS de la API como URI del id. de aplicación.

Definición de permisos delegados con privilegios mínimos

Si las aplicaciones que tienen usuarios van a llamar a la API, debe definir al menos un permiso delegado (consulte Adición de un ámbito en el registro de 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 los atacantes que desean acceder a esos datos. En lugar de tener solo un permiso delegado, diseñe los permisos con el principio de confianza cero de acceso con privilegios mínimos en mente. Más adelante, podría ser difícil aplicar un modelo con privilegios mínimos si todas las aplicaciones cliente comienzan con acceso con privilegios completos.

A menudo, los desarrolladores caen en el patrón de usar un solo permiso, como "acceso como usuario" o "suplantación de usuario" (que es una frase común aunque técnicamente inexacta). Los permisos únicos, como estos, solo permiten el acceso completo y con privilegios 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 no prevista. Defina los distintos á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. "Acceso de escritura", incluye privilegios para las operaciones de creación, actualización y eliminación. Un cliente nunca debe requerir acceso de escritura solo para leer datos.

Considere usar permisos de acceso "estándar" y "completos" si la API trabaja 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 con privilegios mínimos absoluto 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. Busque 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 administrador, tiene dos consideraciones principales:

  1. Si el intervalo de operaciones detrás del 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 (por ejemplo, ver perfiles de usuario completos de otros usuarios), defina ese permiso para requerir el consentimiento del administrador.

  2. Si el intervalo de operaciones detrás del permiso tiene un ámbito amplio. Por ejemplo, con ámbito amplio nos referimos a 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.

Quédese con la opción conservadora y requiera consentimiento del administrador si está en duda. Describa clara 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 forma 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 compilar aplicaciones que no son de usuario, no tiene un usuario que pueda solicitar 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 la API, debe definir permisos de aplicación para la API. Al definir un permiso de aplicación, se usa 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 mediante 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 variedad de operaciones.

Exigir acceso

Asegúrese de que las API aplican el acceso validando e interpretando tokens de acceso que las aplicaciones que llaman proporcionan como tokens de portador en el encabezado de autorización de la solicitud HTTPS. Puede aplicar el acceso validando tokens, administrando la actualización de metadatos y aplicando ámbitos y roles, como se describe en las secciones siguientes.

Validar tokens

Una vez que la API recibe un token, debe validarlo. La validación garantiza que el token proceda del emisor adecuado sin modificar ni alterar. Compruebe la firma, porque no se obtiene el token directamente de Microsoft Entra ID como lo hace con los tokens de identidad. 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 JSON Web Token, use una biblioteca de validación de tokens estándar bien mantenida y definida. 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. Use la notificación de id. de inquilino (tid) para restringir los inquilinos en los que la API puede obtener un token. Use las notificaciones azp y appid para filtrar las aplicaciones que pueden llamar a la API. Use la notificación de id. de objeto (oid) para restringir aún 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 del host tenga el tiempo adecuado para obtener esas claves.

Por ejemplo, las bibliotecas anteriores se codificaban de forma ocasional 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 si las claves que descargó no incluyen las nuevas claves rotadas. La API podría estar sin conexión durante un día mientras espera al ciclo de actualización de metadatos. Consulte 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.

Aplicar ámbitos y roles

Después de validar el token, la API examina las notificaciones 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 las notificaciones de id. de objeto (oid) o clave de asunto (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 permisos de aplicación no tienen una notificación 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 notificaciones de roles, la API puede devolver los resultados.

Pasos siguientes