Exemplo de diagrama de sequência: o fluxo de código de autorização do OAuth 2.0 com PKCE

Um diagrama de arquitetura mostra quem fala com quem. Ele não consegue mostrar em que ordem nem quem espera por quem, e em muitos problemas essa ordem é a história inteira. Fluxos de login são o caso clássico: as mesmas cinco mensagens em outra ordem são uma falha de segurança.

Este guia ensina a notação de diagramas de sequência com um fluxo que quase todo engenheiro encontra cedo ou tarde: uma aplicação de página única que faz o login de um usuário com o fluxo de código de autorização do OAuth 2.0 e PKCE e depois chama uma API.

O que um diagrama de sequência mostra

O tempo corre para baixo. Cada participante tem uma linha de vida, uma caixa com uma linha tracejada embaixo, e cada mensagem é uma seta horizontal do remetente para o destinatário. Ler de cima para baixo dá a ordem dos eventos; ler na horizontal mostra quem participa de cada passo.

A notação, segundo a especificação UML 2.5.1:

O fluxo: código de autorização com PKCE

Uma aplicação de página única é um cliente público: tudo o que ela envia ao navegador pode ser lido, então ela não consegue guardar um client secret. O PKCE, definido na RFC 7636, protege o código de autorização mesmo assim: a aplicação prova que quem troca o código é a mesma instância que iniciou o fluxo. A melhor prática atual de segurança do OAuth 2.0, a RFC 9700, exige PKCE para clientes públicos, recomenda para todos os outros e diz que os clientes não devem usar o implicit grant.

Os passos:

1. O usuário seleciona Entrar.
2. A aplicação cria um code verifier e um challenge. O code_verifier é uma string aleatória de 43 a 128 caracteres. O code_challenge é BASE64URL(SHA256(code_verifier)), o método S256. A aplicação também guarda um state aleatório.
3. A aplicação manda o navegador para o endpoint de autorização com o challenge:

GET /authorize?response_type=code
    &client_id=orders-spa
    &redirect_uri=https%3A%2F%2Fapp.example.com%2Fcallback
    &scope=orders.read
    &state=af0ifjsldkj
    &code_challenge=E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM
    &code_challenge_method=S256 HTTP/1.1
Host: auth.example.com

4. O servidor de autorização faz o login do usuário e pede o consentimento.
5. Ele redireciona de volta para a redirect_uri com um code de vida curta e o mesmo state.
6. A aplicação confere o state com o valor que guardou.
7. A aplicação troca o código no endpoint de token, enviando o verifier que guardou:

POST /token HTTP/1.1
Host: auth.example.com
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code&code=SplxlOBeZQQYbYS6WxSbIA
&redirect_uri=https%3A%2F%2Fapp.example.com%2Fcallback
&client_id=orders-spa&code_verifier=dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk

8. O servidor de autorização calcula o hash do verifier e compara o resultado com o challenge do passo 3. Se baterem, ele devolve um access token e, se emitir, um refresh token.
9. A aplicação chama a API com Authorization: Bearer <access token>.
10. A API valida o token, por exemplo a assinatura, o emissor, a audiência, a expiração e o escopo, e responde.

O verifier e o challenge acima são os valores de exemplo da RFC 7636, então você pode conferir o cálculo S256 por conta própria.

O diagrama

Como ler:

• Quatro participantes em uma fileira: o usuário como ator e, depois, as linhas de vida do app de navegador, do servidor de autorização e da API. Cada mensagem é uma seta horizontal na sua própria altura, numerada em ordem.
• As mensagens 2 a 7 são o fluxo de código de autorização. As notas mostram as duas checagens que o tornam seguro: a aplicação compara o state depois do redirecionamento, e o servidor de autorização compara o hash do verifier com o challenge.
• As mensagens 8 e 9 são a chamada à API. As respostas são tracejadas, com pontas de seta abertas.
• O fragmento opt cobre o caso em que o access token expirou: um 401, uma renovação e uma nova tentativa.

Mostre o caminho de falha, não só o caminho feliz

A maioria dos diagramas de sequência para no "200 OK". Os bugs interessantes moram nas ramificações, então desenhe pelo menos a que acontece todo dia. Use alt quando o diagrama mostrar várias ramificações mutuamente exclusivas, cada uma com uma guarda, e opt para uma parte que só roda quando a sua guarda é verdadeira. A renovação aqui é um opt: ela só acontece quando o access token expirou.

