Guia para desenvolvedores sobre a API Federated Credential Management

Saiba como usar o FedCM para a federação de identidade que preserva a privacidade.

O FedCM (Federated Credential Management) é um serviço que preserva a privacidade abordagem para serviços de identidade federada (como "Fazer login com..."), em que os usuários podem fazer login em sites sem compartilhar suas informações pessoais com o serviço de identidade ou o site.

Para saber mais sobre casos de uso, fluxos de usuários e roteiro da API do FedCM, confira o introdução à API FedCM.

Ambiente de desenvolvimento do FedCM

Você precisa de um contexto seguro (HTTPS ou localhost) no IdP e na RP no Chrome para usar o FedCM.

Depurar código no Chrome para Android

Configure e execute um servidor localmente para depurar seu código do FedCM. Você pode acessar este servidor no Chrome em um dispositivo Android conectado por um cabo USB com porta encaminhamento.

Use o DevTools no computador para depurar o Chrome no Android seguindo as instruções em Depuração remota do Android dispositivos.

Bloquear cookies de terceiros no Chrome

Simule a descontinuação de cookies de terceiros configurando o Chrome para bloqueá-los
Simule a descontinuação de cookies de terceiros configurando o Chrome para bloqueá-los

Você pode testar como o FedCM funciona no Chrome sem cookies de terceiros são aplicadas.

Para bloquear cookies de terceiros, use o modo de navegação anônima ou escolha "Bloquear cookies de terceiros" nas configurações do computador em chrome://settings/cookies ou em dispositivo móvel, acessando Configurações > Configurações do site > Cookies.

Como usar a API FedCM

Você se integra ao FedCM criando um arquivo conhecido, arquivo de configuração e endpoints para contas lista, emissão de declaração e opcionalmente, metadados do cliente.

A partir daí, o FedCM expõe APIs JavaScript que os representantes podem usar para assinar in com o IdP.

Criar um arquivo conhecido

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

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

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

O arquivo JSON precisa conter a propriedade provider_urls com uma matriz de IdP de arquivo de configuração que podem ser especificados como parte do caminho configURL em navigator.credentials.get pelas partes restritas. O número de As strings de URL na matriz são limitadas a uma, mas isso pode mudar com sua feedback no futuro.

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

O arquivo de configuração do IdP oferece uma lista de endpoints necessários para o navegador. IdPs vai hospedar esse arquivo de configuração e os endpoints e URLs necessários. Todo JSON as respostas precisam ser veiculadas com o tipo de conteúdo application/json.

O URL do arquivo de configuração é determinado pelos valores fornecidos ao Chamada navigator.credentials.get executada em uma RP.

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

Especifique um URL completo do local do arquivo de configuração do IdP como um configURL. Quando navigator.credentials.get() é chamado no RP, o navegador busca o arquivo de configuração com uma solicitação GET sem o cabeçalho Origin ou o Referer. A solicitação não tem cookies e não segue redirecionamentos. Isso impede efetivamente que o IdP saiba quem fez a solicitação e qual O participante está tentando se conectar. Exemplo:

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

O navegador espera uma resposta JSON do IdP que inclui o seguinte propriedades:

Propriedade Descrição
accounts_endpoint (obrigatório) URL do endpoint das contas.
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) O 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 marca.
branding.background_color (opcional) Opção de branding que define a cor de fundo da opção "Continuar como..." . Use a sintaxe CSS relevante, ou seja, hex-color, hsl(), rgb() ou named-color
branding.color (opcional) Opção de branding que define a cor do texto do campo "Continuar como..." . Use a sintaxe CSS relevante, ou seja, hex-color, hsl(), rgb() ou named-color
branding.icons (opcional) Opção de marca que define o objeto do ícone, exibida na caixa de diálogo de login. O objeto de ícone é uma matriz com dois parâmetros:
  • url (obrigatório): URL da imagem do ícone. Ele não é compatível com 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.

O RP pode modificar a string na interface da caixa de diálogo do FedCM usando o valor identity.context. para que o navigator.credentials.get() acomode a autenticação predefinida contextos de negócios diferentes. A propriedade opcional pode ser "signin" (padrão), "signup", "use" ou "continue".

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

