Guía para desarrolladores sobre la API de Federated Credential Management

Obtén información sobre cómo usar FedCM para la federación de identidades que preserva la privacidad.

FedCM (Federated Credential Management) es una herramienta que preserva enfoque a los servicios de identidad federada (como “Acceder con...”), en los que los usuarios pueden acceder a los sitios sin compartir su información personal con el de identidad del sitio o del servicio de identidad.

Para obtener más información sobre los casos de uso, los flujos de usuarios y la hoja de ruta de la API de FedCM, consulta la introducción a la API de FedCM.

Entorno de desarrollo de FedCM

Necesitas un contexto seguro (HTTPS o localhost) en el IdP y el RP en Chrome. para usar la FedCM.

Cómo depurar código en Chrome para Android

Configura y ejecuta un servidor localmente para depurar tu código FedCM. Puedes acceder a este servidor En Chrome, en un dispositivo Android conectado por medio de un cable USB con el puerto el reenvío.

Puedes usar las Herramientas para desarrolladores en una computadora de escritorio para depurar Chrome en Android siguiendo los pasos que se indican a continuación: instrucciones en Depuración remota de Android dispositivos.

Bloquea cookies de terceros en Chrome

Simula la eliminación gradual de las cookies de terceros configurando Chrome para bloquearlas
Simula la eliminación gradual de las cookies de terceros configurando Chrome para bloquearlas.

Puedes probar cómo funciona FedCM sin cookies de terceros en Chrome antes de que realmente aplicado.

Para bloquear cookies de terceros, usa Incógnito o elige "Bloquear cookies de terceros" en la configuración de tu escritorio, en chrome://settings/cookies o en móvil, ve a Configuración > Configuración de sitios > Cookies

Uso de la API de FedCM

La integración con FedCM crea un archivo conocido. archivo de configuración y extremos para cuentas list, emisión de aserciones y opcionalmente metadatos de cliente.

A partir de ahí, FedCM expone las APIs de JavaScript que los RP pueden usar para firmar in con el IdP.

Crea un archivo conocido

Para evitar que los sistemas de seguimiento abusen de la API, un archivo conocido se debe publicadas desde /.well-known/web-identity de eTLD+1 de los IdP.

Por ejemplo, si los extremos del IdP se entregan en https://accounts.idp.example/, deben entregar un archivo conocido en https://idp.example/.well-known/web-identity y una configuración de IdP .tfvars. A continuación, se incluye un ejemplo de contenido de archivo conocido:

{
  "provider_urls": ["https://accounts.idp.example/config.json"]
}

El archivo JSON debe contener la propiedad provider_urls con un array de IdP archivo de configuración, las que se pueden especificar como una parte de la ruta de acceso de configURL en navigator.credentials.get por RP. El número de Las cadenas de URL del array están limitadas a una, pero esto puede cambiar con tu comentarios en el futuro.

Crea un archivo de configuración y extremos de IdP

El archivo de configuración del IdP proporciona una lista de extremos necesarios para el navegador. IdPs alojará este archivo de configuración, además de las URL y los extremos requeridos. Todos los JSON las respuestas se deben entregar con application/json content-type.

La URL del archivo de configuración está determinada por los valores proporcionados al Llamada a navigator.credentials.get ejecutada en un RP.

const credential = await navigator.credentials.get({
  identity: {
    context: 'signup',
    providers: [{
      configURL: 'https://accounts.idp.example/config.json',
      clientId: '********',
      nonce: '******'
    }]
  }
});
const { token } = credential;

Especifica una URL completa de la ubicación del archivo de configuración del IdP como configURL. Cuándo Se llama a navigator.credentials.get() en la parte restringida, el navegador recupera el archivo de configuración con una solicitud GET sin el encabezado Origin ni el Referer. La solicitud no tiene cookies y no sigue redireccionamientos. Esto evita que el IdP sepa quién realizó la solicitud y qué La parte restringida está intentando conectarse. Por ejemplo:

GET /config.json HTTP/1.1
Host: accounts.idp.example
Accept: application/json
Sec-Fetch-Dest: webidentity

El navegador espera una respuesta JSON del IdP que incluya lo siguiente propiedades:

