Implementa una solución de identidad con FedCM del lado de la parte autenticada

Las entidades externas (RP) deben completar los siguientes pasos para habilitar FedCM en su sitio:

• Asegúrate de que los extremos de FedCM estén permitidos en el sitio del RP.
• Usa la API de FedCM de JavaScript para iniciar la autenticación del usuario.
• Proporcionar sus metadatos (como las URLs de la política de privacidad y las condiciones del servicio) al IdP (o a varios IdPs a partir de Chrome 136)
• [Opcional] Personaliza la experiencia del usuario eligiendo un modo de UX, proporcionando sugerencias de acceso o de dominio, pasando parámetros personalizados, solicitando información específica del usuario, proporcionando un mensaje de error personalizado o eligiendo cómo volver a autenticar a los usuarios.

Llama a la API de FedCM en el RP

Una vez que la configuración del IdP y los extremos estén disponibles, los RP pueden llamar a navigator.credentials.get() para solicitar que se permita que un usuario acceda 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, incluye este código en tu implementación de FedCM:

  if ('IdentityCredential' in window) {
    // If the feature is available, take action
  } else {
    // FedCM is not supported, use a different identity solution
  }

Para permitir que un usuario acceda al IdP en una RP con FedCM, la RP puede llamar a navigator.credentials.get(). A partir de Chrome 136, el RP puede admitir varios IdP especificando un array de varios proveedores de identidad en una sola llamada a navigator.credentials.get(), por ejemplo:

  const credential = await navigator.credentials.get({
      identity: {
        // Specify the IdP (or multiple IdPs, supported from Chrome 136) this Relying Party supports
        providers: [
        {
              configURL: 'https://accounts.idp-1.example/config.json',
              clientId: '********'
        },
        {
          configURL: 'https://accounts.idp-2.example/config.json',
          clientId: '********'
        }]
      }
    },
  );
  const { token } = credential;
  
  // Get the current IdP's configURL to identify which provider the user is signed in with
  const currentIdpConfigUrl = credential.configURL;
  if (currentIdpConfigUrl === 'https://idp1.example/foo.json') {
    // handle the case where the user signed in with idp1
  } else if (currentIdpConfigUrl === 'https://idp2.example/bar.json') {
    // handle the case where the user signed in with idp2
    }

Prueba la función de varios IdPs accediendo con IdP1 y IdP2.

Propiedad de contexto

Con la propiedad context opcional, el RP puede modificar la cadena en la IU del diálogo de FedCM (por ejemplo, "Accede a rp.example…", "Usa idp.example…") para adaptarse a contextos de autenticación predefinidos, por ejemplo. La propiedad context puede tener los siguientes valores:

• signin (predeterminada)
• signup
• use

Por ejemplo, si se configura context como use, se generará el siguiente mensaje:

El navegador controla los casos de uso de registro y acceso de manera diferente según la existencia de approved_clients en la respuesta del endpoint 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.
La propiedad providers toma un array de objetos IdentityProvider que tienen las siguientes propiedades:

Propiedad Providers

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

Modo activo

FedCM admite diferentes configuraciones de modo de UX. El modo pasivo es el modo predeterminado y los desarrolladores no necesitan configurarlo.

Para usar FedCM en el modo activo, haz lo siguiente:

1. Verifica la disponibilidad de la función en el navegador del usuario.
2. Invoca la API con un gesto transitorio del usuario, como un clic en un botón.
3. Pasa el parámetro mode a la llamada a la API:

  let supportsFedCmMode = false;
  try {
    navigator.credentials.get({
      identity: Object.defineProperty(
        // Check if this Chrome version supports the Mode API.
        {}, 'mode', {
          get: function () { supportsFedCmMode = true; }
        }
      )
    });
  } catch(e) {}

  if (supportsFedCmMode) {
    // The button mode is supported. Call the API with mode property:
    return await navigator.credentials.get({
      identity: {
        providers: [{
          configURL: 'https://idp.example/config.json',
          clientId: '123',
        }],
        // The 'mode' value defines the UX mode of FedCM.
        // - 'active': Must be initiated by user interaction (e.g., clicking a button).
        // - 'passive': Can be initiated without direct user interaction.
        mode: 'active'
      }
    });
  }

