Ejemplo de diagrama de secuencia: el flujo de código de autorización de OAuth 2.0 con PKCE

Un diagrama de arquitectura muestra quién habla con quién. No puede mostrar en qué orden ni quién espera a quién, y en muchos problemas ese orden es toda la historia. Los flujos de inicio de sesión son el caso clásico: los mismos cinco mensajes en otro orden son un fallo de seguridad.

Esta guía enseña la notación de los diagramas de secuencia con un flujo que la mayoría de los ingenieros se encuentra tarde o temprano: una aplicación de una sola página que inicia la sesión de un usuario con el flujo de código de autorización de OAuth 2.0 y PKCE, y después llama a una API.

Qué muestra un diagrama de secuencia

El tiempo avanza hacia abajo. Cada participante tiene una línea de vida, una caja con una línea discontinua debajo, y cada mensaje es una flecha horizontal del emisor al receptor. Leer de arriba abajo te da el orden de los eventos; leer de lado a lado te dice quién participa en cada paso.

La notación, según la especificación UML 2.5.1:

El flujo: código de autorización con PKCE

Una aplicación de una sola página es un cliente público: todo lo que envía al navegador se puede leer, así que no puede guardar un secreto de cliente. PKCE, definido en la RFC 7636, protege igualmente el código de autorización: la aplicación demuestra que quien canjea el código es la misma instancia que inició el flujo. La mejor práctica actual de seguridad de OAuth 2.0, la RFC 9700, exige PKCE para los clientes públicos, lo recomienda para todos los demás y dice que los clientes no deberían usar el implicit grant.

Los pasos:

1. El usuario selecciona Iniciar sesión.
2. La aplicación crea un code verifier y un challenge. El code_verifier es una cadena aleatoria de 43 a 128 caracteres. El code_challenge es BASE64URL(SHA256(code_verifier)), el método S256. La aplicación también guarda un state aleatorio.
3. La aplicación envía el navegador al endpoint de autorización con el 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. El servidor de autorización inicia la sesión del usuario y le pide su consentimiento.
5. Redirige de vuelta a la redirect_uri con un code de vida corta y el mismo state.
6. La aplicación comprueba el state contra el valor que guardó.
7. La aplicación canjea el código en el endpoint de token y envía el verifier que conservó:

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. El servidor de autorización calcula el hash del verifier y compara el resultado con el challenge del paso 3. Si coinciden, devuelve un token de acceso y, si los emite, un token de actualización.
9. La aplicación llama a la API con Authorization: Bearer <access token>.
10. La API valida el token, por ejemplo su firma, emisor, audiencia, caducidad y scope, y responde.

El verifier y el challenge de arriba son los valores de ejemplo de la RFC 7636, así que puedes comprobar el cálculo S256 tú mismo.

El diagrama

Cómo leerlo:

• Cuatro participantes en una fila: el usuario como actor y, después, las líneas de vida de la app de navegador, el servidor de autorización y la API. Cada mensaje es una flecha horizontal a su propia altura, numerada en orden.
• Los mensajes 2 a 7 son el flujo de código de autorización. Las notas muestran las dos comprobaciones que lo hacen seguro: la aplicación compara el state tras la redirección y el servidor de autorización compara el hash del verifier con el challenge.
• Los mensajes 8 y 9 son la llamada a la API. Las respuestas son discontinuas y con punta de flecha abierta.
• El fragmento opt cubre el caso en que el token de acceso ha caducado: un 401, una renovación y un reintento.

Muestra el camino del fallo, no solo el camino feliz

La mayoría de los diagramas de secuencia se detienen en "200 OK". Los bugs interesantes viven en las ramas, así que dibuja al menos la que ocurre todos los días. Usa alt cuando el diagrama muestre varias ramas mutuamente excluyentes, cada una con una guarda, y opt para una parte que solo se ejecuta cuando su guarda es verdadera. La renovación de aquí es un opt: solo ocurre cuando el token de acceso ha caducado.

