Início de sessão: chaves, códigos, redes sociais, SSO

Ative um método com PUT methods/{name}/ e {"enabled": true} na API de gestão de autenticação da sua aplicação, ou na consola. O início de sessão alojado mostra apenas os métodos que ativou. Cada chamada JSON abaixo começa com uma transaction de POST authorize/. Essa transação dura 10 minutos. Um início de sessão bem-sucedido devolve {code, redirect_uri, state}. Troque o código em POST token/ no prazo de 60 segundos (ver tokens e JWKS). Em vez de um código, uma chamada de início de sessão pode devolver um destes passos. Conclua o passo e receberá depois o código.

​

Palavra-passe

POST password/ recebe transaction, email e password.

• Uma palavra-passe tem de cumprir o password_min_length definido (8, 10, 12 ou 14 caracteres; 10 por predefinição). Palavras-passe comuns e apenas numéricas são rejeitadas com password_policy. Quando a verificação de palavras-passe comprometidas está ativa, uma palavra-passe conhecida como comprometida é rejeitada com password_breached.
• Só as pessoas com um e-mail verificado podem iniciar sessão com palavra-passe.
• Uma palavra-passe errada, um e-mail desconhecido, um e-mail não verificado, uma conta bloqueada e uma conta bloqueada recebem todos a mesma resposta: 400 {"error": "invalid_credentials"}. A sua interface não consegue distinguir qual foi, e um atacante também não.

​

Registo

O registo verifica primeiro o e-mail. Chame POST email/start/ com purpose: "signup", email e password, e depois POST email/complete/ com o código. A conta é criada com um e-mail verificado.

• signup_policy define quem pode fazer o registo: anyone, invited (apenas com uma ligação de convite) ou allowed_domains.
• Com allow_subaddresses: false (a predefinição), um endereço com + na parte local é rejeitado.
• Quando a sua identidade visual define ligações para os termos ou para a política de privacidade, o formulário de registo alojado pede à pessoa que as aceite.

​

Código por e-mail

POST email/start/ recebe transaction, purpose (login ou signup) e email, e devolve 202 {challenge, expires_in: 600}. A pessoa recebe um código de 6 dígitos válido durante 10 minutos. POST email/complete/ recebe transaction, purpose, challenge e code. Há 5 tentativas; depois disso, a pessoa tem de pedir um novo código. A página alojada oferece um novo código após 30 segundos. Um código de início de sessão para um endereço sem conta cria uma conta quando o seu signup_policy o permitir. Isto é registo sem palavra-passe.

​

Ligação mágica

A página alojada envia uma ligação de início de sessão válida durante 15 minutos. Fica associada à transação PKCE original, pelo que a ligação só funciona no fluxo que a iniciou. A pessoa confirma o início de sessão na página que a ligação abre. Não existe endpoint JSON para ligações mágicas.

​

Código por telefone

POST phone/start/ recebe transaction, phone e um channel opcional (sms, a predefinição, ou whatsapp). O número é normalizado para E.164. Devolve 202 {challenge, expires_in: 600}. POST phone/complete/ recebe transaction, challenge e o code de 6 dígitos. Há 5 tentativas.

• Os códigos por telefone são enviados através da Verificação de telefone da Didit. Ative o método com o workflow_id de um fluxo que contenha verificação de telefone.
• Um primeiro início de sessão por telefone só cria uma conta quando signup_policy for anyone.
• Se o envio falhar, a chamada devolve 503 {"error": "delivery_unavailable"}.

​

Passkeys

As passkeys usam WebAuthn. A parte confiante (relying party) é a origem de início de sessão da sua aplicação. A Didit pede uma credencial detetável (resident key) e exige sempre verificação do utilizador, como impressão digital, rosto ou PIN do dispositivo. A Didit não pede atestação.

• Um desafio de passkey dura 5 minutos.
• Adicionar uma passkey exige uma sessão criada nos últimos 5 minutos. Caso contrário, a chamada devolve 403 {"error": "reauthentication_required"}. Peça primeiro à pessoa que volte a iniciar sessão.
• Um início de sessão com passkey conta como autenticação multifator.
• Após o registo, a página alojada oferece adicionar uma passkey (passkeys/setup/begin/ e passkeys/setup/complete/).
• As aplicações Android registadas na sua aplicação podem usar as mesmas passkeys.

​

Início de sessão social

O Google, a Microsoft, a Apple e o GitHub usam as suas próprias credenciais de aplicação OAuth, definidas com PUT methods/{provider}/ e credentials: {client_id, client_secret}. O URL de retorno do fornecedor encontra-se na origem de início de sessão. Na primeira vez que alguém inicia sessão com um fornecedor, também comprova que é titular do endereço de e-mail, com um código (POST social/email/start/ e POST social/email/verify/). Os inícios de sessão seguintes com esse fornecedor saltam este passo. O GitHub não consegue comprovar um início de sessão recente, por isso não é disponibilizado quando envia prompt=login ou max_age.

​

SSO da organização

O SSO da organização permite que a empresa de um cliente inicie sessão através do seu próprio fornecedor de identidade SAML ou OIDC. Configure-o por organização de cliente em organizations/{id}/sso/ com protocol (saml ou oidc), enabled e config.

• Pode enviar à equipa de TI do cliente uma ligação de configuração válida durante 7 dias.
• Os metadados do seu fornecedor de serviço SAML são publicados em {origin}/sso/saml/metadata/.
• O início de sessão alojado encontra a ligação a partir do domínio de e-mail verificado da pessoa, ou a partir de organization=<slug> no URL de início de sessão.

​

Didit ID Wallet

As pessoas que já verificaram a sua identidade com a Didit podem iniciar sessão com a sua Didit ID Wallet. Este método está sempre ativado. O verified_identity da sessão contém então o que a pessoa escolheu partilhar.

​

MFA

O segundo fator é uma aplicação de autenticação (TOTP) com códigos de recuperação, ou uma passkey.

• mfa_policy decide quem tem de usar MFA: optional, everyone ou organization_admins (o valor predefinido). Quem tiver registado uma aplicação de autenticação tem sempre de a usar.
• Para registar uma aplicação de autenticação, chame POST mfa/enroll/ com uma sessão recente (criada há menos de 5 minutos). A resposta devolve {challenge, uri}; apresente o uri como código QR. Depois envie o primeiro código para POST mfa/confirm/. A resposta contém 10 códigos de recuperação de utilização única. Mostre-os uma única vez.
• No início de sessão, envie um código TOTP ou um código de recuperação para POST mfa/complete/ com o challenge. Tem 5 tentativas. Para usar uma passkey, chame POST mfa/passkey/begin/ e POST mfa/passkey/complete/.
• Os códigos usam passos de 30 segundos. Um código já aceite não pode voltar a ser usado.
• Os códigos por SMS e por e-mail não estão disponíveis como segundo fator.

​

Recuperação e reposição da palavra-passe

POST password-reset/start/ recebe email e devolve 202 {"status": "sent", "expires_in": 1800}. A resposta é a mesma, tenha ou não conta associada ao endereço. A ligação de reposição é válida durante 30 minutos. POST password-reset/complete/ recebe token e password e devolve {"status": "password_changed"}. Além disso:

• remove um bloqueio,
• termina todas as sessões quando revoke_on_password_change está ativado (o valor predefinido),
• invalida os outros códigos e ligações pendentes dessa pessoa.

​

Convites

Com signup_policy: "invited", só as pessoas convidadas podem criar conta. Uma ligação de convite é válida durante 7 dias e abre a página /invite alojada. Continue com tokens e JWKS, ou leia proteção contra bots para bloqueios e desafios.