Atualizações do FedCM: testes de origem do pacote da API Continuation e da concessão automática da API Storage Access

Eiji Kitamura

No Chrome 126, os desenvolvedores podem começar a fazer um teste de origem de um pacote de recursos da API Federated Credential Management (FedCM) para computadores que permitem que alguns Casos de uso de autorização. O pacote consiste na API de continuação e na API Parameters, que permite uma experiência semelhante a um fluxo de autorização OAuth que envolve uma caixa de diálogo de permissão fornecida pelo provedor de identidade (IdP). O pacote também inclui outras alterações, como a API Fields, vários configURLs e Rótulos da conta. A partir do Chrome 126, também lançaremos um teste de origem para o A API Storage Access (SAA) que concede automaticamente solicitações de SAA se o usuário tiver fez login usando o FedCM no passado.

Teste de origem: pacote da API FedCM Continuation

O pacote da API de continuação do FedCM consiste em várias extensões do FedCM:

• API de continuação
• API Parameters
• API Fields
• Vários configURLs
• Rótulos de conta personalizados

API de continuação

Um usuário faz login na parte restrita e autoriza usando o modo de botão.

Confira uma demonstração da API no Glitch.

Com a API de continuação, Declaração de ID do IdP endpoint para retornar um URL que o FedCM renderizará para permitir que o usuário continue uma fluxo de login de várias etapas. Isso permite que o IdP solicite ao usuário a concessão de permissões de parte confiável (RP) além do que é possível na interface do FedCM como o acesso aos recursos do lado do servidor.

Normalmente, o endpoint de declaração de ID retorna um token necessário para autenticação.

{
  "token": "***********"
}

No entanto, com a API de continuação, a declaração de ID endpoint de e-mails pode retornar uma propriedade continue_on que inclui um caminho absoluto ou um 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 pop-up window:
  "continue_on": "/oauth/authorize?scope=..."
}

Assim que o navegador receber a resposta continue_on, uma nova janela pop-up será exibida. é aberto e leva o usuário ao caminho especificado.

Depois que o usuário interage com a página, por exemplo, concedendo mais permissões para compartilhar informações extras com a parte restrita, a página do IdP pode chamar IdentityProvider.resolve() para resolver o problema original navigator.credentials.get() e retornam um token como argumento.

document.getElementById('allow_btn').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 fechará o pop-up e retornará o token para a API. autor da chamada.

Se o usuário rejeitar a solicitação, você poderá fechar a janela chamando IdentityProvider.close():

IdentityProvider.close();

Observação :o pop-up se comporta como se fosse noopener, noreferrer foi especificado (portanto, window.opener é nulo) e não há como para os a janela principal (RP, na sigla em inglês) e a janela pop-up (IdP) interagem entre si. A a única forma de se comunicar precisa ser IdentityProvider.resolve() uma única vez que também fecha o pop-up.

Observação: a API de continuação só é permitida quando há uma interação do usuário. (cliques explícitos). Portanto, o usuário deve selecionar uma conta em modo widget (com mediation: 'required') ou no botão modo (que sempre requer ativação do usuário). Mas o pop-up não é permitido para mediation: silent: Para o modo de widget mediation: optional, a API verifica ativação temporária do usuário se a reautenticação automática for acionada. Caso contrário, nenhuma janela pop-up é aberta e a promessa é rejeitada.

Se, por algum motivo, o usuário tiver alterado a conta no pop-up (por exemplo, o IdP oferece uma opção de "trocar de usuário" ou em casos de delegação), a resolução call usa um segundo argumento opcional que permite algo como:

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

API Parameters

A API Parameters permite que o RP para fornecer parâmetros adicionais à declaração de ID endpoint do Google Cloud. Com a API Parameters, os RPs podem transmitir outros parâmetros ao IdP para solicitar permissões para recursos além do login básico. O usuário autorizaria essas permissões por um fluxo de UX controlado pelo IdP que é iniciado por o API de continuação.

Para usar a API, adicione parâmetros à propriedade params como um objeto na 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',
        ETC: 'MOAR',
        scope: 'calendar.readonly photos.write',
      }
    },
  }
});

Os nomes de propriedades no objeto params são prefixados com param_. Na exemplo acima, a propriedade params contém IDP_SPECIFIC_PARAM como '1', foo como 'BAR', ETC como 'MOAR' e scope como 'calendar.readonly photos.write'. Ela será traduzida como param_IDP_SPECIFIC_PARAM=1&param_foo=BAR&param_ETC=MOAR&param_scope=calendar.readonly%20photos.write no corpo HTTP da solicitação:

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

