Compartir vía

Instrucciones para desarrolladores sobre el contexto de autenticación del acceso condicional

Se aplica a: Un círculo verde con un símbolo de marca de verificación blanca que indica que el siguiente contenido se aplica a los inquilinos laborales. Inquilinos laborales Un círculo verde con un símbolo de marca de verificación blanca que indica que el siguiente contenido se aplica a los inquilinos externos. Inquilinos externos (obtén más información)

El acceso condicional es el plano de control de Confianza cero que permite establecer directivas de destino para el acceso a todas las aplicaciones: antiguas o nuevas, privadas o públicas, locales o en varias nubes. Con el contexto de autenticación del acceso condicional, puede aplicar diferentes directivas dentro de esas aplicaciones.

El contexto de autenticación del acceso condicional permite aplicar directivas específicas a datos y acciones confidenciales en lugar de solo en el nivel de la aplicación. Puede ajustar las directivas de Confianza cero para el acceso con privilegios mínimos al tiempo que minimiza las desavenencias entre los usuarios y hace que estos sean más productivos y que sus recursos estén más protegidos. En la actualidad, las aplicaciones que usan OpenId Connect pueden usarlo para la autenticación desarrollada por su empresa con el fin de proteger recursos confidenciales, como transacciones de alto valor o la visualización de datos personales de empleados.

Utilice la característica de contexto de autenticación del motor de acceso condicional de Microsoft Entra para desencadenar una demanda de actualización a una edición superior desde las aplicaciones y los servicios. Los desarrolladores ahora tienen la capacidad de exigir una autenticación más sólida y mejorada, de forma selectiva, como MFA, a los usuarios finales desde sus aplicaciones. Esta característica ayuda a los desarrolladores a crear experiencias de usuario más fluidas para la mayoría de los componentes de su aplicación, mientras que el acceso a operaciones y datos más protegidos permanece detrás de controles de autenticación más sólidos.

Declaración del problema

A menudo, los administradores y reguladores de TI tienen dificultades para equilibrar la solicitud de los usuarios con factores adicionales de autenticación y lograr el cumplimiento adecuado de la seguridad y la directiva para las aplicaciones. Puede ser una opción entre una directiva sólida que afecte a la productividad de los usuarios o a una directiva que no sea lo suficientemente fuerte para los recursos confidenciales.

Entonces, ¿qué ocurre si las aplicaciones pudieran mezclar ambas? Funcionamiento con un nivel inferior de seguridad y menos solicitudes para la mayoría de los escenarios. Reforzar condicionalmente los requisitos de seguridad al acceder a datos sensibles?

Escenarios frecuentes

Por ejemplo, aunque los usuarios pueden iniciar sesión en SharePoint mediante la autenticación multifactor, el acceso a la colección de sitios de SharePoint que contiene documentos confidenciales puede requerir un dispositivo compatible y solo ser accesible desde intervalos IP de confianza.

Requisitos previos

En primer lugar, la aplicación debe integrarse con la plataforma de identidad de Microsoft mediante el uso de los protocolos OpenID Connect/ OAuth 2.0 para la autenticación y autorización. Se recomienda usar las Bibliotecas de autenticación de la plataforma de identidad de Microsoft para integrar y proteger la aplicación con Microsoft Entra ID. La documentación de la plataforma de identidad de Microsoft es un buen lugar para aprender a integrar las aplicaciones con dicha plataforma. La compatibilidad con las características de contexto de autenticación del acceso condicional se basa en las extensiones de protocolo proporcionadas por el protocolo estándar OpenID Connect del sector. Los desarrolladores usan un valor de referencia para el contexto de autenticación del acceso condicional con el parámetro Solicitud de notificaciones para proporcionar a las aplicaciones una manera de desencadenar y cumplir con la directiva.

En segundo lugar, el Acceso condicional requiere una licencia de Microsoft Entra ID P1. Para más información sobre las licencias, consulte la página de precios de Microsoft Entra.

