API de Dominios Personalizados

Los Dominios Personalizados te permiten servir las páginas de login alojadas de Auris y los flujos OAuth bajo tu propio dominio con marca (p. ej., auth.tudominio.com) en lugar del dominio predeterminado de Auris. Esto proporciona una experiencia sin interrupciones y de marca blanca donde tus usuarios nunca ven la marca de Auris.

El ciclo de vida del dominio personalizado sigue estos pasos:

1. Añadir el dominio a través de la API
2. Configurar DNS — añadir el registro CNAME o TXT que proporciona Auris
3. Verificar — Auris comprueba el registro DNS y aprovisiona un certificado SSL
4. Activar — establecer el dominio como el dominio principal para tu tenant

Una vez activo, todas las redirecciones OAuth, páginas de login alojadas, enlaces de email y configuraciones del SDK usan tu dominio personalizado.

Todos los endpoints requieren el encabezado x-tenant y un Bearer token válido. La gestión de dominios personalizados requiere acceso a nivel de administrador.

Listar Dominios Personalizados

Respuesta exitosa

{
  "ok": true,
  "data": [
    {
      "id": "cd_abc123",
      "domain": "auth.acme-corp.com",
      "status": "ACTIVE",
      "sslStatus": "ACTIVE",
      "verificationMethod": "CNAME",
      "verificationToken": "auris-verify-abc123def456",
      "primaryDomain": true,
      "createdAt": "2025-01-15T10:00:00Z",
      "verifiedAt": "2025-01-15T10:45:00Z"
    },
    {
      "id": "cd_def456",
      "domain": "login.acme.io",
      "status": "PENDING",
      "sslStatus": "PENDING",
      "verificationMethod": "TXT",
      "verificationToken": "auris-verify-ghi789jkl012",
      "primaryDomain": false,
      "createdAt": "2025-02-10T08:00:00Z",
      "verifiedAt": null
    }
  ]
}

Ciclo de Vida del Estado del Dominio

Estado SSL

Añadir un Dominio Personalizado

Cuerpo de la solicitud

{
  "domain": "auth.acme-corp.com"
}

Respuesta exitosa

{
  "ok": true,
  "data": {
    "id": "cd_ghi789",
    "domain": "auth.acme-corp.com",
    "status": "PENDING",
    "sslStatus": "PENDING",
    "verificationMethod": "CNAME",
    "verificationToken": "auris-verify-mno345pqr678",
    "primaryDomain": false,
    "dnsRecord": {
      "type": "CNAME",
      "host": "auth.acme-corp.com",
      "value": "your-auris-domain.com"
    },
    "createdAt": "2025-02-18T10:00:00Z"
  }
}

Después de crear el dominio, añade el registro DNS mostrado en dnsRecord en tu registrador de dominio. El tipo de registro depende de la configuración del dominio:

Verificación CNAME (para subdominios como auth.acme-corp.com):

CNAME auth.acme-corp.com → your-auris-domain.com

Verificación TXT (método alternativo):

TXT _auris-verify.auth.acme-corp.com → auris-verify-mno345pqr678

Una vez que el registro DNS se haya propagado, llama al endpoint de verificación.

Códigos de error

Verificar un Dominio

Solicitud: No se requiere cuerpo.

Respuesta exitosa — verificado

{
  "ok": true,
  "data": {
    "id": "cd_ghi789",
    "domain": "auth.acme-corp.com",
    "status": "ACTIVE",
    "sslStatus": "PENDING",
    "verifiedAt": "2025-02-18T10:45:00Z"
  }
}

Después de que la verificación sea exitosa, el estado SSL pasa de PENDING a ACTIVE en pocos minutos mientras se aprovisiona el certificado.

Respuesta exitosa — aún no propagado

{
  "ok": true,
  "data": {
    "id": "cd_ghi789",
    "domain": "auth.acme-corp.com",
    "status": "PENDING",
    "message": "DNS record not found yet. DNS propagation can take up to 48 hours."
  }
}

Respuesta exitosa — verificación fallida

{
  "ok": true,
  "data": {
    "id": "cd_ghi789",
    "domain": "auth.acme-corp.com",
    "status": "FAILED",
    "message": "CNAME record found but points to an incorrect target. Expected: your-auris-domain.com, Found: other-service.com"
  }
}

Códigos de error

Eliminar un Dominio Personalizado

Respuesta exitosa

{
  "ok": true,
  "data": { "deleted": true }
}

Códigos de error

Establecer Dominio Principal

Establecer un dominio como principal hace que todas las URLs generadas por Auris (base de redirección OAuth, enlaces de email, emisor de Descubrimiento OIDC) usen este dominio en lugar del dominio predeterminado de Auris.

Cuerpo de la solicitud

{
  "primaryDomain": true
}

Respuesta exitosa

{
  "ok": true,
  "data": {
    "id": "cd_abc123",
    "domain": "auth.acme-corp.com",
    "primaryDomain": true,
    "updatedAt": "2025-02-18T12:00:00Z"
  }
}

Códigos de error

Cómo Funcionan los Dominios Personalizados

Cuando un dominio personalizado se establece como principal, los siguientes comportamientos de Auris cambian:

Métodos de Verificación DNS

Auris soporta dos métodos de verificación DNS:

Verificación CNAME (Recomendado)

Usado para subdominios. El registro CNAME sirve un doble propósito — verifica la propiedad y enruta el tráfico a Auris.

Tipo:  CNAME
Host:  auth.acme-corp.com
Valor: your-auris-domain.com
TTL:   3600 (o Auto)

Verificación TXT

Método alternativo cuando CNAME no es adecuado. Se añade un registro TXT separado bajo el subdominio _auris-verify.

Tipo:  TXT
Host:  _auris-verify.auth.acme-corp.com
Valor: auris-verify-mno345pqr678
TTL:   3600 (o Auto)

Con la verificación TXT, también debes configurar un registro CNAME o A por separado para enrutar el tráfico a Auris.

Referencia de Permisos

La gestión de dominios personalizados generalmente está restringida a los administradores del tenant. El permiso está incluido en el rol predeterminado admin.

Relacionado

• Guía de Dominios Personalizados — Configuración y verificación de dominios paso a paso
• Dominios Personalizados — Añade y verifica dominios desde la Consola