Implementa una solución de identidad con FedCM

La FedCM (Administración de credenciales federadas) es un enfoque que preserva la privacidad de los servicios de identidad federada (como "Acceder con…") que permite a los usuarios acceder a sitios sin compartir su información personal con el servicio de identidad o el sitio.

La implementación de FedCM incluye varios pasos principales para el IdP (proveedor de identidad) y el RP (entidad de confianza).

Los IdPs deben completar los siguientes pasos para implementar FedCM:

• Crea un archivo conocido.
• Crea un archivo de configuración.
• Crea los siguientes extremos:
  • Extremo de la cuenta
  • Extremo de aserción de ID
  • [opcional] Desconectar extremo
  • [Opcional] Extremo de metadatos del cliente
  • Extremo de acceso
• Informa al navegador sobre el estado de acceso del usuario.

Los RP deben completar los siguientes pasos para habilitar FedCM en su sitio:

• Asegúrate de que se permitan los extremos de FedCM en el sitio del RP.
• Usa la API de FedCM 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) a la IdP
• [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.

Nota: Recomendamos a las AC que proporcionen bibliotecas para acceder a la API de FedCM JavaScript mientras la API madura y que desalienten a los RP a alojar SDKs por su cuenta. Esto garantizará que los IdP puedan realizar cambios a medida que la API evoluciona, sin tener que pedirles a todas las partes de confianza que vuelvan a implementarla.

Implementa FedCM como un IdP

Obtén más información sobre los pasos para implementar FedCM del lado de la AC.

Crea un archivo well-known

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

El archivo conocido puede incluir las siguientes propiedades:

Propiedad	Obligatorio	Descripción
provider_urls	obligatorio	Es un array de rutas de acceso de archivos de configuración del IdP. Se ignora (pero aún es obligatorio) si se especifican accounts_endpoint y login_url.
accounts_endpoint	recomendado, requiere login_url	Es la URL del extremo de cuentas. Esto permite admitir varias configuraciones, siempre que cada archivo de configuración use la misma URL de login_url y accounts_endpoint. Nota: El parámetro es compatible a partir de Chrome 132.
login_url	recomendado, requiere accounts_endpoint	La URL de la página de acceso para que el usuario acceda al IdP. Esto permite admitir varias configuraciones, siempre que cada archivo de configuración use los mismos login_url y accounts_endpoint. Nota: El parámetro es compatible a partir de Chrome 132 y versiones posteriores.

Por ejemplo, si los extremos del IdP se entregan en https://accounts.idp.example/, deben entregar un archivo well-known en https://idp.example/.well-known/web-identity, así como un archivo de configuración del IdP. Este es un ejemplo de contenido de archivo conocido:

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

Los proveedores de identidad pueden admitir varios archivos de configuración para un proveedor de identidad. Para ello, especifica accounts_endpoint y login_url en el archivo conocido.
Esta función puede ser útil en los siguientes casos:

• Un IdP debe admitir varias configuraciones de prueba y producción diferentes.
• Un IdP debe admitir diferentes configuraciones por región (por ejemplo, eu-idp.example y us-idp.example).

Para admitir varias configuraciones (por ejemplo, para diferenciar entre el entorno de prueba y el de producción), la AC debe especificar accounts_endpoint y login_url:

  {
    // This property is required, but will be ignored when IdP supports
    // multiple configs (when `accounts_endpoint` and `login_url` are
    // specified), as long as `accounts_endpoint` and `login_url` in
    // that config file match those in the well-known file.
    "provider_urls": [ "https://idp.example/fedcm.json" ],

    // Specify accounts_endpoint and login_url properties to support
    // multiple config files.
    // Note: The accounts_endpoint and login_url must be identical
    // across all config files. Otherwise,
    // the configurations won't be supported.
    "accounts_endpoint": "https://idp.example/accounts",
    "login_url": "https://idp.example/login"
  }

Nota: Cuando se usa FedCM, los dominios de los servidores de RP de prueba o de etapa de pruebas pueden ser los subdominios del servidor de la IdP de producción. Por ejemplo, el servidor de la IdP de producción se encuentra en idp.example, y el servidor de RP y el servidor de la IdP de la etapa de pruebas se encuentran en staging.idp.example. Sin embargo, como el archivo conocido debe estar en la raíz del eTLD+1 del servidor de la IdP, debe estar en idp.example/.well-known/web-identity y es el servidor de producción. Dado que no es posible que los desarrolladores coloquen archivos en el entorno de producción mientras están en desarrollo, esto les impide probar FedCM. Si el dominio del RP y el del IdP son iguales, Chrome puede omitir la verificación del archivo conocido a partir de Chrome 122. También puedes omitir la verificación de configURL habilitando la marca chrome://flags#fedcm-without-well-known-enforcement. Esto es útil cuando tu entorno de desarrollo usa un DNS al que no se puede acceder de forma pública.

Crea un archivo de configuración y extremos del IdP

El archivo de configuración del IdP proporciona una lista de los extremos necesarios para el navegador. Las IdP deben alojar uno o varios archivos de configuración, y los extremos y las URLs necesarios. Todas las respuestas JSON se deben entregar con el tipo de contenido application/json.

La URL del archivo de configuración se determina según los valores proporcionados a la llamada navigator.credentials.get() que se ejecuta 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;

El RP pasará la URL del archivo de configuración a la llamada a la API de FedCM para permitir que el usuario acceda:

  // Executed on RP's side:
  const credential = await navigator.credentials.get({
    identity: {
      context: 'signup',
      providers: [{
        // To allow users to sign in with an IdP using FedCM, RP specifies the IdP's config file URL:
        configURL: 'https://accounts.idp.example/fedcm.json',
        clientId: '********',
  });
  const { token } = credential;

El navegador recuperará el archivo de configuración con una solicitud GET sin el encabezado Origin ni el encabezado Referer. La solicitud no tiene cookies y no sigue redireccionamientos. Esto evita que la IdP sepa 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

Precaución: Todas las solicitudes que se envían desde el navegador con FedCM incluyen un encabezado Sec-Fetch-Dest: webidentity para evitar ataques CSRF. Los siguientes extremos de la IdP deben confirmar que se incluye este encabezado:

• Extremo de cuentas
• Extremo de aserción de ID
• Cómo desconectar un extremo

El IdP debe implementar un extremo de configuración que responda con un JSON. El JSON incluye las siguientes propiedades:

Propiedad	Descripción
accounts_endpoint (obligatorio)	Es la URL del extremo de cuentas.
accounts.include (opcional)	Es una cadena de etiqueta de cuenta personalizada que determina qué cuentas se deben mostrar cuando se usa este archivo de configuración, por ejemplo: "accounts": {"include": "developer"}. Un IdP puede implementar el etiquetado de cuentas personalizado de la siguiente manera: Crea un archivo de configuración asociado con etiquetas específicas (con este parámetro accounts.include). Especifica etiquetas en el extremo de cuentas. Por ejemplo, un IdP implementa el archivo de configuración "https://idp.example/developer-config.json" con "accounts": {"include": "developer"} especificado. El IdP también marca algunas cuentas con la etiqueta "developer" con el parámetro labels en el extremo de cuentas. Cuando un RP llama a navigator.credentials.get() con el archivo de configuración "https://idp.example/developer-config.json" especificado, solo se muestran las cuentas con la etiqueta "developer".
client_metadata_endpoint (opcional)	Es la URL del extremo de metadatos del cliente.
id_assertion_endpoint (obligatorio)	Es la URL del extremo de aserción de ID.
disconnect (opcional)	Es la 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)	Es un objeto que contiene varias opciones de desarrollo de la marca.
branding.background_color (opcional)	Es una opción de desarrollo de la marca que establece el color de fondo del botón "Continuar como…". Usa la sintaxis CSS relevante, es decir, hex-color, hsl(), rgb() o named-color.
branding.color (opcional)	Es una opción de desarrollo de la marca que establece el color del texto del botón "Continuar como…". Usa la sintaxis CSS relevante, es decir, hex-color, hsl(), rgb() o named-color.
branding.icons (opcional)	Array de objetos de íconos. Estos íconos se muestran en el diálogo de acceso. El objeto de ícono tiene dos parámetros: url (obligatorio): Es la URL de la imagen del ícono. No admite imágenes SVG. size (opcional): Dimensiones del ícono, que la aplicación supone que son cuadradas y de resolución única. Este número debe ser mayor o igual que 25 px en modo pasivo y mayor o igual que 40 px en modo activo.
modes	Objeto que contiene especificaciones sobre cómo se mostrará la IU de FedCM en diferentes modos: active passive
modes.active	Objeto que contiene propiedades que permiten personalizar el comportamiento de FedCM en un modo específico. Tanto modes.active como modes.passive pueden contener el siguiente parámetro: supports_use_other_account: Es un valor booleano que especifica si el usuario puede acceder con una cuenta diferente de la que accedió actualmente (si el IdP admite varias cuentas). Nota: La función Usar otra cuenta y el modo activo son compatibles a partir de Chrome 132.
modes.passive

Este es un ejemplo de cuerpo de respuesta del IdP:

  {
    "accounts_endpoint": "/accounts.example",
    "client_metadata_endpoint": "/client_metadata.example",
    "id_assertion_endpoint": "/assertion.example",
    "disconnect_endpoint": "/disconnect.example",
    "login_url": "/login",
    // When RPs use this config file, only those accounts will be
    //returned that include `developer` label in the accounts endpoint.
    "accounts": {"include": "developer"},
    "modes": {
        "active": {
          "supports_use_other_account": true,
        }
    },
    "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 a los extremos del IdP:

Extremos de la AC

Usar otra cuenta

Los usuarios pueden cambiar a una cuenta que sea diferente de la que usaron para acceder, si la AC admite varias cuentas o reemplaza la cuenta existente.

Para permitir que el usuario elija otras cuentas, el IdP debe especificar esta función en el archivo de configuración:

  {
    "accounts_endpoint" : "/accounts.example",
    "modes": {
      "active": {
        // Allow the user to choose other account (false by default)
        "supports_use_other_account": true
      }
      // "passive" mode can be configured separately
    }
  }

Extremo de cuentas

El extremo de cuentas del IdP muestra una lista de las cuentas en las que el usuario accedió al IdP. Si el IdP admite varias cuentas, este extremo mostrará todas las cuentas a las que se accedió.

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 de manera eficaz que el IdP sepa a qué RP intenta acceder el usuario. Por ejemplo:

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

Cuando recibe la solicitud, el servidor debe hacer lo siguiente:

1. Verifica que la solicitud contenga un encabezado HTTP Sec-Fetch-Dest: webidentity.
2. Haz coincidir las cookies de sesión con los IDs de las cuentas a 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 con las siguientes propiedades:

Propiedad	Descripción
id (obligatorio)	Es el ID único del usuario.
name (obligatorio)	Nombre y apellido del usuario.
email (obligatorio)	Es la dirección de correo electrónico del usuario.
given_name (opcional)	Es el nombre de pila del usuario.
picture (opcional)	Es la URL de la imagen del avatar del usuario.
approved_clients (opcional)	Es un array de IDs de cliente de RP con los que se registró el usuario.
login_hints (opcional)	Es un array de todos los tipos de filtros posibles que admite el IdP para especificar una cuenta. El RP puede invocar 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.
labels (opcional)	Es un array de cadenas de etiquetas de cuenta personalizadas con las que está asociada una cuenta. Un IdP puede implementar el etiquetado de cuentas personalizado de la siguiente manera: Especifica las etiquetas de la cuenta en el extremo de cuentas (con este parámetro labels). Crea un archivo de configuración para cada etiqueta específica. Por ejemplo, un IdP implementa el archivo de configuración https://idp.example/developer-config.json con "accounts": {"include": "developer"} especificado. El IdP también marca algunas cuentas con la etiqueta "developer" con el parámetro labels en el extremo de cuentas. Cuando un RP llama a navigator.credentials.get() con el archivo de configuración https://idp.example/developer-config.json especificado, solo se muestran las cuentas con la etiqueta "developer". Las etiquetas de cuenta personalizadas son diferentes de las sugerencias de acceso y de dominio de manera tal que el servidor de IdP las mantiene por completo, y el RP solo especifica el archivo de configuración que se usará.

Cuerpo de la respuesta de ejemplo:

  {
    "accounts": [{
      "id": "1234",
      "given_name": "John",
      "name": "John Doe",
      "email": "[e-mail]",
      "picture": "https://idp.example/profile/123",
      // Ids of those RPs where this account can be used
      "approved_clients": ["123", "456", "789"],
      // This account has 'login_hints`. When an RP calls `navigator.credentials.get()`
      // with a `loginHint` value specified, for example, `exampleHint`, only those
      // accounts will be shown to the user whose 'login_hints' array contains the `exampleHint`.
      "login_hints": ["demo1", "exampleHint"],
      // This account is labelled. IdP can implement a specific config file for a
      // label, for example, `https://idp.example/developer-config.json`. Like that
      // RPs can filter out accounts by calling `navigator.credentials.get()` with
      // `https://idp.example/developer-config.json` config file.
      "labels": ["hr", "developer"]
    }, {
      "id": "5678",
      "given_name": "Johnny",
      "name": "Johnny",
      "email": "[e-mail]",
      "picture": "https://idp.example/profile/456",
      "approved_clients": ["abc", "def", "ghi"],
      "login_hints": ["demo2"],
      "domain_hints": ["@domain.example"]
    }]
  }

Si el usuario no accedió, responde con HTTP 401 (sin autorización).

El navegador consume la lista de cuentas que se muestra y no estará disponible 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 con una llamada 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 accede
disclosure_text_shown	Genera una cadena de "true" o "false" (en lugar de un valor booleano). El resultado es "false" en estos casos: Si el texto de divulgación no se mostró porque el ID de cliente del RP se incluyó en la lista de propiedades approved_clients de la respuesta del extremo de cuentas. Si el texto de divulgación no se mostró porque el navegador observó un momento de registro en el pasado en ausencia de approved_clients. Si el parámetro fields no incluye uno o más de los tres campos ("name", "email" y "picture"), por ejemplo, fields=[ ] o fields=['name', 'picture']. Esto es necesario para la retrocompatibilidad con implementaciones de IdP anteriores que esperan que una cadena de divulgación siempre incluya los tres campos.
is_auto_selected	Si se realiza la reautorización automática en la RP, is_auto_selected indica "true". De lo contrario, "false". Esto es útil para admitir más funciones relacionadas con la seguridad. Por ejemplo, algunos usuarios pueden preferir un nivel de seguridad más alto que requiera mediación explícita del usuario en la autenticación. Si un IdP recibe una solicitud de token sin esa mediación, podría controlar la solicitud de manera diferente. Por ejemplo, muestra un código de error para que el RP pueda volver a llamar a la API de FedCM con mediation: required.
fields (opcional)	Es un array de cadenas que especifica la información del usuario ("name", "email", "picture") que el RP necesita que la AC comparta con él. El navegador enviará fields, disclosure_text_shown y disclosure_shown_for con una lista de los campos especificados en la solicitud POST, como en el siguiente ejemplo. Nota: El parámetro Fields es compatible a partir de Chrome 132.
params (opcional)	Cualquier objeto JSON válido que permita especificar parámetros clave-valor personalizados adicionales, por ejemplo: scope: Un valor de cadena que contiene permisos adicionales que el RP debe solicitar, por ejemplo, "drive.readonly calendar.readonly" nonce: Es una cadena aleatoria que proporciona el RP para garantizar que se emita la respuesta para esta solicitud específica. Evita los ataques de repetición. Otros parámetros de par clave-valor personalizados Cuando el navegador envíe una solicitud POST, el valor params se serializará a JSON y, luego, se codificará en porcentaje. Nota: La API de Parameters es compatible con Chrome 132 y versiones posteriores.

Ejemplo de encabezado HTTP:

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

  // disclosure_text_shown is set to 'false', as the 'name' field value is missing in 'fields' array
  // params value is serialized to JSON and then percent-encoded.
  account_id=123&client_id=client1234&disclosure_text_shown=false&is_auto_selected=true&params=%22%7B%5C%22nonce%5C%22%3A%5C%22nonce-value%5C%22%7D%22.%0D%0A4&disclosure_text_shown=true&fields=email,picture&disclosure_shown_for=email,picture

Cuando recibe la solicitud, el servidor debe hacer lo siguiente:

1. Responde la solicitud con CORS (uso compartido de recursos entre dominios).
2. Verifica que la solicitud contenga un encabezado HTTP Sec-Fetch-Dest: webidentity.
3. Haz coincidir el encabezado Origin con el origen de RP determinado por client_id. Rechaza la solicitud si no coincide.
4. Haz coincidir account_id con el ID de la cuenta a la que ya se accedió. Rechaza la solicitud si no coinciden.
5. Responde con un token. Si se rechaza la solicitud, responde con una respuesta de error.

Advertencia: La solicitud de CORS debe tener credenciales, lo que significa que el encabezado de respuesta Access-Control-Allow-Origin debe indicar un origen explícito en lugar de un comodín con "*".

HTTP/1.1 200 OK
Access-Control-Allow-Origin: https://rp.example
Access-Control-Allow-Credentials: true
  

El IdP puede decidir cómo emitir el token. En general, se firma con información como el ID de la cuenta, el ID del cliente, el origen del emisor y el nonce, de modo que el RP pueda verificar que el token es original.

Advertencia: Dado que la verificación de dominio en OAuth o OpenID Connect se basa en un redireccionamiento del navegador, es fundamental en FedCM que el servidor de la AC verifique que un valor de encabezado Origin coincida con el origen registrado del RP.

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

Propiedad	Descripción
token	Un token es una cadena que contiene declaraciones sobre la autenticación.
continue_on	Es la URL de redireccionamiento que habilita un flujo de acceso de varios pasos.

El navegador pasa el token que se muestra a la RP para que esta pueda validar la autenticación.

  {
    // IdP can respond with a token to authenticate the user
    "token": "***********"
  }

Continuar en la función

El IdP puede proporcionar una URL de redireccionamiento en la respuesta del extremo de aserción de ID para habilitar un flujo de acceso de varios pasos. Esto es útil cuando la AC necesita solicitar información o permisos adicionales, por ejemplo:

• Permiso para acceder a los recursos del servidor del usuario
• Verificación de que la información de contacto esté actualizada
• Controles parentales.

El extremo de la aserción de ID puede mostrar una propiedad continue_on que incluye una ruta de acceso absoluta o relativa al extremo de la aserción de ID.

  {
    // In the id_assertion_endpoint, instead of returning a typical
    // "token" response, the IdP decides that it needs the user to
    // continue on a popup window:
    "continue_on": "https://idp.example/continue_on_url"
  }

Si la respuesta contiene el parámetro continue_on, se abrirá una nueva ventana emergente y se navegará al usuario a la ruta de acceso especificada. Después de que el usuario interactúe con la página continue_on, la AC debe llamar a IdentityProvider.resolve() con el token pasado como argumento para que se pueda resolver la promesa de la llamada navigator.credentials.get() original:

  document.getElementById('example-button').addEventListener('click', async () => {
    let accessToken = await fetch('/generate_access_token.cgi');
    // Closes the window and resolves the promise (that is still hanging
    // in the relying party's renderer) with the value that is passed.
    IdentityProvider.resolve(accessToken);
  });

Luego, el navegador cerrará automáticamente la ventana emergente y devolverá el token al llamador de la API. Una llamada IdentityProvider.resolve() única es la única forma en que la ventana superior (RP) y la ventana emergente (IdP) pueden comunicarse.
Si el usuario rechaza la solicitud, la AC puede cerrar la ventana llamando a IdentityProvider.close().

  IdentityProvider.close();

La API de Continuation requiere una interacción explícita del usuario (clics) para funcionar. A continuación, se muestra cómo funciona la API de Continuation con diferentes modos de mediación:

• En el modo pasivo:
  • mediation: 'optional' (predeterminado): La API de Continuation solo funcionará con un gesto del usuario, como hacer clic en un botón de la página o en la IU de FedCM. Cuando se activa la reautorización automática sin un gesto del usuario, no se abre una ventana emergente y se rechaza la promesa.
  • mediation: 'required': Siempre le pide al usuario que interactúe, por lo que la API de Continuation siempre funciona.
• En el modo activo:
  • La activación del usuario siempre es obligatoria. La API de Continuation es compatible.

Si, por algún motivo, el usuario cambió su cuenta en la ventana emergente (por ejemplo, la AC ofrece una función "Usar otra cuenta" o en casos de delegación), la llamada de resolución toma un segundo argumento opcional que permite algo como lo siguiente:

  IdentityProvider.resolve(token, {accountId: '1234');

Cómo mostrar 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_error y temporarily_unavailable) o usar cualquier cadena arbitraria. Si es el último caso, Chrome renderiza la IU de error con un mensaje de error genérico y pasa el código a la RP.
• url: Identifica una página web legible por humanos con información sobre el error para proporcionar información adicional a los usuarios. Este campo es útil para los usuarios porque los navegadores no pueden proporcionar mensajes de error enriquecidos en una IU integrada. Por ejemplo, vínculos para los próximos pasos o información de contacto del servicio de atención al cliente. Si un usuario quiere 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 el configURL de la IdP.

  // id_assertion_endpoint response
  {
    "error" : {
      "code": "access_denied",
      "url" : "https://idp.example/error?type=access_denied"
    }
  }

Nota: Implementar la respuesta "error" es opcional. Si un IdP no notifica al navegador sobre el tipo de error cuando se produce, Chrome mostrará una IU de error con un mensaje genérico. Si no se proporciona el campo url, Chrome no incluye el botón Más detalles.

Etiquetas de cuenta personalizadas

Con las etiquetas de cuenta personalizadas, el IdP puede anotar cuentas de usuario con etiquetas, y el RP puede elegir recuperar solo cuentas con etiquetas específicas especificando el configURL para esa etiqueta específica. Esto puede ser útil cuando un RP necesita filtrar cuentas por criterios específicos, por ejemplo, para mostrar solo cuentas específicas del rol, como "developer" o "hr".

Se puede aplicar un filtrado similar con las funciones Domain Hint y Login Hint. Para ello, especifícalas en la llamada a navigator.credentials.get(). Sin embargo, las etiquetas de cuenta personalizadas pueden filtrar usuarios especificando el archivo de configuración, lo que es especialmente útil cuando se usan varios configURLs. Las etiquetas de cuenta personalizadas también son diferentes en cuanto a que se proporcionan desde el servidor de la IdP, en lugar de desde el RP, como las sugerencias de acceso o dominio.

Considera un IdP que desea diferenciar entre cuentas "developer" y "hr". Para lograrlo, la IdP debe admitir dos configURLs para "developer" y "hr", respectivamente:

• El archivo de configuración para desarrolladores https://idp.example/developer/fedcm.json tiene una etiqueta "developer", y el archivo de configuración empresarial https://idp.example/hr/fedcm.json tiene una etiqueta "hr" de la siguiente manera:

  // The developer config file at `https://idp.example/developer/fedcm.json`
  {
    "accounts_endpoint": "https://idp.example/accounts",
    "client_metadata_endpoint": "/client_metadata",
    "login_url": "https://idp.example/login",
    "id_assertion_endpoint": "/assertion",
    "accounts": {
      // Account label
      "include": "developer"
    }
  }

  // The hr config file at `https://idp.example/hr/fedcm.json`
  {
    "accounts_endpoint": "https://idp.example/accounts",
    "client_metadata_endpoint": "/client_metadata",
    "login_url": "https://idp.example/login",
    "id_assertion_endpoint": "/assertion",
    "accounts": {
      // Account label
      "include": "hr"
    }
  }

• Con esa configuración, el archivo conocido debe incluir accounts_endpoint y login_url para permitir múltiples configURLs:

  {
    "provider_urls": [ "https://idp.example/fedcm.json" ],
    "accounts_endpoint": "https://idp.example/accounts",
    "login_url": "https://idp.example/login"
  }

• El extremo de cuentas común del IdP (en este ejemplo, https://idp.example/accounts) muestra una lista de cuentas que incluye una propiedad labels con etiquetas asignadas en un array para cada cuenta:

  {
  "accounts": [{
    "id": "123",
    "given_name": "John",
    "name": "John Doe",
    "email": "[e-mail]",
    "picture": "https://idp.example/profile/123",
    "labels": ["developer"]
    }], [{
    "id": "4567",
    "given_name": "Jane",
    "name": "Jane Doe",
    "email": "[e-mail]",
    "picture": "https://idp.example/profile/4567",
    "labels": ["hr"]
    }]
  }

Cuando un RP quiere permitir que los usuarios de "hr" accedan, puede especificar el https://idp.example/hr/fedcm.json de configURL en la llamada a navigator.credentials.get():

  let { token } = await navigator.credentials.get({
    identity: {
      providers: [{
        clientId: '1234',
        nonce: '234234',
        configURL: 'https://idp.example/hr/fedcm.json',
      },
    }
  });

Como resultado, solo el ID de la cuenta de 4567 está disponible para que el usuario acceda. El navegador oculta de forma silenciosa el ID de la cuenta de 123 para que no se le proporcione al usuario una cuenta que no sea compatible con el IdP en este sitio.

Nota:

• Las etiquetas son cadenas. Si el array labels o el campo include contienen algo que no es una cadena, se ignora.
• Si no se especifican etiquetas en el configURL, se mostrarán todas las cuentas en el selector de cuentas de FedCM.
• Si no se especifican etiquetas para una cuenta, solo se mostrará en el selector de cuentas si configURL tampoco especifica una etiqueta.
• Si no hay ninguna cuenta que coincida con la etiqueta solicitada en el modo pasivo (similar a la función de sugerencia de dominio), el diálogo de FedCM muestra un mensaje de acceso, que le permite al usuario acceder a una cuenta de IdP. En el modo activo, la ventana emergente de acceso se abre directamente.

Desconecta el 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.example 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 recibe la solicitud, el servidor debe hacer lo siguiente:

1. Responde la solicitud con CORS (uso compartido de recursos entre dominios).
2. Verifica que la solicitud contenga un encabezado HTTP Sec-Fetch-Dest: webidentity.
3. Haz que el encabezado Origin coincida con el origen de RP determinado por client_id. Rechaza la solicitud si no coincide.
4. Haz coincidir account_hint con los IDs de las cuentas a las que ya se accedió.
5. Desconecta la cuenta de usuario del RP.
6. Responde al navegador con la información de la cuenta de usuario identificada en formato JSON.

Advertencia: La solicitud de CORS debe tener credenciales, lo que significa que el encabezado de respuesta Access-Control-Allow-Origin debe indicar un origen explícito en lugar de un comodín con "*".

HTTP/1.1 200 OK
Access-Control-Allow-Origin: https://rp.example
Access-Control-Allow-Credentials: true
  

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, "*".

Extremo de metadatos del cliente

El extremo de metadatos del cliente de la AC muestra los metadatos de la parte de confianza, como la política de privacidad, las condiciones del servicio y los íconos de logotipos de la RP. Los RP deben proporcionar vínculos a su política de privacidad y a sus condiciones del servicio a la AC con anticipación. Estos vínculos se muestran en el diálogo de acceso cuando el usuario aún no se registró en la RP con el IdP.

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

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

Cuando recibe la solicitud, el servidor debe hacer lo siguiente:

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

Las propiedades del extremo de metadatos del cliente incluyen las siguientes:

Propiedad	Descripción
privacy_policy_url (opcional)	URL de la política de privacidad del RP.
terms_of_service_url (opcional)	URL de las Condiciones del Servicio del RP
icons (opcional)	Array de objetos, como [{ "url": "https://rp.example/rp-icon.ico", "size": 40}]

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",
    "icons": [{
          "url": "https://rp.example/rp-icon.ico",
          "size": 40
      }]
  }

El navegador consume los metadatos del cliente que se devuelven y no estarán disponibles para la RP.

URL de acceso

Este extremo se usa para permitir que el usuario acceda a la IdP.

Con la API de Login Status, la AC debe informar el estado de acceso del usuario al navegador. Sin embargo, el estado podría estar desincronizado, por ejemplo, cuando vence la sesión. En ese caso, el navegador puede permitir que el usuario acceda de forma dinámica 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.

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

Un diálogo de FedCM que 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 de la AC.

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

Nota: El sitio web no puede controlar el tamaño del diálogo antes de que se abra. De forma predeterminada, el tamaño se establece en 500 px de ancho y 600 px de alto.

El diálogo es una ventana de navegador normal que tiene 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 entre dominios a la página de la RP. Después de que el usuario acceda, el IdP debe hacer lo siguiente:

• Envía el encabezado Set-Login: logged-in o llama a la API de navigator.login.setStatus("logged-in") para informarle al navegador que el usuario accedió.
• Llama a IdentityProvider.close() para cerrar el diálogo.

Nota: Lee Inform the browser about the user's login status para obtener más información sobre el encabezado HTTP Set-Login y la función IdentityProvider.close().

Un usuario accede a un RP después de acceder al IdP con FedCM.

Informa al navegador sobre el estado de acceso del usuario

La API de Login Status es un mecanismo en el que un sitio web, en especial una IdP, informa al navegador el estado de acceso del usuario en la IdP. Con esta API, el navegador puede reducir las solicitudes innecesarias al IdP y mitigar posibles ataques de sincronización.

Los IdPs pueden indicar el estado de acceso del usuario al navegador enviando un encabezado HTTP o llamando a una API de JavaScript cuando el usuario accedió al IdP o cuando salió 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 los siguientes valores posibles:

• logged-in
• logged-out
• unknown (predeterminada)

Estado de acceso	Descripción
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 cuentas de la AC y muestra las cuentas disponibles al usuario en el diálogo de FedCM.
logged-out	Cuando el estado de acceso del usuario es logged-out, la llamada a FedCM falla de forma silenciosa sin realizar una solicitud al extremo de cuentas de la AC.
unknown (predeterminada)	El estado unknown se establece antes de que el IdP envíe un indicador con la API de Login Status. Cuando el estado es unknown, el navegador realiza una solicitud al extremo de cuentas del IdP y actualiza el estado según la respuesta del extremo de cuentas.

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 de la IdP:

  Set-Login: logged-in

Como alternativa, llama al método JavaScript navigator.login.setStatus('logged-in') desde el origen de la AC en una navegación de nivel superior:

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

El estado de acceso del usuario se establecerá como logged-in.

Para indicar que el usuario salió de todas sus cuentas, envía un 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 de la IdP en una navegación de nivel superior:

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

El estado de acceso del usuario se establecerá como logged-out.

El estado unknown se establece antes de que el IdP envíe un indicador con la API de Login Status. El navegador envía una solicitud al extremo de cuentas del IdP y actualiza el estado según la respuesta del extremo de cuentas:

• Si el extremo muestra 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 falla la llamada a FedCM.

Nota: El encabezado de estado de acceso también se puede enviar desde subrecursos del mismo sitio, a partir de Chrome 122. Esto es útil, por ejemplo, cuando un sitio web permite que los usuarios ingresen su nombre de usuario y contraseña en idp.example, pero las credenciales se publican en login.idp.example con fetch(). La respuesta de recuperación de login.idp.example aún puede establecer el estado de acceso de idp.example enviando el encabezado HTTP Set-Login: logged-in.

Permite que el usuario acceda a través de un flujo de acceso dinámico

Aunque el IdP sigue informando el estado de acceso del usuario al navegador, podría estar desincronizado, por ejemplo, cuando vence la sesión. El navegador intenta enviar una solicitud con credenciales al extremo de cuentas cuando el estado de acceso es logged-in, pero el servidor no muestra ninguna cuenta porque la sesión ya no está disponible. En ese caso, el navegador puede permitir que el usuario acceda de forma dinámica al IdP a través de una ventana emergente.

Esta experiencia de acceso dinámico está diseñada para cuando una sesión del IdP venció sin un cierre de sesión explícito, lo que hace que el estado de acceso del navegador contradiga el estado real del usuario. Esto no se activa para los usuarios que aún no accedieron al proveedor de identidad. Este flujo está diseñado para abarcar los casos en los que el estado de acceso del IdP del usuario en el navegador es logged-in, pero el extremo de cuentas del IdP no muestra ninguna cuenta. Si se supone que se llama a la API de Login Status de inmediato, cuando se invoca a FedCM, puede ocurrir cualquiera de las siguientes situaciones:

• Si el estado de acceso del usuario se establece como desconocido, el estado se actualiza (logged-in o logged-out) según la respuesta del IdP desde el extremo de cuentas. No se activará un flujo de acceso dinámico.
• Si un usuario accedió al IdP en el navegador y, luego, salió de él de forma explícita, no se activará el flujo de acceso dinámico.
• Si un usuario accedió al IdP en el navegador, pero la sesión vence sin una actualización explícita a logged-out, se activa el flujo de acceso dinámico.

La API de Login Status no permite que el RP muestre un diálogo "Acceder al IdP" a los usuarios que no hayan accedido al IdP. Esta es una función independiente que se puede agregar en el futuro.

Implementa FedCM como RP

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 a la 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
  }

Precaución: Si el RP implementa una Política de Seguridad del Contenido (CSP) en la página a la que se llama a FedCM y aplica la directiva connect-src, el RP debe permitir explícitamente los extremos proporcionados en el archivo de configuración.

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

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

Por ejemplo, si configuras context en use, se mostrará el siguiente mensaje:

Diálogo de FedCM que muestra un mensaje de contexto personalizado.

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:

Propiedad	Descripción
configURL (obligatorio)	Es una ruta de acceso completa del archivo de configuración del IdP.
clientId (obligatorio)	El identificador de cliente del RP, emitido por el IdP.
nonce (opcional)	Es una cadena aleatoria para garantizar que se emita la respuesta para esta solicitud específica. Evita los ataques de repetición.
loginHint (opcional)	Cuando especificas uno de los valores login_hints que proporcionan los extremos de las cuentas, el diálogo de FedCM muestra de forma selectiva la cuenta especificada.
domainHint (opcional)	Cuando especificas uno de los valores domain_hints que proporcionan los extremos de las cuentas, el diálogo de FedCM muestra de forma selectiva la cuenta especificada.
mode (opcional)	Es una cadena que especifica el modo de la IU de FedCM. Puede ser uno de estos valores: "active": La solicitud de FedCM debe iniciarse mediante la interacción del usuario (por ejemplo, hacer clic en un botón). "passive": Se iniciará la solicitud de FedCM sin interacción directa del usuario. Consulta la página de descripción general para obtener más información sobre la diferencia entre los modos activo y pasivo. Nota: El parámetro mode es compatible a partir de Chrome 132.
fields (opcional)	Es un array de cadenas que especifica la información del usuario ("name", "email", "picture") que el RP necesita que la AC comparta con él. Nota: Chrome 132 y versiones posteriores admiten la API de Field.
parameters (opcional)	Objeto personalizado que permite especificar parámetros de par clave-valor adicionales: scope: Un valor de cadena que contiene permisos adicionales que el RP debe solicitar, por ejemplo, "drive.readonly calendar.readonly" nonce: Es una cadena aleatoria para garantizar que se emita la respuesta para esta solicitud específica. Evita los ataques de repetición. Otros parámetros de par clave-valor personalizados Nota: parameters es compatible a partir de Chrome 132.

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.

Nota: Pasar un ícono de logotipo de RP al navegador es opcional. Si no está presente el ícono de RP, Chrome solo mostrará el logotipo del IdP en la IU de divulgación en la que se le solicita al usuario permiso de uso compartido.

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 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'
      }]
    }
  });

