Implementar uma solução de identidade com o FedCM

O FedCM (gerenciamento de credenciais federadas) é uma abordagem que preserva a privacidade nos serviços de identidade federada (como "Fazer login com..."), em que os usuários podem fazer login nos sites sem compartilhar informações pessoais com o serviço de identidade ou com o site.

A implementação do FedCM inclui várias etapas principais para o IdP (provedor de identidade) e a RP (parte confiável).

Os IdPs precisam concluir as etapas a seguir para implementar o FedCM:

• Crie um arquivo conhecido.
• Crie um arquivo de configuração.
• Crie os seguintes endpoints:
  • Endpoint da conta
  • Endpoint de declaração de ID
  • [Opcional] Desconectar endpoint
  • [Opcional] Endpoint de metadados do cliente
  • Endpoint de login
• Informar o navegador sobre o status de login do usuário.

Os RPs precisam concluir as etapas a seguir para ativar o FedCM no site:

• Confira se os endpoints do FedCM são permitidos no site do RP.
• Use a API JavaScript FedCM para iniciar a autenticação do usuário.
• Disponibilizar os metadados (como a Política de Privacidade e os URLs dos Termos de Serviço) para o IdP
• [Opcional] Personalize a experiência do usuário escolhendo um modo de UX, fornecendo login ou dicas de domínio, transmitindo parâmetros personalizados, solicitando informações específicas do usuário, fornecendo uma mensagem de erro personalizada ou escolhendo como re-autenticar os usuários.

Observação: recomendamos que os IdPs forneçam bibliotecas para acessar a API FedCM JavaScript enquanto ela está sendo aprimorada e desencorajar os RPs a hospedar SDKs por conta própria. Isso garante que os IdPs possam fazer mudanças à medida que a API evolui, sem precisar pedir que todas as partes confiáveis sejam reimplantadas.

Implementar a FedCM como um IdP

Saiba mais sobre as etapas para implementar o FedCM no lado do IdP.

Criar um arquivo conhecido

Para evitar que os rastreadores abusem da API, um arquivo conhecido precisa ser enviado do /.well-known/web-identity do eTLD+1 do IdP.

O arquivo conhecido pode incluir as seguintes propriedades:

Propriedade	Obrigatório	Descrição
provider_urls	obrigatório	Matriz de caminhos de arquivos de configuração do IdP. Será ignorado (mas ainda obrigatório) se accounts_endpoint e login_url forem especificados.
accounts_endpoint	recomendado, requer login_url	URL do endpoint de contas. Isso permite o suporte a várias configurações, desde que cada arquivo de configuração use o mesmo URL login_url e accounts_endpoint. Observação: o parâmetro tem suporte no Chrome 132.
login_url	recomendado, requer accounts_endpoint	O URL da página de login para o usuário fazer login no IdP. Isso permite o suporte a várias configurações, desde que cada arquivo de configuração use o mesmo login_url e accounts_endpoint. Observação: o parâmetro é aceito a partir do Chrome 132 e versões mais recentes.

Por exemplo, se os endpoints do IdP forem veiculados em https://accounts.idp.example/, eles precisarão veicular um arquivo conhecido em https://idp.example/.well-known/web-identity, além de um arquivo de configuração do IdP. Confira um exemplo de conteúdo de arquivo conhecido:

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

Os IdPs podem acomodar vários arquivos de configuração para um IdP, especificando accounts_endpoint e login_url no arquivo conhecido.
Esse recurso pode ser útil nos seguintes casos:

• Um IdP precisa oferecer suporte a várias configurações diferentes de teste e produção.
• Um IdP precisa oferecer suporte a diferentes configurações por região (por exemplo, eu-idp.example e us-idp.example).

Para oferecer suporte a várias configurações (por exemplo, para diferenciar o ambiente de teste do ambiente de produção), o IdP precisa especificar accounts_endpoint e 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"
  }

Dica:ao usar o FedCM, os domínios de RP de teste ou de preparo podem ser os subdomínios do servidor de IdP de produção. Por exemplo, o servidor do IdP de produção está em idp.example, e o servidor de RP e o servidor do IdP de preparação estão em staging.idp.example. No entanto, como o arquivo conhecido precisa estar na raiz do eTLD+1 do servidor do IdP, ele precisa estar em idp.example/.well-known/web-identity e ser o servidor de produção. Como não é possível que os desenvolvedores coloquem arquivos no ambiente de produção durante o desenvolvimento, isso impede que eles testem o FedCM. Se o domínio do RP e do IdP forem iguais, o Chrome poderá pular a verificação do arquivo conhecido a partir do Chrome 122. Também é possível ignorar a verificação configURL ativando a flag chrome://flags#fedcm-without-well-known-enforcement. Isso é útil quando o ambiente de desenvolvimento usa um DNS que não é acessível publicamente.

Criar um arquivo de configuração do IdP e endpoints

O arquivo de configuração do IdP fornece uma lista de endpoints necessários para o navegador. Os IdPs precisam hospedar um ou vários arquivos de configuração e os endpoints e URLs necessários. Todas as respostas JSON precisam ser veiculadas com o tipo de conteúdo application/json.

O URL do arquivo de configuração é determinado pelos valores fornecidos para a chamada navigator.credentials.get() executada em um RP.

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

O RP vai transmitir o URL do arquivo de configuração para a chamada da API FedCM para permitir que o usuário faça login:

  // 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;

O navegador vai buscar o arquivo de configuração com uma solicitação GET sem o cabeçalho Origin ou Referer. A solicitação não tem cookies e não segue redirecionamentos. Isso impede que o IdP saiba quem fez a solicitação e qual RP está tentando se conectar. Exemplo:

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

Atenção:todas as solicitações enviadas do navegador usando o FedCM incluem um cabeçalho Sec-Fetch-Dest: webidentity para evitar ataques CSRF. Os seguintes endpoints do IdP precisam confirmar que esse cabeçalho está incluído:

• Endpoint de contas
• Endpoint de declaração de ID
• Desconectar endpoint