Confira um exemplo de corpo de resposta do IdP:

{
  "accounts_endpoint": "/accounts.php",
  "client_metadata_endpoint": "/client_metadata.php",
  "id_assertion_endpoint": "/assertion.php",
  "disconnect_endpoint": "/disconnect.php",
  "login_url": "/login",
  "branding": {
    "background_color": "green",
    "color": "#FFEEAA",
    "icons": [{
      "url": "https://idp.example/icon.ico",
      "size": 25
    }]
  }
}

Assim que o navegador busca o arquivo de configuração, ele envia solicitações subsequentes para o Endpoints do IdP:

Endpoints do IdP
Endpoints do IdP

Endpoint de contas

O endpoint de contas do IdP retorna uma lista de contas em que o usuário está fez login no IdP. Se o IdP suporta várias contas, este endpoint retornará todas as contas conectadas.

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 qual parte da parte restrita o usuário está tentando assinar. Exemplo:

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

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

  1. Verifique se a solicitação contém um cabeçalho HTTP Sec-Fetch-Dest: webidentity.
  2. Relacione 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 de conta com as seguintes propriedades:

Propriedade Descrição
id (obrigatório) ID exclusivo do usuário.
name (obrigatório) 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 de avatar do usuário.
approved_clients (opcional) Uma matriz de IDs do cliente da parte restrita em que o usuário se registrou.
login_hints (opcional) Uma matriz de todos os tipos de filtro possíveis que o IdP aceita para especificar uma conta. A parte restrita pode invocar navigator.credentials.get() com a propriedade loginHint para exibir seletivamente a conta especificada.
domain_hints (opcional) Uma matriz de todos os domínios associados à conta. A parte restrita sabe chamar navigator.credentials.get() com um propriedade domainHint para filtrar os contas de serviço.

Exemplo de corpo de resposta:

{
  "accounts": [{
    "id": "1234",
    "given_name": "John",
    "name": "John Doe",
    "email": "john_doe@idp.example",
    "picture": "https://idp.example/profile/123",
    "approved_clients": ["123", "456", "789"],
    "login_hints": ["demo1", "demo1@idp.example"]
  }, {
    "id": "5678",
    "given_name": "Johnny",
    "name": "Johnny",
    "email": "johnny@idp.example",
    "picture": "https://idp.example/profile/456",
    "approved_clients": ["abc", "def", "ghi"],
    "login_hints": ["demo2", "demo2@idp.example"],
    "domain_hints": ["corp.example"]
  }]
}

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

A lista de contas retornadas é consumida pelo navegador e não fica disponível para parte restrita.

Endpoint de metadados do cliente

O endpoint de metadados do cliente do IdP retorna os metadados da parte confiável, como a Política de Privacidade e os Termos de Serviço da parte restrita. Os RPs devem fornecer links para seus a Política de Privacidade e os Termos de Serviço ao IdP com antecedência. Esses links são exibido na caixa de diálogo de login quando o usuário não se registrou na parte restrita com o IdP.

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

GET /client_metadata.php?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 deve:

  1. Determine a parte restrita da 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 da parte restrita.
terms_of_service_url (opcional) URL dos Termos de Serviço da parte restrita.

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

Os metadados do cliente retornados são consumidos pelo navegador e não serão disponíveis para a parte restrita.

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 da parte restrita usando navigator.credentials.get() chamada, o navegador envia uma solicitação POST com cookies com SameSite=None e um tipo de conteúdo de application/x-www-form-urlencoded para endpoint com as seguintes informações:

Propriedade Descrição
client_id (obrigatório) O identificador do cliente da parte restrita.
account_id (obrigatório) O ID exclusivo do usuário que fez login.
nonce (opcional) O valor de uso único da solicitação, fornecido pela parte restrita.
disclosure_text_shown Resulta em uma string de "true" ou "false" (em vez de um booleano). O resultado será "false" se o texto da declaração não for mostrado. Isso acontece quando o ID do cliente da parte restrita foi incluído na lista de propriedades approved_clients da resposta do endpoint de contas ou se o navegador observou um momento de inscrição no passado na ausência de approved_clients.
is_auto_selected Se a reautenticação automática for realizada na parte restrita, 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 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á lidar com a solicitação de forma diferente. Por exemplo, retorne um código de erro para que a RP possa chamar a API FedCM novamente com mediation: required.

