Login hospedado

Cada client ganha um conjunto de telas que o Authio hospeda e desenha no servidor: login, segundo fator, esqueci a senha, termos, consentimento, logout e as páginas da conta. A sua aplicação nunca recebe uma senha. Ela envia o navegador ao endpoint de autorização do realm, e o Authio conduz a pessoa por tudo o que o client foi configurado para pedir.

Esta página explica como um login acontece, as etapas que você compõe por client, o que a pessoa vê, a marca e os idiomas, e como rodar o login num popup em vez de um redirecionamento completo.

Como um login acontece

1. 1

   A sua aplicação envia um pedido de autorização

   Um pedido authorization code com PKCE padrão, enviado ao endpoint de autorização do realm. Qualquer biblioteca OpenID Connect monta esse pedido para você:

   Pedido de autorizaçãoTexto simples

   https://authio.api.hyperio.tech/realms/acme/protocol/openid-connect/auth
     ?client_id=acme-web
     &response_type=code
     &redirect_uri=http://localhost:3000/api/auth/callback/authio
     &scope=openid profile email
     &state=STATE
     &code_challenge=CODE_CHALLENGE
     &code_challenge_method=S256

2. 2

   O Authio procura uma sessão que possa reaproveitar

   Se o client participa do single sign-on e o navegador já tem um login válido no realm, a pessoa passa direto ou escolhe uma conta no seletor. Caso contrário, o navegador chega à tela de login do client, /realms/acme/clients/acme-web/login, levando o pedido inteiro junto.

3. 3

   O login hospedado executa as etapas do client

   Senha, passkey, um botão de provedor e, depois, o segundo fator que o client ainda exigir. Comprovada a credencial, o Authio aplica as verificações do realm nesta ordem: suspensão, situação da conta e acesso a este client, endereço de origem do login, expiração da senha e, só então, o segundo fator.

4. 4

   Termos e consentimento, quando o client pede

   Com a conta definida, o pedido volta pelo endpoint de autorização. A tela de termos vem primeiro, se a conta ainda não aceitou a versão vigente, e depois a de consentimento, se o client pede consentimento e algum escopo ainda não foi concedido.

5. 5

   O navegador volta para a sua aplicação

   O Authio redireciona para a redirect URI registrada com code, state e iss. A sua aplicação troca o código por tokens como de costume.

Etapas do login

Cada client escolhe, em ordem, de quais etapas o seu login é feito. Clients do mesmo realm podem ser diferentes: um pede só senha, outro uma passkey, um terceiro senha mais aprovação no celular.

Exigência e cadastro

As etapas passkey e push têm duas configurações. Exigência diz o quanto a etapa é pedida; Cadastro diz o que acontece com uma conta que ainda não tem o fator.

Combinações que trancariam pessoas do lado de fora são recusadas ao salvar o client, com o motivo no campo:

• Etapa Obrigatória com cadastro Nunca num client que tem a etapa login: uma conta sem o fator nunca conseguiria entrar.
• Etapa Opcional com cadastro Exigir: a conta cadastraria um fator que nunca é pedido.
• Etapa mfa marcada como Opcional: o código nunca seria enviado. Remova a etapa em vez disso.
• Etapa que oferece cadastro num client sem a etapa login: não há sessão a partir da qual cadastrar, então defina o cadastro como Nunca.

Configurar as etapas

1. 1

   Abra a tela de login do client

   Em Clients, abra o client, escolha Editar e depois o passo Tela de login. As etapas vêm primeiro, de cima para baixo na ordem em que a tela as pede.

2. 2

   Adicione, remova e ordene as etapas

   Mova cada etapa para cima ou para baixo e defina Exigência e Cadastro para passkey e push. O aceite de termos é um interruptor à parte, marcado Depois do login; os documentos e a versão ficam na Configuração do client.

3. 3

   Salve

   As etapas novas valem a partir do próximo login. Um client que usa o fluxo authorization code precisa de pelo menos uma etapa; sem ela, o salvamento é recusado.

O que a pessoa vê

Em volta das etapas, a tela de login oferece:

• Continuar conectado, que mantém a sessão depois que o navegador fecha.
• Esqueceu a senha?, que abre a redefinição de senha deste client.
• Um botão Continuar com … para cada provedor de identidade que o client oferece, embaixo do botão de entrar.
• Preenchimento automático de passkey no campo de usuário, quando o client também tem a etapa passkey.
• Começar de novo, que descarta o que foi digitado e reabre a primeira etapa com o mesmo pedido.
• O seletor de contas, quando o navegador já tem mais de um login reaproveitável.