O IdP precisa implementar um endpoint de configuração que responda com um JSON. O JSON inclui as seguintes propriedades:

Propriedade	Descrição
accounts_endpoint (obrigatório)	URL do endpoint de contas.
accounts.include (opcional)	String de rótulo de conta personalizada, que determina quais contas devem ser retornadas quando esse arquivo de configuração é usado. Por exemplo: "accounts": {"include": "developer"}. Um IdP pode implementar o rotulagem de contas personalizada da seguinte maneira: Crie um arquivo de configuração associado a rótulos específicos (usando este parâmetro accounts.include). Especifique rótulos no endpoint de contas. Por exemplo, um IdP implementa o arquivo de configuração "https://idp.example/developer-config.json" com "accounts": {"include": "developer"} especificado. O IdP também marca algumas contas com o rótulo "developer" usando o parâmetro labels no endpoint de contas. Quando um RP chama navigator.credentials.get() com o arquivo de configuração "https://idp.example/developer-config.json" especificado, apenas as contas com o rótulo "developer" são retornadas.
client_metadata_endpoint (opcional)	URL do endpoint de metadados do cliente.
id_assertion_endpoint (obrigatório)	URL do endpoint de declaração de ID.
disconnect (opcional)	URL do endpoint de desconexão.
login_url (obrigatório)	O URL da página de login para o usuário fazer login no IdP.
branding (opcional)	Objeto que contém várias opções de branding.
branding.background_color (opcional)	Opção de marca que define a cor de plano de fundo do botão "Continuar como...". Use a sintaxe CSS relevante, ou seja, hex-color, hsl(), rgb() ou named-color.
branding.color (opcional)	Opção de marca que define a cor do texto do botão "Continuar como...". Use a sintaxe CSS relevante, ou seja, hex-color, hsl(), rgb() ou named-color.
branding.icons (opcional)	Matriz de objetos de ícone. Esses ícones são exibidos na caixa de diálogo de login. O objeto de ícone tem dois parâmetros: url (obrigatório): URL da imagem do ícone. Ele não oferece suporte a imagens SVG. size (opcional): dimensões do ícone, presumidas pelo aplicativo como quadradas e de resolução única. Esse número precisa ser maior ou igual a 25 px no modo passivo e maior ou igual a 40 px no modo ativo.
modes	Objeto que contém especificações sobre como a interface da FedCM será exibida em diferentes modos: active passive
modes.active	Objeto que contém propriedades que permitem a personalização do comportamento do FedCM em um modo específico. modes.active e modes.passive podem conter o seguinte parâmetro: supports_use_other_account: booleano que especifica se o usuário pode fazer login com uma conta diferente da que está usando no momento (se o IdP oferece suporte a várias contas). Observação: o recurso "Usar outra conta" e o modo ativo são compatíveis com o Chrome 132.
modes.passive

Confira um exemplo de corpo de resposta do 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
      }]
    }
  }

Depois que o navegador recupera o arquivo de configuração, ele envia solicitações subsequentes para os endpoints do IdP:

Endpoints do IdP

Usar outra conta

Os usuários podem mudar para uma conta diferente da que estão usando no momento, se o IdP oferecer suporte a várias contas ou substituir a conta atual.

Para permitir que o usuário escolha outras contas, o IdP precisa especificar esse recurso no arquivo de configuração:

  {
    "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
    }
  }

Endpoint de contas

O endpoint de contas do IdP retorna uma lista de contas em que o usuário fez login no IdP. Se o IdP oferecer suporte a várias contas, esse endpoint vai retornar todas as contas que fizeram login.

O navegador envia uma solicitação GET com cookies com SameSite=None, mas sem um parâmetro client_id, o cabeçalho Origin ou o cabeçalho Referer. Isso impede que o IdP saiba em qual RP o usuário está tentando fazer login. Exemplo:

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

Ao receber a solicitação, o servidor precisa:

1. Verifique se a solicitação contém um cabeçalho HTTP Sec-Fetch-Dest: webidentity.
2. Correlacione os cookies de sessão aos IDs das contas já conectadas.
3. Responda com a lista de contas.

O navegador espera uma resposta JSON que inclua uma propriedade accounts com uma matriz de informações da conta com as seguintes propriedades:

Propriedade	Descrição
id (obrigatório)	ID exclusivo do usuário.
name (obrigatório)	Nome e sobrenome do usuário.
email (obrigatório)	Endereço de e-mail do usuário.
given_name (opcional)	Nome do usuário.
picture (opcional)	URL da imagem do avatar do usuário.
approved_clients (opcional)	Uma matriz de IDs de cliente de RP com que o usuário se registrou.
login_hints (opcional)	Uma matriz de todos os tipos de filtro possíveis com suporte do IdP para especificar uma conta. O RP pode invocar navigator.credentials.get() com a propriedade loginHint para mostrar seletivamente a conta especificada.
domain_hints (opcional)	Uma matriz de todos os domínios aos quais a conta está associada. O RP pode chamar navigator.credentials.get() com uma propriedade domainHint para filtrar as contas.
labels (opcional)	Matriz de rótulos de conta personalizados de string associados a uma conta. Um IdP pode implementar o rotulagem de contas personalizada da seguinte maneira: Especifique rótulos de contas no endpoint de contas (usando este parâmetro labels). Crie um arquivo de configuração para cada rótulo específico. Por exemplo, um IdP implementa o arquivo de configuração https://idp.example/developer-config.json com "accounts": {"include": "developer"} especificado. O IdP também marca algumas contas com o rótulo "developer" usando o parâmetro labels no endpoint de contas. Quando um RP chama navigator.credentials.get() com o arquivo de configuração https://idp.example/developer-config.json especificado, apenas as contas com o rótulo "developer" são retornadas. Os rótulos de conta personalizados são diferentes das dicas de login e de domínio, de modo que são totalmente mantidos pelo servidor do provedor de identidade, e o RP especifica apenas o arquivo de configuração a ser usado.

Exemplo de corpo de resposta:

  {
    "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"]
    }]
  }

Se o usuário não estiver conectado, responda com HTTP 401 (Não autorizado).