Exemplo de cabeçalho HTTP:

POST /assertion.php HTTP/1.1
Host: accounts.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=Ct60bD&disclosure_text_shown=true&is_auto_selected=true

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

  1. Responda à solicitação com o CORS (Cross-Origin Resource, na sigla em inglês) compartilhamento).
  2. Verifique se a solicitação contém um cabeçalho HTTP Sec-Fetch-Dest: webidentity.
  3. Combine o cabeçalho Origin com a origem da RP determinada por client_id. Rejeite se não forem correspondentes.
  4. Corresponda account_id ao ID da conta já conectada. Rejeitar se mas não correspondem.
  5. Responda com um token. Se a solicitação for rejeitada, responda com um erro resposta.
.

Como o token é emitido depende do IdP, mas, em geral, ele é assinado com informações como ID da conta, ID do cliente, origem do emissor, nonce, para que a parte restrita pode verificar se o token é genuíno.

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

Propriedade Descrição
token (obrigatório) Um token é uma string que contém declarações sobre a autenticação. 
{
  "token": "***********"
}

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

Retornar uma resposta de erro

id_assertion_endpoint também pode retornar um "erro" que tem dois campos opcionais:

  • code: o IdP pode escolher um dos erros conhecidos do OAuth 2.0 erro especificado lista (invalid_request, unauthorized_client, access_denied, server_error e temporarily_unavailable) ou usar qualquer string arbitrária. Se não for o caso, o Chrome renderiza a interface de erro com uma mensagem de erro genérica e transmite o código para a RP.
  • url: identifica uma página da Web legível com informações sobre o para fornecer mais informações sobre o erro aos usuários. Este campo é útil para os usuários porque os navegadores não podem fornecer mensagens de erro avançadas em um interface nativa do usuário. Por exemplo, links para as próximas etapas, contato de atendimento ao cliente e assim por diante. Se um usuário quiser saber mais sobre os detalhes do erro e como corrigir isso, eles podem acessar a página fornecida na interface do navegador para mais detalhes. O URL precisa ser do mesmo site que o IdP configURL.
// id_assertion_endpoint response
{
  "error" : {
     "code": "access_denied",
     "url" : "https://idp.example/error?type=access_denied"
  }
}

Desconectar endpoint

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

Propriedade Descrição
account_hint Uma dica para a conta do IdP.
client_id O identificador do cliente da parte restrita. 
POST /disconnect.php 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 deve:

  1. Responda à solicitação com o CORS (Cross-Origin Resource, na sigla em inglês) compartilhamento).
  2. Verifique se a solicitação contém um cabeçalho HTTP Sec-Fetch-Dest: webidentity.
  3. Combine o cabeçalho Origin com a origem da RP determinada por client_id. Rejeite se não forem correspondentes.
  4. Corresponda account_hint aos IDs das contas já conectadas.
  5. Desconecte a conta de usuário da parte restrita.
  6. Responder ao navegador com as informações da conta de usuário identificada em um JSON .
.

Um exemplo de payload JSON de resposta é semelhante ao seguinte:

{
  "account_id": "account456"
}

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

URL de login

Com a API Login Status, o IdP precisa informar os dados status de login no navegador. No entanto, o status pode estar fora de sincronia, por exemplo, quando a sessão expirar. Nesse caso, o o navegador pode permitir que o usuário faça login no IdP dinamicamente pela página de login URL especificado com o login_url do arquivo de configuração IdP.

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

A
Uma caixa de diálogo do FedCM sugerindo fazer 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.

Esses
Um exemplo de caixa de diálogo mostrada após clicar no botão "Fazer login no IdP".
.

A caixa de diálogo é uma janela normal do navegador que tem cookies primários. Seja qual for acontece na caixa de diálogo é tarefa do IdP, e nenhum identificador de janela está disponível para fazer uma solicitação de comunicação entre origens à página da parte restrita. Depois que o usuário estiver conectado, o IdP precisa:

  • Envie o cabeçalho Set-Login: logged-in ou chame o método 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.