En tercer lugar, actualmente solo está disponible para las aplicaciones en las que inician sesión los usuarios. No se admiten las aplicaciones que se autentican por sí mismas. Use la Guía de flujos de autenticación y escenarios de aplicaciones para obtener más información sobre los tipos y flujos de aplicaciones de autenticación admitidos en la plataforma de identidad de Microsoft.

Pasos de integración

Puede empezar a integrar esta característica en las aplicaciones una vez integrada mediante los protocolos de autenticación admitidos y registrados en un inquilino de Microsoft Entra que tenga disponible la característica de acceso condicional.

Nota

También hay disponible un tutorial detallado de esta característica en una sesión grabada de Uso del contexto de autenticación del acceso condicional en la aplicación para la autenticación por pasos.

Primero, declare y haga que los contextos de autenticación estén disponibles en el inquilino. Para más información, consulte Configurar contextos de autenticación.

Los valores C1-C99 están disponibles para su uso como identificadores de los contextos de autenticación de un inquilino. Estos son algunos ejemplos de contexto de autenticación:

  • C1: requiere autenticación segura
  • C2: requiere dispositivos compatibles
  • C3: requiere ubicaciones de confianza

Para usar los contextos de autenticación de acceso condicional, cree o modifique las directivas de acceso condicional. Estos son algunos ejemplos de directivas:

  • Todos los usuarios que inician sesión en esta aplicación web deben completar correctamente 2FA para el identificador de contexto de autenticación C1.
  • Todos los usuarios que inician sesión en esta aplicación web deben completar correctamente la 2FA y también acceder a la aplicación desde un intervalo de direcciones IP definido para el identificador de contexto de autenticación C3.

Nota

Los valores del contexto de autenticación del acceso condicional se declaran y mantienen de manera independiente de las aplicaciones. No es aconsejable que las aplicaciones tengan una dependencia fuerte de los identificadores del contexto de autenticación. Los administradores de TI suelen crear directivas de acceso condicional, ya que tienen una mejor comprensión de los recursos disponibles. De forma similar, si la aplicación se usa en varios inquilinos, los identificadores de contextos de autenticación en uso podrían ser diferentes y, en algunos casos, no estar disponibles en absoluto.

Segundo: se recomienda a los desarrolladores de una aplicación que planeen usar el contexto de autenticación del acceso condicional que proporcionen primero a los administradores de aplicaciones o de TI un medio para asignar posibles acciones confidenciales a identificadores de contextos de autenticación. Estos son, a grandes rasgos, los pasos:

  1. Acciones de identidad del código que están disponibles para su asignación a identificadores de contextos de autenticación.
  2. Cree una pantalla en el portal de administración de la aplicación (o una funcionalidad equivalente) que los administradores de TI puedan usar para asignar acciones confidenciales a un identificador de contexto de autenticación disponible.
  3. Consulte el ejemplo de código , Use the Conditional Access Auth Context to perform step-up authentication (Usar el contexto de autenticación de acceso condicional para realizar la autenticación paso a paso) para obtener un ejemplo.

Estos pasos son los cambios que debe llevar a cabo en el código base. A grandes rasgos, los pasos son:

  • Consulte MS Graph para que muestre todos los contextos de autenticación disponibles.
  • Permita a los administradores de TI seleccionar operaciones confidenciales o con privilegios elevados, y asignarlas a los contextos de autenticación disponibles mediante directivas de acceso condicional.
  • Guarde esta información de asignación en la base de datos o almacén local.

Flujo de configuración para crear un contexto de autenticación

