Saltar al contenido principal

Flujo de Autorización de Clave API

Este documento describe el flujo de creación de claves API de autoservicio para aplicaciones de terceros.

Visión General​

Las aplicaciones pueden solicitar acceso a la API de un servidor Unraid redirigiendo a los usuarios a una página de autorización especial donde los usuarios pueden revisar los permisos solicitados y crear una clave API con un solo clic.

Flujo​

  1. La aplicación inicia la solicitud: La aplicación redirige al usuario a:

    https://[unraid-server]/ApiKeyAuthorize?name=MyApp&scopes=docker:read,vm:*&redirect_uri=https://myapp.com/callback&state=abc123

  2. Autenticación del usuario: Si no ha iniciado sesión, el usuario es redirigido para iniciar sesión primero (autenticación estándar de Unraid)

  3. Pantalla de consentimiento: El usuario ve:

    • Nombre y descripción de la aplicación
    • Permisos solicitados (con casillas de verificación para aprobar/denegar ámbitos específicos)
    • Campo de nombre de la clave API (rellenado previamente)
    • Botones Autorizar y Cancelar

  4. Creación de la clave API: Tras la autorización:

    • La clave API se crea con los ámbitos aprobados
    • La clave se muestra al usuario
    • Si se proporciona redirect_uri, el usuario es redirigido con la clave

  5. Llamada de retorno: La aplicación recibe la clave API:

    https://myapp.com/callback?api_key=xxx&state=abc123

Parámetros de consulta​

  • name (requerido): Nombre de la aplicación solicitante
  • description (opcional): Descripción de la aplicación
  • scopes (requerido): Lista de ámbitos solicitados separados por comas
  • redirect_uri (opcional): URL para redirigir tras la autorización
  • state (opcional): Valor opaco para mantener el estado

Formato del ámbito​

Los ámbitos siguen el patrón: recurso:acción

Ejemplos:​

  • docker:read - Acceso de lectura a Docker
  • vm:* - Acceso completo a las VMs
  • system:update - Acceso de actualización al sistema
  • role:viewer - Acceso como rol de espectador
  • role:admin - Acceso como rol de administrador

Recursos Disponibles:​

  • docker, vm, system, share, user, network, disk, etc.

Acciones Disponibles:​

  • create, read, update, delete o * para todas

Consideraciones de Seguridad​

  1. Se requiere HTTPS: Las URIs de redirección deben usar HTTPS (excepto localhost para desarrollo)
  2. Consentimiento del usuario: Los usuarios aprueban explícitamente cada permiso
  3. Basado en sesión: Utiliza la sesión de autenticación existente de Unraid
  4. Visualización única: Las claves API se muestran una vez y deben guardarse de forma segura

Ejemplo de Integración​

// Ejemplo de JavaScript
const unraidServer = 'tower.local';
const appName = 'My Docker Manager';
const scopes = 'docker:*,system:read';
const redirectUri = 'https://myapp.com/unraid/callback';
const state = generateRandomState();

// Almacenar estado para verificación
sessionStorage.setItem('oauth_state', state);

// Redirigir usuario a la página de autorización
window.location.href =
    `https://${unraidServer}/ApiKeyAuthorize?` +
    `name=${encodeURIComponent(appName)}&` +
    `scopes=${encodeURIComponent(scopes)}&` +
    `redirect_uri=${encodeURIComponent(redirectUri)}&` +
    `state=${encodeURIComponent(state)}`;

// Manejar retorno
const urlParams = new URLSearchParams(window.location.search);
const apiKey = urlParams.get('api_key');
const returnedState = urlParams.get('state');

if (returnedState === sessionStorage.getItem('oauth_state')) {
    // Guardar clave API de forma segura
    saveApiKey(apiKey);
}