A lista de contas retornada é consumida pelo navegador e não estará disponível para o RP.

Endpoint de declaração de ID

O endpoint de declaração de ID do IdP retorna uma declaração para o usuário conectado. Quando o usuário faz login em um site de RP usando a chamada navigator.credentials.get(), o navegador envia uma solicitação POST com cookies com SameSite=None e um tipo de conteúdo application/x-www-form-urlencoded para esse endpoint com as seguintes informações:

Propriedade	Descrição
client_id (obrigatório)	O identificador de cliente do RP.
account_id (obrigatório)	O ID exclusivo do usuário que fez login.
disclosure_text_shown	Resulta em uma string de "true" ou "false" (em vez de um booleano). O resultado é "false" nestes casos: Se o texto de divulgação não foi mostrado porque o ID do cliente do RP foi incluído na lista de propriedades approved_clients da resposta do endpoint de contas. Se o texto de divulgação não foi mostrado porque o navegador observou um momento de inscrição no passado na ausência de approved_clients. Se o parâmetro fields não incluir um ou mais dos três campos ("name", "email" e "picture"), por exemplo, fields=[ ] ou fields=['name', 'picture']. Isso é necessário para compatibilidade com implementações de IdP mais antigas que esperam que uma string de declaração sempre inclua os três campos.
is_auto_selected	Se a reautorização automática for realizada no RP, is_auto_selected vai indicar "true". Caso contrário, "false". Isso é útil para oferecer suporte a mais recursos relacionados à segurança. Por exemplo, alguns usuários podem preferir um nível de segurança mais alto, que exige a mediação explícita do usuário na autenticação. Se um IdP receber uma solicitação de token sem essa mediação, ele poderá processar a solicitação de maneira diferente. Por exemplo, retorne um código de erro para que o RP possa chamar a API FedCM novamente com mediation: required.
fields (opcional)	Matriz de strings que especifica as informações do usuário ("name", "email", "picture") que o RP precisa que o IdP compartilhe. O navegador vai enviar fields, disclosure_text_shown e disclosure_shown_for listando os campos especificados na solicitação POST, como no exemplo abaixo. Observação: o parâmetro "Fields" é aceito a partir do Chrome 132.
params (opcional)	Qualquer objeto JSON válido que permita especificar outros parâmetros de chave-valor personalizados, por exemplo: scope: um valor de string com outras permissões que o RP precisa solicitar, por exemplo, "drive.readonly calendar.readonly" nonce: uma string aleatória fornecida pelo RP para garantir que a resposta seja emitida para essa solicitação específica. Evita ataques de repetição. Outros parâmetros de chave-valor personalizados. Quando o navegador envia uma solicitação POST, o valor params é serializado em JSON e, em seguida, codificado em percentual. Observação: a API Parameters é compatível com o Chrome 132 e versões mais recentes.

Exemplo de cabeçalho 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

Ao receber a solicitação, o servidor precisa:

1. Responda à solicitação com o CORS (Compartilhamento de recursos entre origens).
2. Verifique se a solicitação contém um cabeçalho HTTP Sec-Fetch-Dest: webidentity.
3. Correlacione o cabeçalho Origin com a origem do RP determinada pelo client_id. Rejeite se não forem correspondentes.
4. Compare account_id com o ID da conta já conectada. Recuse se elas não corresponderem.
5. Responda com um token. Se a solicitação for rejeitada, responda com uma resposta de erro.

Aviso:a solicitação CORS precisa ter credenciais, o que significa que o cabeçalho de resposta Access-Control-Allow-Origin precisa indicar uma origem explícita em vez de um caractere curinga usando "*".

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

O IdP pode decidir como emitir o token. Em geral, ele é assinado com informações como o ID da conta, o ID do cliente, a origem do emissor e o valor de uso único, para que o RP possa verificar se o token é genuíno.

Aviso: como a verificação de domínio no OAuth ou no OpenID Connect depende de um redirecionamento do navegador, é fundamental que o servidor do provedor de identidade verifique se um valor de cabeçalho Origin corresponde à origem registrada do provedor de registro.

O navegador espera uma resposta JSON que inclua a seguinte propriedade:

Propriedade	Descrição
token	Um token é uma string que contém declarações sobre a autenticação.
continue_on	URL de redirecionamento que ativa um fluxo de login de várias etapas.

O token retornado é transmitido ao RP pelo navegador para que ele possa validar a autenticação.

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

Continuar no recurso

O IdP pode fornecer um URL de redirecionamento na resposta do endpoint de declaração de ID para ativar um fluxo de login em várias etapas. Isso é útil quando o IdP precisa solicitar informações ou permissões adicionais, por exemplo:

• Permissão para acessar os recursos do lado do servidor do usuário.
• Verificação de que os dados de contato estão atualizados.
• Controles da família.

O endpoint de declaração de ID pode retornar uma propriedade continue_on que inclui um caminho absoluto ou relativo para o endpoint de declaração 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"
  }

Se a resposta contiver o parâmetro continue_on, uma nova janela pop-up será aberta e direcionará o usuário para o caminho especificado. Após a interação do usuário com a página continue_on, o IdP precisa chamar IdentityProvider.resolve() com o token transmitido como um argumento para que a promessa da chamada navigator.credentials.get() original possa ser resolvida:

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

O navegador vai fechar o pop-up automaticamente e retornar o token para o chamador da API. Uma chamada IdentityProvider.resolve() única é a única maneira de a janela pai (RP) e a janela pop-up (IdP) se comunicarem.
Se o usuário rejeitar a solicitação, o IdP poderá fechar a janela chamando IdentityProvider.close().

  IdentityProvider.close();

A API Continuation exige interação explícita do usuário (cliques) para funcionar. Confira como a API Continuation funciona com diferentes modos de mediação:

• No modo passivo:
  • mediation: 'optional' (padrão): a API Continuation só funciona com um gesto do usuário, como clicar em um botão na página ou na interface do FedCM. Quando a nova autenticação automática é acionada sem um gesto do usuário, nenhuma janela pop-up é aberta e a promessa é rejeitada.
  • mediation: 'required': sempre pede ao usuário para interagir, para que a API Continuation sempre funcione.