A ramificação de renovação tem regras próprias. Em apps de navegador, refresh tokens costumam ser bearer tokens, por isso a RFC 9700 e a RFC 10017, a melhor prática atual para aplicações baseadas em navegador publicada em agosto de 2026, exigem que o servidor de autorização faça a rotação deles a cada uso ou os vincule ao cliente, e que limite o tempo de vida. É por isso que a mensagem 13 devolve um novo refresh token.

A RFC 10017 também ordena as arquiteturas de apps de navegador por segurança. Um backend-for-frontend que mantém os tokens no servidor é a mais forte; um app de navegador que age como cliente OAuth, como neste diagrama, é a mais simples e a mais exposta a JavaScript malicioso. Se você escolher o padrão de navegador, o diagrama é um bom lugar para registrar o porquê.

Erros comuns em diagramas de sequência

• Linhas de vida demais. Passando de seis ou sete, os rótulos se sobrepõem e o leitor perde o fio. Divida o fluxo ou agrupe os serviços internos atrás de uma linha de vida.
• Respostas sem rótulo. "Resposta" não diz nada. Escreva o status ou o conteúdo: "302 com code", "401 invalid_token".
• Níveis de detalhe misturados. Parâmetros HTTP em uma seta e "usuário está feliz" na seguinte confundem os dois públicos. Escolha um nível e mantenha.
• Só o caminho feliz. Timeouts, novas tentativas e credenciais expiradas são exatamente onde os diagramas se pagam.
• Todos os parâmetros. Mostre os que o leitor precisa conferir, como state, code_challenge e code_verifier, e deixe o resto para a referência da API.

Quando usar e quando não usar

Use um diagrama de sequência para protocolos, handshakes, novas tentativas, timeouts, condições de corrida e linhas do tempo de incidentes: tudo em que a ordem e a espera importam. Use outra coisa para estrutura estática (um diagrama de arquitetura ou C4), para eventos distribuídos a muitos consumidores (um diagrama de arquitetura orientada a eventos) e para revisões de segurança sobre onde os dados cruzam limites de confiança (um diagrama de fluxo de dados para modelagem de ameaças).

Monte no Archboard

1. Entre com Google ou GitHub e crie um diagrama.
2. Pelo pack Sequência, adicione um Ator para o usuário e três nós Linha de vida para o app de navegador, o servidor de autorização e a API, em uma fileira e na mesma altura.
3. Desenhe cada mensagem como uma conexão reta entre duas linhas de vida, de cima para baixo, com um rótulo numerado. Deixe as respostas tracejadas.
4. Adicione um Fragmento combinado em volta das mensagens 10 a 14, defina o operador como opt e o rótulo como "[access token expired]".
5. Adicione nós Nota do pack UML para as checagens: o state, o hash do verifier e a validação do token.

O exemplo usa 5 nós de diagrama e fica dentro do plano Free. O próprio servidor MCP do Archboard faz o login de apps de IA com este fluxo, o authorization code grant com PKCE (S256); veja como criar diagramas de arquitetura com agentes de IA.

Perguntas frequentes

PKCE é só para apps mobile? Não. Ele foi criado para apps nativos, mas a RFC 9700 exige PKCE para todos os clientes públicos, inclusive aplicações de página única, e também o recomenda para clientes confidenciais.

Uma aplicação de página única deve usar o fluxo implícito? Não. A RFC 9700 diz que os clientes não devem usar o implicit grant. Use o fluxo de código de autorização com PKCE.

O OAuth 2.1 é um padrão finalizado? Não no momento em que este texto foi escrito (outubro de 2026). Ele ainda é um Internet-Draft do IETF que consolida o OAuth 2.0 e suas práticas de segurança, incluindo o PKCE.

Qual é a diferença entre alt e opt? alt contém duas ou mais ramificações mutuamente exclusivas, cada uma com uma guarda. opt contém uma parte que só roda quando a sua guarda é verdadeira.

Quantas mensagens cabem em um diagrama de sequência? Tantas quantas continuarem legíveis no tamanho em que as pessoas o veem, geralmente de 15 a 20. Divida fluxos mais longos em vários diagramas, um por fase.

Comece grátis — um assento, sem cartão de crédito.