.
A
Um usuário faz login em uma parte restrita depois de fazer login no IdP usando o FedCM.

Informa o navegador sobre o status de login do usuário no provedor de identidade

A API de Status de Login é um mecanismo Em que um site, especialmente um IdP, informa ao navegador o status de login do usuário. no IdP. Com essa API, o navegador pode reduzir solicitações desnecessárias para os IdP e reduza 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 fizer login no IdP ou o o usuário saiu de todas as contas do IdP. Para cada IdP (identificado pelos URL de configuração) o navegador mantém uma variável de três estados que representa o estado do login com os valores possíveis logged-in, logged-out e unknown. O estado padrão é unknown.

Para indicar que o usuário está conectado, envie um cabeçalho HTTP Set-Login: logged-in. em uma navegação de nível superior ou em uma solicitação de sub-recurso no mesmo site no IdP origem:

Set-Login: logged-in

Se preferir, chame a API JavaScript navigator.login.setStatus("logged-in"). da origem do IdP em uma navegação de nível superior:

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

Essas chamadas registram o status de login do usuário como logged-in. Quando o login do usuário estiver definido como logged-in, a RP que chama o FedCM faz solicitações ao IdP endpoint de contas e exibe as contas disponíveis para o usuário no FedCM caixa de diálogo.

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

Set-Login: logged-out

Se preferir, 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")

Essas chamadas registram o status de login do usuário como logged-out. Quando o endereço de e-mail status de login for logged-out, chamar o FedCM silenciosamente falha sem fazer uma para o endpoint de contas do IdP.

O status unknown é definido antes de o IdP enviar um indicador usando o status de login. API. O Unknown foi introduzido para oferecer uma transição melhor, porque um usuário pode ter já estavam conectados ao IdP quando essa API foi enviada. O IdP pode não ter um a chance de sinalizar isso ao navegador no momento em que o FedCM é invocado pela primeira vez. Neste caso, o Chrome faz uma solicitação ao endpoint de contas do IdP e atualiza o com base na resposta do endpoint das contas:

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

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

Mesmo que o IdP continue informando o status de login do usuário ao navegador, ele podem estar fora de sincronia, como quando a sessão expira. O navegador tenta enviar uma solicitação credenciada para o endpoint de contas quando o status de login for logged-in, mas o servidor não retorna contas porque a sessão não está mais disponíveis. Nesse caso, o navegador pode permitir dinamicamente que o usuário faça login ao IdP em uma janela pop-up.

Fazer login como parte confiável com o provedor de identidade

Depois que a configuração e os endpoints do IdP estiverem disponíveis, os RPs poderão chamar navigator.credentials.get() para solicitar que os usuários façam login na parte restrita. com o IdP.

Antes de chamar a API, você precisa confirmar se o [FedCM está disponível no navegador do usuário]. Para verificar se o FedCM está disponível, envolva este código na sua Implementação do FedCM:

if ('IdentityCredential' in window) {
  // If the feature is available, take action
}

Para solicitar que os usuários façam login no IdP no RP, siga estas etapas: Por exemplo:

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

A propriedade providers usa uma matriz de IdentityProvider Objetos que têm 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 da 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 repetidos.
loginHint (opcional) Ao especificar um dos valores login_hints fornecidos pelo os endpoints das contas, o FedCM mostra seletivamente a conta especificada.
domainHint (opcional) Ao especificar um dos valores domain_hints fornecidos pelo os endpoints das contas, o FedCM para mostrar seletivamente a conta especificada.

O navegador lida com casos de uso de inscrição e login de forma diferente, dependendo do a existência de approved_clients na resposta da lista de contas endpoint. O navegador não vai mostrar uma declaração envie "Para continuar com ...." se o usuário já tiver se inscrito na parte restrita.

O estado de inscrição é determinado com base na condição a seguir atendidas ou não:

  • Se approved_clients incluir o clientId da RP.
  • Se o navegador lembrar que o usuário já se inscreveu na parte restrita.
.
Um usuário faz login em uma parte restrita usando o FedCM

