Aprende a usar FedCM para la federación de identidades que preserva la privacidad.
FedCM (Administración de credenciales federadas) es un enfoque que preserva la privacidad de los servicios de identidad federada (como "Acceder con...") en el que los usuarios pueden acceder a sitios sin compartir su información personal con el servicio de identidad o el sitio.
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 en el RP en Chrome para usar FedCM.
Depura el código en Chrome para Android
Configura y ejecuta un servidor de manera local para depurar tu código de FedCM. Puedes acceder a este servidor en Chrome en un dispositivo Android conectado a través de un cable USB con redirección de puertos.
Puedes usar las Herramientas para desarrolladores en una computadora de escritorio a fin de depurar Chrome en Android. Para ello, sigue las instrucciones que se indican en Depuración remota de dispositivos Android.
Bloquear cookies de terceros en Chrome
Puedes probar cómo funciona FedCM sin cookies de terceros en Chrome antes de que se aplique.
Para bloquear cookies de terceros, usa el modo Incógnito o elige “Bloquear cookies de terceros” en la configuración de tu computadora, en chrome://settings/cookies, o en un dispositivo móvil. Para ello, navega a Configuración > Configuración de sitios > Cookies.
Usa la API de FedCM
Para realizar la integración con FedCM, crea un archivo conocido, un archivo de configuración y extremos para la lista de cuentas, la emisión de aserciones y, de manera opcional, los metadatos del cliente.
Desde allí, FedCM expone las APIs de JavaScript que los RP pueden usar para acceder con el IdP.
Cómo crear un archivo conocido
Para evitar que las herramientas de seguimiento abusen de la API, se debe entregar un archivo conocido desde /.well-known/web-identity de eTLD+1 del IdP.
Por ejemplo, si los extremos de IdP se entregan en https://accounts.idp.example/, deben entregar un archivo conocido en https://idp.example/.well-known/web-identity y también un archivo de configuración de IdP. A continuación, se muestra 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 las URLs del archivo de configuración de IdP que los RP puedan especificar como parte de la ruta de acceso de configURL en navigator.credentials.get. La cantidad de cadenas de URL en el array está limitada a una, pero esto puede cambiar con tus 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. Los IdP alojarán este archivo de configuración y los extremos y las URLs requeridos. Todas las respuestas JSON deben entregarse con el tipo de contenido application/json.
La URL del archivo de configuración se determina según los valores proporcionados a la 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. Cuando se llama a navigator.credentials.get() en el RP, el navegador recupera el archivo de configuración con una solicitud GET sin el encabezado Origin ni Referer. La solicitud no tiene cookies ni sigue los redireccionamientos.
Esto evita que el IdP aprenda quién realizó la solicitud y qué RP intenta 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 las siguientes propiedades:
| Propiedad | Descripción |
|---|---|
accounts_endpoint (obligatorio) |
URL del extremo de cuentas. |
client_metadata_endpoint (opcional) |
URL para el extremo de metadatos del cliente. |
id_assertion_endpoint (obligatorio) |
URL del extremo de aserción de ID. |
disconnect (opcional) |
URL del extremo de desconexión. |
login_url (obligatorio) |
La URL de la página de acceso para que el usuario acceda al IdP. |
branding (opcional) |
Objeto que contiene varias opciones de desarrollo de la marca |
branding.background_color (opcional) |
Opción de desarrollo de la marca que establece el color de fondo del botón "Continuar como...". Usa la sintaxis de CSS relevante, es decir, hex-color, hsl(), rgb() o named-color. |
branding.color (opcional) |
Opción de desarrollo de la marca que establece el color del texto del botón "Continuar como...". Usa la sintaxis de CSS relevante, 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 cuadro de diálogo de acceso. El objeto icon es un array con dos parámetros:
|
El RP podría modificar la cadena en la IU del diálogo de FedCM con el valor identity.context para navigator.credentials.get() a fin de adaptarse a contextos de autenticación predefinidos. La propiedad opcional puede ser una de las siguientes: "signin" (configuración predeterminada), "signup", "use" o "continue".
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 las solicitudes posteriores a los extremos de IdP:
Extremo de cuentas
El extremo de cuentas del IdP muestra una lista de cuentas a las que el usuario accedió en el IdP. Si el IdP admite varias cuentas, este extremo mostrará 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 ni el encabezado Referer. Esto evita que el IdP aprenda a qué RP el usuario intenta acceder. Por ejemplo:
GET /accounts.php HTTP/1.1
Host: accounts.idp.example
Accept: application/json
Cookie: 0x23223
Sec-Fetch-Dest: webidentity
Cuando reciba la solicitud, el servidor deberá hacer lo siguiente:
- Verifica que la solicitud contenga un encabezado HTTP
Sec-Fetch-Dest: webidentity. - Hacer coincidir las cookies de sesión con los ID de las cuentas que ya accedieron
- 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 con las siguientes propiedades:
| Propiedad | Descripción |
|---|---|
id (obligatorio) |
Es el ID único del usuario. |
name (obligatorio) |
Nombre y apellido del usuario. |
email (obligatorio) |
Dirección de correo electrónico del usuario. |
given_name (opcional) |
Indica el nombre del usuario. |
picture (opcional) |
URL de la imagen de avatar del usuario. |
approved_clients (opcional) |
Es un array de IDs de cliente de RP con el que se registró el usuario. |
login_hints (opcional) |
Un array de todos los tipos de filtros posibles que admite el IdP para especificar una cuenta. El RP puede invocar a navigator.credentials.get() con la propiedad loginHint para mostrar de forma selectiva la cuenta especificada. |
domain_hints (opcional) |
Es un array de todos los dominios con los que está asociada la cuenta. El RP puede llamar a navigator.credentials.get() con una propiedad domainHint para filtrar las cuentas. |
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 el RP.
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 del RP. Los RP deben proporcionar vínculos a sus políticas de privacidad y Condiciones del Servicio al IdP con anticipación. Estos vínculos se muestran en el diálogo de acceso cuando el usuario aún no se registró 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
Cuando reciba la solicitud, el servidor deberá hacer lo siguiente:
- Determina el RP para
client_id. - Responder con metadatos del cliente
Las propiedades del extremo de metadatos del cliente incluyen lo siguiente:
| 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 RP. |
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 del cliente que se muestran y no estarán disponibles para el RP.
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 una llamada a navigator.credentials.get(), 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) |
Es el identificador de cliente del RP. |
account_id (obligatorio) |
El ID único del usuario que accedió. |
nonce (opcional) |
El nonce de la solicitud, proporcionado por el RP. |
disclosure_text_shown |
Genera una string de "true" o "false" (en lugar de un 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 cuentas o si el navegador observó un momento de registro en el pasado sin 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 de usuarios en la autenticación. Si un IdP recibe una solicitud de token sin esa mediación, podría manejar la solicitud de manera diferente. Por ejemplo, se muestra un código de error para 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
Cuando reciba la solicitud, el servidor deberá hacer lo siguiente:
- Responde a la solicitud con CORS (uso compartido de recursos entre dominios).
- Verifica que la solicitud contenga un encabezado HTTP
Sec-Fetch-Dest: webidentity. - Haz coincidir el encabezado
Origincon el origen del RP determinado porclient_id. Recházalas si no coinciden. - Haz coincidir
account_idcon el ID de la cuenta a la que ya accediste. Rechazar si no coinciden. - Responder con un token Si se rechaza la solicitud, responde con una respuesta de error.
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 pueda 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 muestra al RP para que el RP pueda validar la autenticación.
Muestra una respuesta de error
id_assertion_endpoint también puede mostrar una respuesta de “error”, que tiene dos campos opcionales:
code: El IdP puede elegir uno de los errores conocidos de la lista de errores especificada de OAuth 2.0 (invalid_request,unauthorized_client,access_denied,server_errorytemporarily_unavailable) o usar cualquier string arbitraria. De lo contrario, Chrome renderiza la IU de 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 error para proporcionar información adicional sobre el error 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 para los próximos pasos, información de contacto de atención al cliente, etcétera. Si un usuario desea obtener más información sobre los detalles del error y cómo corregirlo, puede visitar la página proporcionada desde la IU del navegador para obtener más detalles. La URL debe ser del mismo sitio que elconfigURLdel IdP.
// id_assertion_endpoint response
{
"error" : {
"code": "access_denied",
"url" : "https://idp.example/error?type=access_denied"
}
}
Desconectar extremo
Cuando se invoca IdentityCredential.disconnect(), el navegador envía una solicitud POST de origen cruzado
con cookies con SameSite=None y un tipo de contenido de
application/x-www-form-urlencoded a este extremo de desconexión con la
siguiente información:
| Propiedad | Descripción |
|---|---|
account_hint |
Una sugerencia para la cuenta de IdP. |
client_id |
Es el identificador de cliente del 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
Cuando reciba la solicitud, el servidor deberá hacer lo siguiente:
- Responde a la solicitud con CORS (uso compartido de recursos entre dominios).
- Verifica que la solicitud contenga un encabezado HTTP
Sec-Fetch-Dest: webidentity. - Haz coincidir el encabezado
Origincon el origen del RP determinado porclient_id. Recházalas si no coinciden. - Haz coincidir
account_hintcon los IDs de las cuentas a las que ya se accedió. - Desconecta la cuenta de usuario de la parte restringida.
- Responde al navegador con la información de la cuenta de usuario identificada en formato JSON.
Una carga útil de JSON de respuesta de ejemplo 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 estado de acceso, el IdP debe informar el estado de acceso del usuario al navegador. Sin embargo, el estado podría no estar sincronizado, como cuando expira la sesión. En ese caso, el navegador puede permitir de forma dinámica que el usuario acceda al IdP a través de la URL de la página de acceso especificada con el login_url del archivo de configuración de IdP.
En el diálogo de FedCM, se muestra un mensaje que sugiere un acceso, como se muestra en la siguiente imagen.
Cuando el usuario hace clic en el botón Continuar, el navegador abre una ventana emergente para la página de acceso del IdP.
El diálogo es una ventana normal del navegador con cookies propias. Lo que suceda dentro del diálogo depende del IdP, y no hay controladores de ventana disponibles para realizar una solicitud de comunicación de origen cruzado a la página de RP. Después de que el usuario accede, el IdP debe hacer lo siguiente:
- Envía el encabezado
Set-Login: logged-ino llama a la API denavigator.login.setStatus("logged-in")para informar al navegador que el usuario accedió. - Llama a
IdentityProvider.close()para cerrar el diálogo.
Informa al navegador sobre 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, en especial 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 IdP y mitigar posibles ataques de tiempo.
Los IdP pueden indicar el estado de acceso del usuario al navegador mediante el envío de un encabezado HTTP o una llamada a una API de JavaScript cuando el usuario accede al IdP o cuando sale de todas sus cuentas de IdP. Para cada IdP (identificado por su URL de configuración), el navegador mantiene una variable de tres estados que representa el estado de acceso con 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 origen del IdP:
Set-Login: logged-in
Como alternativa, llama a la API de JavaScript navigator.login.setStatus("logged-in") 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 estado de acceso del usuario se establece en logged-in, el RP que llama a FedCM realiza solicitudes al extremo de las cuentas del IdP y muestra las cuentas disponibles al usuario en el diálogo de 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 una solicitud de subrecurso del mismo sitio en el origen del IdP:
Set-Login: logged-out
Como alternativa, llama a la API de JavaScript navigator.login.setStatus("logged-out") 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 el estado de acceso del usuario es logged-out, la llamada a FedCM falla silenciosamente sin realizar una solicitud al extremo de las cuentas del IdP.
El estado unknown se establece antes de que el IdP envíe un indicador con la API de estado de acceso. Se introdujo Unknown para mejorar la transición, ya que es posible que un usuario ya haya accedido al IdP cuando se envió esta API. Es posible que el IdP no tenga la oportunidad de indicar esto al navegador antes de que se invoque FedCM por primera vez. En este caso, Chrome envía una solicitud al extremo de las cuentas del IdP y actualiza el estado en función de la respuesta del extremo de las cuentas:
- Si el extremo muestra una lista de cuentas activas, actualiza el estado a
logged-iny abre el diálogo de FedCM para mostrar esas cuentas. - Si el extremo no muestra ninguna cuenta, actualiza el estado a
logged-outy falla la llamada a FedCM.
Permitir 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 sincronizado, como cuándo vence la sesión. El navegador intenta enviar una solicitud con credenciales al extremo de las cuentas cuando el estado de acceso es logged-in, pero el servidor no muestra cuentas porque la sesión ya no está disponible. En ese caso, el navegador puede permitir de forma dinámica que el usuario acceda 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 a navigator.credentials.get() para solicitar que los usuarios accedan al RP con el IdP.
Antes de llamar a la API, debes confirmar que [FedCM está disponible en el navegador del usuario]. Para verificar si FedCM está disponible, une este código a tu 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:
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 objetos IdentityProvider que tienen las siguientes propiedades:
| Propiedad | Descripción |
|---|---|
configURL (obligatorio) |
Una ruta de acceso completa del archivo de configuración del IdP. |
clientId (obligatorio) |
Es el identificador de cliente del RP, emitido por el IdP. |
nonce (opcional) |
Una cadena aleatoria para garantizar que se emita la respuesta para esta solicitud específica. Impide ataques de repetición. |
loginHint (opcional) |
Cuando se especifica uno de los valores de login_hints proporcionados por los extremos de las cuentas, el diálogo de FedCM muestra de forma selectiva la cuenta especificada. |
domainHint (opcional) |
Cuando se especifica uno de los valores de domain_hints proporcionados por los extremos de las cuentas, el diálogo de FedCM muestra de forma selectiva la cuenta especificada. |
El navegador maneja los casos de uso de registro y acceso de manera diferente según la existencia de approved_clients en la respuesta del extremo de la lista de cuentas. El navegador no mostrará un texto de divulgación "Para continuar con ...." si el usuario ya se registró en el RP.
El estado de registro se determina en función de si se cumplen o no las siguientes condiciones:
- Si
approved_clientsincluye elclientIddel RP. - Si el navegador recuerda que el usuario ya se registró en el RP.
Cuando el RP llama a navigator.credentials.get(), se llevan a cabo las siguientes actividades:
- El navegador envía solicitudes y recupera varios documentos:
- El archivo conocido y un archivo de configuración de IdP que declaran extremos.
- Una lista de cuentas.
- Opcional: URLs de la política de privacidad y las Condiciones del Servicio del RP, que se recuperan del extremo de metadatos del cliente.
- 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.
- Una vez que el usuario elige una cuenta para acceder, se envía una solicitud al extremo de aserción de ID al IdP para recuperar un token.
- El RP puede validar el token para autenticar al usuario.
Se espera que los RP sean compatibles con navegadores que no admiten FedCM, por lo que los usuarios deberían poder usar un proceso de acceso existente que no sea de FedCM. Hasta que las cookies de terceros se eliminen por completo, esto no debería causar problemas.
Una vez que el servidor de RP valida el token, el RP puede registrar al usuario o permitirle que acceda y, luego, inicie una nueva sesión.
API de información de acceso
Después de que el usuario accede, a veces, el usuario de confianza (RP) le solicita que se vuelva a autenticar. Sin embargo, es posible que el usuario no esté seguro de qué cuenta ha estado usando. Si el RP puede especificar con qué cuenta acceder, sería más fácil para el usuario elegir una.
Los RP pueden mostrar de forma selectiva una cuenta específica invocando navigator.credentials.get() con la propiedad loginHint con uno de los valores login_hints recuperados del extremo de la lista de cuentas, como se observa 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 ninguna cuenta coincide con loginHint, el diálogo de FedCM muestra un mensaje de acceso, que permite al usuario acceder a una cuenta de IdP que coincida con la sugerencia solicitada por el RP. Cuando el usuario presiona el mensaje, se abre una ventana emergente con la URL de acceso especificada en el archivo de configuración. Luego, el vínculo se adjunta 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 dominio determinado pueden acceder al sitio. Esto es particularmente común en situaciones empresariales en las que el sitio al que se accede está restringido a un dominio corporativo. Para brindar una mejor experiencia del usuario, la API de FedCM permite que el RP solo muestre las cuentas que se pueden usar para acceder a la parte restringida. Esto evita situaciones en las que un usuario intenta acceder al RP con una cuenta fuera del dominio corporativo, solo para recibir un mensaje de error más tarde (o silenciar cuando no funciona el acceso) porque no se usó el tipo de cuenta correcto.
Los RP pueden mostrar solo cuentas coincidentes de forma selectiva invocando navigator.credentials.get() con la propiedad domainHint con uno de los valores domain_hints recuperados del extremo de la lista de cuentas, 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 ninguna cuenta coincide con domainHint, el diálogo de FedCM muestra un mensaje de acceso, que permite al usuario acceder a una cuenta de IdP que coincida con la sugerencia solicitada por el RP. Cuando el usuario presiona el mensaje, se abre una ventana emergente con la URL de acceso especificada en el archivo de configuración. Luego, el vínculo se adjunta con la sugerencia de acceso y los parámetros de consulta de la sugerencia de dominio.
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 cuando el cliente no está autorizado porque el servidor no está disponible temporalmente. Si el IdP muestra una respuesta de "error", el RP puede detectarla y Chrome notifica al usuario con una IU del navegador con la información de error proporcionada por el IdP.
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 automáticamente a los usuarios después del consentimiento inicial
La reautenticación automática de FedCM (“reautenticación automática” en la forma abreviada) puede permitir que los usuarios vuelvan a autenticarse automáticamente, cuando regresen después de su autenticación inicial con FedCM. “La autenticación inicial” significa que el usuario crea una cuenta o accede al sitio web del RP presionando el botón “Continuar como...” 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 objetivos principales de FedCM), resulta innecesariamente engorrosa después de que el usuario la haya realizado una vez: después de que el usuario otorga permiso para permitir la comunicación entre el RP y el IdP, no hay ningún beneficio de privacidad o seguridad para aplicar otra confirmación explícita del usuario para algo que ya confirmó.
Con la reautenticación automática, el navegador cambia su comportamiento según la opción que especifiques para la mediation cuando llames 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 en la API de Credential Management, se comporta de la misma manera que para PasswordCredential y FederatedCredential, y también es compatible parcialmente con PublicKeyCredential. La propiedad acepta los siguientes cuatro valores:
'optional'(opción predeterminada): Reautenticación automática si es posible; si no es posible, requiere una mediación. Te recomendamos que elijas esta opción en la página de acceso.'required': Siempre requiere una mediación para continuar, por ejemplo, hacer clic en el botón "Continuar" en la IU. Elige esta opción si se espera que tus usuarios otorguen permiso de manera explícita cada vez que necesiten autenticación.'silent': La reautenticación automática si es posible. De lo contrario, falla sin solicitar una mediación. Te recomendamos que elijas esta opción en páginas que no sean la página de acceso dedicada, pero en las que quieras mantener a los usuarios conectados, por ejemplo, una página de artículo en un sitio web de envíos o una página de artículo en un sitio web de noticias.'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 inhabilitó FedCM a nivel global ni para el RP en la configuración.
- El usuario usó una sola cuenta con la API de FedCM para acceder al sitio web en este navegador.
- El usuario accedió al IdP con esa cuenta.
- La reautenticación automática no se realizó en los últimos 10 minutos.
- El RP no llamó a
navigator.credentials.preventSilentAccess()después del acceso anterior.
Cuando se cumplen estas condiciones, se inicia un intento de volver a autenticar automáticamente al usuario en cuanto se invoca el navigator.credentials.get() de FedCM.
Cuando es mediation: optional, la reautenticación automática puede no estar disponible debido a motivos que solo el navegador sabe. El RP puede verificar si se realiza la reautenticación automática cuando se examina la propiedad isAutoSelected.
Esto es útil para evaluar el rendimiento de la API y mejorar la UX según corresponda.
Además, cuando no esté disponible, es posible que se le solicite al usuario que acceda con la mediación explícita del usuario, que es un flujo con mediation: required.
Aplica la mediación con preventSilentAccess()
Volver a autenticar a los usuarios de forma automática inmediatamente después de que salen de sus cuentas no sería una muy buena experiencia del usuario. Es por eso que FedCM tiene un período de inactividad de 10 minutos después de una reautenticación automática para evitar este comportamiento. Esto significa que la reautenticación automática ocurre, como máximo, una vez cada 10 minutos, a menos que el usuario vuelva a acceder en un plazo de 10 minutos. El RP debe llamar a navigator.credentials.preventSilentAccess() para solicitar de forma explícita al navegador que inhabilite la reautenticación automática cuando un usuario sale de la RP, por ejemplo, con un clic en el botón 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 en el menú de configuración:
- En la versión de Chrome para computadoras de escritorio, 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 inhabilitas el botón de activación, el usuario podrá inhabilitar por completo el comportamiento de reautenticación automática. Esta configuración se almacena y sincroniza en todos los dispositivos si el usuario accede a una Cuenta de Google en la instancia de Chrome y la sincronización está habilitada.
Desconecta el IdP del RP
Si un usuario ya accedió al RP con el IdP a través de FedCM, el navegador memoriza la relación de forma local como la lista de cuentas conectadas. El RP puede iniciar una desconexión invocando la función IdentityCredential.disconnect(). Se puede llamar a esta función desde un fotograma de RP de nivel superior. El RP debe pasar un configURL, el clientId que usa debajo del IdP y un accountHint para que se desconecte el IdP. Una sugerencia de la cuenta puede ser una string arbitraria siempre que el extremo de desconexión pueda identificar la cuenta, por ejemplo, una dirección de correo electrónico o un ID de usuario que no coincida necesariamente 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 generar una excepción por los siguientes motivos:
- El usuario no accedió al RP con 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.
- Falla 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 muestra una respuesta, el RP y el IdP se desconectan en el navegador y se resuelve la promesa. El ID de las cuentas desconectadas se especifica en la respuesta del extremo de desconexión.
Llamar a FedCM desde un iframe de origen cruzado
FedCM se puede invocar desde un iframe de origen cruzado mediante una
política de permisos identity-credentials-get, si el marco superior lo permite. 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 desea 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")
Puedes obtener más información sobre cómo funciona la política de permisos en Controla las funciones del navegador con la política de permisos.