StackPractices
advanced Por Mathias Paulenko

Patrón Federated Identity

Delega la autenticación a proveedores de identidad externos. Un patrón para integrar OAuth2, OIDC, SAML y SSO entre múltiples servicios y organizaciones.

Visión General

El patrón Federated Identity delega la autenticación a un proveedor de identidad externo (IdP) en lugar de gestionar credenciales dentro de tu aplicación. Los usuarios inician sesión a través de un tercero de confianza — Google, GitHub, Microsoft Entra ID, Okta — y la aplicación recibe un token firmado que puede verificar sin tocar jamás una contraseña.

La ventaja inmediata es la responsabilidad: sin tabla de contraseñas no hay brechas de credenciales, ni flujos de restablecimiento que mantener, ni superficie de credential stuffing. La ventaja estructural es el single sign-on — un solo inicio de sesión en el IdP autentica al usuario en silencio en todas las aplicaciones confiadas, que es exactamente lo que las empresas quieren decir cuando piden “SSO” en una lista de requisitos.

Cuándo Usarlo

  • No quieres almacenar ni gestionar contraseñas de usuarios
  • Los usuarios ya tienen cuentas en Google, GitHub, Microsoft u Okta
  • Varias aplicaciones necesitan single sign-on en una organización
  • Debes autenticar usuarios de organizaciones aliadas sin crear cuentas locales
  • Los requisitos de cumplimiento exigen gestión de identidad centralizada (SOC2, HIPAA)

La identidad federada es excesiva cuando tu base de usuarios son unos pocos administradores internos, cuando operas completamente offline, o cuando la regulación prohíbe procesadores externos en la ruta de autenticación. Un login local sencillo supera a una integración OIDC a medio configurar siempre.

Solución

Flujo de authorization code: el usuario inicia sesión, la app redirige al proveedor de identidad con state y PKCE, el proveedor devuelve un código de autorización, la app lo intercambia por tokens y verifica el JWT contra el JWKS del proveedor.

Los ejemplos de abajo implementan el flujo completo de authorization code: redirigir al IdP, intercambiar el código por tokens y luego verificar la firma del ID token contra las claves publicadas por el proveedor.

Python (FastAPI + OAuth2/OIDC)

from fastapi import FastAPI, HTTPException, Depends, Header
from fastapi.responses import RedirectResponse
import httpx
import jwt
import time

app = FastAPI()

GOOGLE_CLIENT_ID = "your-client-id"
GOOGLE_CLIENT_SECRET = "your-client-secret"
GOOGLE_REDIRECT_URI = "http://localhost:8000/auth/callback"
GOOGLE_DISCOVERY = "https://accounts.google.com/.well-known/openid-configuration"

async def get_google_discovery():
    async with httpx.AsyncClient() as client:
        resp = await client.get(GOOGLE_DISCOVERY)
        return resp.json()

async def extract_user(authorization: str = Header(None)):
    if not authorization or not authorization.startswith("Bearer "):
        raise HTTPException(status_code=401, detail="Missing token")
    token = authorization.split(" ")[1]
    discovery = await get_google_discovery()
    jwks_client = jwt.PyJWKClient(discovery["jwks_uri"])
    try:
        signing_key = jwks_client.get_signing_key_from_jwt(token)
        decoded = jwt.decode(
            token,
            signing_key.key,
            algorithms=["RS256"],
            audience=GOOGLE_CLIENT_ID,
        )
        return decoded
    except jwt.PyJWTError:
        raise HTTPException(status_code=401, detail="Invalid token")

@app.get("/auth/login")
async def login():
    discovery = await get_google_discovery()
    auth_url = (
        f"{discovery['authorization_endpoint']}"
        f"?client_id={GOOGLE_CLIENT_ID}"
        f"&redirect_uri={GOOGLE_REDIRECT_URI}"
        f"&response_type=code"
        f"&scope=openid email profile"
    )
    return RedirectResponse(auth_url)