Quando a parte restrita chama navigator.credentials.get(), as seguintes atividades levam lugar:

  1. O navegador envia solicitações e busca vários documentos:
    1. O arquivo conhecido e uma configuração do IdP que declaram endpoints.
    2. Uma lista de contas.
    3. Opcional: URLs dos Termos de Serviço e da Política de Privacidade da parte restrita recuperados do endpoint de metadados do cliente.
  2. O navegador mostra a lista de contas que o usuário pode usar para fazer login. além dos termos de serviço e da política de privacidade, se disponíveis.
  3. Assim que o usuário escolhe uma conta para fazer login, uma solicitação para o ID endpoint de declaração é enviado ao IdP para recuperar uma com base no token correto anterior.
  4. A parte restrita pode validar o token para autenticar o usuário.
.
chamada de API de login
chamada de API de login

Espera-se que os RPs ofereçam suporte a navegadores que não oferecem suporte ao FedCM, portanto, os usuários devem conseguir usar um processo de login atual não do FedCM. Até cookies de terceiros sejam completamente desativados, isso deve permanecer não problemática.

Depois que o token é validado pelo servidor da RP, a RP pode registrar o usuário ou permitir que eles façam login e iniciem uma nova sessão.

API Login Hint

Depois que o usuário faz login, às vezes a parte confiável (RP) pede que o usuário reautenticar. No entanto, o usuário pode não ter certeza de qual conta está usando. Se a parte restrita puder especificar com qual conta fazer login, será mais fácil para o escolha uma conta.

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

return await navigator.credentials.get({
  identity: {
    providers: [{
      configURL: "https://idp.example/manifest.json",
      clientId: "123",
      nonce: nonce,
      loginHint : "demo1@example.com"
    }]
  }
});

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

API Domain Hint

Há casos em que a parte restrita já sabe que apenas as contas associadas a um determinados domínios têm permissão para fazer login no site. Isso é particularmente comum em cenários corporativos em que o site que está sendo acessado é restrito a uma empresa domínio. Para proporcionar uma melhor experiência ao usuário, a API FedCM permite que o RP apenas mostrar as contas que podem ser usadas para fazer login na parte restrita. Isso evita cenários em que um usuário tenta fazer login na parte restrita usando uma conta fora da organização domínio, para ser veiculado apenas com uma mensagem de erro posteriormente (ou silenciar quando o URL login não funcionou), porque o tipo correto de conta não foi usado.

As partes restritas podem mostrar seletivamente apenas as contas correspondentes invocando navigator.credentials.get() pela propriedade domainHint com um dos domain_hints valores buscados na lista de contas endpoint, conforme mostrado no exemplo de código a seguir:

return await navigator.credentials.get({
  identity: {
    providers: [{
      configURL: "https://idp.example/manifest.json",
      clientId: "abc",
      nonce: nonce,
      domainHint : "corp.example"
    }]
  }
});

Quando nenhuma conta corresponde a domainHint, a caixa de diálogo do FedCM mostra uma solicitação de login. que permite que o usuário faça login em uma conta do IdP correspondente à dica solicitada pelo parte restrita. Quando o usuário toca na solicitação, uma janela pop-up é aberta com o URL de login especificado no arquivo de configuração. Entã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 a "domainHint".
Um exemplo de solicitação de login quando nenhuma conta corresponde ao domainHint.

Mostrar uma mensagem de erro

Às vezes, o IdP pode não conseguir emitir um token por motivos legítimos, como ou seja, quando o cliente não tem autorização, o servidor fica temporariamente indisponível. Se o IdP retorna um "erro" resposta, a parte restrita pode capturá-la, e o Chrome notifica o usuário mostrando uma interface do navegador com as informações de erro fornecidas pelo IdP.

A
Uma caixa de diálogo do FedCM mostrando a mensagem de erro após a falha na tentativa de login do usuário. 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;
}

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

Reautenticação automática do FedCM ("reautenticação automática") permite que os usuários se reautentiquem automaticamente quando e voltar após a autenticação inicial com o FedCM. "O autenticação" aqui significa que o usuário cria uma conta ou faz login na tocando no botão Continuar como... na caixa de diálogo de login do FedCM na mesma instância do navegador.