Prueba el modo activo con esta demostración.

Ícono personalizado en modo activo

El modo activo permite que los IdP incluyan el ícono del logotipo oficial del RP directamente en la respuesta del extremo de metadatos del cliente. El RP debe proporcionar sus datos de desarrollo de la marca con anticipación.

Llama a FedCM desde un iframe de origen cruzado

Se puede invocar a FedCM desde un iframe de origen cruzado con 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 iframe de la siguiente manera:

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

Puedes verlo en acción en un ejemplo.

De manera opcional, si el iframe 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")

Puedes obtener más información sobre cómo funciona la Política de permisos en Cómo controlar las funciones del navegador con la Política de permisos.

API de Login Hint

Con la sugerencia de acceso, el RP puede recomendar con qué cuenta debe acceder un usuario. Esto puede ser útil para volver a autenticar a los usuarios que no saben qué cuenta usaron antes.

Los RP pueden mostrar de forma selectiva una cuenta específica invocando navigator.credentials.get() con la propiedad loginHint y uno de los valores de login_hints recuperados del endpoint de la lista de cuentas, como se muestra en el siguiente ejemplo de código:

  return await navigator.credentials.get({
    identity: {
      providers: [{
        configURL: 'https://idp.example/manifest.json',
        clientId: '123',
        // Accounts endpoint can specify a 'login_hints' array for an account.
        // When RP specifies a 'exampleHint' value, only those accounts will be
        // shown to the user whose 'login_hints' array contains the 'exampleHint'
        // value
        loginHint : 'exampleHint'
      }]
    }
  });

Cuando ninguna cuenta coincide con el 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 la instrucción, se abre una ventana emergente con la URL de acceso especificada en el archivo de configuración. Luego, se agregan los parámetros de consulta de sugerencia de acceso y sugerencia de dominio al vínculo.

API de Domain Hint

Los RP pueden mostrar de forma selectiva solo las cuentas asociadas a un dominio determinado. Esto puede ser útil para los RP que están restringidos a un dominio corporativo.

Para mostrar solo cuentas de dominios específicos, el RP debe llamar a navigator.credentials.get() con la propiedad domainHint y uno de los valores de domain_hints recuperados del extremo de la lista de cuentas, como se muestra en la siguiente muestra de código:

  return await navigator.credentials.get({
    identity: {
      providers: [{
        configURL: 'https://idp.example/manifest.json',
        clientId: 'abc',
        // Accounts endpoint can specify a 'domain_hints' array for an account.
        // When RP specifies a '@domain.example' value, only those accounts will be
        // shown to the user whose 'domain_hints' array contains the
        // '@domain.example' value
        domainHint : '@domain.example'
      }]
    }
  });

Cuando ninguna cuenta coincide con el 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 la instrucción, se abre una ventana emergente con la URL de acceso especificada en el archivo de configuración. Luego, se agregan los parámetros de consulta de sugerencia de acceso y sugerencia de dominio al vínculo.

Consulta la demostración para obtener más detalles.

Parámetros personalizados

La función de parámetros personalizados permite que el RP proporcione parámetros clave-valor adicionales al endpoint de aserción de ID. Con la API de Parameters, los RP pueden pasar parámetros adicionales al IdP para solicitar permisos para recursos más allá del acceso básico. Pasar parámetros adicionales puede ser útil en los siguientes casos:

• El RP debe solicitar de forma dinámica permisos adicionales que tenga el IdP, como la dirección de facturación o el acceso al calendario. El usuario puede autorizar estos permisos a través de un flujo de UX controlado por el IdP que se inicia con la función Continuar en, y el IdP luego compartiría esta información.