Propiedad Descripción
accounts_endpoint (obligatorio) URL del extremo de las cuentas.
client_metadata_endpoint (opcional) URL del extremo de metadatos del cliente.
id_assertion_endpoint (obligatorio) URL para el extremo de aserción de ID.
disconnect (opcional) URL para el extremo de desconexión.
login_url (obligatorio) Es la URL de la página de acceso para que el usuario acceda al IdP.
branding (opcional) Objeto que contiene varias opciones de marca.
branding.background_color (opcional) Opción de desarrollo de la marca que establece el color de fondo de "Continuar como..." . Usar la sintaxis de CSS correspondiente, es decir, hex-color: hsl(), rgb() o named-color.
branding.color (opcional) Opción de desarrollo de la marca que establece el color de texto de la opción "Continuar como..." . Usar la sintaxis de CSS correspondiente, es decir, hex-color: hsl(), rgb() o named-color.
branding.icons (opcional) Opción de desarrollo de la marca que establece el objeto de ícono, que se muestra en el diálogo de acceso. El objeto de ícono es un array con dos parámetros:
  • url (obligatorio): Es la URL de la imagen del ícono. Esto no es compatible con imágenes SVG.
  • size (opcional): Dimensiones del ícono, que la aplicación considera cuadrada y de resolución única. Este número debe ser mayor o igual que 25.

El RP puede modificar la cadena en la IU del diálogo FedCM a través del valor identity.context para que navigator.credentials.get() admita la autenticación predefinida diferentes. La propiedad opcional puede ser "signin" (predeterminada), "signup" "use" o "continue".

Cómo se aplica la marca al diálogo de FedCM
Cómo se aplica el desarrollo de la marca al diálogo de FedCM

Este es un ejemplo de cuerpo de respuesta del IdP:

{
  "accounts_endpoint": "/accounts.php",
  "client_metadata_endpoint": "/client_metadata.php",
  "id_assertion_endpoint": "/assertion.php",
  "disconnect_endpoint": "/disconnect.php",
  "login_url": "/login",
  "branding": {
    "background_color": "green",
    "color": "#FFEEAA",
    "icons": [{
      "url": "https://idp.example/icon.ico",
      "size": 25
    }]
  }
}

Una vez que el navegador recupera el archivo de configuración, envía solicitudes posteriores al Extremos del IdP:

Extremos de IdP
Extremos de IdP

Extremo de cuentas

El extremo de cuentas del IdP muestra una lista de cuentas a las que se encuentra el usuario accediste actualmente en el IdP. Si el IdP admite varias cuentas, este extremo devolverá todas las cuentas con las que accediste.

El navegador envía una solicitud GET con cookies con SameSite=None, pero sin un parámetro client_id, el encabezado Origin o el encabezado Referer. Esta evita que el IdP sepa qué RP intenta firmar el usuario . Por ejemplo:

GET /accounts.php HTTP/1.1
Host: accounts.idp.example
Accept: application/json
Cookie: 0x23223
Sec-Fetch-Dest: webidentity

Al recibir la solicitud, el servidor debe hacer lo siguiente:

  1. Verifica que la solicitud contenga un encabezado HTTP Sec-Fetch-Dest: webidentity.
  2. Hacer coincidir las cookies de sesión con los ID de las cuentas con las que ya se accedió
  3. Responde con la lista de cuentas.

El navegador espera una respuesta JSON que incluya una propiedad accounts. con un array de información de la cuenta que tiene las siguientes propiedades:

Propiedad Descripción
id (obligatorio) Es el ID único del usuario.
name (obligatorio) Es el nombre y apellido del usuario.
email (obligatorio) Dirección de correo electrónico del usuario.
given_name (opcional) Es el nombre del usuario.
picture (opcional) URL de la imagen de avatar del usuario.
approved_clients (opcional) Un array de los IDs de cliente de RP con los que se registró el usuario.
login_hints (opcional) Un array de todos los tipos de filtros posibles que el IdP admite para especificar una cuenta. La parte restringida puede invocar a navigator.credentials.get(). con la propiedad loginHint mostrar selectivamente la cuenta especificada.
domain_hints (opcional) Es un array de todos los dominios con los que está asociada la cuenta. La parte restringida puede llama a navigator.credentials.get() con un domainHint para filtrar las cuentas de servicio.

Ejemplo de cuerpo de respuesta:

{
  "accounts": [{
    "id": "1234",
    "given_name": "John",
    "name": "John Doe",
    "email": "john_doe@idp.example",
    "picture": "https://idp.example/profile/123",
    "approved_clients": ["123", "456", "789"],
    "login_hints": ["demo1", "demo1@idp.example"]
  }, {
    "id": "5678",
    "given_name": "Johnny",
    "name": "Johnny",
    "email": "johnny@idp.example",
    "picture": "https://idp.example/profile/456",
    "approved_clients": ["abc", "def", "ghi"],
    "login_hints": ["demo2", "demo2@idp.example"],
    "domain_hints": ["corp.example"]
  }]
}

