Configurar los metadatos del Token de actualización

Aprenda a configurar los metadatos del Token de actualización de Auth0

Los metadatos del Token de actualización están actualmente en Early Access solo para clientes Enterprise. Al usar esta funcionalidad, acepta los términos aplicables de la prueba gratuita del Master Subscription Agreement de Okta. Para obtener más información sobre el ciclo de lanzamiento de productos de Auth0, consulte Etapas de lanzamiento del producto.

Para configurar los metadatos del Token de actualización, puede usar una Action de Post-Login de Auth0 y la Management API.

​

Actions de Auth0 Post-Login

Puede gestionar operaciones CRUD de metadatos del token de actualización mediante los objetos api.refreshToken con una Action Post-Login. Esto le permite gestionar el metadato del token de actualización según la lógica específica del usuario o del contexto.

​

Recupera los metadatos existentes del token de actualización

Usa el objeto event.refresh_token.metadata para leer los metadatos del token de actualización:

const deviceName = event.refresh_token?.metadata?.deviceName;

El objeto event.refresh_token.metadata incluye metadatos establecidos en:

• Actions previas dentro del mismo flujo
• Transacciones anteriores si el token de actualización se reutilizó durante un intercambio de token de actualización

​

Agregue o actualice metadatos existentes

Use el método api.refreshToken.setMetadata() para establecer o actualizar los metadatos del Token de actualización:

api.refreshToken.setMetadata("deviceName", "Auth0's iPhone");

Los cambios están disponibles de inmediato en el objeto event.refresh_token en las Actions siguientes.

​

Eliminar metadatos del Token de actualización

Utilice los siguientes métodos de api.refreshToken para eliminar los metadatos del Token de actualización:

• api.refreshToken.deleteMetadata("key") elimina los metadatos especificados del Token de actualización

• api.refreshToken.evictMetadata() elimina todos los metadatos del Token de actualización

Para obtener más información sobre estos objetos, consulte:

• Objeto Event: Obtenga más información sobre el objeto Event del Token de actualización y sus propiedades.
• Objeto API: Obtenga más información sobre el objeto API del Token de actualización y sus métodos.

​

Auth0 Management API

Puede gestionar las solicitudes CRUD (crear, reemplazar, actualizar y eliminar) de los metadatos del token de actualización con la Management API:

Las llamadas al endpoint /api/v2/refresh-tokens/{id} requieren un token de acceso de la Management API con el scope update:refresh_tokens.

​

Recuperar los metadatos de un token de actualización existente

Haga una solicitud GET al endpoint /api/v2/refresh-tokens/{id}:

GET /api/v2/refresh-tokens/{id}

​

Agregue o actualice los metadatos de un Token de actualización existente

Haga una solicitud PATCH al endpoint /api/v2/refresh-tokens/{id}:

PATCH /api/v2/refresh-tokens/{id}
Content-Type: application/json

{
  "refresh_token_metadata": {
    "my_metadata": "my new metadata"
  }
}

​

Eliminar los metadatos del token de actualización

Haz una solicitud PATCH al endpoint /api/v2/refresh-tokens/{id} con un objeto de metadatos vacío:

PATCH /api/v2/refresh-tokens/{id}
Content-Type: application/json

{
  "refresh_token_metadata": {}
}

​

Caso de uso: Almacenar y utilizar el contexto de la organización

Puede usar los metadatos del Token de actualización para almacenar el contexto de la organización durante la autenticación inicial y utilizarlo más adelante durante los intercambios del Token de actualización. Esto resulta útil para sistemas posteriores, como las canalizaciones de auditoría, análisis y revocación.

​

Establecer metadatos en la autenticación inicial

Durante el primer inicio de sesión, establezca el contexto de la organización en los metadatos del token de actualización:

/**
 * Action Post-Login
 * Agrega el contexto de organización a los metadatos del Token de actualización durante la autenticación inicial.
 * Estos metadatos estarán disponibles en los intercambios posteriores del Token de actualización.
 */
exports.onExecutePostLogin = async (event, api) => {
  // Continuar solo si la transacción tiene como destino una Organización
  if (!event.organization) return;

  // Mantener los valores cortos y solo como cadenas (los metadatos del Token de actualización requieren cadenas)
  const orgId = String(event.organization.id || "");
  const orgSlug = String(event.organization.name || "");
  const orgDisplay = String(event.organization.display_name || orgSlug);

  // Establecer metadatos: se almacenarán junto con el Token de actualización
  api.refreshToken.setMetadata("org_id", orgId);
  api.refreshToken.setMetadata("org_slug", orgSlug);
  api.refreshToken.setMetadata("org_name", orgDisplay);
};