Tercero: la aplicación que, en este ejemplo, se supone que es una API web, posteriormente, necesita evaluar las llamadas a la asignación guardada y, en consecuencia, plantear desafíos de notificación para sus aplicaciones cliente. Para prepararse para esta acción, se deben realizar los pasos siguientes:

  1. En una operación confidencial y protegida mediante el contexto de autenticación, evalúe los valores de la notificación acrs en comparación con las asignaciones de identificador del contexto de autenticación guardadas anteriormente y genere un desafío de notificaciones como se ofrece en el fragmento de código siguiente.

  2. En el diagrama siguiente se muestra la interacción entre el usuario, la aplicación cliente y la API web.

    Diagrama que muestra la interacción del usuario, la aplicación web, la API y Microsoft Entra ID

    El fragmento de código siguiente pertenece al ejemplo de código Uso del contexto de autenticación del acceso condicional para realizar la autenticación por pasos. El primer método, CheckForRequiredAuthContext() en la API

    • Comprueba si la acción de la aplicación a la que se llama requiere autenticación por pasos. Para ello, compruebe en su base de datos una asignación guardada para este método.
    • Si esta acción requiere realmente un contexto de autenticación con privilegios elevados, se busca la notificación acrs de un identificador de contexto de autenticación existente que coincida.
    • Si no se encuentra un identificador de contexto de autenticación que coincida, se genera un desafío de notificaciones.
    public void CheckForRequiredAuthContext(string method)
{
    string authType = _commonDBContext.AuthContext.FirstOrDefault(x => x.Operation == method
                && x.TenantId == _configuration["AzureAD:TenantId"])?.AuthContextId;

    if (!string.IsNullOrEmpty(authType))
    {
        HttpContext context = this.HttpContext;
        string authenticationContextClassReferencesClaim = "acrs";

        if (context == null || context.User == null || context.User.Claims == null
            || !context.User.Claims.Any())
        {
            throw new ArgumentNullException("No Usercontext is available to pick claims from");
        }

        Claim acrsClaim = context.User.FindAll(authenticationContextClassReferencesClaim).FirstOrDefault(x
            => x.Value == authType);

        if (acrsClaim == null || acrsClaim.Value != authType)
        {
            if (IsClientCapableofClaimsChallenge(context))
            {
                string clientId = _configuration.GetSection("AzureAd").GetSection("ClientId").Value;
                var base64str = Convert.ToBase64String(Encoding.UTF8.GetBytes("{\"access_token\":{\"acrs\":{\"essential\":true,\"value\":\"" + authType + "\"}}}"));

                context.Response.Headers.Append("WWW-Authenticate", $"Bearer realm=\"\", authorization_uri=\"https://login.microsoftonline.com/common/oauth2/authorize\", client_id=\"" + clientId + "\", error=\"insufficient_claims\", claims=\"" + base64str + "\", cc_type=\"authcontext\"");
                context.Response.StatusCode = (int)HttpStatusCode.Unauthorized;
                string message = string.Format(CultureInfo.InvariantCulture, "The presented access tokens had insufficient claims. Please request for claims requested in the WWW-Authentication header and try again.");
                context.Response.WriteAsync(message);
                context.Response.CompleteAsync();
                throw new UnauthorizedAccessException(message);
            }
            else
            {
                throw new UnauthorizedAccessException("The caller does not meet the authentication  bar to carry our this operation. The service cannot allow this operation");
            }
        }
    }
}

    Nota

    El formato del desafío de notificaciones se describe en el artículo Desafíos de notificaciones en la plataforma de identidad de Microsoft.

  3. En la aplicación cliente, intercepte el desafío de notificaciones y redirija al usuario a Microsoft Entra ID para una evaluación de directiva adicional. El fragmento de código siguiente pertenece al ejemplo de código Uso del contexto de autenticación del acceso condicional para realizar la autenticación por pasos.

    internal static string ExtractHeaderValues(WebApiMsalUiRequiredException response)
{
    if (response.StatusCode == System.Net.HttpStatusCode.Unauthorized && response.Headers.WwwAuthenticate.Any())
    {
        AuthenticationHeaderValue bearer = response.Headers.WwwAuthenticate.First(v => v.Scheme == "Bearer");
        IEnumerable<string> parameters = bearer.Parameter.Split(',').Select(v => v.Trim()).ToList();
        var errorValue = GetParameterValue(parameters, "error");

        try
        {
            // read the header and checks if it contains error with insufficient_claims value.
            if (null != errorValue && "insufficient_claims" == errorValue)
            {
                var claimChallengeParameter = GetParameterValue(parameters, "claims");
                if (null != claimChallengeParameter)
                {
                    var claimChallenge = ConvertBase64String(claimChallengeParameter);

                    return claimChallenge;
                }
            }
        }
        catch (Exception ex)
        {
            throw ex;
        }
    }
    return null;
}

    Controle la excepción en la llamada a la API web; si se presenta un desafío de notificaciones, redirija al usuario a Microsoft Entra ID para un procesamiento adicional.

    try
{
    // Call the API
    await _todoListService.AddAsync(todo);
}
catch (WebApiMsalUiRequiredException hex)
{
    // Challenges the user if exception is thrown from Web API.
    try
    {
        var claimChallenge =ExtractHeaderValues(hex);
        _consentHandler.ChallengeUser(new string[] { "user.read" }, claimChallenge);

        return new EmptyResult();
    }
    catch (Exception ex)
    {
        _consentHandler.HandleException(ex);
    }

    Console.WriteLine(hex.Message);
}
return RedirectToAction("Index");

  4. (Opcional) Declare la funcionalidad del cliente. Las funcionalidades de cliente ayudan a los proveedores de recursos (RP) como nuestra API web a detectar si la aplicación cliente entiende el desafío de notificaciones y, a continuación, puede personalizar su respuesta en consecuencia. Esta funcionalidad podría ser útil en aquellos casos en los que no todos los clientes API son capaces de controlar los desafíos de notificaciones y algunos anteriores todavía esperan una respuesta diferente. Para más información, consulte la sección Funcionalidades de cliente.