@app.get("/auth/callback")
async def callback(code: str):
    discovery = await get_google_discovery()
    async with httpx.AsyncClient() as client:
        token_resp = await client.post(
            discovery["token_endpoint"],
            data={
                "code": code,
                "client_id": GOOGLE_CLIENT_ID,
                "client_secret": GOOGLE_CLIENT_SECRET,
                "redirect_uri": GOOGLE_REDIRECT_URI,
                "grant_type": "authorization_code",
            },
        )
        tokens = token_resp.json()

    id_token = tokens.get("id_token")
    jwks_client = jwt.PyJWKClient(discovery["jwks_uri"])
    signing_key = jwks_client.get_signing_key_from_jwt(id_token)
    decoded = jwt.decode(
        id_token,
        signing_key.key,
        algorithms=["RS256"],
        audience=GOOGLE_CLIENT_ID,
    )
    return {
        "user": {
            "email": decoded["email"],
            "name": decoded["name"],
            "sub": decoded["sub"],
        },
        "access_token": tokens["access_token"],
    }

@app.get("/protected")
async def protected(user: dict = Depends(extract_user)):
    return {"message": f"Hello {user['email']}"}

Dos detalles importan en esta versión. extract_user se define antes de cualquier endpoint que dependa de él — referenciarlo antes lanza NameError al importar, porque Depends() se evalúa inmediatamente. Y ambas verificaciones de token consultan las JWKS del IdP y validan firma, audiencia y expiración; decodificar con verify_signature=False acepta tokens falsificados.

En producción, lee el client secret de una variable de entorno o gestor de secretos, y cachea el documento de discovery y las JWKS en lugar de descargarlos en cada petición.

JavaScript (Express + OIDC)

const express = require("express");
const { auth } = require("express-openid-connect");

const app = express();

app.use(
    auth({
        issuerBaseURL: "https://accounts.google.com",
        baseURL: "http://localhost:3000",
        clientID: "your-client-id",
        secret: "your-secret-key",
        authRequired: false,
        auth0Logout: true,
        routes: {
            login: "/auth/login",
            callback: "/auth/callback",
            logout: "/auth/logout",
        },
    })
);

app.get("/", (req, res) => {
    if (req.oidc.isAuthenticated()) {
        res.json({
            user: req.oidc.user,
            token: req.oidc.accessToken,
        });
    } else {
        res.json({ message: "Not authenticated. Visit /auth/login" });
    }
});

app.get("/profile", (req, res) => {
    if (!req.oidc.isAuthenticated()) {
        return res.status(401).json({ error: "Unauthorized" });
    }
    res.json({ user: req.oidc.user });
});

app.listen(3000);

express-openid-connect resuelve discovery, validación JWKS, el parámetro state y las cookies de sesión por ti — por eso la versión con middleware es el default correcto para apps Node. Escribir tu propio flujo solo merece la pena cuando necesitas mapeo de claims personalizado o un proveedor fuera de lo estándar.

Java (Spring Security + OAuth2)

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.security.config.annotation.web.builders.HttpSecurity;
import org.springframework.security.config.annotation.web.configuration.EnableWebSecurity;
import org.springframework.security.oauth2.client.oidc.web.logout.OidcClientInitiatedLogoutSuccessHandler;
import org.springframework.security.oauth2.client.registration.ClientRegistrationRepository;
import org.springframework.security.web.SecurityFilterChain;
import org.springframework.context.annotation.Bean;
import org.springframework.security.core.annotation.AuthenticationPrincipal;
import org.springframework.security.oauth2.core.oidc.user.OidcUser;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RestController;

@SpringBootApplication
@RestController
public class FederatedIdentityApp {

    @GetMapping("/user")
    public String user(@AuthenticationPrincipal OidcUser principal) {
        if (principal == null) return "Not authenticated";
        return "Hello, " + principal.getFullName() + " (" + principal.getEmail() + ")";
    }