Embora a experiência explícita do usuário faça sentido antes de o usuário criar o conta federada para impedir o rastreamento (que é uma das principais metas do FedCM), é desnecessariamente complicado depois de o usuário ter passado por ele uma vez: depois de o usuário concede permissão para permitir a comunicação entre a parte restrita e o IdP não há benefício de privacidade ou segurança ao aplicar outra regra a confirmação de algo que já foi reconhecido anteriormente.

Com a reautenticação automática, o navegador muda de comportamento dependendo da opção que você especificar 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 no Gerenciador de credenciais API, ele se comporta da mesma maneira quanto para PasswordCredential e FederatedCredential e é parcialmente compatível com PublicKeyCredential . A propriedade aceita os quatro valores a seguir:

  • 'optional'(padrão): a reautenticação automática, se possível, exige uma mediação. Qa recomendamos escolher essa opção na página de login.
  • 'required': sempre exige uma mediação para prosseguir, por exemplo, clicando no "Continuar" na interface. Escolha essa opção se for esperado que os usuários conceder permissão explicitamente sempre que eles precisarem ser autenticados.
  • 'silent': reautenticação automática, se possível, que falha silenciosamente sem exigir uma mediação, caso contrário. Recomendamos escolher essa opção nas páginas que não página de login dedicada, mas em que você quer manter os usuários conectados, por exemplo, exemplo, uma página de itens em um site de frete ou uma página de artigos em uma notícia site.
  • 'conditional': usado para WebAuthn e não disponível para FedCM no momento.

Nessa chamada, a reautenticaçã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 seja globalmente ou para a parte restrita nas configurações.
  • O usuário usou apenas uma conta com a API FedCM para fazer login no site navegador.
  • O usuário fez login no IdP com essa conta.
  • A reautenticação automática não aconteceu nos últimos 10 minutos.
  • A parte restrita não ligou navigator.credentials.preventSilentAccess() depois login anterior.

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

Quando mediation: optional, a reautenticação automática pode ser indisponível por motivos que somente o navegador sabe; a parte restrita pode verificar se a reautenticação automática foi realizada examinando a propriedade isAutoSelected.

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

Reautenticação automática de um usuário pelo FedCM.

Aplicar a mediação com preventSilentAccess()

A reautenticação automática de usuários imediatamente após eles saíram não resultaria em uma uma experiência do usuário muito boa. É por isso que a FedCM tem um período de silêncio de 10 minutos após uma reautenticação automática para evitar esse comportamento. Isso significa que a reautenticação automática acontece no máximo uma vez a cada 10 minutos, a menos que o usuário faça login novamente dentro de 10 minutos. O participante precisa chamar navigator.credentials.preventSilentAccess() para solicitar explicitamente que o navegador desative a reautenticação automática quando um usuário sair da a parte restrita explicitamente, por exemplo, clicando em um botão para sair.

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

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

Os usuários podem desativar a reautenticaçã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 um engrenagem no canto superior direito > Login automático.

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

Desconectar o IdP da parte restrita

Se um usuário já tiver feito login na parte restrita usando o IdP pelo FedCM, o é memorizada pelo navegador localmente como a lista de redes contas de serviço. A parte restrita pode iniciar uma desconexão invocando o 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 o IdP ser desconectado. Uma conta A dica pode ser uma string arbitrária, desde que o endpoint de desconexão possa identificar da conta, por exemplo, um endereço de e-mail ou ID de usuário que não necessariamente correspondem ao ID da conta que o endpoint da lista de contas forneceu:

// 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 pelos seguintes motivos:

  • O usuário não fez login na parte restrita usando o IdP no FedCM.
  • A API é invocada de dentro de um iframe sem a política de permissões do FedCM.
  • O configURL é inválido ou o endpoint de desconexão não foi informado.
  • 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 um resposta, a parte restrita e o IdP são desconectados na navegador e a promessa é resolvida. O ID das contas desconectadas é especificado na resposta do erro endpoint do Google Cloud.

Chamar o FedCM a partir de um iframe de origem cruzada

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

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

Para saber como isso funciona, confira um exemplo.

Opcionalmente, 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 funciona a política de permissões em Como controlar recursos do navegador com permissões Política.