Nota: Cuando se usa domainHint: 'any', Chrome filtra las cuentas que no tienen ningún dominio (es decir, no se pasa domain_hints o está vacío). Por ejemplo, esto permite casos de uso en los que el RP solo permite cuentas administradas en su proceso de registro.

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 solicitada por 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.

Ejemplo de un mensaje de acceso cuando no hay cuentas que coincidan con el domainHint.

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.

Nota: De forma predeterminada, el mensaje de la IU de divulgación incluye todos los campos implementados actualmente: "Para continuar, idp.example compartirá tu nombre, dirección de correo electrónico y foto de perfil con este sitio". Los usuarios recurrentes no verán la IU de divulgación.

Mensaje de divulgación en modo activo: el RP solicita al IdP que comparta solo el correo electrónico y la foto de perfil del usuario.

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.

El mensaje de divulgación no se muestra en el modo pasivo. En el flujo de botones, se omite por completo 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.

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 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.

Un usuario se vuelve a autenticar automáticamente a través de FedCM.

Aplica la mediación con preventSilentAccess()

La autenticación automática de los usuarios inmediatamente después de que salgan 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 plazo. 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.

Nota: Los usuarios también pueden inhabilitar la FedCM por dominio.

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.

Nota: Si no se recibe una respuesta válida del extremo de desconexión o si el ID de cuenta recibido no coincide con ninguna cuenta de la lista de cuentas conectadas, el usuario-agente quitará todas las cuentas que coincidan con el RP y la IdP de la lista de cuentas conectadas.