Si el usuario no accedió, responde con HTTP 401 (no autorizado).

El navegador consume la lista de cuentas que se muestra y no estará disponible para la parte restringida.

Extremo de metadatos del cliente

El extremo de metadatos del cliente del IdP muestra los metadatos del usuario de confianza, como la política de privacidad y las condiciones del servicio de la parte restringida. Las RP deben proporcionar vínculos a sus la política de privacidad y las condiciones del servicio al IdP con anticipación. Estos vínculos son que se muestra en el diálogo de acceso cuando el usuario no se ha registrado en el RP con el IdP.

El navegador envía una solicitud GET con client_id. navigator.credentials.get sin cookies. Por ejemplo:

GET /client_metadata.php?client_id=1234 HTTP/1.1
Host: accounts.idp.example
Origin: https://rp.example/
Accept: application/json
Sec-Fetch-Dest: webidentity

Al recibir la solicitud, el servidor debe hacer lo siguiente:

  1. Determina el RP para client_id.
  2. Responde con los metadatos del cliente.

Entre las propiedades del extremo de metadatos del cliente, se incluyen las siguientes:

Propiedad Descripción
privacy_policy_url (opcional) URL de la política de privacidad de la RP.
terms_of_service_url (opcional) URL de las Condiciones del Servicio de la parte restringida.

El navegador espera una respuesta JSON del extremo:

{
  "privacy_policy_url": "https://rp.example/privacy_policy.html",
  "terms_of_service_url": "https://rp.example/terms_of_service.html",
}

El navegador consume los metadatos de cliente que se muestran y no se usarán que están disponibles para el grupo restringido.

Extremo de aserción de ID

El extremo de aserción de ID del IdP muestra una aserción para el usuario que accedió. Cuando el usuario accede a un sitio web de RP mediante navigator.credentials.get() llamada, el navegador envía una solicitud POST con cookies con SameSite=None y un tipo de contenido de application/x-www-form-urlencoded a este extremo con la siguiente información:

Propiedad Descripción
client_id (obligatorio) El identificador de cliente de la RP.
account_id (obligatorio) El ID único del usuario que accede.
nonce (opcional) El nonce de solicitud, proporcionado por el RP.
disclosure_text_shown Genera una cadena de "true" o "false" (en lugar de un valor booleano). El resultado es "false" si no se mostró el texto de divulgación. Esto sucede cuando el ID de cliente del RP se incluyó en la lista de propiedades approved_clients de la respuesta del extremo de las cuentas o si el navegador observó un momento de registro en el pasado en ausencia de approved_clients.
is_auto_selected Si se realiza la reautenticación automática en el RP, is_auto_selected indica "true". De lo contrario, es "false". Esto es útil para admitir más funciones relacionadas con la seguridad. Por ejemplo, es posible que algunos usuarios prefieran un nivel de seguridad más alto que requiera una mediación explícita del usuario en la autenticación. Si un IdP recibe una solicitud de token sin dicha mediación, podría manejar la solicitud de manera diferente. Por ejemplo, muestra un código de error de modo que el RP pueda volver a llamar a la API de FedCM con mediation: required.

Ejemplo de encabezado HTTP:

POST /assertion.php HTTP/1.1
Host: accounts.idp.example
Origin: https://rp.example/
Content-Type: application/x-www-form-urlencoded
Cookie: 0x23223
Sec-Fetch-Dest: webidentity

account_id=123&client_id=client1234&nonce=Ct60bD&disclosure_text_shown=true&is_auto_selected=true

Al recibir la solicitud, el servidor debe hacer lo siguiente:

  1. Responde a la solicitud con CORS (recurso multiorigen) Uso compartido).
  2. Verifica que la solicitud contenga un encabezado HTTP Sec-Fetch-Dest: webidentity.
  3. Haz coincidir el encabezado Origin con el origen de la RP determinado por el client_id. Recházala si no coinciden.
  4. Haz coincidir account_id con el ID de la cuenta con la que accediste. Rechazar si no coinciden.
  5. Responder con un token Si se rechaza la solicitud, responder con un error respuesta.

La forma en que se emite el token depende del IdP, pero, en general, se firma con información, como el ID de la cuenta, el ID de cliente, el origen de la entidad emisora, nonce, para que el RP puede verificar que el token sea genuino.

El navegador espera una respuesta JSON que incluya la siguiente propiedad:

Propiedad Descripción
token (obligatorio) Un token es una cadena que contiene reclamaciones sobre la autenticación. 
{
  "token": "***********"
}

El navegador pasa el token que se devuelve al RP para que este pueda y validar la autenticación.

Muestra una respuesta de error

El objeto id_assertion_endpoint también puede mostrar un "error". de respuesta, que tiene dos campos opcionales:

  • code: El IdP puede elegir uno de los errores conocidos de OAuth 2.0. error especificado lista (invalid_request, unauthorized_client, access_denied, server_error y temporarily_unavailable) o usar cualquier cadena arbitraria. Si esta última opción, Chrome Renderiza la IU del error con un mensaje de error genérico y pasa el código al RP.
  • url: Identifica una página web legible por humanos con información sobre el para proporcionar información adicional sobre él a los usuarios. Este campo es útil para los usuarios porque los navegadores no pueden proporcionar mensajes de error enriquecidos en una IU nativa. Por ejemplo, vínculos de próximos pasos, información de contacto del servicio de atención al cliente información, etcétera. Si un usuario quiere obtener más información sobre los detalles del error y cómo solucionarlo, puede visitar la página proporcionada desde la IU del navegador para más detalles. La URL debe ser del mismo sitio que el IdP configURL.
// id_assertion_endpoint response
{
  "error" : {
     "code": "access_denied",
     "url" : "https://idp.example/error?type=access_denied"
  }
}

Desconectar extremo

Cuando invocas IdentityCredential.disconnect(), el navegador envía un origen cruzado Solicitud POST con cookies con SameSite=None y un tipo de contenido de application/x-www-form-urlencoded a este extremo de desconexión con el la siguiente información:

Propiedad Descripción
account_hint Una sugerencia para la cuenta de IdP.
client_id El identificador de cliente de la RP. 
POST /disconnect.php HTTP/1.1
Host: idp.example
Origin: rp.example
Content-Type: application/x-www-form-urlencoded
Cookie: 0x123
Sec-Fetch-Dest: webidentity

account_hint=account456&client_id=rp123

Al recibir la solicitud, el servidor debe hacer lo siguiente:

  1. Responde a la solicitud con CORS (recurso multiorigen) Uso compartido).
  2. Verifica que la solicitud contenga un encabezado HTTP Sec-Fetch-Dest: webidentity.
  3. Haz coincidir el encabezado Origin con el origen de la RP determinado por el client_id. Recházala si no coinciden.
  4. Haz coincidir account_hint con los IDs de las cuentas con las que accediste.
  5. Desconectar la cuenta de usuario de la parte restringida
  6. Responder al navegador con la información de la cuenta de usuario identificada en un archivo JSON de un conjunto de datos tengan un formato común.

Una carga útil de ejemplo de respuesta JSON se ve de la siguiente manera:

{
  "account_id": "account456"
}

En cambio, si el IdP desea que el navegador desconecte todas las cuentas asociadas con el RP, pasa una cadena que no coincida con ningún ID de cuenta, por ejemplo, "*".

URL de acceso

Con la API de inicio de sesión, el IdP debe informar la solicitud estado de acceso al navegador. Sin embargo, el estado podría no estar sincronizado, como en el siguiente ejemplo: cuando expira la sesión. En este caso, el el navegador puede permitir que el usuario acceda de forma dinámica al IdP a través de la página de acceso URL especificada con el login_url del archivo de configuración del IdP.

El cuadro de diálogo FedCM muestra un mensaje en el que se sugiere un acceso, como se indica en siguiente imagen.

A
Un diálogo de FedCM en el que se sugiere acceder al IdP.

Cuando el usuario hace clic en el botón Continuar, el navegador abre una ventana emergente. para la página de acceso del IdP.

Los
Un diálogo de ejemplo que se muestra después de hacer clic en el botón para acceder al IdP.

El diálogo es una ventana del navegador normal que contiene cookies propias. No importa en el diálogo depende del IdP, y no hay controladores de ventana disponibles para enviar una solicitud de comunicación de origen cruzado a la página de RP. Cuando el usuario el IdP debe hacer lo siguiente:

  • Envía el encabezado Set-Login: logged-in o llama al API de navigator.login.setStatus("logged-in") para informar al navegador que el elemento accedió a su cuenta.
  • Llama a IdentityProvider.close() para cerrar el diálogo.
A
Un usuario accede a un RP después de acceder al IdP mediante FedCM.

Informa al navegador el estado de acceso del usuario en el proveedor de identidad