account_id=123&client_id=client1234&nonce=234234&disclosure_text_shown=false&param_IDP_SPECIFIC_PARAM=1&param_foo=BAR&param_ETC=MOAR&param_scope=calendar.readonly%20photos.write

Receber permissões dinamicamente

Em geral, para os usuários, é mais útil solicitar permissões quando eles estão necessário, e não quando o desenvolvedor achar que é mais fácil de implementar. Para exemplo, pedir permissão para acessar uma câmera quando o usuário está prestes a tirar é preferível usar uma foto do que pedir a permissão assim que o usuário chegar ao site. A mesma prática se aplica aos recursos do servidor. Solicitar apenas permissões quando forem necessários para o usuário. Isso é chamado de "autorização dinâmica".

Para solicitar autorização dinamicamente com o FedCM, o IdP pode:

1. Chamar navigator.credentials.get() com os parâmetros obrigatórios que o IdP pode acessar. entender, como scope.
2. A declaração de ID endpoint do Google Cloud confirma que o usuário já fez login e responde com um URL continue_on.
3. O navegador abre uma janela pop-up com a página de permissões do IdP solicitando o seguinte: permissão adicional que corresponde aos escopos solicitados.
4. Depois de autorizado pelo IdP com IdentityProvider.resolve(), a janela será fechada, e a chamada navigator.credentials.get() original da parte restrita recebe uma um token relevante ou um código de autorização, para que a parte restrita possa trocá-lo por um token de acesso adequado.

API Fields

Com a API Fields, o RP declarar atributos de conta a serem solicitados ao IdP para que o navegador possa Renderizar uma interface de divulgação adequada na caixa de diálogo do FedCM é responsabilidade do IdP para incluir os campos solicitados no token retornado. Considerar esta solicitação um "perfil básico" no OpenID Connect versus "escopos" no OAuth.

Mensagem de divulgação no modo de widget.

.

Mensagem de divulgação no modo de botão.

Para usar a API Fields, adicione parâmetros à propriedade fields como uma matriz na navigator.credentials.get(). Os campos podem conter 'name' e 'email' e 'picture' por enquanto, mas pode ser expandido para incluir mais valores na futuro.

Uma solicitação com fields ficaria assim:

