> ## Documentation Index
> Fetch the complete documentation index at: https://docs.didit.me/llms.txt
> Use this file to discover all available pages before exploring further.

# Guia de integração de autenticação: arquitetura e entrada em produção

> Como integrar o Didit Authentication em produção: ecrãs, tokens, verificações no backend, sessões, apps nativas e checklist de lançamento.

Este guia explica como funciona uma integração de produção do Didit Authentication, desde o primeiro redirecionamento até à lista de verificação para entrada em produção.
Comece pelo [guia de início rápido](https://docs.didit.me/pt/authentication/quickstart.md) se ainda não tiver autenticado uma pessoa, e use os guias de início rápido das plataformas para o código de cada SDK.

## Arquitetura

```mermaid theme={null}
sequenceDiagram
    participant App as Your app (browser or mobile)
    participant Hosted as Your Didit sign-in origin
    participant API as Your backend
    participant Webhook as Your webhook endpoint

    App->>Hosted: Open /sign-in (redirect_uri, state, PKCE challenge)
    Note over Hosted: Sign-in method, MFA,<br/>bot protection, verification
    Hosted-->>App: Redirect to redirect_uri with code and state
    App->>Hosted: POST /token/ (code, PKCE verifier)
    Hosted-->>App: Access token (5 min), ID token, refresh token
    App->>API: Request with Authorization: Bearer access token
    Note over API: Verify the signature<br/>with the cached JWKS
    API->>Hosted: GET /session/ before a sensitive action
    Hosted-->>API: Live session, or 401
    Hosted->>Webhook: auth.signup, auth.login, auth.new_device ...
```

Intervêm quatro componentes:

| Componente | Responsável por |
| - | - |
| A sua aplicação | Iniciar o processo de início de sessão, manter o verificador PKCE e o `state`, guardar os tokens e enviar o token de acesso para o seu backend. Os SDKs fazem tudo isto. |
| A sua origem de início de sessão | `https://<slug>.auth.didit.me` (ou o seu [domínio personalizado](https://docs.didit.me/pt/authentication/branding-and-custom-domain.md#domínio-personalizado)): as páginas alojadas, o endpoint do token, a sessão, a descoberta e as chaves de assinatura. |
| O seu backend | Verificar o token de acesso em cada pedido protegido, validar a sessão antes de ações sensíveis e decidir o que a pessoa pode fazer. |
| Consola Didit e webhooks | Configuração, as pessoas e as respetivas sessões, eventos de início de sessão e os webhooks `auth.*` que o seu servidor subscreve. |

Nunca deve existir uma chave de API da Didit nem um segredo na sua aplicação: a chave publicável é pública, e a troca do código é protegida por PKCE em vez de um segredo do cliente.

## Páginas alojadas ou os seus próprios ecrãs

Escolha onde as pessoas introduzem o e-mail, a palavra-passe ou o código.
A definição é `sign_in_ui` (`hosted` por omissão, ou `own`), e pode alterá-la mais tarde.

| | Páginas alojadas (recomendado) | Os seus próprios ecrãs |
| - | - | - |
| O que constrói | Um botão de início de sessão e uma página de retorno. | Todos os ecrãs e todos os passos intermédios. |
| Métodos | Todos, incluindo ligações mágicas, SSO da empresa e chaves de acesso. | Palavra-passe, código por e-mail, código por telefone, MFA e desafios de proteção através dos métodos sem interface dos SDKs. As ligações mágicas funcionam apenas nas páginas alojadas. |
| Próximos passos | Tratados por si: MFA, inscrição no MFA, desafios de proteção e verificação no registo. | Os seus ecrãs tratam `mfa_required`, `mfa_enrollment_required`, `protection_required` e `verification_required`. Consulte [métodos de início de sessão](https://docs.didit.me/pt/authentication/sign-in-methods.md). |
| Marca | O seu logótipo, cores e textos a partir de [marca](https://docs.didit.me/pt/authentication/branding-and-custom-domain.md). | Totalmente seus. |
| Configuração | URLs de redirecionamento. | URLs de redirecionamento, além da sua origem web em **Allowed origins**. |

As chaves de acesso pertencem à origem de início de sessão da sua aplicação.
Os métodos de chaves de acesso dos SDKs funcionam apenas em páginas servidas a partir dessa origem. Por isso, nos seus próprios ecrãs num domínio diferente, encaminhe as pessoas para a página alojada para usar chaves de acesso.

## Escolha o seu SDK

| A sua aplicação | Pacote | Onde ficam os tokens |
| - | - | - |
| Aplicação web de página única | [`@didit-protocol/auth`](https://docs.didit.me/pt/authentication/quickstarts/javascript) ou [`@didit-protocol/auth-react`](https://docs.didit.me/pt/authentication/quickstarts/react) | Armazenamento web ou memória do navegador. Mantenha uma Política de Segurança de Conteúdo (CSP) rigorosa. |
| Aplicação web renderizada no servidor | [`@didit-protocol/auth-nextjs`](https://docs.didit.me/pt/authentication/quickstarts/nextjs) | Cookies HttpOnly definidos pelo seu servidor. A página nunca vê os tokens. |
| iOS | [`DiditAuth`](https://docs.didit.me/pt/authentication/quickstarts/ios) | O Keychain. |
| Android | [`me.didit:didit-auth`](https://docs.didit.me/pt/authentication/quickstarts/android) | Armazenamento protegido pelo Android Keystore. |
| React Native ou Flutter | [`@didit-protocol/auth-react-native`](https://docs.didit.me/pt/authentication/quickstarts/react-native) ou [`didit_auth`](https://docs.didit.me/pt/authentication/quickstarts/flutter) | O armazenamento protegido da plataforma, através dos módulos nativos. |
| Qualquer backend | [SDKs para servidor](https://docs.didit.me/pt/integration/server-sdks/overview.md), `verifyToken` de `@didit-protocol/auth/server`, ou qualquer biblioteca JWT | Nada para guardar: verifica o token que recebe. |

Sem um SDK, implemente você mesmo o fluxo de código de autorização com PKCE: o [início rápido em JavaScript](https://docs.didit.me/pt/authentication/quickstarts/javascript.md#sem-o-sdk) mostra o contrato completo.

## Proteja o seu backend

Uma verificação da sessão no frontend controla apenas o que mostra.
O seu backend toma todas as decisões com base num token verificado.

1. **Verifique o token de acesso em cada pedido.** Valide a assinatura ES256 com o JWKS do seu emissor e, depois, `iss`, `aud`, `exp` e `typ: at+jwt`. Rejeite um token cujo `act` não seja `null`, a menos que a rota aceite [agentes de IA](https://docs.didit.me/pt/authentication/agent-access.md). Consulte [verificar um token no seu servidor](https://docs.didit.me/pt/authentication/tokens-and-jwks.md#verifique-um-token-no-seu-servidor).
2. **Verifique a sessão ativa antes de uma ação sensível.** Um token de acesso mantém-se válido até expirar, no máximo 5 minutos. `GET /session/` falha de imediato quando a sessão foi revogada, ficou inativa ou expirou, quando a pessoa foi bloqueada ou quando a sessão deixa de cumprir a sua política de MFA. Consulte [verificar a sessão](https://docs.didit.me/pt/authentication/tokens-and-jwks.md#verifique-a-sessão).
3. **Peça uma verificação adicional quando a ação for arriscada.** Antes de um pagamento a beneficiário, de uma nova conta bancária ou de uma alteração de e-mail ou de telefone, pergunte à Didit se a pessoa tem de voltar a verificar-se, e atue apenas com base num step-up `approved` que o seu backend tenha lido por si próprio. Consulte [step-up antes de ações sensíveis](https://docs.didit.me/pt/authentication/verified-identity.md#verificação-reforçada-antes-de-ações-sensíveis).
4. **Obtenha o `vendor_data` a partir do token verificado**, nunca de um campo enviado pelo navegador, e use-o nas verificações e transações da pessoa.

## Sessões

| Evento | O que acontece |
| - | - |
| Início de sessão | Uma sessão começa. A duração é o valor de `session_lifetime` (30 dias por predefinição) e a sessão termina mais cedo, após o período de `idle_timeout` sem atividade (1 dia por predefinição). |
| A cada poucos minutos | O SDK renova o token de acesso, que dura no máximo 5 minutos. O token de atualização é rotacionado: cada um só funciona uma vez. |
| Um token de atualização já usado é enviado de novo | A Didit trata-o como roubo e termina a sessão. Execute apenas uma renovação de cada vez por sessão. |
| Início de sessão noutro dispositivo | Com `multiple_sessions: false`, as outras sessões da pessoa terminam. |
| Redefinição da palavra-passe | Todas as sessões terminam quando `revoke_on_password_change` está ativo (o valor predefinido). |
| Terminar sessão | `DELETE /session/` termina a sessão, e a sua aplicação envia a pessoa para o seu `post_logout_redirect_uri`. |
| A sua equipa age | A consola pode revogar uma sessão, terminar as sessões da pessoa em todo o lado ou bloqueá-la. Consulte o [guia da consola](https://docs.didit.me/pt/authentication/console.md#inícios-de-sessão-e-sessões). |

Altere as durações em **Authentication > Security and sessions**, ou por API, nas [definições da aplicação](https://docs.didit.me/pt/authentication/overview.md#definições-da-aplicação).

![A vista Active sessions na Didit Business Console, com a lista das sessões iniciadas, incluindo dispositivo, localização, início, última atividade, fim e um botão Revoke](https://mintcdn.com/didit-0f962782/RpqZjIB1GnUPdMTN/images/authentication/console-active-sessions.png?fit=max\&auto=format\&n=RpqZjIB1GnUPdMTN\&q=85\&s=098f6be31804b0af7c680e569f341bfb)

Authentication > Sign-ins > Active sessions, com Revoke em cada sessão.

## Aplicações nativas

A Didit só redireciona as pessoas para uma aplicação nativa através de um redirecionamento HTTPS: não aceita esquemas de URL personalizados.

* **iOS:** configure o redirecionamento como um domínio associado, com `webcredentials` no seu `apple-app-site-association`.
* **Android:** configure o redirecionamento como um App Link, com o seu `assetlinks.json`.
* Registe cada URL de redirecionamento em **Authentication > Security and sessions**, tal como um callback web.

Para usar passkeys na sua aplicação, registe as aplicações que partilham as passkeys da sua aplicação com `PUT native-apps/` na [API de gestão de autenticação](https://docs.didit.me/pt/authentication/set-up-by-api.md).
A Didit inclui-as depois na lista do `apple-app-site-association` e do `assetlinks.json` que disponibiliza na sua origem de início de sessão.
`MANAGEMENT_BASE` é o endereço da API de gestão da sua aplicação, e uma chave de API com o âmbito `authentication` e permissão **write** pode fazer a chamada.
A chamada substitui ambas as listas, por isso envie as duas:

```bash theme={null}
curl --fail-with-body --request PUT "${MANAGEMENT_BASE}native-apps/" \
  -H "x-api-key: $DIDIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "ios_app_ids": ["ABCDE12345.com.example.app"],
    "android_apps": [
      {
        "package_name": "com.example.app",
        "sha256_cert_fingerprints": ["14:6D:E9:83:C5:73:06:50:D8:EE:B9:95:2F:34:FC:64:16:A0:83:42:E6:1D:BE:A8:8A:04:96:B2:3F:CF:44:E5"]
      }
    ]
  }'
```

| Campo | Regra |
| - | - |
| `ios_app_ids` | Até 10 entradas, cada uma com o seu Team ID e identificador do bundle, por exemplo `ABCDE12345.com.example.app`. |
| `android_apps` | Até 10 aplicações, cada uma com o seu `package_name` e de 1 a 5 impressões digitais SHA-256 do certificado de assinatura. |

Os guias de início rápido para [iOS](https://docs.didit.me/pt/authentication/quickstarts/ios.md) e [Android](https://docs.didit.me/pt/authentication/quickstarts/android.md) mostram o lado da aplicação.

## Ligar a verificação de identidade e a monitorização de transações

Cada pessoa tem um valor `vendor_data`, nos seus tokens e na sua sessão.
Use-o como `vendor_data` ao [criar uma sessão de verificação](https://docs.didit.me/pt/sessions-api/create-session.md) ou ao [submeter uma transação](https://docs.didit.me/pt/transaction-monitoring/transactions.md), e a consola mostra os inícios de sessão, as verificações e as transações da mesma pessoa.

* Para verificar pessoas no registo ou novamente antes de um pagamento, sem criar um fluxo de verificação, use a [identidade verificada](https://docs.didit.me/pt/authentication/verified-identity.md).
* Os eventos de início de sessão chegam automaticamente às [regras de eventos](https://docs.didit.me/pt/transaction-monitoring/event-rules.md) e às vistas de fraude. Não envie os seus próprios eventos `auth.login` para os mesmos inícios de sessão.
* Um início de sessão bem-sucedido nunca aprova uma verificação ou uma transação: trate a decisão de cada produto separadamente.

Consulte [manter a mesma pessoa em todos os produtos](https://docs.didit.me/pt/authentication/overview.md#manter-uma-só-pessoa-em-todos-os-produtos).

## Receber eventos de início de sessão

Subscreva um [destino do webhook](https://docs.didit.me/pt/integration/webhooks.md) para os tipos `auth.*` de que precisa, como `auth.new_device` ou `auth.account_locked`.
Deduplique por `auth_event.event_id` e verifique a assinatura tal como faz para qualquer webhook da Didit.
Consulte [eventos e webhooks](https://docs.didit.me/pt/authentication/events-and-webhooks.md) para ver todos os tipos e o respetivo payload.

## Migrar utilizadores existentes

Se os seus utilizadores já tiverem contas noutra plataforma de identidade ou na sua própria base de dados, [importe-os](https://docs.didit.me/pt/authentication/migration.md) antes de mudar o início de sessão.
Importe os hashes de palavra-passe dos utilizadores sempre que a origem os fornecer, mantenha as ligações sociais e guarde os seus IDs de utilizador como `external_id`, que passa a ser o `vendor_data` de cada utilizador.
Nada muda para os utilizadores até mudar a sua aplicação para a Didit.

## Lista de verificação antes de passar para produção

1. A autenticação está ativada na sua aplicação Live, na página **Products**.
2. Os seus URLs de redirecionamento `https://` de produção e as origens permitidas estão registados na aplicação Live. Uma aplicação Live não aceita endereços `http://`.
3. Cada método de início de sessão social usa o ID de cliente e o segredo da sua própria aplicação: as credenciais de teste da Didit só funcionam no Sandbox.
4. A sua configuração de produção tem a chave publicável Live (`pk_live_`) e o seu emissor Live.
5. A sua política de MFA, a duração da sessão, o tempo limite de inatividade, o comprimento da palavra-passe e a política de registo estão como pretende. Consulte as [definições da aplicação](https://docs.didit.me/pt/authentication/overview.md#definições-da-aplicação).
6. A [proteção contra bots](https://docs.didit.me/pt/authentication/bot-protection.md) está ativada, com a verificação de palavras-passe comprometidas.
7. O seu backend verifica todos os tokens de acesso e chama `GET /session/` antes de ações sensíveis.
8. A sua identidade visual, os textos das páginas e as ligações para os termos e para a política de privacidade estão definidos. Se planeia usar um [domínio personalizado](https://docs.didit.me/pt/authentication/branding-and-custom-domain.md#domínio-personalizado), ative-o antes de as pessoas começarem a adicionar chaves de acesso.
9. O seu destino do webhook está subscrito aos tipos `auth.*` que trata.
10. Testou na aplicação Live o registo, o início de sessão de quem já tem conta, o cancelamento, o fluxo de palavra-passe esquecida, a MFA, a expiração de sessão, o fim de sessão e uma sessão revogada.

## Resolução de problemas

| Sintoma | Causa e correção |
| - | - |
| Todas as rotas em tempo de execução respondem com `404` | A autenticação está desativada para a aplicação, ou o endereço mistura uma origem de sandbox com uma origem de produção. Ative-a na página **Products** e use a origem indicada na sua chave publicável. |
| A página de início de sessão responde com `400` e pede que registe um endereço, ou `POST /authorize/` responde com `invalid_redirect_uri` | O `redirect_uri` não está registado exatamente: o esquema, o host, a porta, o caminho e a cadeia de consulta têm de corresponder carácter a carácter. Consulte [URLs de redirecionamento](https://docs.didit.me/pt/authentication/overview.md#urls-de-redirecionamento). |
| Uma chamada do navegador à sua origem de início de sessão responde com `403` e `origin_not_allowed` | A sua origem web não está em **Allowed origins**. Adicione-a sem caminho e sem barra final. |
| `POST /token/` responde com `invalid_grant` | O código já foi utilizado, tem mais de 60 segundos, ou foi enviado com outro verificador PKCE ou outro `redirect_uri`. Numa renovação, o token de atualização já tinha sido utilizado, o que termina a sessão. Inicie novamente o processo de início de sessão. |
| Um início de sessão com palavra-passe responde com `invalid_credentials` mesmo com a palavra-passe correta | O e-mail não está verificado, ou a conta está bloqueada ou impedida. A Didit dá a mesma resposta de propósito. Verifique a pessoa em **Users**. |
| `GET /session/` responde com `401` | A sessão foi revogada, ficou inativa ou expirou, a pessoa foi bloqueada, o token foi substituído numa operação de renovação, ou a sessão deixou de cumprir a sua política de MFA. Renove o token ou volte a autenticar a pessoa. |
| Adicionar uma chave de acesso ou um autenticador responde com `403 reauthentication_required` | Estas operações requerem uma sessão criada nos últimos 5 minutos. Volte primeiro a autenticar a pessoa. |
| Um código por telefone responde com `503 delivery_unavailable` | O código não pôde ser entregue. Deixe a pessoa tentar novamente ou ofereça outro método. |
| Uma chamada responde com `429` | Atingiu um limite de pedidos. Tente novamente após o tempo indicado em `Retry-After`. Consulte [limites de pedidos](https://docs.didit.me/pt/authentication/bot-protection.md#limites-de-pedidos). |
| Uma chamada de configuração com uma chave de API responde com `409 product_disabled` | A autenticação está desativada para a aplicação. Uma pessoa ativa-a na consola. |
| Uma chamada responde com `403 plan_required` | A funcionalidade, como funções personalizadas ou ligações de configuração de SSO da empresa, requer o plano Scale ou Enterprise. As aplicações de sandbox têm-na ativa em qualquer plano. |
| Os tokens falham depois de ativar um domínio personalizado | O emissor e a chave publicável mudaram. Copie a nova chave para a sua aplicação e atualize o emissor que o seu sistema de back-end verifica. |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.