La API de estado de acceso es un mecanismo en el que un sitio web, especialmente un IdP, informa al navegador el estado de acceso del usuario en el IdP. Con esta API, el navegador puede reducir las solicitudes innecesarias al de Google Cloud y mitigar posibles ataques de tiempo.

Los IdP pueden indicar el estado de acceso del usuario al navegador con el envío de un encabezado HTTP o llamando a una API de JavaScript cuando el usuario accede al IdP o cuando el usuario salió de todas sus cuentas del IdP. Para cada IdP (identificado por su config) el navegador mantiene una variable de tres estados que representa el estado de acceso con los valores posibles logged-in, logged-out y unknown. El estado predeterminado es unknown.

Para indicar que el usuario accedió, envía un encabezado HTTP Set-Login: logged-in. en una navegación de nivel superior o una solicitud de subrecurso del mismo sitio en el IdP origen:

Set-Login: logged-in

Como alternativa, puedes llamar a navigator.login.setStatus("logged-in") de la API de JavaScript. desde el origen del IdP en una navegación de nivel superior:

navigator.login.setStatus("logged-in")

Estas llamadas registran el estado de acceso del usuario como logged-in. Cuando el usuario accede el estado se establece en logged-in, el RP que llama a FedCM realiza solicitudes al IdP de usuario y muestra las cuentas disponibles al usuario en la FedCM .

Para indicar que el usuario salió de todas sus cuentas, envía el encabezado HTTP Set-Login: logged-out en una navegación de nivel superior o en un subrecurso del mismo sitio. en el origen del IdP:

Set-Login: logged-out

Como alternativa, puedes llamar a navigator.login.setStatus("logged-out") de la API de JavaScript. desde el origen del IdP en una navegación de nivel superior:

navigator.login.setStatus("logged-out")

Estas llamadas registran el estado de acceso del usuario como logged-out. Cuando se agrega el estado de acceso es logged-out, la llamada a la FedCM falla silenciosamente sin hacer un al extremo de cuentas del IdP.

El estado unknown se establece antes de que el IdP envíe un indicador con el estado de acceso en la API de Cloud. Se introdujo Unknown para una mejor transición, ya que es posible que un usuario ya accediste al IdP cuando se envió esta API. Es posible que el IdP no tenga un Indicar esto al navegador antes de que se invoque FedCM por primera vez. En este en ese caso, Chrome envía una solicitud al extremo de cuentas del IdP y actualiza el estado basado en la respuesta del extremo de las cuentas:

  • Si el extremo devuelve una lista de cuentas activas, actualiza el estado a logged-in y abre el diálogo de FedCM para mostrar esas cuentas.
  • Si el extremo no muestra ninguna cuenta, actualiza el estado a logged-out y fallar la llamada a FedCM.

Permite que el usuario acceda mediante un flujo de acceso dinámico

Aunque el IdP sigue informando el estado de acceso del usuario al navegador, podría no estar sincronizada, como cuando vence la sesión. El navegador intenta envíe una solicitud con credenciales al extremo de las cuentas cuando el estado de acceso sea logged-in, pero el servidor no muestra ninguna cuenta porque la sesión ya no está disponibles. En este caso, el navegador puede permitir dinámicamente el acceso del usuario al IdP a través de una ventana emergente.

Accede al usuario de confianza con el proveedor de identidad

Una vez que la configuración y los extremos del IdP están disponibles, los RP pueden llamar navigator.credentials.get() para solicitar que los usuarios accedan a la parte restringida con el IdP.

Antes de llamar a la API, debes confirmar que [FedCM está disponible en la navegador del usuario). Para comprobar si FedCM está disponible, une este código alrededor de Implementación de FedCM:

if ('IdentityCredential' in window) {
  // If the feature is available, take action
}

Para solicitar que los usuarios puedan acceder al IdP desde el RP, haz lo siguiente: por ejemplo:

const credential = await navigator.credentials.get({
  identity: {
    providers: [{
      configURL: 'https://accounts.idp.example/config.json',
      clientId: '********',
      nonce: '******'
    }]
  }
});
const { token } = credential;

La propiedad providers toma un array de IdentityProvider. objetos que tienen las siguientes propiedades:

Propiedad Descripción
configURL (obligatorio) Una ruta de acceso completa del archivo de configuración del IdP.
clientId (obligatorio) El identificador de cliente de la RP, emitido por el IdP.
nonce (opcional) Una cadena aleatoria para garantizar que la respuesta se emita para esta solicitud específica. Impide los ataques de repetición.
loginHint (opcional) Con la especificación de uno de los valores login_hints proporcionados por los extremos de las cuentas, la FedCM Este diálogo muestra la cuenta especificada de manera selectiva.
domainHint (opcional) Con la especificación de uno de los valores domain_hints proporcionados por los extremos de las cuentas, la FedCM estas opciones muestran la cuenta especificada de manera selectiva.

