Definition
Una credencial de larga duración utilizada para obtener nuevos tokens de acceso sin requerir re-autenticación del usuario. Los tokens de actualización se emiten junto con los tokens de acceso y se intercambian en el endpoint de token por tokens de acceso nuevos cuando los actuales expiran.
Example
Después de iniciar sesión, recibes un token de acceso (expira en 15 minutos) y un token de actualización (expira en 30 días). Cuando el token de acceso expira, tu app usa el token de actualización para obtener un nuevo token de acceso sin pedirle al usuario que inicie sesión nuevamente.
Analogía
Como un pase de temporada a un parque temático. Tu boleto diario (token de acceso) expira al final del día, pero tu pase de temporada (token de actualización) te permite obtener un nuevo boleto diario mañana sin pasar por el proceso de compra nuevamente. Si pierdes el pase de temporada, necesitas comprar uno nuevo.
Code Example
// Request refresh token during initial authorization
const tokenResponse = await fetch('https://oauth.provider.com/token', {
method: 'POST',
headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
body: new URLSearchParams({
grant_type: 'authorization_code',
code: authorizationCode,
client_id: 'your_client_id',
client_secret: 'your_client_secret',
redirect_uri: 'https://yourapp.com/callback'
})
});
const { access_token, refresh_token, expires_in } = await tokenResponse.json();
// Store refresh token securely
secureStorage.set('refresh_token', refresh_token);
// Use refresh token to get new access token
async function refreshAccessToken() {
const response = await fetch('https://oauth.provider.com/token', {
method: 'POST',
headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
body: new URLSearchParams({
grant_type: 'refresh_token',
refresh_token: secureStorage.get('refresh_token'),
client_id: 'your_client_id',
client_secret: 'your_client_secret'
})
});
const tokens = await response.json();
// Update stored tokens (some providers rotate refresh tokens)
if (tokens.refresh_token) {
secureStorage.set('refresh_token', tokens.refresh_token);
}
return tokens.access_token;
}
// Automatic token refresh on 401
async function apiCall(url) {
let response = await fetch(url, {
headers: { 'Authorization': `Bearer ${currentAccessToken}` }
});
if (response.status === 401) {
currentAccessToken = await refreshAccessToken();
response = await fetch(url, {
headers: { 'Authorization': `Bearer ${currentAccessToken}` }
});
}
return response;
}
Diagrama
sequenceDiagram
participant Cliente as Cliente
participant AuthServer as Servidor Auth
participant API
Note over Cliente,AuthServer: Autenticación Inicial
Cliente->>AuthServer: 1. Login (credenciales)
AuthServer->>Cliente: 2. Access Token (15 min) + Refresh Token (30 días)
Note over Cliente: Almacenar ambos tokens de forma segura
Cliente->>API: 3. Llamada API + Access Token
API->>Cliente: 4. Respuesta OK
Note over Cliente,API: Pasa el tiempo... Access token expira
Cliente->>API: 5. Llamada API + Access Token expirado
API->>Cliente: 6. 401 No autorizado
Note over Cliente,AuthServer: Flujo de Refresh Token
Cliente->>AuthServer: 7. Refresh Token
AuthServer->>AuthServer: Validar refresh token
AuthServer->>AuthServer: Rotar: invalidar viejo, crear nuevo
AuthServer->>Cliente: 8. Nuevo Access Token + Nuevo Refresh Token
Cliente->>API: 9. Llamada API + Nuevo Access Token
API->>Cliente: 10. Respuesta OK
Notas de Seguridad
CRÍTICO - …
Configuración y Validación:
- Los tokens de actualización son altamente sensibles, proteger como contraseñas.
- Almacenar en almacenamiento seguro (cookies httpOnly para web, almacenamiento encriptado para móvil, nunca localStorage).
- Implementar rotación de tokens de actualización (emitir nuevo token de actualización con cada uso, invalidar el antiguo).
- Establecer expiración razonable (días a meses, no años).
- Transmitir solo sobre HTTPS.
- Los tokens de actualización deben estar vinculados a clientes específicos.
Monitoreo y Protección:
- Implementar mecanismos de revocación (logout de usuario, detección de compromiso).
- Monitorear reutilización de tokens de actualización (indicador potencial de ataque).
- Usar tokens de actualización separados por dispositivo/cliente.
- Implementar detección de actividad sospechosa (cambios de geolocalización, etc.).
- Clientes confidenciales deben autenticarse al usar tokens de actualización.
- Considerar políticas de expiración de tokens de actualización (absoluta, ventana deslizante).
- Nunca registrar tokens de actualización.