    @Bean
    public SecurityFilterChain filterChain(HttpSecurity http,
            ClientRegistrationRepository repo) throws Exception {
        http
            .authorizeHttpRequests(auth -> auth
                .requestMatchers("/user").authenticated()
                .anyRequest().permitAll()
            )
            .oauth2Login(oauth -> {})
            .logout(logout -> logout
                .logoutSuccessHandler(
                    new OidcClientInitiatedLogoutSuccessHandler(repo)
                )
            );
        return http.build();
    }

    public static void main(String[] args) {
        SpringApplication.run(FederatedIdentityApp.class, args);
    }
}

// application.yml:
// spring.security.oauth2.client.registration.google.client-id=xxx
// spring.security.oauth2.client.registration.google.client-secret=xxx

Spring Security conecta todo el flujo solo desde configuración — oauth2Login dispara el baile de redirección y callback, y OidcClientInitiatedLogoutSuccessHandler propaga el logout al IdP para que la sesión SSO realmente termine.

Explicación

El patrón reparte el trabajo de identidad entre tres actores:

  • Proveedor de Identidad (IdP) — Google, GitHub, Entra ID, Okta. Posee las credenciales, ejecuta el flujo de login, firma los tokens.
  • Relying Party (RP) — esa es tu app, la que confía en las firmas del IdP. Recibe tokens y nunca ve una contraseña.
  • Protocolos — OAuth2 gestiona la autorización (acceso delegado), OIDC añade una capa de autenticación encima (ID tokens con claims de usuario), SAML cubre el SSO empresarial en formato XML.

El flujo de tokens del diagrama tiene dos controles de seguridad que la gente se salta. Primero, el parámetro state de la redirección saliente debe volver idéntico — esa es tu protección CSRF sobre el propio login. Segundo, la verificación de firma del ID token debe consultar las claves publicadas del IdP (jwks_uri en el documento de discovery), no una clave que empaquetaste tú. Saltarte cualquiera de los dos convierte “Login con Google” en “entra como quien quieras”.

Para SSO entre varias apps, cada relying party ejecuta el mismo flujo de forma independiente y la sesión del IdP hace el trabajo silencioso: la segunda app redirige al proveedor, el proveedor ve una sesión activa y emite el código sin pedir nada. Tus apps nunca hablan entre sí sobre identidad — todas confían en el mismo firmante.

Un detalle que merece atención: el claim sub es único por registro de cliente, no globalmente. Google y la mayoría de proveedores emiten un sub distinto para la misma persona en diferentes client IDs, así que usar sub solo como clave se rompe cuando separas móvil y web en clientes OAuth distintos. Combina iss + sub para la clave primaria y mantén un ID de usuario interno independiente del proveedor para todo lo demás.

Variantes

VarianteProtocoloCaso de Uso
OAuth2 Authorization CodeOAuth2Apps web con intercambio de token en servidor
OIDCOIDC (OAuth2 + ID tokens)Apps web y móviles modernas
SAML 2.0SAMLSSO empresarial, sistemas legacy
Client CredentialsOAuth2Autenticación servicio a servicio
Device CodeOAuth2TV, IoT, dispositivos CLI sin navegador

Elige OIDC salvo que una restricción lo impida. SAML sobrevive en empresas donde el IdP es anterior a OIDC — típicamente ADFS o federaciones antiguas de Entra — y lo heredarás por requisitos de contratación, no por elección. Client Credentials y Device Code ni siquiera son variantes de login de usuario: uno autentica servicios, el otro arranca la autenticación en dispositivos que no pueden mostrar una página de login.