Advertencias y recomendaciones

No codifique de forma rígida los valores del contexto de autenticación de la aplicación. Las aplicaciones deben leer y aplicar el contexto de autenticación mediante llamadas de MS Graph. Este procedimiento es fundamental para las aplicaciones multiinquilino. Los valores de contexto de autenticación varían entre los inquilinos de Microsoft Entra y no están disponibles en microsoft Entra ID Free Edition. Para obtener más información sobre cómo una aplicación debe consultar, establecer y usar el contexto de autenticación en su código, consulte el ejemplo de código Usar el contexto de autenticación de acceso condicional para realizar la autenticación paso a paso.

No use el contexto de autenticación en aquellos casos en los que la propia aplicación va a ser un destino de las directivas de acceso condicional. La característica funciona mejor cuando los componentes de la aplicación requieren que el usuario cumpla un nivel mayor de autenticación.

Ejemplos de código

Contexto de autenticación [ACR] en el comportamiento esperado del acceso condicional

Satisfacción explícita del contexto de autenticación en solicitudes

Un cliente puede solicitar explícitamente un token con un contexto de autenticación (ACRS) a través de las notificaciones en el cuerpo de la solicitud. Si se solicitó un ACRS, el acceso condicional permite emitir el token con el ACRS solicitado si se completaron todos los desafíos.

Comportamiento esperado cuando un contexto de autenticación no está protegido por el acceso condicional en el inquilino

El acceso condicional puede emitir un ACRS en las notificaciones de un token cuando se ha cumplido toda la directiva de acceso condicional asignada al valor de ACRS. Si no se asigna ninguna directiva de acceso condicional a un valor de ACRS, es posible que la notificación todavía se emita, ya que se cumplen todos los requisitos de directiva.

Tabla de resumen para el comportamiento esperado cuando se solicita explícitamente ACRS

ACRS solicitado Directiva aplicada Control satisfecho ACRS agregado a notificaciones
Sí No Sí Sí
Sí Sí No No
Sí Sí Sí Sí
Sí No hay directivas configuradas con ACRS Sí Sí

Satisfacción implícita del contexto de autenticación por evaluación oportunista

Un proveedor de recursos puede participar en la notificación opcional de "acrs". El acceso condicional intenta agregar ACRS a las notificaciones de token oportunamente para evitar recorridos de ida y vuelta para adquirir nuevos tokens en Microsoft Entra ID. En esa evaluación, el acceso condicional comprueba si las directivas que protegen los desafíos del contexto de autenticación ya están satisfechas y agrega ACRS a las notificaciones del token si es así.