let { token } = await navigator.credentials.get({
  identity: {
    providers: [{
      fields: ['name', 'email', 'picture'],
      clientId: '1234',
      configURL: 'https://idp.example/fedcm.json',
      params: {
        scope: 'drive.readonly calendar.readonly',
      }
    },
  }
  mediation: 'optional',
});

A solicitação HTTP para a declaração de ID endpoint do Google Cloud inclui o parâmetro fields especificado pela RP, com disclosure_text_shown definido como true se este não for um usuário recorrente, e os campos que o navegador divulgado ao usuário em um parâmetro disclosure_shown_for:

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=true&fields=email,name,picture&disclosure_shown_for=email,name,picture

Observação :no momento, o Chrome gera uma exceção, a menos que o RP peça uma fields: ['name', 'email', 'picture'] ou nada com fields: []. No futuro, o Chrome tornará a interface mais capaz de solicitar diferentes e vai começar a aceitar subconjuntos desses valores.

Se a parte restrita precisar acessar outros dados do IdP, como acesso a um agenda, isso deve ser tratado com um parâmetro personalizado, conforme mencionado acima. A O IdP retorna um URL continue_on para solicitar a permissão.

Se fields for uma matriz vazia, a solicitação será assim:

let { token } = await navigator.credentials.get({
  identity: {
    providers: [{
      fields: [],
      clientId: '1234',
      configURL: 'https://idp.example/fedcm.json',
      params: {
        scope: 'drive.readonly calendar.readonly',
      }
    },
  }
  mediation: 'optional',
});

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

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

Isso acontecerá mesmo se a resposta das contas endpoint do Google Cloud não contém um ID do cliente que corresponda à parte restrita em approved_clients.

Nesse caso, o disclosure_text_shown enviado à declaração de ID endpoint é false no corpo do 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

Vários configURLs

Vários configURLs permitem IdPs para acomodar vários arquivos de configuração para um IdP, especificando accounts_endpoint e login_url nos conhecidos locais arquivo igual que os arquivos de configuração.

Se accounts_endpoint e login_url forem adicionados ao arquivo conhecido, os provider_urls são ignorados para que o IdP aceite vários arquivos de configuração. Se não forem, a provider_urls vai continuar em vigor para voltar a entrar em vigor compatíveis.

O arquivo mais conhecido compatível com vários configURLs pode ter esta aparência:

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

Com isso, podemos:

1. Manter compatibilidade com versões anteriores e posteriores com arquivos conhecidos e a versão anterior de navegadores já implantados.
2. Ter um número arbitrário de arquivos de configuração, desde que todos apontem para o os mesmos accounts_endpoint e login_url.
3. Não têm oportunidade para que a entropia seja adicionada à solicitação de busca credenciada feita na accounts_endpoint, já que ela precisa ser especificada ".well-known" nível

O suporte a vários configURLs é opcional, e o FedCM atual e as implementações podem permanecer as mesmas.

Rótulos de conta personalizados

Os rótulos de conta personalizados permitem o FedCM IdPs para anotar as contas para que as partes interessadas possam filtrá-las especificando o rótulo em um arquivo de configuração. Foi possível realizar uma filtragem semelhante usando a dica de domínio API e a seção Login API Hint ao especificar na chamada navigator.credentials.get(), mas os rótulos de conta personalizados pode filtrar usuários especificando o arquivo de configuração, que é especialmente útil ao vários configURLs são usados. Os rótulos de conta personalizados são também diferentes porque são fornecidos pelo servidor do IdP, e não pelo na parte restrita, como dicas de login ou de domínio.

Exemplo

Um IdP é compatível com dois configURLs para consumidor e empresarial, respectivamente. A o arquivo de configuração do consumidor tem um rótulo 'consumer', e o arquivo de configuração empresarial tem um rótulo 'enterprise'.

Com essa configuração, o arquivo conhecido inclui 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"
}

Quando o accounts_endpoint é fornecido no arquivo conhecido, o provider_urls são ignorados. O RP pode apontar diretamente para a respectiva configuração arquivos na chamada de navigator.credentials.get().

O arquivo de configuração do consumidor está em https://idp.example/fedcm.json, que inclui Propriedade accounts que especifica 'consumer' usando include.

{
  "accounts_endpoint": "https://idp.example/accounts",
  "client_metadata_endpoint": "/client_metadata",
  "login_url": "https://idp.example/login",
  "id_assertion_endpoint": "/assertion",
  "accounts": {
    "include": "consumer"
  }
}

O arquivo de configuração da empresa está em https://idp.example/enterprise/fedcm.json, que inclui a propriedade accounts, que especifica 'enterprise' usando o include.

{
  "accounts_endpoint": "https://idp.example/accounts",
  "client_metadata_endpoint": "/enterprise/client_metadata",
  "login_url": "https://idp.example/login",
  "id_assertion_endpoint": "/assertion",
  "accounts": {
    "include": "enterprise"
  }
}

As contas de IdP comuns endpoint do Google Cloud (neste exemplo, https://idp.example/accounts) retorna uma lista de contas que inclui uma propriedade "labels" com um labels atribuído em uma matriz para cada conta. Veja a seguir um exemplo de resposta para um usuário que tem duas contas. Um é para consumidor e o outro para empresas:

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

Quando uma parte restrita quer permitir que usuários do 'enterprise' façam login, ele pode especificar o 'enterprise' configURL 'https://idp.example/enterprise/fedcm.json' no Chamada do navigator.credentials.get():

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

Como resultado, apenas o ID da conta '4567' está disponível para o usuário assinar. O ID da conta '123' é oculto silenciosamente pelo navegador para que o usuário não vão receber uma conta que não seja compatível com o IdP neste site.

Observação:

• Rótulos são strings. Se a matriz labels ou O campo include contém algo que não é uma string, é ignorada.
• Se nenhum rótulo for especificado no configURL, todas as contas serão exibido no seletor de conta do FedCM.
• Se nenhum rótulo for especificado para uma conta, ele só será exibido no Seletor de conta se o configURL também não especificar um rótulo.
• Se nenhuma conta corresponder ao rótulo solicitado no fluxo do widget (semelhante ao Domain Hint API), a caixa de diálogo do FedCM mostra um prompt de login, que permite que o usuário para fazer login em uma conta do IdP. Para o fluxo do botão, a janela pop-up de login é são abertos diretamente.

Teste de origem: FedCM como um sinal de confiança para a API Storage Access

O Chrome 126 está iniciando um teste de origem do FedCM como um sinal de confiança para a Acesso ao armazenamento API. Com uma autorização prévia via FedCM se torna um motivo válido para aprovar automaticamente uma solicitação de acesso ao armazenamento pelo papel Acesso ao armazenamento APIs do Google.

Isso é útil quando um iframe incorporado quer acessar recursos personalizados: por exemplo, se idp.example estiver incorporado em rp.example e precisar mostrar uma recurso personalizado. Se o navegador restringir o acesso a cookies de terceiros, mesmo que o usuário esteja conectado a rp.example usando idp.example com o FedCM, o O iframe do idp.example incorporado não poderá solicitar recursos personalizados porque as solicitações não vão incluir cookies de terceiros.

Para isso, idp.example precisa de uma permissão de acesso ao armazenamento pelo iframe incorporado no site, e isso só pode ser obtido através de uma solicitação de permissão.

Com o FedCM como um sinal de confiança para o Storage Access API, As verificações de permissão da API Storage Access não apenas aceitam a concessão de permissão é dada por um prompt de acesso ao armazenamento, mas também a permissão concedida por um Solicitação do FedCM.

// In top-level rp.example:

// Ensure FedCM permission has been granted.
const cred = await navigator.credentials.get({
  identity: {
    providers: [{
      configURL: 'https://idp.example/fedcm.json',
      clientId: '123',
    }],
  },
  mediation: 'optional',
});

// In an embedded IdP iframe:

// No user gesture is needed to call this, and the call will be auto-granted.
await document.requestStorageAccess();

// This returns `true`.
const hasAccess = await document.hasStorageAccess();

Depois que o usuário faz login com o FedCM, a permissão é concedida automaticamente, desde que a autenticação do FedCM está ativa. Isso significa que, quando o usuário é desconectado, solicitando permissão, será exibida uma solicitação.

Observação: para permitir que um iframe do IdP incorporado receba a concessão automática de acesso ao armazenamento, apesar de O FedCM não é invocado no iframe, e o RP deve adicionar explicitamente o Permissões do FedCM identity-credentials-get política.

Participar do teste de origem

Para testar o pacote da API FedCM Continuation, ative uma versão do Chrome flag chrome://flags#fedcm-authz no Chrome 126 ou mais recente. Você também pode testar o FedCM como um sinal de confiança para a API Storage Access localmente. Basta ativar #fedcm-with-storage-access-api no Chrome 126 ou mais recente.

Esses recursos também estão disponíveis como testes de origem. Os testes de origem permitem que você teste novos recursos e dê feedback sobre usabilidade, praticidade e eficácia. Para mais informações, confira Introdução aos testes de origem.

Para testar a origem do pacote da API FedCM Continuation período de teste, crie dois tokens de teste de origem:

• Inscreva-se no teste. Incorporar o token ao IdP origem.
• Inscreva-se no teste de origem com a caixa de seleção de terceiros correspondente marcada. Siga as instruções em Registrar um teste de origem de terceiros para o RP para incorporar o token à RP.

Se você quiser ativar a API de continuação com o botão fluxo, ative o modo de botões Origem da API período de teste também:

• Inscreva-se no teste de origem como um terceiro. Siga as instruções Registrar um teste de origem de terceiros para a parte restrita para incorporar o token para a parte restrita.

Testar o FedCM como um sinal de confiança para a origem da API Storage Access teste:

• Inscreva-se no teste de origem. Incorporar o token ao IdP origem.

O teste de origem do pacote da API de continuação e o FedCM como um indicador de confiança para a O teste de origem da API Storage Access está disponível no Chrome 126 em diante.

Registrar um teste de origem de terceiros para a parte restrita

1. Acesse a página de registro do teste de origem.
2. Clique no botão Registrar e preencha o formulário para solicitar um token.
3. Digite a origem do IdP como Web Origin.
4. Verificar a correspondência de terceiros para injetar o token com JavaScript em outras origens.
5. Clique em Enviar.
6. Incorporar o token emitido em um site de terceiros.

Para incorporar o token em um site de terceiros, adicione o seguinte código ao IdP Biblioteca JavaScript ou SDK disponibilizado a partir da origem do IdP.

const tokenElement = document.createElement('meta');
tokenElement.httpEquiv = 'origin-trial';
tokenElement.content = 'TOKEN_GOES_HERE';
document.head.appendChild(tokenElement);

Substitua TOKEN_GOES_HERE pelo seu próprio token.

Observação :se a API FedCM for invocada pela RP, e não por um script carregado no IdP, a RP precisam registrar a origem e realizar o teste de origem próprio.