Implementar uma solução de identidade com o FedCM na parte confiável

As partes confiáveis (RPs, na sigla em inglês) precisam concluir as seguintes etapas para ativar o FedCM no site:

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

Chamar a API FedCM na parte confiável

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

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

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

Para permitir que um usuário faça login no IdP em uma RP usando o FedCM, a RP pode chamar navigator.credentials.get(). A partir do Chrome 136, o RP pode oferecer suporte a vários IdPs especificando uma matriz de vários provedores de identidade em uma única chamada navigator.credentials.get(). Por exemplo:

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

Teste o recurso de vários IdPs fazendo login com IdP1 e IdP2.

Propriedade de contexto

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

• signin (padrão)
• signup
• use

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

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 na 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:

Modo ativo

A FedCM é compatível com diferentes configurações de 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. Invoque a API com um gesto transitório do usuário, como um clique em um 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'
      }
    });
  }

Teste o modo ativo com esta demonstração.

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

Chamar a FedCM de um iframe entre origens

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

  <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 Controle de recursos do navegador com a Política de permissões.

API Login Hint

Usando a dica de login, o RP pode recomendar com qual conta um usuário deve fazer login. Isso pode ser útil para reautenticar usuários que não sabem qual conta usaram antes.

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

  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 da FedCM mostra uma solicitação de login, que permite ao usuário fazer login em uma conta do IdP que corresponda à dica solicitada pelo RP. Quando o usuário toca no aviso, uma janela pop-up é aberta com o URL de login especificado no arquivo de configuração. Em seguida, o link é anexado com os parâmetros de consulta de dica de login e 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 a seguir:

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

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

Confira a demonstração para mais detalhes.

Parâmetros personalizados

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

• A RP precisa solicitar dinamicamente outras permissões que o IdP tem, como endereço de faturamento ou acesso à agenda. O usuário pode autorizar essas permissões em um fluxo de UX controlado por um IdP, que é iniciado usando o recurso "Continuar em". Depois, 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 JSON serializado e 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, em 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 que ele precisa que o IdP compartilhe com ele. Isso pode incluir qualquer combinação de nome, endereço de e-mail, nome de usuário, número de telefone e foto do perfil. As informações solicitadas serão incluídas na interface de divulgação da caixa de diálogo do FedCM.

Os usuários que se inscreverem vão receber uma mensagem informando que o idp.example vai compartilhar as informações solicitadas com o rp.example se o usuário optar por se inscrever. Se a resposta do endpoint de contas não incluir um campo solicitado pelo RP, o texto de divulgação não vai incluir esse campo. O IdP vai aprender todos os campos solicitados no endpoint de declaração de ID e decidir se precisa coletar mais permissões do usuário para continuar.

Para usar o recurso "Campos", o RP precisa adicionar uma matriz fields na chamada navigator.credentials.get(). Os campos podem conter propriedades como name, email, tel, username ou picture. Isso pode ser ampliado para incluir mais valores no futuro. Uma solicitação com fields seria assim:

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

O navegador vai traduzir automaticamente isso 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 ao 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 for mostrado e os campos solicitados incluírem todos os três campos: 'name', 'email' e 'picture'. A partir do Chrome 141, o valor de disclosure_text_shown não indica se o texto de divulgação foi realmente mostrado ao usuário.

  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 divulgação.

Isso acontece mesmo que a resposta do endpoint "accounts" não contenha um ID do cliente que corresponda ao RP em approved_clients.

Nesse caso, o disclosure_text_shown enviado ao 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 consegue 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á capturá-la, e o Chrome poderá notificar o usuário mostrando a interface do navegador com as informações de erro fornecidas pelo IdP.

  try {
    const cred = await navigator.credentials.get({
      identity: {
        providers: [
          {
            configURL: 'https://idp.example/manifest.json',
            clientId: '1234',
          },
        ],
      }
    });
  } catch (e) {
    const code = e.code;
    const url = e.url;
  }

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