El navegador maneja los casos de uso de registro y acceso de manera diferente según el la existencia de approved_clients en la respuesta de la lista de cuentas extremo. El navegador no muestra ninguna divulgación. Envía el texto “Para continuar con......” si el usuario ya se registró en la parte restringida.

El estado de registro se determina en función de si se cumplen las siguientes condiciones: se cumplió o no:

  • Si approved_clients incluye el clientId del RP.
  • Si el navegador recuerda que el usuario ya se registró en la parte restringida:
Un usuario accede a una RP con FedCM

Cuando el RP llama a navigator.credentials.get(), se toman las siguientes actividades: lugar:

  1. El navegador envía solicitudes y recupera varios documentos:
    1. El archivo conocido y una configuración de IdP archivo que declaran extremos.
    2. Una lista de cuentas.
    3. Opcional: URLs de las Condiciones del Servicio y la Política de Privacidad del RP. recuperados del extremo de metadatos del cliente.
  2. El navegador muestra la lista de cuentas que el usuario puede usar para acceder. así como las condiciones del servicio y la política de privacidad (si están disponibles).
  3. Una vez que el usuario elige una cuenta para acceder, se enviará una solicitud al ID extremo de aserción al IdP para recuperar un token.
  4. El RP puede validar el token para autenticar al usuario.
llamada a la API de acceso
llamada a la API de acceso
.

Se espera que las RP sean compatibles con navegadores que no admiten FedCM; por lo tanto, los usuarios deben poder usar un proceso de acceso existente que no es de FedCM. Hasta las cookies de terceros se eliminan por completo, esto debería seguir no problemático.

Una vez que el servidor de RP valida el token, este puede registrar al usuario y permitirles acceder y comenzar una nueva sesión.

API de Access Hint

Después de que el usuario accede, a veces el usuario de confianza (RP) le pide que haga lo siguiente: volver a autenticarte. Sin embargo, es posible que el usuario no sepa qué cuenta está usando. Si la parte restringida puede especificar con qué cuenta acceder, será más fácil para el usuario elija una cuenta.

Las RP pueden mostrar de forma selectiva una cuenta específica invocando navigator.credentials.get() por la propiedad loginHint con uno de login_hints valores recuperados de la lista de cuentas extremo, como se indica en la siguiente muestra de código:

return await navigator.credentials.get({
  identity: {
    providers: [{
      configURL: "https://idp.example/manifest.json",
      clientId: "123",
      nonce: nonce,
      loginHint : "demo1@example.com"
    }]
  }
});

Cuando no hay cuentas que coincidan con loginHint, el diálogo de FedCM mostrará una solicitud de acceso. que le permite al usuario acceder a una cuenta de IdP que coincide con la sugerencia solicitada por la parte restringida. Cuando el usuario presiona el mensaje, se abre una ventana emergente con los la URL de acceso especificada en el archivo de configuración. Luego, el vínculo con la sugerencia de acceso y los parámetros de consulta de la sugerencia de dominio.

API de Domain Hint

Hay casos en los que el RP ya sabe que solo las cuentas asociadas con un determinados dominios pueden acceder al sitio. Esto es particularmente común en empresariales en los que el acceso al sitio está restringido a un dominio. Para brindar una mejor experiencia del usuario, la API de FedCM permite que la parte restringida solo Muestra las cuentas que pueden usarse para acceder a la parte restringida. Esto evita situaciones cuando un usuario intenta acceder a la parte restringida con una cuenta ajena a la empresa dominio, solo para recibir un mensaje de error más adelante (o silenciar cuando información de acceso no funcionó) porque no se usaba el tipo de cuenta correcto.

Las RP pueden mostrar de forma selectiva solo las cuentas que coincidan invocando navigator.credentials.get() por la propiedad domainHint con uno de domain_hints valores recuperados de la lista de cuentas extremo, como se indica en la siguiente muestra de código:

return await navigator.credentials.get({
  identity: {
    providers: [{
      configURL: "https://idp.example/manifest.json",
      clientId: "abc",
      nonce: nonce,
      domainHint : "corp.example"
    }]
  }
});

