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

Los terceros de confianza (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 JavaScript de FedCM para iniciar la autenticación del usuario.
• Proporcionar sus metadatos (como las URLs de la política de privacidad y las condiciones del servicio) a la AC
• [Opcional] Para personalizar la experiencia del usuario, elige un modo de UX, proporciona acceso o sugerencias de dominio, pasa parámetros personalizados, solicita información específica del usuario, proporciona un mensaje de error personalizado o elige cómo volver a autenticar a los usuarios.

Una vez que la configuración y los extremos del IdP estén disponibles, los RPs pueden llamar a navigator.credentials.get() para solicitar que se permita 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 comprobar 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
  } else {
    // FedCM is not supported, use a different identity solution
  }

Para permitir que los usuarios accedan al IdP en un RP con FedCM, el RP puede llamar a navigator.credentials.get(), por ejemplo:

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

Propiedad de contexto

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

• signin (predeterminada)
• signup
• use

Por ejemplo, si configuras context en use, se mostrará 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 extremo de la lista de cuentas. El navegador no mostrará el texto de divulgación "Para continuar con ...." si el usuario ya se registró en la 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 modo activo, haz lo siguiente:

1. Verifica la disponibilidad de la función en el navegador del usuario.
2. Invoca a la API con un gesto transitorio del usuario, como hacer 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'
      }
    });
  }

Ícono personalizado en modo activo

El modo activo permite que los IdP incluyan el ícono del logotipo oficial de la 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

FedCM se puede invocar desde un iframe de origen cruzado con una política de permisos identity-credentials-get, si el marco superior lo permite. Para hacerlo, 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 ver cómo funciona en un ejemplo.

De forma opcional, si la trama 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 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 están seguros de cuál fue la cuenta que usaron anteriormente.

Los RP pueden mostrar de forma selectiva una cuenta específica invocando a navigator.credentials.get() con la propiedad loginHint con uno de los valores login_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: '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 no hay cuentas que coincidan con loginHint, el diálogo de FedCM muestra un mensaje de acceso, que le permite al usuario acceder a una cuenta de IdP que coincida con la sugerencia que solicitó el RP. Cuando el usuario presiona la indicación, se abre una ventana emergente con la URL de acceso especificada en el archivo de configuración. Luego, se le agrega el vínculo con los parámetros de consulta de sugerencia de acceso y sugerencia de dominio.

API de Domain Hint

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

Para mostrar solo cuentas de dominio específicas, el RP debe llamar a navigator.credentials.get() con la propiedad domainHint con uno de los valores de domain_hints recuperados de el 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 no hay cuentas que coincidan con domainHint, el diálogo de FedCM muestra un mensaje de acceso, que le permite al usuario acceder a una cuenta de IdP que coincida con la sugerencia que solicitó el RP. Cuando el usuario presiona la indicación, se abre una ventana emergente con la URL de acceso especificada en el archivo de configuración. Luego, se le agrega el vínculo con los parámetros de consulta de sugerencia de acceso y sugerencia de dominio.

Custom parameters

La función de parámetros personalizados permite que el RP proporcione parámetros de clave-valor adicionales al extremo 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 permisos adicionales de forma dinámica que tenga la AC, 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 la IdP que se inicia con la función Continuar con, y la IdP compartirá 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 lo traducirá automáticamente en una solicitud POST al IdP con parámetros como un solo objeto serializado 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, la AC 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 (cualquier combinación de nombre, dirección de correo electrónico y foto de perfil) que necesita que la AC comparta con él. La información solicitada se incluirá en la IU de divulgación del diálogo de FedCM. El usuario verá un mensaje que le notificará que idp.example compartirá la información solicitada con rp.example si decide acceder.

Para usar la función Campos, el RP debe agregar un array fields en la llamada navigator.credentials.get(). Los campos pueden contener cualquier permutación de name, email y picture. Esto 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 user email and profile picture
        fields: [ 'email', '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 le reveló al usuario en un parámetro disclosure_shown_for. Para garantizar la retrocompatibilidad, 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'.

  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.

Este es el caso incluso si la respuesta del extremo de cuentas no contiene un ID de cliente que coincida con el RP en approved_clients.

En este caso, el 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

Cómo mostrar un mensaje de error

A veces, es posible que la AC no pueda emitir un token por motivos legítimos, por ejemplo, cuando el cliente no tiene autorización o el servidor no está disponible temporalmente. Si el IdP muestra una respuesta de "error", el RP puede detectarla y Chrome puede notificar al usuario mostrándole la IU del navegador con la información de error que proporciona 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 ("auto-reauthn" en resumen) puede permitir que los usuarios se vuelvan a autenticar automáticamente cuando regresen después de su autenticación inicial con FedCM. "La autenticación inicial" aquí 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 del usuario explícita tiene sentido antes de que el usuario haya creado la cuenta federada para evitar el seguimiento (que es uno de los objetivos principales del 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 aplicar otra confirmación explícita del usuario para algo que ya reconoció anteriormente.

Con la reautorizació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 en la API de Credential Management, se comporta de la misma manera que para PasswordCredential y FederatedCredential, y también es compatible de forma parcial con PublicKeyCredential. La propiedad acepta los siguientes cuatro valores:

• 'optional'(predeterminado): Reautorización automática si es posible, requiere una mediación si no es así. 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 los usuarios otorguen permiso de forma explícita cada vez que necesiten autenticarse.
• 'silent': Si es posible, realiza la reautorización automática y, de lo contrario, falla de forma silenciosa sin requerir 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 en sus cuentas, por ejemplo, una página de artículos en un sitio web de noticias o una página de artículos en un sitio web de envíos.
• 'conditional': Se usa para WebAuthn y no está disponible para FedCM en este momento.

Con esta llamada, la reautorizació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 la 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.
• La reautorizació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 apenas se invoca el navigator.credentials.get() de FedCM.

Cuando mediation: optional, es posible que la reautorización automática esté indisponible por razones que solo el navegador conoce. El RP puede verificar si se realiza la reautorización automática examinando 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 mediación del usuario explícita, que es un flujo con mediation: required.

Aplica la mediación con preventSilentAccess()

La autenticación automática de los usuarios inmediatamente después de que salen de sus cuentas no sería una experiencia del usuario muy buena. Es por eso que FedCM tiene un período de inactividad de 10 minutos después de una reautorización automática para evitar este comportamiento. Esto significa que la reautorización automática se produce como máximo una vez cada 10 minutos, a menos que el usuario vuelva a acceder en ese período. El RP debe llamar a navigator.credentials.preventSilentAccess() para solicitar de forma explícita al navegador que inhabilite la reautorización automática cuando un usuario salga de la RP de forma explícita, por ejemplo, haciendo clic en un botón de salida.

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

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

Los usuarios pueden inhabilitar la autorizació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 engranaje en la esquina superior derecha > Acceder automáticamente.

Si inhabilitas el botón de activación, el usuario puede inhabilitar por completo el comportamiento de la reautorizació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 de la RP

Si un usuario accedió anteriormente a la 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 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 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 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ó a la RP con el IdP a través de FedCM.
• La API se invoca desde un iframe sin la política de permisos de FedCM.
• El configURL no es válido o le falta el extremo de desconexión.
• La verificación de la Política de Seguridad del Contenido (CSP) falla.
• 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.

Pasos siguientes