• No modo ativo:
  • A ativação do usuário é sempre necessária. A API Continuation é compatível.

Se, por algum motivo, o usuário tiver mudado a conta no pop-up (por exemplo, se o IdP oferecer uma função "usar outra conta" ou em casos de delegação), a chamada de resolução terá um segundo argumento opcional, permitindo algo como:

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

Retornar uma resposta de erro

O id_assertion_endpoint também pode retornar uma resposta de "erro", que tem dois campos opcionais:

• code: o IdP pode escolher um dos erros conhecidos da lista de erros especificados do OAuth 2.0 (invalid_request, unauthorized_client, access_denied, server_error e temporarily_unavailable) ou usar qualquer string arbitrária. Se for o último caso, o Chrome renderizará a interface do erro com uma mensagem genérica e transmitirá o código para o RP.
• url: identifica uma página da Web legível por humanos com informações sobre o erro para fornecer mais informações aos usuários. Esse campo é útil para os usuários porque os navegadores não podem fornecer mensagens de erro detalhadas em uma interface integrada. Por exemplo: links para as próximas etapas ou informações de contato do atendimento ao cliente. Se um usuário quiser saber mais sobre os detalhes do erro e como corrigi-lo, ele poderá visitar a página fornecida na interface do navegador para mais detalhes. O URL precisa ser do mesmo site do IdP configURL.

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

Observação: a implementação da resposta "error" é opcional. Se um IdP não notificar o navegador sobre o tipo de erro quando ele ocorrer, o Chrome vai mostrar uma interface de erro com uma mensagem genérica. Se o campo url não for fornecido, o Chrome não vai incluir o botão Mais detalhes.

Rótulos personalizados da conta

Com os rótulos de conta personalizados, o IdP pode anotar contas de usuário com rótulos, e o RP pode escolher buscar apenas contas com rótulos específicos, especificando o configURL para esse rótulo específico. Isso pode ser útil quando um RP precisa filtrar contas por critérios específicos, por exemplo, para mostrar apenas contas específicas de função, como "developer" ou "hr".

É possível usar a Dica de domínio e os recursos de Dica de login para fazer uma filtragem semelhante, especificando-os na chamada navigator.credentials.get(). No entanto, os rótulos de conta personalizados podem filtrar usuários especificando o arquivo de configuração, o que é especialmente útil quando vários configURLs são usados. Os rótulos de conta personalizados também são diferentes porque são fornecidos pelo servidor do IdP, e não pelo RP, como login ou dicas de domínio.

Considere um IdP que quer diferenciar contas "developer" e "hr". Para isso, o IdP precisa oferecer suporte a dois configURLs para "developer" e "hr", respectivamente:

• O arquivo de configuração do desenvolvedor https://idp.example/developer/fedcm.json tem um rótulo "developer", e o arquivo de configuração empresarial https://idp.example/hr/fedcm.json tem um rótulo "hr", conforme mostrado abaixo:

  // 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"
    }
  }

• Com essa configuração, o arquivo conhecido precisa incluir accounts_endpoint e login_url para permitir vários configURLs:

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

• O endpoint de contas (neste exemplo, https://idp.example/accounts) do IdP comum retorna uma lista de contas que inclui uma propriedade labels com rótulos atribuídos em uma matriz para cada conta:

  {
  "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"]
    }]
  }

Quando um RP quer permitir que os usuários do "hr" façam login, ele pode especificar o configURL https://idp.example/hr/fedcm.json na chamada navigator.credentials.get():

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

Como resultado, apenas o ID da conta 4567 está disponível para o usuário fazer login. O ID da conta de 123 é ocultado silenciosamente pelo navegador para que o usuário não receba uma conta que não tenha suporte do IdP nesse site.

Observação:

• Os rótulos são strings. Se a matriz labels ou o campo include contiverem algo que não seja uma string, ele será ignorado.
• Se nenhum rótulo for especificado no configURL, todas as contas vão aparecer no seletor de contas do FedCM.
• Se nenhum rótulo for especificado para uma conta, ela só vai aparecer no seletor de contas se o configURL também não especificar um rótulo.
• Se nenhuma conta corresponder ao rótulo solicitado no modo passivo (semelhante ao recurso de dica de domínio), a caixa de diálogo do FedCM vai mostrar uma solicitação de login, que permite que o usuário faça login em uma conta do IdP. No modo ativo, a janela pop-up de login é aberta diretamente.

Desconectar endpoint

Ao invocar IdentityCredential.disconnect(), o navegador envia uma solicitação POST entre origens com cookies com SameSite=None e um tipo de conteúdo de application/x-www-form-urlencoded para esse endpoint de desconexão com as seguintes informações:

Propriedade	Descrição
account_hint	Uma dica para a conta do IdP.
client_id	O identificador de cliente do 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

Ao receber a solicitação, o servidor precisa:

1. Responda à solicitação com o CORS (Compartilhamento de recursos entre origens).
2. Verifique se a solicitação contém um cabeçalho HTTP Sec-Fetch-Dest: webidentity.
3. Correlacione o cabeçalho Origin com a origem do RP determinada pelo client_id. Rejeite se não forem correspondentes.
4. Compare account_hint com os IDs das contas já conectadas.
5. Desconecte a conta do usuário do RP.
6. Responda ao navegador com as informações da conta de usuário identificada em formato JSON.

Aviso:a solicitação CORS precisa ter credenciais, o que significa que o cabeçalho de resposta Access-Control-Allow-Origin precisa indicar uma origem explícita em vez de um caractere curinga usando "*".

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

Um exemplo de payload JSON de resposta é parecido com este:

  {
    "account_id": "account456"
  }

Em vez disso, se o IdP quiser que o navegador desconecte todas as contas associadas ao RP, transmita uma string que não corresponda a nenhum ID de conta, por exemplo, "*".

Endpoint de metadados do cliente

