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
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:
|
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"
.
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:
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:
- Verifique se a solicitação contém um cabeçalho HTTP
Sec-Fetch-Dest: webidentity
. - Relacione os cookies de sessão aos IDs das contas já conectadas.
- 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:
- Determine a parte restrita da
client_id
. - 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:
- Responda à solicitação com o CORS (Cross-Origin Resource, na sigla em inglês) compartilhamento).
- Verifique se a solicitação contém um cabeçalho HTTP
Sec-Fetch-Dest: webidentity
. - Combine o cabeçalho
Origin
com a origem da RP determinada porclient_id
. Rejeite se não forem correspondentes. - Corresponda
account_id
ao ID da conta já conectada. Rejeitar se mas não correspondem. - 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
etemporarily_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 IdPconfigURL
.
// 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:
- Responda à solicitação com o CORS (Cross-Origin Resource, na sigla em inglês) compartilhamento).
- Verifique se a solicitação contém um cabeçalho HTTP
Sec-Fetch-Dest: webidentity
. - Combine o cabeçalho
Origin
com a origem da RP determinada porclient_id
. Rejeite se não forem correspondentes. - Corresponda
account_hint
aos IDs das contas já conectadas. - Desconecte a conta de usuário da parte restrita.
- 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.
Quando o usuário clica no botão Continuar, o navegador abre uma janela pop-up. para a página de login do 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 APInavigator.login.setStatus("logged-in")
para informar ao navegador que o usuário fez login. - Chame
IdentityProvider.close()
para fechar a caixa de diálogo.
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 oclientId
da RP. - Se o navegador lembrar que o usuário já se inscreveu na parte restrita.
Quando a parte restrita chama navigator.credentials.get()
, as seguintes atividades levam
lugar:
- O navegador envia solicitações e busca vários documentos:
- O arquivo conhecido e uma configuração do IdP que declaram endpoints.
- Uma lista de contas.
- Opcional: URLs dos Termos de Serviço e da Política de Privacidade da parte restrita recuperados do endpoint de metadados do cliente.
- 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.
- 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.
- A parte restrita pode validar o token para autenticar o usuário.
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.
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.
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
.
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.