La rama de renovación tiene sus propias reglas. En las aplicaciones de navegador, los tokens de actualización suelen ser bearer tokens, así que la RFC 9700 y la RFC 10017, la mejor práctica actual para aplicaciones basadas en navegador publicada en agosto de 2026, exigen que el servidor de autorización los rote en cada uso o los vincule al cliente, y que limite su vida útil. Por eso el mensaje 13 devuelve un token de actualización nuevo.

La RFC 10017 también ordena por seguridad las arquitecturas para aplicaciones de navegador. Un backend-for-frontend que guarda los tokens en el servidor es la más sólida; una aplicación de navegador que actúa como cliente OAuth, como en este diagrama, es la más sencilla y la más expuesta a JavaScript malicioso. Si eliges el patrón de navegador, el diagrama es un buen lugar para explicar por qué.

Errores habituales en los diagramas de secuencia

• Demasiadas líneas de vida. Pasadas seis o siete, las etiquetas chocan y el lector pierde el hilo. Divide el flujo o agrupa los servicios internos detrás de una sola línea de vida.
• Respuestas sin etiqueta. "Respuesta" no dice nada. Escribe el estado o el contenido: "302 con code", "401 invalid_token".
• Niveles de detalle mezclados. Parámetros HTTP en una flecha y "el usuario está contento" en la siguiente confunden a los dos públicos. Elige un nivel y mantenlo.
• Solo el camino feliz. Los timeouts, los reintentos y las credenciales caducadas son justo donde los diagramas se ganan su sitio.
• Todos los parámetros. Muestra los que el lector debe comprobar, como state, code_challenge y code_verifier, y deja el resto para la referencia de la API.

Cuándo usarlo y cuándo no

Usa un diagrama de secuencia para protocolos, handshakes, reintentos, timeouts, condiciones de carrera y cronologías de incidentes: todo lo que dependa del orden y de las esperas. Usa otra cosa para la estructura estática (un diagrama de arquitectura o C4), para la difusión de eventos a muchos consumidores (un diagrama de arquitectura orientada a eventos) y para revisiones de seguridad sobre dónde cruzan los datos los límites de confianza (un diagrama de flujo de datos para el modelado de amenazas).

Constrúyelo en Archboard

1. Inicia sesión con Google o GitHub y crea un diagrama.
2. Desde el pack Secuencia, añade un Actor para el usuario y tres nodos Línea de vida para la app de navegador, el servidor de autorización y la API, en una fila y a la misma altura.
3. Dibuja cada mensaje como una conexión recta entre dos líneas de vida, de arriba abajo, con una etiqueta numerada. Pon las respuestas en discontinuo.
4. Añade un Fragmento combinado alrededor de los mensajes 10 a 14, pon su operador en opt y su etiqueta en "[access token expired]".
5. Añade nodos Nota del pack UML para las comprobaciones: el state, el hash del verifier y la validación del token.

El ejemplo usa 5 nodos de diagrama, dentro del plan Free. El propio servidor MCP de Archboard inicia la sesión de las aplicaciones de IA con este flujo, el authorization code grant con PKCE (S256); consulta cómo crear diagramas de arquitectura con agentes de IA.

Preguntas frecuentes

¿PKCE es solo para aplicaciones móviles? No. Se diseñó para aplicaciones nativas, pero la RFC 9700 lo exige para todos los clientes públicos, incluidas las aplicaciones de una sola página, y también lo recomienda para los clientes confidenciales.

¿Debe una aplicación de una sola página usar el flujo implícito? No. La RFC 9700 dice que los clientes no deberían usar el implicit grant. Usa el flujo de código de autorización con PKCE.

¿OAuth 2.1 es un estándar terminado? No en el momento de escribir esto (octubre de 2026). Sigue siendo un Internet-Draft del IETF que reúne OAuth 2.0 y sus prácticas de seguridad, incluido PKCE.

¿Qué diferencia hay entre alt y opt? alt contiene dos o más ramas mutuamente excluyentes, cada una con una guarda. opt contiene una parte que solo se ejecuta cuando su guarda es verdadera.

¿Cuántos mensajes caben en un diagrama de secuencia? Tantos como sigan siendo legibles al tamaño en que la gente lo mira, normalmente entre 15 y 20. Divide los flujos más largos en varios diagramas, uno por fase.

Empieza gratis — un puesto, sin tarjeta de crédito.