Para usar la API, el RP agrega parámetros a la propiedad params como un objeto en la llamada navigator.credentials.get():

  let {token} = await navigator.credentials.get({
    identity: {
      providers: [{
        clientId: '1234',
        configURL: 'https://idp.example/fedcm.json',
        // Key/value pairs that need to be passed from the
        // RP to the IdP but that don't really play any role with
        // the browser.
        params: {
          IDP_SPECIFIC_PARAM: '1',
          foo: 'BAR'
        }
      },
    }
  });

El navegador traducirá automáticamente esto en una solicitud POST al IdP con parámetros como un solo objeto serializado en JSON codificado en URL:

  // The assertion endpoint is drawn from the config file
  POST /fedcm_assertion_endpoint HTTP/1.1
  Host: idp.example
  Origin: https://rp.example/
  Content-Type: application/x-www-form-urlencoded
  Cookie: 0x23223
  Sec-Fetch-Dest: webidentity

  // params are translated into urlencoded version of `{"IDP_SPECIFIC_PARAM":"1","foo":"bar"}`
  account_id=123&client_id=client1234&params=%22%7B%5C%22IDP_SPECIFIC_PARAM%5C%22%3A1%2C%5C%22foo%5C%22%3A%5C%22BAR%5C%22%7D%22.

Si el RP necesita permisos adicionales, el IdP puede proporcionar un vínculo de redireccionamiento. Por ejemplo, en Node.js:

  if (rpRequestsPermissions) {
    // Response with a URL if the RP requests additional permissions
    return res.json({
      continue_on: '/example-redirect',
    });
  }

Campos

El RP puede especificar la información del usuario que necesita que el IdP comparta con él. Esto puede incluir cualquier combinación de nombre, dirección de correo electrónico, nombre de usuario, número de teléfono y foto de perfil. La información solicitada se incluirá en la IU de divulgación del diálogo de FedCM.

Los usuarios que se registren verán un mensaje que les notificará que idp.example compartirá la información solicitada con rp.example si el usuario decide registrarse. Si la respuesta del endpoint de cuentas no incluye un campo que solicitó el RP, el texto de divulgación no incluirá este campo. El IdP obtendrá todos los campos solicitados del endpoint de aserción de ID y decidirá si debe recopilar más permisos del usuario para continuar.

Para usar la función Fields, RP debe agregar un array fields en la llamada navigator.credentials.get(). Los campos pueden contener propiedades como name, email, tel, username o picture. Esta lista se puede expandir para incluir más valores en el futuro. Una solicitud con fields se vería de la siguiente manera:

   let { token } = await navigator.credentials.get({
    identity: {
      providers: [{
        // RP requests the IdP to share only username and profile picture
        fields: [ 'username', 'picture'],
        clientId: '1234',
        configURL: 'https://idp.example/fedcm.json',
      },
    }
  });

El navegador lo traducirá automáticamente en una solicitud HTTP al extremo de aserción de ID que incluye el parámetro fields especificado por el RP, con los campos que el navegador divulgó al usuario en un parámetro disclosure_shown_for. Para garantizar la compatibilidad con versiones anteriores, el navegador también enviará disclosure_text_shown=true si se mostró el texto de divulgación y los campos solicitados incluyen los tres campos: 'name', 'email' y 'picture'. A partir de Chrome 141, el valor de disclosure_text_shown no indica si el texto de divulgación se mostró realmente al usuario.

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

  // The RP only requested to share email and picture. The browser will send `disclosure_text_shown=false`, as the 'name' field value is missing
  account_id=123&client_id=client1234&disclosure_text_shown=false&fields=email,picture&disclosure_shown_for=email,picture

Si fields es un array vacío, el usuario-agente omitirá la IU de divulgación.

Esto sucede incluso si la respuesta del endpoint de cuentas no contiene un ID de cliente que coincida con el RP en approved_clients.

En este caso, el valor de disclosure_text_shown enviado al extremo de aserción de ID es falso en el cuerpo HTTP:

  POST /id_assertion_endpoint HTTP/1.1
  Host: 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=234234&disclosure_text_shown=false

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 o el servidor no está disponible temporalmente. Si el IdP devuelve una respuesta de "error", el RP puede detectarla y Chrome puede notificar al usuario mostrando la IU del navegador con la información del 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 de la autenticación inicial

La reautenticación automática de FedCM (o "auto-reauthn" para abreviar) permite que los usuarios se reautentiquen automáticamente. Se deben cumplir las siguientes condiciones para volver a autenticar al usuario automáticamente:

• El usuario ya realizó la autenticación inicial con FedCM. Aquí, "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.
• El usuario solo tiene una cuenta de cliente recurrente. Si existen cuentas que regresan para varios IdP, el usuario no se volverá a autenticar automáticamente.

Si bien la experiencia del usuario explícita tiene sentido antes de que el usuario cree la cuenta federada para evitar el seguimiento (que es uno de los objetivos principales de FedCM), es 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 exigir otra confirmación explícita del usuario para algo que ya reconoció anteriormente.

Con la reautenticación automática, el navegador cambia su comportamiento según la opción que especifiques para 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 de la API de Credential Management, se comporta de la misma manera que lo hace para PasswordCredential y FederatedCredential, y también es parcialmente compatible con PublicKeyCredential. La propiedad acepta los siguientes cuatro valores:

• 'optional'(predeterminado): Se vuelve a autenticar automáticamente si es posible y requiere mediación si no lo es. 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 forma explícita cada vez que necesiten autenticarse.
• 'silent': Se vuelve a autenticar automáticamente si es posible. Si no lo es, falla de forma silenciosa sin requerir una mediación. Recomendamos elegir esta opción en las páginas que no sean la página de acceso dedicada, pero en las que desees que los usuarios permanezcan conectados, por ejemplo, una página de artículos en un sitio web de envío o una página de artículos 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 se produce en las siguientes condiciones:

• FedCM está disponible para su uso. Por ejemplo, el usuario no inhabilitó FedCM de forma global ni para el RP en la configuración.
• El usuario usó solo una cuenta con la API de FedCM para acceder al sitio web en este navegador.
• El usuario accedió al IdP con esa cuenta.
• No se produjo la reautenticación automática 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 mediation: optional, la reautenticación automática puede estar disponible por motivos que solo conoce el navegador. El RP puede verificar si se realiza la reautenticación automática examinando la propiedad isAutoSelected.

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

Aplica la mediación con preventSilentAccess()

La reautenticación automática de los usuarios inmediatamente después de que salgan de su cuenta no sería una experiencia del usuario muy buena. Por eso, FedCM tiene un período de silencio 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 ese plazo. El RP debe llamar a navigator.credentials.preventSilentAccess() para solicitar explícitamente al navegador que inhabilite la reautenticación automática cuando un usuario salga del RP de forma explícita, por ejemplo, haciendo clic en un botón de cierre de sesión.

  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 Chrome para computadoras, ve a chrome://password-manager/settings > Acceder automáticamente.
• En Chrome para Android, abre Configuración > Administrador de contraseñas > Presiona el ícono de ajustes en la esquina superior derecha > Acceso automático.

Si inhabilita el botón de activación, el usuario puede inhabilitar por completo el comportamiento de reautenticación automática. Este parámetro de configuración se almacena y sincroniza en todos los dispositivos si el usuario accedió a una Cuenta de Google en la instancia de Chrome y la sincronización está habilitada.

Desconecta el IdP del RP

Si un usuario accedió previamente a la RP con el IdP a través de FedCM, el navegador recuerda 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 marco de RP de nivel superior. El RP debe pasar un configURL, el clientId que usa en el IdP y un accountHint para que se desconecte el IdP. Una sugerencia de cuenta puede ser una cadena arbitraria, siempre y cuando 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 necesariamente coincida con el ID de 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() devuelve un Promise. Esta promesa puede arrojar una excepción por los siguientes motivos:

• El usuario no accedió al RP con el IdP a través de FedCM.
• Se invoca la API desde un iframe sin una política de permisos de FedCM.
• El parámetro configURL no es válido 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 devuelve una respuesta, el RP y el IdP se desconectan en el navegador y se resuelve la promesa. Los IDs de las cuentas desconectadas se especifican en la respuesta del extremo de desconexión.

Pasos siguientes

Implementa FedCM en el IdP

Revisa cómo implementar tu solución de identidad con FedCM del lado del proveedor de identidad.

Personalización y anulación de la habilitación

Explora cómo los usuarios y los desarrolladores pueden administrar la participación en FedCM, incluida la habilitación o inhabilitación, en todas las plataformas y sitios.