Nota

Cada tipo de token debe activarse individualmente (token de ID, token de acceso).

Si un proveedor de recursos no acepta la declaración opcional "acrs", la única manera de obtener un ACRS en el token es solicitarlo explícitamente en una solicitud de token. No obtendrá las ventajas de la evaluación oportunista, por lo que cada vez que falta el ACRS necesario en las reivindicaciones del token, el proveedor de recursos solicita al cliente obtener un nuevo token que lo contenga en las reivindicaciones.

Comportamiento esperado con controles de sesión y contexto de autenticación para la evaluación oportunista implícita de ACRS

Frecuencia de inicio de sesión por intervalo

El acceso condicional considera la "frecuencia de inicio de sesión por intervalo" como cumplida para la evaluación de ACRS oportunista cuando todos los factores de autenticación actuales estén dentro del intervalo de frecuencia de inicio de sesión. En caso de que alguno de los factores de autenticación esté obsoleto, la frecuencia de inicio de sesión por intervalo no se cumplirá y el ACRS no se emitirá en el token de manera oportunista.

Cloud App Security (CAS)

El acceso condicional considera el control de sesión CAS como satisfecho para la evaluación de ACRS oportunista cuando se ha establecido una sesión CAS durante esa solicitud. Por ejemplo, cuando llega una solicitud y cualquier directiva de acceso condicional ha aplicado una sesión CAS, y además hay una directiva de acceso condicional que también requiere una sesión CAS, puesto que se aplicará la sesión CAS, se cumple el control de sesión CAS para la evaluación oportunista.

Comportamiento esperado cuando un inquilino contiene directivas de acceso condicional que protegen el contexto de autenticación

En la tabla siguiente se muestran todos los casos especiales en los que ACRS se agrega a las notificaciones del token mediante la evaluación oportunista.

Directiva A: requerir MFA de todos los usuarios, excepto el usuario "Ariel", al solicitar acrs "c1". Directiva B: bloquear todos los usuarios, excepto el usuario "Jay", al solicitar acrs "c2" o "c3".

Flujo ACRS solicitado Directiva aplicada Control satisfecho ACRS agregado a notificaciones
Solicitudes de Ariel para un token de acceso "c1" Ninguno Sí para "c1". No para "c2" y "c3" "c1" (solicitado)
Solicitudes de Ariel para un token de acceso "c2" Directiva B Bloqueado por la directiva B Ninguno
Solicitudes de Ariel para un token de acceso Ninguno Ninguno Sí para "c1". No para "c2" y "c3" "c1" (agregado de forma oportunista a partir de la directiva A)
Solicitudes de Jay para un token de acceso (sin MFA) "c1" Directiva A No Ninguno
Solicitudes de Jay para un token de acceso (con MFA) "c1" Directiva A Sí "c1" (solicitado), "c2" (agregado de forma oportunista a partir de la directiva B), "c3" (agregado de forma oportunista a partir de la directiva B)
Solicitudes de Jay para un token de acceso (sin MFA) "c2" Ninguno Sí para "c2" y "c3". No para "c1" "c2" (solicitado), "c3" (agregado de forma oportunista a partir de la directiva B)
Solicitudes de Jay para un token de acceso (con MFA) "c2" Ninguno Sí para "c1", "c2" y "c3" "c1" (mejor intento de A), "c2" (solicitado), "c3" (agregado de forma oportunista de la directiva B)
Solicitudes de Jay para un token de acceso (con MFA) Ninguno Ninguno Sí para "c1", "c2" y "c3" "c1", "c2", "c3" agregados de forma oportunista
Solicitudes de Jay para un token de acceso (sin MFA) Ninguno Ninguno Sí para "c2" y "c3". No para "c1" "c2", "c3" agregados de forma oportunista

Pasos siguientes

  • Last updated on