Cuando no hay cuentas que coincidan con domainHint, el diálogo de FedCM mostrará una solicitud de acceso. que le permite al usuario acceder a una cuenta de IdP que coincide con la sugerencia solicitada por la parte restringida. Cuando el usuario presiona el mensaje, se abre una ventana emergente con los la URL de acceso especificada en el archivo de configuración. Luego, el vínculo con la sugerencia de acceso y los parámetros de consulta de la sugerencia de dominio.

Ejemplo de una solicitud de acceso cuando no hay cuentas que coincidan con el campo DomainHint.
Un ejemplo de una solicitud de acceso cuando no hay cuentas que coincidan con domainHint.

Cómo mostrar un mensaje de error

A veces, es posible que el IdP no pueda emitir un token por motivos legítimos, como como cuando el cliente no tiene autorización, el servidor no está disponible temporalmente. Si el IdP muestra un “error” respuesta, la parte restringida puede detectarla, así como la notifica al usuario mostrando una IU del navegador con la información de error proporcionada por el IdP.

A
Un diálogo de FedCM que muestra el mensaje de error después de que falla el intento de acceso del usuario. La cadena está asociada con el tipo de error.
try {
  const cred = await navigator.credentials.get({
    identity: {
      providers: [
        {
          configURL: "https://idp.example/manifest.json",
          clientId: "1234",
        },
      ],
    }
  });
} catch (e) {
  const code = e.code;
  const url = e.url;
}

Vuelve a autenticar los usuarios automáticamente después de la autenticación inicial

Reautenticación automática de FedCM (“reautenticación automática”) puede permitir que los usuarios vuelvan a autenticarse automáticamente cuando regresan después de la autenticación inicial con FedCM. “La autenticación” significa que el usuario crea una cuenta o accede a la parte restringida si presionas el botón "Continue as..." en el diálogo de acceso de FedCM. por primera vez en la misma instancia del navegador.

Si bien la experiencia explícita del usuario tiene sentido antes de que el usuario cree la cuenta federada para evitar el seguimiento (que es uno de los principales objetivos de FedCM) es innecesariamente engorroso después de que el usuario lo ha atravesado una vez: después de el usuario otorga permiso para permitir la comunicación entre el RP y el IdP no brinda ningún beneficio de privacidad o seguridad por exigir que otros usuarios confirmación para algo que ya hayan aceptado previamente.

Con la reautenticación automática, el navegador cambia su comportamiento según la opción que especificar para el mediation cuando se llama a navigator.credentials.get().

const cred = await navigator.credentials.get({
  identity: {
    providers: [{
      configURL: "https://idp.example/fedcm.json",
      clientId: "1234",
    }],
  },
  mediation: 'optional', // this is the default
});

// `isAutoSelected` is `true` if auto-reauthn was performed.
const isAutoSelected = cred.isAutoSelected;

mediation es una propiedad de Credential Management API, se comporta de la misma manera como lo hace por PasswordCredential y FederatedCredential y está parcialmente respaldado por PublicKeyCredential a tus conjuntos de datos. La propiedad acepta los siguientes cuatro valores:

  • 'optional'(predeterminado): Reautenticación automática si es posible. De lo contrario, requiere una mediación. Mié te recomendamos que elijas esta opción en la página de acceso.
  • 'required': Siempre requiere una mediación para continuar; por ejemplo, al hacer clic en el "Continuar" en la IU. Elige esta opción si se espera que tus usuarios otorgar permiso explícitamente cada vez que se deba autenticar.
  • 'silent': Reautenticación automática si es posible; falla silenciosamente sin requerir una mediación si no lo es. Recomendamos elegir esta opción en páginas que no sean la página de acceso dedicada, pero en la que quieres mantener el acceso de los usuarios, por Por ejemplo, la página de un artículo en un sitio web de envíos o la página de un artículo de una sitio web.
  • 'conditional': Se usa para WebAuthn y no está disponible para FedCM en este momento.

Con esta llamada, la reautenticación automática ocurre en las siguientes condiciones:

  • FedCM está disponible para su uso. Por ejemplo, el usuario no ha inhabilitado FedCM ya sea a nivel global o para la parte restringida en la configuración.
  • El usuario utilizó una sola cuenta con la API de FedCM para acceder al sitio web en esta navegador.
  • El usuario accedió al IdP con esa cuenta.
  • La reautenticación automática no se realizó en los últimos 10 minutos.
  • La parte restringida no llamó navigator.credentials.preventSilentAccess() después el acceso anterior.

Cuando se cumplen estas condiciones, un intento de volver a autenticar automáticamente el el usuario inicia apenas se invoca la navigator.credentials.get() de FedCM.