O endpoint de metadados do cliente do provedor de identidade retorna os metadados da parte confiável, como a política de privacidade, os termos de serviço e os ícones do logotipo. Os RPs precisam fornecer links para a Política de Privacidade e os Termos de Serviço ao IdP com antecedência. Esses links são mostrados na caixa de diálogo de login quando o usuário ainda não se registrou no RP com o IdP.

O navegador envia uma solicitação GET usando o client_id navigator.credentials.get sem cookies. Exemplo:

  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

Ao receber a solicitação, o servidor precisa:

1. Determine o RP para o client_id.
2. Responda com os metadados do cliente.

As propriedades do endpoint de metadados do cliente incluem:

Propriedade	Descrição
privacy_policy_url (opcional)	URL da Política de Privacidade do RP.
terms_of_service_url (opcional)	URL dos Termos de Serviço do RP.
icons (opcional)	Matriz de objetos, como [{ "url": "https://rp.example/rp-icon.ico", "size": 40}]

O navegador espera uma resposta JSON do endpoint:

  {
    "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
      }]
  }

Os metadados do cliente retornados são consumidos pelo navegador e não estarão disponíveis para o RP.

URL de login

Esse endpoint é usado para permitir que o usuário faça login no IdP.

Com a API Login Status, o IdP precisa informar o status de login do usuário ao navegador. No entanto, o status pode estar desincronizado, por exemplo, quando a sessão expira. Nesse cenário, o navegador pode permitir que o usuário faça login no IdP dinamicamente pelo URL da página de login especificado com o login_url do arquivo de configuração do IdP.

A caixa de diálogo FedCM mostra uma mensagem sugerindo um login, conforme mostrado na imagem a seguir.

Uma caixa de diálogo do FedCM sugerindo o login no IdP.

Quando o usuário clica no botão Continuar, o navegador abre uma janela pop-up para a página de login do IdP.

Exemplo de caixa de diálogo mostrada após clicar no botão de login no IdP.

Observação: o site não pode controlar o tamanho da caixa de diálogo antes de ela ser aberta. Por padrão, o tamanho é definido como 500 px de largura e 600 px de altura.

A caixa de diálogo é uma janela de navegador normal com cookies primários. O que acontecer na caixa de diálogo fica a critério do IdP, e nenhum identificador de janela está disponível para fazer uma solicitação de comunicação entre origens para a página de RP. Depois que o usuário fizer login, o IdP precisará:

• Envie o cabeçalho Set-Login: logged-in ou chame a API navigator.login.setStatus("logged-in") para informar ao navegador que o usuário fez login.
• Chame IdentityProvider.close() para fechar a caixa de diálogo.

Observação: leia Informar o navegador sobre o status de login do usuário para saber mais sobre o cabeçalho HTTP Set-Login e a função IdentityProvider.close().

Um usuário faz login em um RP depois de fazer login no IdP usando o FedCM.

Informar o navegador sobre o status de login do usuário

A API Status do login é um mecanismo em que um site, especialmente um provedor de identidade (IdP, na sigla em inglês), informa ao navegador o status de login do usuário no IdP. Com essa API, o navegador pode reduzir solicitações desnecessárias ao IdP e mitigar possíveis ataques de tempo.

Os IdPs podem sinalizar o status de login do usuário para o navegador enviando um cabeçalho HTTP ou chamando uma API JavaScript quando o usuário está conectado no IdP ou quando ele está desconectado de todas as contas do IdP. Para cada IdP (identificado pelo URL de configuração), o navegador mantém uma variável de três estados que representa o estado de login com os seguintes valores possíveis:

• logged-in
• logged-out
• unknown (padrão)

Estado de login	Descrição
logged-in	Quando o status de login do usuário está definido como logged-in, o RP que chama o FedCM faz solicitações para o endpoint de contas do provedor de identidade e mostra as contas disponíveis para o usuário na caixa de diálogo do FedCM.
logged-out	Quando o status de login do usuário é logged-out, a chamada para o FedCM falha silenciosamente sem fazer uma solicitação para o endpoint de contas do provedor de identidade.
unknown (padrão)	O status unknown é definido antes que o IdP envie um sinal usando a API Login Status. Quando o status é unknown, o navegador faz uma solicitação para o endpoint de contas do provedor de identidade e atualiza o status com base na resposta do endpoint de contas.

Para indicar que o usuário fez login, envie um cabeçalho HTTP Set-Login: logged-in em uma navegação de alto nível ou uma solicitação de subrecurso no mesmo site na origem do IDP:

  Set-Login: logged-in

Como alternativa, chame o método JavaScript navigator.login.setStatus('logged-in') da origem do IdP em uma navegação de nível superior:

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

O status de login do usuário será definido como logged-in.

Para indicar que o usuário fez logout de todas as contas, envie um cabeçalho HTTP Set-Login: logged-out em uma navegação de nível superior ou uma solicitação de subrecurso no mesmo site na origem do IdP:

  Set-Login: logged-out

Como alternativa, chame a API JavaScript navigator.login.setStatus('logged-out') da origem do IdP em uma navegação de nível superior:

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

O status de login do usuário será definido como logged-out.

O status unknown é definido antes que o IdP envie um sinal usando a API Login Status. O navegador faz uma solicitação ao endpoint de contas do provedor de identidade e atualiza o status com base na resposta do endpoint de contas:

• Se o endpoint retornar uma lista de contas ativas, atualize o status para logged-in e abra a caixa de diálogo FedCM para mostrar essas contas.
• Se o endpoint não retornar nenhuma conta, atualize o status para logged-out e falha na chamada FedCM.

Observação:o cabeçalho de status de login também pode ser enviado de subrecursos do mesmo site, a partir do Chrome 122. Isso é útil, por exemplo, quando um site permite que os usuários insiram o nome de usuário e a senha em idp.example, mas as credenciais são enviadas para login.idp.example com fetch(). A resposta de busca de login.idp.example ainda pode definir o status de login para idp.example enviando o cabeçalho HTTP Set-Login: logged-in.

Permitir que o usuário faça login por um fluxo dinâmico