​

Consumir metadatos durante el intercambio del token de actualización

Durante un intercambio del token de actualización, el objeto event.refresh_token está disponible y puedes leer los metadatos almacenados previamente:

/**
 * Post-Login Action
 * Consume el contexto de organización de los metadatos del Token de actualización durante el intercambio de tokens.
 * Úselo para aplicar políticas o agregar claims según el contexto de autenticación original.
 */
exports.onExecutePostLogin = async (event, api) => {
  // Verifica si se trata de un intercambio de Token de actualización (event.refresh_token existe)
  if (!event.refresh_token) return;

  // Lee el contexto de organización almacenado durante la autenticación inicial
  const orgId = event.refresh_token.metadata?.org_id;
  const orgSlug = event.refresh_token.metadata?.org_slug;

  if (orgId) {
    // Usa el contexto de organización para lógica condicional
    console.log(`Refresh token exchange for organization: ${orgSlug}`);
    
    // Ejemplo: Agrega custom claims según el contexto de organización original
    api.accessToken.setCustomClaim("org_id", orgId);
  }
};

​

Obtener mediante Management API

También puede consultar los metadatos del Token de actualización mediante el endpoint /api/v2/refresh-tokens/:

GET /api/v2/refresh-tokens/{id}

Respuesta de ejemplo:

{
  "refresh_token_metadata": {
    "org_id": "org_abc123",
    "org_slug": "acme",
    "org_name": "Acme Corp"
  }
}

​

Caso de uso: Registrar y validar la información del dispositivo

Puede usar los metadatos del Token de actualización para recopilar información del dispositivo durante la autenticación inicial y validarla en los intercambios posteriores del Token de actualización con fines de seguridad.

​

Establecer la información del dispositivo durante la autenticación inicial

exports.onExecutePostLogin = async (event, api) => {
  // Solo establecer información del dispositivo si NO es un intercambio de Token de actualización
  // (es decir, esta es la autenticación inicial)
  if (event.refresh_token) return;

  // Almacenar información del dispositivo en los metadatos del Token de actualización
  api.refreshToken.setMetadata("initial_ip", event.request?.ip || "unknown");
  api.refreshToken.setMetadata("initial_asn", event.request?.asn?.value || "unknown");
  api.refreshToken.setMetadata("initial_country", event.request?.geoip?.country_code || "unknown");
  api.refreshToken.setMetadata("initial_user_agent", event.request?.user_agent || "unknown");
};

​

Validar la información del dispositivo al intercambiar el Token de actualización

exports.onExecutePostLogin = async (event, api) => {
  // Solo validar si se trata de un intercambio de token de actualización
  if (!event.refresh_token) return;

  // Leer la información original del dispositivo
  const initialCountry = event.refresh_token.metadata?.initial_country;
  const currentCountry = event.request?.geoip?.country_code;

  // Ejemplo: Detectar cambio de país y tomar acción
  if (initialCountry && currentCountry && initialCountry !== currentCountry) {
    console.log(`Country changed from ${initialCountry} to ${currentCountry}`);
    
    // Opción 1: Revocar el token de actualización por actividad sospechosa
    // api.refreshToken.revoke("Suspicious country change detected");
    
    // Opción 2: Actualizar los metadatos para registrar el cambio
    api.refreshToken.setMetadata("country_changed", "true");
    api.refreshToken.setMetadata("last_country", currentCountry);
  }
};

​

Manejo de errores

Puede revisar los eventos de registro de metadatos del Token de actualización navegando a Dashboard > Monitoring > Logs o recuperar los registros mediante el endpoint de registros de Management API.

• Si se produce un error al agregar o actualizar los metadatos del Token de actualización con Actions, la transacción de autenticación falla y se devuelve un error a la URL de devolución de llamada.

Se registra un código de evento de error f con el error correspondiente:

{
  "error": "access_denied",
  "error_description": "Failed to set refresh token metadata: Invalid metadata: Metadata keys may only include letters, numbers, underscores, or hyphens",
  "state": "my-custom-state"
}

• Si se produce un error al administrar los metadatos del Token de actualización mediante la Management API de Auth0, la API responde con un error HTTP status: 400 y el mensaje correspondiente:

{
  "statusCode": 400,
  "message": "Metadata must not exceed 25 entries. Each key and value must be ≤ 255 characters."
}

​

Más información

• Metadatos del token de actualización
• Tokens de actualización con Actions
• Tokens de actualización
• Objeto de evento Post-Login
• Objeto de API Post-Login