Cuando sea mediation: optional, es posible que se realice la reautenticación automática no disponible debido a los siguientes motivos solo el navegador sabe; la parte restringida puede comprobar si examinar la propiedad isAutoSelected.

Esto es útil para evaluar el rendimiento de la API y mejorar la UX en consecuencia. Además, si no está disponible, es posible que se le solicite al usuario acceder con mediación de usuarios, que es un flujo con mediation: required

Un usuario que autentica automáticamente mediante FedCM

Aplicar la mediación con preventSilentAccess()

La autenticación automática de usuarios inmediatamente después de que salen de sus cuentas no implica un experiencia del usuario muy buena. Por eso, el FedCM tiene un período de inactividad de 10 minutos una reautenticación automática para evitar este comportamiento. Esto significa que la autenticación automática como máximo, una vez cada 10 minutos, a menos que el usuario vuelva a acceder dentro de 10 minutos. La parte restringida debe llamar a navigator.credentials.preventSilentAccess() para solicitar explícitamente al navegador que inhabilite la autenticación automática cuando un usuario salga de su cuenta de forma explícita, por ejemplo, con un botón para salir.

function signout() {
  navigator.credentials.preventSilentAccess();
  location.href = '/signout';
}

Los usuarios pueden inhabilitar la reautenticación automática en la configuración.

Los usuarios pueden inhabilitar la reautenticación automática desde el menú de configuración:

  • En la versión de Chrome para computadoras, ve a chrome://password-manager/settings > Acceder automáticamente.
  • En Chrome para Android, abre Configuración > Administrador de contraseñas > Presiona un engranaje en la esquina superior derecha > Acceso automático.

Si se inhabilita el botón de activación, el usuario podrá rechazar el comportamiento de reautenticación automática entre sí. Este parámetro de configuración se almacena y sincroniza entre dispositivos, si el usuario accedió a una Cuenta de Google en la instancia de Chrome y la sincronización se habilitado.

Desconecta el IdP del RP

Si un usuario ya accedió al RP mediante el IdP a través de FedCM, el relación es memorizada por el navegador localmente como la lista de redes cuentas de servicio. El RP puede iniciar una desconexión invocando la función IdentityCredential.disconnect(). Se puede llamar a esta función desde un marco RP de nivel superior. El RP debe pasar un configURL, el clientId que usa en el IdP, y un accountHint para que el IdP se desconecte. Una cuenta hint puede ser una cadena arbitraria siempre que el extremo de desconexión pueda identificar la cuenta, como una dirección de correo electrónico o un ID de usuario, que no necesariamente coincida con el ID de la cuenta que proporcionó el extremo de la lista de cuentas:

// Disconnect an IdP account "account456" from the RP "https://idp.com/". This is invoked on the RP domain.
IdentityCredential.disconnect({
  configURL: "https://idp.com/config.json",
  clientId: "rp123",
  accountHint: "account456"
});

IdentityCredential.disconnect() muestra un Promise. Esta promesa puede arrojar una excepción por los siguientes motivos:

  • El usuario no accedió al RP mediante el IdP a través de FedCM.
  • La API se invoca desde un iframe sin la política de permisos de FedCM.
  • La configURL no es válida o falta el extremo de desconexión.
  • Falló la verificación de la Política de Seguridad del Contenido (CSP).
  • Hay una solicitud de desconexión pendiente.
  • El usuario inhabilitó FedCM en la configuración del navegador.

Cuando el extremo de desconexión del IdP devuelve un respuesta, el RP y el IdP se desconectan en el navegador y se resuelve la promesa. El ID de las cuentas desconectadas se especificado en la respuesta a la desconexión extremo.

Llamar a FedCM desde un iframe de origen cruzado

FedCM puede invocarse desde un iframe de origen cruzado mediante un Política de permisos identity-credentials-get, si el marco superior lo permite. Para Para ello, agrega el atributo allow="identity-credentials-get" a la etiqueta de iframe de la siguiente manera:

<iframe src="https://fedcm-cross-origin-iframe.glitch.me" allow="identity-credentials-get"></iframe>

Puedes ver cómo funciona en un ejemplo.

De manera opcional, si el marco superior quiere restringir los orígenes para llamar a FedCM, envía un encabezado Permissions-Policy con una lista de orígenes permitidos.

Permissions-Policy: identity-credentials-get=(self "https://fedcm-cross-origin-iframe.glitch.me")

Para obtener más información sobre cómo funciona la política de permisos, consulta Controla funciones del navegador con Permisos Política.