OAuth 2.0 y SSO con OpenID Connect

El Authorization Code Flow de OAuth 2.0 es el flujo recomendado y más seguro para la mayoría de aplicaciones, incluidas las aplicaciones web y las aplicaciones de una sola página (SPA). Usa PKCE (Proof Key for Code Exchange) para clientes públicos, con el fin de evitar ataques de interceptación del código de autorización.

Recomendado para: Aplicaciones web, SPAs, apps móviles, integraciones de terceros

Usa refresh tokens para obtener nuevos access tokens sin necesidad de que el usuario vuelva a iniciar sesión. Los refresh tokens son válidos durante 14 días y pueden rotarse para mantener la seguridad.

Recomendado para: Sesiones de larga duración, servicios en segundo plano, acceso sin conexión

El flujo Resource Owner Password Credentials de OAuth 2.0 se admite por compatibilidad con integraciones heredadas. Las integraciones nuevas deben usar el Authorization Code Flow en su lugar.

Recomendado para: Aplicaciones heredadas, herramientas internas (no recomendado para desarrollos nuevos)

GET /connect/authorize

Inicia el flujo de autorización de OAuth. Redirige al usuario para que inicie sesión con su proveedor de identidad (Microsoft, Google, o email/contraseña).

Parámetros de consulta:

• client_id (obligatorio): El ID de tu aplicación
• redirect_uri (obligatorio): URL a la que redirigir tras la autenticación
• response_type (obligatorio): Debe ser 'code'
• scope (obligatorio): Lista de scopes separados por espacios (openid, email, profile, offline_access, roles)
• code_challenge (obligatorio para SPA): Code challenge de PKCE
• code_challenge_method (obligatorio junto con code_challenge): 'S256'
• state (recomendado): Cadena aleatoria para prevenir ataques CSRF
• tenant_id (opcional): Tenant específico en el que autenticarse

POST /connect/token

Intercambia un código de autorización por access tokens, ID token y, opcionalmente, un refresh token.

Formato de la petición: application/x-www-form-urlencoded

Parámetros:

• grant_type (obligatorio): 'authorization_code', 'refresh_token', o 'password'
• code (obligatorio para el flujo authorization code): Código de autorización obtenido de /authorize
• client_id (obligatorio): El ID de tu aplicación
• client_secret (obligatorio): El secreto de tu aplicación (mantenlo confidencial)
• redirect_uri (obligatorio): Debe coincidir con la petición a /authorize
• code_verifier (obligatorio para SPA): Code verifier de PKCE
• refresh_token (para el flujo de refresco): El refresh token a intercambiar
• username & password (para el flujo de contraseña): Credenciales del usuario

POST /connect/introspect

Valida e inspecciona el contenido de un access token o un refresh token.

GET /.well-known/openid-configuration

Endpoint estándar de metadatos OIDC. Devuelve información de descubrimiento, incluidos endpoints, claves públicas, scopes admitidos y tipos de grant.

Crea un code verifier y un code challenge en el lado del cliente:

// 1. Generate random code verifier (43-128 characters)
const codeVerifier = generateRandomString(128);

// 2. Create code challenge via SHA256 hash
const codeChallenge = await crypto.subtle.digest('SHA-256',
  new TextEncoder().encode(codeVerifier)
);

// 3. Base64-URL encode the challenge
const codeChallengeB64 = base64UrlEncode(codeChallenge);

// Store codeVerifier in sessionStorage for Step 3
sessionStorage.setItem('pkce_verifier', codeVerifier);

Dirige al usuario para que inicie sesión:

GET /connect/authorize?
  client_id={your_app_id}
  &redirect_uri=https://your-app.com/callback
  &response_type=code
  &scope=openid email profile
  &code_challenge={pkce_challenge}
  &state={random_state}

El usuario será redirigido a su proveedor de identidad (Microsoft, Google, o email/contraseña), completará la autenticación y volverá a tu redirect_uri con un código de autorización.

Desde tu backend, intercambia el código de autorización:

POST /connect/token
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code
&code={auth_code}
&client_id={your_app_id}
&client_secret={your_app_secret}
&redirect_uri=https://your-app.com/callback
&code_verifier={pkce_verifier}

Si todo va bien, recibes:

{
  "access_token": "eyJhbGciOiJSUzI1NiIs...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "DefxA1234567890...",
  "id_token": "eyJhbGciOiJSUzI1NiIs..."
}

Valida la firma del ID token usando la clave pública de /.well-known/openid-configuration, comprueba los claims de issuer y audience, y extrae la información del usuario.

El ID token (JWT) contiene la información de identidad del usuario:

{
  "sub": "550e8400-e29b-41d4-a716-446655440000",
  "email": "user@company.com",
  "email_verified": true,
  "name": "John Doe",
  "given_name": "John",
  "family_name": "Doe",
  "tenant_id": "12345678-1234-1234-1234-123456789012",
  "iss": "https://api.advanza.ai",
  "aud": "your_app_id",
  "iat": 1234567890,
  "exp": 1234571490
}

Claims principales:

• sub: Identificador único del usuario (Guid)
• email: Dirección de email del usuario
• email_verified: Si el email está verificado
• name, given_name, family_name: Nombre del usuario
• tenant_id: Tenant/organización activo del usuario
• iss: Emisor del token (siempre https://api.advanza.ai)
• aud: Audiencia prevista (el ID de tu aplicación)
• iat: Momento de emisión del token (timestamp Unix)
• exp: Caducidad del token (timestamp Unix)

El access token (JWT) contiene la información de autorización:

{
  "sub": "550e8400-e29b-41d4-a716-446655440000",
  "email": "user@company.com",
  "name": "John Doe",
  "tenant_id": "12345678-1234-1234-1234-123456789012",
  "roles": ["Owner"],
  "scope": "openid email profile offline_access roles",
  "iss": "https://api.advanza.ai",
  "aud": "your_app_id",
  "iat": 1234567890,
  "exp": 1234571490
}

Claims principales:

• sub: ID del usuario
• email, name: Información del usuario
• tenant_id: Tenant activo (úsalo para el enrutamiento multiinquilino)
• roles: Roles del usuario en el tenant
• scope: Scopes concedidos
• exp: Caducidad (normalmente 1 hora)

Usa el access token para: Inclúyelo en la cabecera Authorization (Authorization: Bearer {access_token}) al llamar a las APIs de Advanza o a tu backend.

En el primer inicio de sesión, se asigna al usuario un tenant por defecto. El claim tenant_id se rellenará con el ID de ese tenant.

Los usuarios con varias membresías de tenant pueden cambiar de tenant pasando el parámetro tenant_id deseado al endpoint de autorización:

GET /connect/authorize?
  client_id={your_app_id}
  &redirect_uri=https://your-app.com/callback
  &response_type=code
  &scope=openid email profile
  &tenant_id=12345678-1234-1234-1234-123456789012
  &code_challenge={pkce_challenge}

Usa el claim tenant_id para dirigir las peticiones al contexto de tenant correcto en tu backend:

// Extract tenant from token claims
const tenantId = tokenClaims.tenant_id;

// Route request to tenant context
const tenantContext = getTenantContext(tenantId);
const result = await performAction(tenantContext, action);