Embora o IdP continue informando o status de login do usuário ao navegador, ele pode estar fora de sincronia, como quando a sessão expira. O navegador tenta enviar uma solicitação com credenciais para o endpoint de contas quando o status de login é logged-in, mas o servidor não retorna nenhuma conta porque a sessão não está mais disponível. Nesse cenário, o navegador pode permitir que o usuário faça login no IdP dinamicamente por uma janela pop-up.

Essa experiência de login dinâmico é destinada a quando uma sessão do IdP expirou sem um logout explícito, fazendo com que o estado de login do navegador contradiga o estado real do usuário. Isso não é acionado para usuários que ainda não fizeram login no IdP. Este fluxo foi criado para abranger os casos em que o status de login do IdP do usuário no navegador é logged-in, mas o endpoint de contas do IdP não retorna contas. Supondo que a API de status de login seja chamada imediatamente, quando o FedCM é invocado, qualquer um dos seguintes cenários pode ocorrer:

• Se o status de login do usuário estiver definido como "desconhecido", o status será atualizado (logged-in ou logged-out) dependendo da resposta do IdP do endpoint das contas. Um fluxo de login dinâmico não será acionado.
• Se um usuário tiver feito login no IdP no navegador e depois tiver saído explicitamente dele, o fluxo de login dinâmico não será acionado.
• Se um usuário tiver feito login no IdP no navegador, mas a sessão expirar sem uma atualização explícita para logged-out, o fluxo de login dinâmico será acionado.

A API Login Status não permite que o RP mostre uma caixa de diálogo "Fazer login no IdP" para usuários que não fizeram login no IdP. Esse é um recurso separado que pode ser adicionado no futuro.

Implementar o FedCM como RP

Quando a configuração e os endpoints do IdP estiverem disponíveis, os RPs poderão chamar navigator.credentials.get() para permitir que os usuários façam login no RP com o IdP.

Antes de chamar a API, confirme se o FedCM está disponível no navegador do usuário. Para verificar se o FedCM está disponível, use este código na implementação do FedCM:

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

Atenção: se o RP implantar uma Política de Segurança de Conteúdo (CSP) na página em que o FedCM é chamado e aplicar a diretiva connect-src, ele precisa permitir explicitamente os endpoints fornecidos no arquivo de configuração.

Para permitir que os usuários façam login no IdP em um RP usando o FedCM, o RP pode chamar navigator.credentials.get(), por exemplo:

  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;

Propriedade de contexto

Com a propriedade context opcional, o RP pode modificar a string na IU de diálogo do FedCM (por exemplo, "Fazer login em rp.example…", "Usar idp.example…") para acomodar contextos de autenticação predefinidos, por exemplo. A propriedade context pode ter os seguintes valores:

• signin (padrão)
• signup
• use

Como o branding é aplicado à caixa de diálogo FedCM

Por exemplo, definir context como use resultará na seguinte mensagem:

Caixa de diálogo da FedCM mostrando uma mensagem de contexto personalizada.

O navegador processa os casos de uso de inscrição e login de maneira diferente, dependendo da existência de approved_clients na resposta do endpoint da lista de contas. O navegador não vai mostrar um texto de divulgação "Para continuar com ...." se o usuário já tiver se inscrito no RP.
A propriedade providers usa uma matriz de objetos IdentityProvider com as seguintes propriedades:

Propriedade "Providers"

A propriedade providers usa uma matriz de objetos IdentityProvider com as seguintes propriedades:

Propriedade	Descrição
configURL (obrigatório)	Um caminho completo do arquivo de configuração do IdP.
clientId (obrigatório)	O identificador do cliente do RP, emitido pelo IdP.
nonce (opcional)	Uma string aleatória para garantir que a resposta seja emitida para essa solicitação específica. Evita ataques de repetição.
loginHint (opcional)	Ao especificar um dos valores login_hints fornecidos pelos endpoints de contas, a caixa de diálogo FedCM mostra seletivamente a conta especificada.
domainHint (opcional)	Ao especificar um dos valores domain_hints fornecidos pelos endpoints de contas, a caixa de diálogo FedCM mostra seletivamente a conta especificada.
mode (opcional)	String que especifica o modo de IU do FedCM. Ele pode ser um destes valores: "active": o comando FedCM precisa ser iniciado pela interação do usuário (como clicar em um botão). "passive": o comando FedCM será iniciado sem interação direta do usuário. Consulte a página de visão geral para saber mais sobre a diferença entre os modos ativo e passivo. Observação: o parâmetro mode é aceito a partir do Chrome 132.
fields (opcional)	Matriz de strings que especifica as informações do usuário ("name", "email", "picture") que o RP precisa que o IdP compartilhe. Observação: a API Field tem suporte no Chrome 132 e versões mais recentes.
parameters (opcional)	Objeto personalizado que permite especificar outros parâmetros de chave-valor: scope: um valor de string com outras permissões que o RP precisa solicitar, por exemplo, "drive.readonly calendar.readonly" nonce: uma string aleatória para garantir que a resposta seja emitida para essa solicitação específica. Evita ataques de repetição. Outros parâmetros de chave-valor personalizados. Observação: o parameters é compatível com o Chrome 132.

Modo ativo

O FedCM oferece suporte a diferentes configurações do modo de UX. O modo passivo é o padrão, e os desenvolvedores não precisam configurá-lo.

Para usar o FedCM no modo ativo:

1. Verifique a disponibilidade do recurso no navegador do usuário.
2. Invocar a API com um gesto temporário do usuário, como um clique no botão.
3. Transmita o parâmetro mode para a chamada de 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'
      }
    });
  }

Ícone personalizado no modo ativo

O modo ativo permite que os IdPs incluam o ícone do logotipo oficial do RP diretamente na resposta do endpoint de metadados do cliente. O RP precisa fornecer os dados de branding com antecedência.

Observação: transmitir um ícone do logotipo do RP para o navegador é opcional. Se o ícone de RP não estiver presente, o Chrome só vai mostrar o logotipo do IdP na interface de divulgação em que o usuário é solicitado a compartilhar a permissão.