Um nome de usuário inexistente e uma senha errada recebem a mesma resposta, então a tela nunca revela quais contas existem. Toda outra recusa só aparece depois que a senha foi aceita, e diz o que fazer em seguida:

Falhas que nenhuma nova tentativa resolve, como um pedido cujo client_id aponta para um client diferente do da tela, substituem o formulário por um cartão de erro com um código de referência que o suporte encontra nos logs.

Marca

Todas as telas hospedadas de um client vestem a aparência dele: login, recuperação, termos, consentimento, erros, verificação de dispositivo e as páginas da conta. Você define a aparência no mesmo passo Tela de login.

O CSS personalizado não pode conter <, expression(, javascript:, vbscript:, behavior: nem -moz-binding, e não pode carregar url() ou @import por http simples. Ele é conferido ao salvar e sanitizado de novo quando a tela é desenhada.

Quando um pedido de autorização nomeia uma organização com organization, o logo, a cor primária e a cor de fundo da organização substituem os do client; a disposição, os textos e o CSS continuam os do client.

Claro e escuro

Passe theme=light ou theme=dark no pedido de autorização para escolher a paleta com que as pessoas começam. As telas também têm um botão de alternância; a escolha da própria pessoa fica num cookie e prevalece até o próximo pedido que nomear um tema.

Idiomas

As telas hospedadas estão escritas em inglês (en) e português do Brasil (pt-BR). O idioma é definido uma vez por login e mantido em todas as etapas:

1. ui_locales no pedido de autorização, uma lista separada por espaços em ordem de preferência.
2. O cabeçalho Accept-Language do navegador, respeitando os pesos.
3. Inglês.

Os erros são redigidos a partir do código, no idioma da visita. Toda página hospedada, inclusive as da conta, também aceita ui_locales e theme diretamente no endereço.

Parâmetros que as telas leem

Além dos parâmetros OAuth padrão, estes mudam o que o login hospedado mostra:

Login num popup

Para manter a sua página onde está, abra o pedido de autorização numa janela popup. Acrescente display=popup para as telas caberem na janela e response_mode=web_message para que, no fim, o Authio envie a resposta à janela que abriu o popup e o feche, em vez de navegar o popup até a sua redirect URI.

A mensagem é um objeto cujo type é authorization_response e cujo response traz code, state e iss (ou error). Ela é enviada só para a origem da redirect URI que o pedido nomeou, então a página que abre o popup precisa estar nessa origem. Se nenhuma janela estiver esperando — o popup foi aberto como aba, ou quem o abriu saiu da página —, o popup volta a um redirecionamento comum.

const ISSUER = 'https://authio.api.hyperio.tech/realms/acme'
const AUTHIO_ORIGIN = new URL(ISSUER).origin

export function signInWithPopup(
  state: string,
  codeChallenge: string,
): Promise<Record<string, string>> {
  const authorize = new URL(ISSUER + '/protocol/openid-connect/auth')
  authorize.search = new URLSearchParams({
    client_id: 'acme-web',
    response_type: 'code',
    redirect_uri: 'http://localhost:3000/callback',
    scope: 'openid profile email',
    state,
    code_challenge: codeChallenge,
    code_challenge_method: 'S256',
    display: 'popup',
    response_mode: 'web_message',
  }).toString()

  const popup = window.open(authorize.toString(), 'authio-sign-in', 'popup,width=480,height=720')

  return new Promise((resolve, reject) => {
    if (!popup) {
      reject(new Error('popup_blocked'))
      return
    }

    function onMessage(event: MessageEvent) {
      if (event.origin !== AUTHIO_ORIGIN || event.source !== popup) return
      if (event.data?.type !== 'authorization_response') return

      window.removeEventListener('message', onMessage)
      resolve(event.data.response)
    }

    window.addEventListener('message', onMessage)
  })
}

Confira se o state é o que você enviou e troque o code com o seu verificador PKCE exatamente como depois de um redirecionamento. Chame a função direto de um handler de clique, ou o navegador bloqueia o popup.

De onde vêm as contas

O login hospedado não tem formulário de cadastro aberto ao público. Uma conta chega a um realm de uma destas três formas:

• Criada por um administrador em Usuários ou pela API administrativa.
• Importada de outro provedor. Veja Migração de usuários.
• Criada no primeiro login por um provedor de identidade configurado para criar contas. Veja Login social e corporativo.

Próximos passos