Lo Que Funciona

  • Usa OIDC en aplicaciones nuevas — ID tokens estandarizados con claims de usuario, y todos los proveedores grandes lo soportan
  • Guarda solo referencias a tokens, no contraseñas — el IdP posee el almacenamiento de credenciales
  • Valida los tokens en cada petición — firma, expiración, emisor, audiencia; nada de atajos con verify_signature=False
  • Usa PKCE en clientes públicos (SPAs, móvil) para prevenir la interceptación del código de autorización
  • Implementa refresco de tokens — los access tokens expiran; los refresh tokens mantienen las sesiones vivas
  • Mapea los roles del IdP a roles locales — no filtres nombres de rol propios del proveedor a la lógica de negocio
  • Gestiona la caída del IdP con elegancia — cachea sesiones, mantén un modo degradado de solo lectura si el negocio lo tolera
  • Usa los endpoints de discovery — los proveedores publican su configuración en /.well-known/openid-configuration; no hardcodees endpoints

Errores Comunes

  • Saltarse la validación de firma — decodificar un JWT sin verificarlo contra las JWKS del IdP acepta cualquier token falsificado; es el bug más común de autenticación federada
  • Sin estrategia de account linking — un usuario que entra por Google hoy y por GitHub mañana son dos identidades distintas salvo que las claves por un claim estable (sub) y las enlaces deliberadamente
  • Logout a medias — borrar tu cookie de sesión mientras la del IdP sigue viva hace que el siguiente “login” reautentique en silencio sin pedir nada; el logout real se propaga al proveedor
  • Ignorar el clock skew — las comprobaciones exp/iat/nbf fallan en servidores desfasados; permite margen o sincroniza NTP antes de culpar al token
  • Falta validación de state/nonce — abre la puerta a login CSRF y ataques de repetición en el callback
  • Pedir todos los scopes — openid email profile suele bastar; los scopes extra suben la fricción del consentimiento y amplían el radio de una brecha
  • Confiar en claims no verificados — email_verified existe por algo; no aprovisiones cuentas automáticamente con emails no verificados

Lectura Adicional

Código complementario: el repo companion de federated-identity-pattern tiene las tres implementaciones como archivos ejecutables más un snippet mínimo de verificación JWKS que puedes llevar a proyectos sin Spring.

Preguntas frecuentes

¿Cuál es la diferencia entre OAuth2 y OIDC?

OAuth2 se ocupa de la autorización, no de la autenticación — concede acceso a recursos. OIDC se apoya en OAuth2 y añade la pieza de identidad: ID tokens que prueban quién es el usuario. Usa OIDC cuando necesitas autenticación, OAuth2 cuando necesitas acceso delegado.

¿Debo usar SAML u OIDC?

OIDC para todo lo nuevo — es más simple, basado en JSON y funciona bien con móvil y SPAs. SAML solo cuando el IdP no puede hacer OIDC, que normalmente significa despliegues empresariales de la era ADFS.

¿Cómo manejo múltiples proveedores de identidad?

Implementa una estrategia multi-IdP: deja que el usuario elija su proveedor al entrar y luego mapea cada proveedor a un registro de usuario local usando el claim sub como identificador. Passport.js y Spring Security soportan varios proveedores de forma nativa; la parte difícil es la UI de vinculación, no la fontanería.

¿Para qué sirven los parámetros state y nonce?

state vincula el callback a la petición de login que lo inició — sin él, un atacante puede intercambiar su propio código de autorización (login CSRF). nonce hace el mismo trabajo dentro del ID token para protección contra repetición. Genera ambos por petición, guárdalos en el servidor o en una cookie de corta duración, y rechaza los que no coincidan.

¿Cómo funciona el logout con identidad federada?

Existen dos sesiones: la tuya y la del IdP. Borrar solo tu cookie deja la sesión del IdP viva, así que el siguiente login redirige y reautentica al instante — que el usuario lo vive como "el logout no funciona". Usa el endpoint de fin de sesión del proveedor (end_session_endpoint del documento de discovery) después de limpiar el estado local.

¿Qué pasa si el proveedor de identidad se cae?

Los logins se detienen — ese es el precio de externalizar la autenticación. Las sesiones existentes siguen funcionando hasta que expiran los tokens, así que sesiones de vida más larga más refresh tokens te compran horas de tolerancia a la caída del IdP. Si el negocio no puede tolerar un corte de logins en absoluto, mantén una cuenta local de emergencia para administradores.