Chamar o FedCM em um iframe entre origens

O FedCM pode ser invocado em um iframe de origem cruzada usando uma política de permissões identity-credentials-get, se o frame pai permitir. Para fazer isso, anexe o atributo allow="identity-credentials-get" à tag iframe da seguinte maneira:

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

Confira um exemplo.

Se o frame pai quiser restringir as origens para chamar o FedCM, envie um cabeçalho Permissions-Policy com uma lista de origens permitidas.

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

Saiba mais sobre como a Política de permissões funciona em Como controlar recursos do navegador com a Política de permissões.

API Login Hint

Usando a dica de login, o RP pode recomendar a conta em que o usuário deve fazer login. Isso pode ser útil para reautenticar usuários que não têm certeza de qual conta usaram antes.

Os RPs podem mostrar seletivamente uma conta específica invocando navigator.credentials.get() com a propriedade loginHint com um dos valores login_hints buscados do endpoint da lista de contas, conforme mostrado no exemplo de código abaixo:

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

Quando nenhuma conta corresponde ao loginHint, a caixa de diálogo FedCM mostra um prompt de login, que permite que o usuário faça login em uma conta do IdP que corresponde à dica solicitada pelo RP. Quando o usuário toca no comando, uma janela pop-up é aberta com o URL de login especificado no arquivo de configuração. O link é anexado com a dica de login e os parâmetros de consulta de dica de domínio.

API Domain Hint

Os RPs podem mostrar seletivamente apenas as contas associadas a um determinado domínio. Isso pode ser útil para RPs restritos a um domínio corporativo.

Para mostrar apenas contas de domínio específicas, o RP precisa chamar navigator.credentials.get() com a propriedade domainHint e um dos valores domain_hints buscados do endpoint da lista de contas, conforme mostrado no exemplo de código abaixo:

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

Observação:quando domainHint: 'any' é usado, o Chrome filtra as contas que não têm domínios, ou seja, domain_hints não é transmitida ou está vazia. Por exemplo, isso permite casos de uso em que o RP só permite contas gerenciadas no processo de inscrição.

Quando nenhuma conta corresponde ao domainHint, a caixa de diálogo FedCM mostra um prompt de login, que permite que o usuário faça login em uma conta do IdP que corresponde à dica solicitada pelo RP. Quando o usuário toca no comando, uma janela pop-up é aberta com o URL de login especificado no arquivo de configuração. O link é anexado com a dica de login e os parâmetros de consulta de dica de domínio.

Exemplo de solicitação de login quando nenhuma conta corresponde ao domainHint.

Parâmetros personalizados

O recurso de parâmetros personalizados permite que o RP forneça outros parâmetros de chave-valor ao endpoint de declaração de ID. Com a API Parameters, os RPs podem transmitir outros parâmetros ao IdP para solicitar permissões de recursos além do login básico. A transmissão de parâmetros adicionais pode ser útil nestes cenários:

• O RP precisa solicitar dinamicamente outras permissões que o IdP tem, como endereço de faturamento ou acesso ao calendário. O usuário pode autorizar essas permissões usando um fluxo de UX controlado pelo IdP que é iniciado com o recurso Continuar, e o IdP compartilha essas informações.

Para usar a API, o RP adiciona parâmetros à propriedade params como um objeto na chamada 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'
        }
      },
    }
  });

O navegador vai traduzir isso automaticamente em uma solicitação POST para o IdP com parâmetros como um único objeto serializado JSON codificado por 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.

Se o RP precisar de mais permissões, o IdP poderá fornecer um link de redirecionamento. Por exemplo, no node.js:

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

Campos

O RP pode especificar as informações do usuário (qualquer combinação de nome, endereço de e-mail e foto do perfil) que ele precisa que o IdP compartilhe. As informações solicitadas serão incluídas na interface de divulgação da caixa de diálogo FedCM. O usuário vai receber uma mensagem informando que o idp.example vai compartilhar as informações solicitadas com o rp.example se ele decidir fazer login.

Observação: por padrão, a mensagem da interface de divulgação inclui todos os campos implementados atualmente: "Para continuar, o idp.example vai compartilhar seu nome, endereço de e-mail e foto do perfil com este site". Os usuários recorrentes não vão ver a interface de exibição.

Mensagem de divulgação no modo ativo: o RP solicita que o IdP compartilhe apenas o e-mail e a foto do perfil do usuário.

Para usar o recurso de campos, o RP precisa adicionar uma matriz fields na chamada navigator.credentials.get(). Os campos podem conter qualquer permutação de name, email e picture. Isso pode ser expandido para incluir mais valores no futuro. Uma solicitação com fields ficaria assim:

  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',

      },
    }
  });

O navegador vai traduzi-lo automaticamente em uma solicitação HTTP para o endpoint de declaração de ID que inclui o parâmetro fields especificado pelo RP, com os campos que o navegador divulgou para o usuário em um parâmetro disclosure_shown_for. Para compatibilidade com versões anteriores, o navegador também vai enviar disclosure_text_shown=true se o texto de divulgação tiver sido mostrado e os campos solicitados incluírem todos os três campos: 'name', 'email' e '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

Se fields for uma matriz vazia, o user agent vai pular a interface de revelação.

A mensagem de declaração não aparece no modo passivo. No fluxo do botão, a interface de divulgação é totalmente ignorada.

Isso acontece mesmo se a resposta do endpoint de contas não contiver um ID de cliente correspondente ao RP em approved_clients.

Nesse caso, o disclosure_text_shown enviado para o endpoint de declaração de ID é falso no corpo 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 uma mensagem de erro

Às vezes, o IdP não pode emitir um token por motivos legítimos, como quando o cliente não está autorizado ou o servidor está temporariamente indisponível. Se o IdP retornar uma resposta de "erro", o RP poderá detectá-la, e o Chrome poderá notificar o usuário mostrando a interface do navegador com as informações de erro fornecidas pelo IdP.

Uma caixa de diálogo do FedCM mostrando a mensagem de erro após a tentativa de login do usuário falhar. A string é associada ao tipo de erro.

  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;
  }

