@bigso/auth-sdk 0.3.0 → 0.3.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +188 -0
- package/package.json +1 -1
package/README.md
ADDED
|
@@ -0,0 +1,188 @@
|
|
|
1
|
+
# @bigso/auth-sdk v0.3.0
|
|
2
|
+
|
|
3
|
+
SDK oficial de autenticación para Bigso SSO, compatible con el estándar SSO v2.3. Este paquete permite integrar aplicaciones web con el flujo de autenticación basado en iframe seguro, utilizando PKCE, JWS firmados y comunicación mediante postMessage.
|
|
4
|
+
|
|
5
|
+
## 🚀 Características
|
|
6
|
+
|
|
7
|
+
✅ **Flujo seguro** con PKCE obligatorio y JWS firmado.
|
|
8
|
+
|
|
9
|
+
✅ **Compatible con SSO v2.3** (whitelist de origins, kid en JWS, validación de nonce, timeout reactivo).
|
|
10
|
+
|
|
11
|
+
✅ **Manejo automático de estados** (state, nonce, verifier, requestId).
|
|
12
|
+
|
|
13
|
+
✅ **Verificación de firma JWS** en el frontend usando `jose` y JWKS remoto.
|
|
14
|
+
|
|
15
|
+
✅ **Timeout reactivo configurable**, activado tras `sso-ready`.
|
|
16
|
+
|
|
17
|
+
✅ **Soporte para redirect_uri y tenant_hint**.
|
|
18
|
+
|
|
19
|
+
✅ **Manejo de errores** incluyendo `version_mismatch` con fallback automático.
|
|
20
|
+
|
|
21
|
+
✅ **API asíncrona** basada en promesas.
|
|
22
|
+
|
|
23
|
+
✅ **Sistema de eventos** (ready, success, error, fallback, debug).
|
|
24
|
+
|
|
25
|
+
✅ **Ligero** (~6 kB) y con tipos TypeScript.
|
|
26
|
+
|
|
27
|
+
## 📦 Instalación
|
|
28
|
+
|
|
29
|
+
```bash
|
|
30
|
+
npm install @bigso/auth-sdk
|
|
31
|
+
# o
|
|
32
|
+
yarn add @bigso/auth-sdk
|
|
33
|
+
# o
|
|
34
|
+
pnpm add @bigso/auth-sdk
|
|
35
|
+
```
|
|
36
|
+
|
|
37
|
+
## 🧪 Uso básico
|
|
38
|
+
|
|
39
|
+
```typescript
|
|
40
|
+
import { BigsoAuth } from '@bigso/auth-sdk';
|
|
41
|
+
|
|
42
|
+
const auth = new BigsoAuth({
|
|
43
|
+
clientId: 'tu-client-id',
|
|
44
|
+
ssoOrigin: 'https://sso.tudominio.com',
|
|
45
|
+
jwksUrl: 'https://sso.tudominio.com/.well-known/jwks.json',
|
|
46
|
+
timeout: 5000, // opcional, por defecto 5000ms
|
|
47
|
+
debug: true, // opcional, logs de depuración
|
|
48
|
+
redirectUri: 'https://miapp.com/callback', // opcional
|
|
49
|
+
tenantHint: 'mi-tenant' // opcional
|
|
50
|
+
});
|
|
51
|
+
|
|
52
|
+
auth.on('ready', () => console.log('✅ Iframe listo'));
|
|
53
|
+
auth.on('success', (payload) => {
|
|
54
|
+
console.log('✅ Autenticación exitosa', payload);
|
|
55
|
+
// Envía el signed_payload al backend para canjear el código
|
|
56
|
+
enviarAlBackend(payload.signed_payload);
|
|
57
|
+
});
|
|
58
|
+
auth.on('error', (error) => console.error('❌ Error:', error));
|
|
59
|
+
auth.on('fallback', () => console.log('⚠️ Fallback por redirección activado'));
|
|
60
|
+
|
|
61
|
+
auth.login().catch(err => console.error('Login falló', err));
|
|
62
|
+
```
|
|
63
|
+
|
|
64
|
+
## 📚 API Reference
|
|
65
|
+
|
|
66
|
+
### `new BigsoAuth(options)`
|
|
67
|
+
Crea una nueva instancia del cliente de autenticación.
|
|
68
|
+
|
|
69
|
+
#### Opciones de configuración
|
|
70
|
+
| Parámetro | Tipo | Obligatorio | Por defecto | Descripción |
|
|
71
|
+
| :--- | :--- | :---: | :---: | :--- |
|
|
72
|
+
| `clientId` | `string` | ✅ | — | Client ID registrado en el SSO. |
|
|
73
|
+
| `ssoOrigin` | `string` | ✅ | — | Origen del SSO (ej. `https://sso.bigso.co`). |
|
|
74
|
+
| `jwksUrl` | `string` | ✅ | — | URL del JWKS para verificar firmas (ej. `/.well-known/jwks.json`). |
|
|
75
|
+
| `timeout` | `number` | ❌ | `5000` | Tiempo máximo de espera tras `sso-ready` (milisegundos). |
|
|
76
|
+
| `debug` | `boolean` | ❌ | `false` | Activa logs de depuración en consola. |
|
|
77
|
+
| `redirectUri` | `string` | ❌ | `''` | URI de redirección registrada (se valida exactamente en el SSO). |
|
|
78
|
+
| `tenantHint` | `string` | ❌ | `''` | Sugerencia de tenant para flujos multi-tenant. |
|
|
79
|
+
|
|
80
|
+
### `auth.login()`
|
|
81
|
+
Inicia el flujo de autenticación. Devuelve una promesa que se resuelve con el payload decodificado del JWS (solo para información; la validación final debe realizarse en el backend).
|
|
82
|
+
|
|
83
|
+
**Retorna**: `Promise<any>` – Payload del JWS (contiene `code`, `state`, `nonce`, `iss`, etc.).
|
|
84
|
+
|
|
85
|
+
**Rechaza**: `Error` o payload de error del iframe.
|
|
86
|
+
|
|
87
|
+
### `auth.abort()`
|
|
88
|
+
Cancela el flujo de autenticación en curso, eliminando el iframe y rechazando la promesa.
|
|
89
|
+
|
|
90
|
+
### `auth.on(event, handler)`
|
|
91
|
+
Registra un manejador para los eventos del SDK.
|
|
92
|
+
|
|
93
|
+
#### Eventos disponibles:
|
|
94
|
+
| Evento | Descripción | Parámetros |
|
|
95
|
+
| :--- | :--- | :--- |
|
|
96
|
+
| `ready` | Se emite cuando el iframe está listo y se ha enviado `sso-init`. | — |
|
|
97
|
+
| `success` | Se emite tras verificar exitosamente la firma JWS y validar `state`/`nonce` en el frontend. | `payload: any` (payload del JWS) |
|
|
98
|
+
| `error` | Se emite cuando ocurre un error (incluyendo `version_mismatch` antes del fallback automático). | `error: Error | SsoErrorPayload` |
|
|
99
|
+
| `fallback` | Se emite justo antes de redirigir a la URL de fallback (por timeout o `version_mismatch`). | — |
|
|
100
|
+
| `debug` | Se emite cuando `debug: true` para logs internos. | `args: any[]` |
|
|
101
|
+
|
|
102
|
+
## ⚙️ Ejemplos avanzados
|
|
103
|
+
|
|
104
|
+
### Personalizar el timeout
|
|
105
|
+
```typescript
|
|
106
|
+
const auth = new BigsoAuth({
|
|
107
|
+
clientId: 'abc123',
|
|
108
|
+
ssoOrigin: 'https://sso.bigso.co',
|
|
109
|
+
jwksUrl: 'https://sso.bigso.co/.well-known/jwks.json',
|
|
110
|
+
timeout: 10000 // 10 segundos
|
|
111
|
+
});
|
|
112
|
+
```
|
|
113
|
+
|
|
114
|
+
### Usar `redirect_uri` y `tenant_hint`
|
|
115
|
+
```typescript
|
|
116
|
+
const auth = new BigsoAuth({
|
|
117
|
+
clientId: 'abc123',
|
|
118
|
+
ssoOrigin: 'https://sso.bigso.co',
|
|
119
|
+
jwksUrl: 'https://sso.bigso.co/.well-known/jwks.json',
|
|
120
|
+
redirectUri: 'https://admin.miapp.com/callback',
|
|
121
|
+
tenantHint: 'enterprise'
|
|
122
|
+
});
|
|
123
|
+
```
|
|
124
|
+
|
|
125
|
+
### Manejo de fallback personalizado
|
|
126
|
+
Puedes escuchar el evento `fallback` para ejecutar tu propia lógica antes de la redirección automática:
|
|
127
|
+
|
|
128
|
+
```typescript
|
|
129
|
+
auth.on('fallback', () => {
|
|
130
|
+
console.log('Mostrando spinner o mensaje...');
|
|
131
|
+
// Por defecto, el SDK redirige a /authorize.
|
|
132
|
+
// Si quieres evitar la redirección automática, puedes sobrescribir el comportamiento
|
|
133
|
+
// pero no es recomendable ya que es el mecanismo de último recurso.
|
|
134
|
+
});
|
|
135
|
+
```
|
|
136
|
+
|
|
137
|
+
## 🔒 Consideraciones de seguridad
|
|
138
|
+
|
|
139
|
+
- **Whitelist de origins**: El SDK asume que el SSO Core está configurado correctamente con la whitelist de origins para cada `client_id` y que responde con `Content-Security-Policy: frame-ancestors`. El SDK no puede controlar esto; es responsabilidad del administrador del SSO.
|
|
140
|
+
- **Validación en backend**: La verificación del JWS en el frontend es solo una capa adicional de integridad. El backend debe validar la firma, el nonce, el state y canjear el código usando PKCE antes de emitir tokens.
|
|
141
|
+
- **nonce y state**: El SDK genera valores aleatorios seguros (`crypto.randomUUID`) y los valida en el frontend. El backend debe realizar la misma validación para prevenir ataques de replay.
|
|
142
|
+
- **Prevención de replay**: El SDK no incluye lógica de deduplicación de JWS en el frontend; esto debe implementarse en el backend usando `jti` si es necesario.
|
|
143
|
+
- **Timeout**: El timeout se inicia solo después de `sso-ready`, evitando falsos positivos. Si se alcanza, el SDK ejecuta un fallback a redirección (endpoint `/authorize`).
|
|
144
|
+
- **Versiones**: El SDK usa `v: '2.3'`. Si el iframe responde con `version_mismatch`, se activa el fallback automático.
|
|
145
|
+
|
|
146
|
+
## 🛠️ Desarrollo
|
|
147
|
+
|
|
148
|
+
### Construcción
|
|
149
|
+
```bash
|
|
150
|
+
npm run build # genera dist/ con formatos ESM, CJS y types
|
|
151
|
+
```
|
|
152
|
+
|
|
153
|
+
### Pruebas
|
|
154
|
+
```bash
|
|
155
|
+
npm test # ejecuta vitest
|
|
156
|
+
```
|
|
157
|
+
|
|
158
|
+
### Linting
|
|
159
|
+
```bash
|
|
160
|
+
npm run lint
|
|
161
|
+
```
|
|
162
|
+
|
|
163
|
+
## 📝 Changelog
|
|
164
|
+
|
|
165
|
+
### v0.3.0 (2026-03-21)
|
|
166
|
+
Protocolo actualizado a SSO v2.3
|
|
167
|
+
- Mensaje `sso-init` con `v: '2.3'`.
|
|
168
|
+
- Timeout reactivo (se inicia tras `sso-ready`).
|
|
169
|
+
- Validación de `requestId` en respuestas.
|
|
170
|
+
- Soporte para `redirect_uri`, `tenant_hint`, `timeout_ms`.
|
|
171
|
+
- Manejo de error `version_mismatch` con fallback automático.
|
|
172
|
+
- Validación de `nonce` en el frontend tras verificar JWS.
|
|
173
|
+
|
|
174
|
+
**Mejoras internas:**
|
|
175
|
+
- Método `abort()` para cancelar operación.
|
|
176
|
+
- Evento `debug` opcional.
|
|
177
|
+
- Documentación completa.
|
|
178
|
+
|
|
179
|
+
**Breaking changes:** Ninguno, pero se recomienda actualizar el backend para validar `nonce` si no lo hacía antes.
|
|
180
|
+
|
|
181
|
+
### v0.2.0 (anterior)
|
|
182
|
+
- Implementación inicial con v2.2.
|
|
183
|
+
|
|
184
|
+
## 📄 Licencia
|
|
185
|
+
MIT © Bigso
|
|
186
|
+
|
|
187
|
+
## 🤝 Contribuciones
|
|
188
|
+
Por favor, abre un issue o pull request en el repositorio oficial.
|