A reautenticação automática do FedCM (abreviada como "auto-reauthn") permite que os usuários se autentiquem novamente de forma automática. As seguintes condições precisam ser atendidas para a autenticação automática do usuário:

• O usuário já fez a autenticação inicial usando a 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 da FedCM pela primeira vez na mesma instância do navegador.
• O usuário tem apenas uma conta recorrente. Se houver contas retornadas para vários IdPs, o usuário não será autenticado novamente de forma automática.

Embora a experiência explícita do usuário faça sentido antes que ele crie a conta federada para evitar o rastreamento (que é um dos principais objetivos do FedCM), ela é desnecessariamente complicada depois que o usuário passa 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 em exigir outra confirmação explícita do usuário para algo que ele já reconheceu anteriormente.

Com a autenticação automática, o navegador muda o comportamento dependendo da opção especificada para 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, se comporta da mesma forma que PasswordCredential e FederatedCredential e também é parcialmente compatível com PublicKeyCredential. A propriedade aceita os quatro valores a seguir:

• 'optional'(padrão): faz a autenticação automática novamente, se possível, e exige uma mediação se não for possível. Recomendamos escolher essa opção na página de login.
• 'required': sempre exige uma mediação para continuar, por exemplo, clicar no botão "Continuar" na interface. Escolha essa opção se os usuários precisarem conceder permissão explicitamente sempre que precisarem ser autenticados.
• 'silent': faça a autenticação automática novamente, se possível. Caso contrário, falhe silenciosamente sem exigir uma mediação. Recomendamos escolher essa opção em páginas que não sejam a de login dedicada, mas em que você quer manter os usuários conectados. Por exemplo, uma página de itens em um site de frete ou uma página de artigos em um site de notícias.
• 'conditional': usado para WebAuthn e indisponível para FedCM no momento.

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

• O FedCM está disponível para uso. Por exemplo, o usuário não desativou o 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 neste navegador.
• O usuário fez login no IdP com essa conta.
• A autenticação automática não ocorreu nos últimos 10 minutos.
• O RP não chamou navigator.credentials.preventSilentAccess() após o login anterior.

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

Quando mediation: optional, a reautenticação automática pode ficar indisponível por motivos que apenas o navegador conhece. O RP pode verificar se a reautenticação automática foi realizada examinando a propriedade isAutoSelected.

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

Aplicar a mediação com preventSilentAccess()

A autenticação automática de usuários imediatamente após a saída não seria uma boa experiência. Por isso, a FedCM tem um período de espera de 10 minutos após uma reautenticação automática para evitar esse comportamento. Isso significa que a autenticação automática acontece no máximo uma vez a cada 10 minutos, a menos que o usuário faça login novamente em 10 minutos. O RP precisa chamar navigator.credentials.preventSilentAccess() para solicitar explicitamente que o navegador desative a reautenticação automática quando um usuário sair do RP explicitamente, por exemplo, ao clicar em um botão de saída.

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

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

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

• No Chrome para computador, acesse chrome://password-manager/settings > Fazer login automaticamente.
• No Chrome para Android, abra Configurações > Gerenciador de senhas > Toque em uma engrenagem no canto superior direito > Login automático.

Ao desativar a opção, o usuário pode recusar o comportamento de reautenticação automática. Essa configuração é armazenada e sincronizada em todos os dispositivos se o usuário estiver conectado a uma Conta do Google na instância do Chrome e a sincronização estiver ativada.

Desconectar o IdP do RP

Se um usuário já tiver feito login na RP usando o IdP pelo 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 de 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 um ID de usuário que não necessariamente corresponda 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 pela FedCM.
• A API é invocada de 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á um pedido 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. Os IDs das contas desconectadas são especificados em a resposta do endpoint de desconexão.

Próximas etapas

Implementar a FedCM no IdP

Saiba como implementar sua solução de identidade com a FedCM no provedor de identidade.

Personalização e desativação

Saiba como os usuários e desenvolvedores podem gerenciar a participação no FedCM, incluindo a ativação ou desativação em várias plataformas e sites.