Refazer a autenticação dos usuários automaticamente após a autenticação inicial

A reautenticação automática do FedCM ("reautenticação automática" em resumo) permite que os usuários se autentiquem novamente automaticamente quando voltam após a autenticação inicial usando o FedCM. "A autenticação inicial" significa que o usuário cria uma conta ou faz login no site do RP tocando no botão Continuar como... na caixa de diálogo de login do FedCM pela primeira vez na mesma instância do navegador.

Embora a experiência explícita do usuário faça sentido antes que o usuário tenha criado a conta federada para evitar o rastreamento (que é uma das principais metas do FedCM), ela é desnecessária depois que o usuário passou por ela uma vez: depois que o usuário concede permissão para permitir a comunicação entre o RP e o IdP, não há benefício de privacidade ou segurança para aplicar outra confirmação explícita do usuário para algo que ele já tenha reconhecido anteriormente.

Com a reautorização automática, o navegador muda o comportamento dependendo da opção especificada para o mediation ao chamar 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;

O mediation é uma propriedade na API Credential Management. Ele se comporta da mesma forma que o PasswordCredential e o FederatedCredential. Ele também tem suporte parcial do PublicKeyCredential. A propriedade aceita os quatro valores a seguir:

• 'optional'(padrão): reautorização automática, se possível, ou requer mediação, se não for. Recomendamos escolher essa opção na página de login.
• 'required': sempre exige uma mediação para continuar, por exemplo, clicando no botão "Continuar" na interface. Escolha essa opção se os usuários precisarem conceder a permissão explicitamente sempre que precisarem ser autenticados.
• 'silent': reautorização automática, se possível, ou falha silenciosa sem exigir uma mediação, se não for possível. Recomendamos escolher essa opção nas páginas que não são de login, mas em que você quer manter os usuários conectados, como uma página de item em um site de frete ou uma página de artigo em um site de notícias.
• 'conditional': usado para WebAuthn e não disponível para FedCM no momento.

Com essa chamada, a reautorização automática ocorre nas seguintes condições:

• O FedCM está disponível para uso. Por exemplo, o usuário não desativou a FedCM globalmente ou para o RP nas configurações.
• O usuário usou apenas uma conta com a API FedCM para fazer login no site nesse navegador.
• O usuário fez login no IdP com essa conta.
• A reautorização automática não aconteceu nos últimos 10 minutos.
• O RP não chamou navigator.credentials.preventSilentAccess() após a entrada anterior.

Quando essas condições são atendidas, uma tentativa de autenticação automática do usuário é iniciada assim que o navigator.credentials.get() do FedCM é invocado.

Quando mediation: optional, a reautorização automática pode estar indisponível por motivos que apenas o navegador conhece. O RP pode verificar se a reautorização automática é realizada analisando a propriedade isAutoSelected.

Isso é útil para avaliar o desempenho da API e melhorar a UX. Além disso, quando ela não está disponível, o usuário pode ser solicitado a fazer login com a mediação explícita do usuário, que é um fluxo com mediation: required.

Um usuário que está se autenticando automaticamente pelo FedCM.

Aplicar a mediação com preventSilentAccess()

A autenticação automática imediata após a saída do usuário não proporciona uma experiência muito boa. É por isso que o FedCM tem um período de inatividade de 10 minutos após uma reautorização automática para evitar esse comportamento. Isso significa que a reautorização automática acontece no máximo uma vez a cada 10 minutos, a menos que o usuário faça login novamente em até 10 minutos. O RP precisa chamar navigator.credentials.preventSilentAccess() para solicitar explicitamente que o navegador desative a reautorização automática quando um usuário sair explicitamente do RP, por exemplo, clicando em um botão de desativação.

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

Os usuários podem desativar a reautorização automática nas configurações

Os usuários podem desativar a reautorização automática no menu de configurações:

• No Chrome para computador, acesse chrome://password-manager/settings > Fazer login automaticamente.
• No Google Chrome para Android, abra Configurações > Gerenciador de senhas > toque na engrenagem no canto superior direito > Fazer login automaticamente.

Ao desativar o botão, o usuário pode desativar o comportamento de reautorização automática por completo. Essa configuração é armazenada e sincronizada entre dispositivos se o usuário estiver conectado a uma Conta do Google na instância do Chrome e a sincronização estiver ativada.

Observação: os usuários também podem desativar o FedCM por domínio.

Desconecte o IdP do RP

Se um usuário já tiver feito login no RP usando o IdP por FedCM, a relação será memorizada pelo navegador localmente como a lista de contas conectadas. O RP pode iniciar uma desconexão invocando a função IdentityCredential.disconnect(). Essa função pode ser chamada em um frame RP de nível superior. O RP precisa transmitir um configURL, o clientId que ele usa no IdP e um accountHint para que o IdP seja desconectado. Uma dica de conta pode ser uma string arbitrária, desde que o endpoint de desconexão possa identificar a conta. Por exemplo, um endereço de e-mail ou ID de usuário que não necessariamente corresponde ao ID da conta fornecido pelo endpoint da lista de contas:

  // 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() retorna um Promise. Essa promessa pode gerar uma exceção pelos seguintes motivos:

• O usuário não fez login no RP usando o IdP por FedCM.
• A API é invocada em um iframe sem a política de permissões do FedCM.
• O configURL é inválido ou não tem o endpoint de desconexão.
• A verificação da Política de Segurança de Conteúdo (CSP) falha.
• Há uma solicitação de desconexão pendente.
• O usuário desativou o FedCM nas configurações do navegador.

Quando o endpoint de desconexão do IdP retorna uma resposta, o RP e o IdP são desconectados no navegador, e a promessa é resolvida. O ID das contas desconectadas é especificado na resposta do endpoint de desconexão.

Observação: se nenhuma resposta válida do endpoint de desconexão for recebida ou se o ID da conta recebido não corresponder a nenhuma conta na lista de contas conectadas, o agente do usuário vai remover todas as contas que correspondem ao RP e ao IdP da lista de contas conectadas.