Dominios Personalizados

Por defecto, Auris sirve las páginas de inicio de sesión alojadas en un subdominio como your-tenant.accounts.altovar.net. Los dominios personalizados te permiten reemplazarlo con tu propio dominio (p. ej., auth.tuempresa.com), proporcionando una experiencia de autenticación completamente personalizada donde los usuarios nunca ven el dominio de Auris.

Esta guía cubre la adición de un dominio personalizado, la verificación DNS y la configuración de tus SDKs para utilizarlo.

Qué Hacen los Dominios Personalizados

Cuando configuras un dominio personalizado:

• La página de inicio de sesión alojada se sirve en https://auth.tuempresa.com en lugar de https://your-tenant.accounts.altovar.net
• Los endpoints de autorización OAuth2 y de tokens usan tu dominio
• El discovery OIDC (.well-known/openid-configuration) resuelve bajo tu dominio
• El endpoint JWKS para la verificación de tokens usa tu dominio
• Los correos enviados a los usuarios (magic links, verificación, restablecimiento de contraseña) contienen enlaces a tu dominio
• Los certificados SSL se aprovisionan y renuevan automáticamente a través de Let’s Encrypt

Tus usuarios interactúan completamente con tu marca, sin ninguna indicación de que Auris gestiona la autenticación.

Requisitos Previos

Antes de configurar un dominio personalizado, asegúrate de tener:

• Acceso administrativo a tu proveedor de DNS (p. ej., Cloudflare, Route 53, GoDaddy)
• Un subdominio reservado para autenticación (p. ej., auth.tuempresa.com, login.tuempresa.com o id.tuempresa.com)
• Un tenant de Auris activo en el plan Pro o Enterprise

Paso 1: Agregar el Dominio en la Consola

1. Abre la Consola de Auris y navega a Configuración y luego a Dominios Personalizados
2. Haz clic en Agregar Dominio
3. Introduce tu dominio (p. ej., auth.tuempresa.com)
4. Haz clic en Agregar

Auris genera un token de verificación y muestra los registros DNS que necesitas crear. El estado del dominio aparecerá como Pendiente hasta que la verificación se complete.

También puedes agregar un dominio a través de la API:

curl -X POST https://auth.tudominio.com/api/custom-domains \
  -H "Authorization: Bearer $AURIS_ACCESS_TOKEN" \
  -H "x-tenant: your-tenant-id" \
  -H "Content-Type: application/json" \
  -d '{
    "domain": "auth.tuempresa.com"
  }'

Respuesta:

{
  "ok": true,
  "data": {
    "id": "cd_abc123",
    "domain": "auth.tuempresa.com",
    "status": "PENDING",
    "verificationMethod": "CNAME",
    "verificationToken": "auris-verify-a1b2c3d4e5f6",
    "sslStatus": "PENDING",
    "primaryDomain": false,
    "createdAt": "2026-01-15T10:00:00Z"
  }
}

Paso 2: Configurar el DNS

Auris admite dos métodos de verificación. La Consola muestra el método y los registros exactos que debes crear.

Método A: Verificación por CNAME (Recomendado)

Crea dos registros DNS en tu proveedor de DNS:

Registro de verificación:

Registro de tráfico (crear después de la verificación):

Método B: Verificación por TXT

Si tu proveedor de DNS no admite CNAME en el subdominio de verificación, usa un registro TXT en su lugar:

Luego crea el CNAME de tráfico:

Ejemplos por Proveedor de DNS

Cloudflare:

1. Ve a la configuración DNS de tu dominio
2. Haz clic en Añadir registro
3. Establece el Tipo en CNAME, el Nombre en _auris-verify.auth y el Destino en verify.accounts.altovar.net
4. Desactiva la nube naranja proxy (configura como DNS Only / nube gris) para el registro de verificación
5. Agrega el CNAME de tráfico: Nombre auth, Destino your-tenant.accounts.altovar.net

AWS Route 53:

1. Abre la zona alojada de tu dominio
2. Haz clic en Crear registro
3. Nombre del registro: _auris-verify.auth
4. Tipo de registro: CNAME
5. Valor: verify.accounts.altovar.net
6. TTL: 300

GoDaddy:

1. Ve a la Gestión de DNS de tu dominio
2. Haz clic en Añadir en la tabla de registros
3. Tipo: CNAME, Nombre: _auris-verify.auth, Valor: verify.accounts.altovar.net, TTL: 600

Paso 3: Esperar a la Verificación y el SSL

Tras crear los registros DNS, Auris comprueba periódicamente el registro de verificación (cada pocos minutos). También puedes iniciar una comprobación manual:

1. En la Consola, ve a Configuración y luego a Dominios Personalizados
2. Haz clic en el botón Comprobar junto a tu dominio pendiente

O mediante la API:

curl -X POST https://auth.tudominio.com/api/custom-domains/cd_abc123/verify \
  -H "Authorization: Bearer $AURIS_ACCESS_TOKEN" \
  -H "x-tenant: your-tenant-id"

Una vez que la verificación DNS sea correcta, el estado del dominio cambia a Verificando y Auris inicia el aprovisionamiento SSL. Se emite automáticamente un certificado SSL a través de Let’s Encrypt. Esto suele completarse en pocos minutos.

Cuando el SSL esté listo, el estado del dominio cambia a Activo y el estado SSL también a Activo. Tu dominio personalizado ya está completamente operativo.

Cronograma de Verificación

Paso 4: Establecer como Dominio Principal

Si tienes varios dominios personalizados (p. ej., para distintas marcas o regiones), puedes designar uno como dominio principal. El dominio principal se usa en:

• Enlaces en correos (magic links, verificación, restablecimiento de contraseña)
• Claim iss predeterminado en los JWTs
• Documento de discovery OIDC

En la Consola, haz clic en el botón Establecer como Principal en el dominio que deseas usar por defecto. O mediante la API:

curl -X PATCH https://auth.tudominio.com/api/custom-domains/cd_abc123 \
  -H "Authorization: Bearer $AURIS_ACCESS_TOKEN" \
  -H "x-tenant: your-tenant-id" \
  -H "Content-Type: application/json" \
  -d '{ "primaryDomain": true }'

Usar Dominios Personalizados con el SDK

Una vez que tu dominio personalizado esté activo, actualiza el parámetro domain en la configuración de tu SDK para usarlo:

import { AurisClient } from '@auris/js'
 
const auris = new AurisClient({
  domain: 'auth.tuempresa.com', // Tu dominio personalizado
  clientId: 'your-client-id',
  redirectUri: 'https://app.tuempresa.com/callback',
})

Para aplicaciones React:

import { AurisProvider } from '@auris/react'
 
function App() {
  return (
    <AurisProvider
      domain="auth.tuempresa.com"
      clientId="your-client-id"
      redirectUri="https://app.tuempresa.com/callback"
    >
      <MyApp />
    </AurisProvider>
  )
}

Para Next.js, actualiza tus variables de entorno:

NEXT_PUBLIC_AURIS_DOMAIN=auth.tuempresa.com
NEXT_PUBLIC_AURIS_CLIENT_ID=your-client-id
AURIS_JWKS_URL=https://auth.tuempresa.com/.well-known/jwks.json

El endpoint de discovery OIDC está disponible en:

https://auth.tuempresa.com/.well-known/openid-configuration

Y el endpoint JWKS en:

https://auth.tuempresa.com/.well-known/jwks.json

Configuración de Marca

Los dominios personalizados funcionan conjuntamente con la configuración de marca en la Consola. Para completar la experiencia white-label:

1. Ve a Consola y luego a Marca
2. Sube tu logotipo (se muestra en la página de inicio de sesión alojada)
3. Establece el nombre de empresa (se muestra en los títulos de página y en las cabeceras de correo)
4. Elige un color de fondo o usa un preset
5. Opcionalmente sube un favicon para las pestañas de la página de inicio de sesión alojada

Estas configuraciones de marca se aplican a todas las páginas alojadas servidas bajo tu dominio personalizado.

Resolución de Problemas

Registros DNS No Encontrados

Síntoma: El dominio permanece en estado PENDING después de crear los registros DNS.

Causas comunes:

• Retraso en la propagación. Los cambios de DNS pueden tardar hasta 48 horas en propagarse globalmente, aunque la mayoría de proveedores propagan en minutos. Comprueba la propagación usando dnschecker.org .
• Nombre de registro incorrecto. Asegúrate de que el nombre del CNAME sea exactamente _auris-verify.auth (no _auris-verify.auth.tuempresa.com — la mayoría de proveedores añaden la zona automáticamente).
• Registro proxificado. Si usas Cloudflare, asegúrate de que el CNAME de verificación esté configurado como “DNS Only” (nube gris), no como “Proxied” (nube naranja).
• TTL demasiado alto. Si tu registro anterior para este subdominio tenía un TTL alto, el valor antiguo puede estar en caché. Espera a que expire el TTL anterior.

Verifica tus registros desde la línea de comandos:

# Comprobar el registro CNAME de verificación
dig _auris-verify.auth.tuempresa.com CNAME +short
 
# Comprobar el registro TXT de verificación (si usas el método TXT)
dig _auris-verify.auth.tuempresa.com TXT +short
 
# Comprobar el CNAME de tráfico
dig auth.tuempresa.com CNAME +short

Certificado SSL No Se Aprovisiona

Síntoma: El dominio está ACTIVE pero el estado SSL permanece PENDING.

Causas comunes:

• CNAME de tráfico faltante. El aprovisionador SSL necesita que el CNAME de tráfico sea resoluble antes de poder emitir un certificado. Asegúrate de que auth.tuempresa.com resuelva a your-tenant.accounts.altovar.net.
• Registros CAA bloqueando la emisión. Si tu dominio tiene registros DNS CAA, asegúrate de que letsencrypt.org esté incluido como CA permitida:

tuempresa.com.  IN  CAA  0 issue "letsencrypt.org"

Renovación del Certificado SSL

Los certificados SSL se renuevan automáticamente antes de su vencimiento. No es necesaria ninguna acción. Si la renovación falla (p. ej., el DNS fue modificado), el estado del dominio cambia a Activo con estado SSL Expirado. Corrige el DNS y Auris reintentará la renovación automáticamente.

Eliminar un Dominio Personalizado

Para eliminar un dominio personalizado:

curl -X DELETE https://auth.tudominio.com/api/custom-domains/cd_abc123 \
  -H "Authorization: Bearer $AURIS_ACCESS_TOKEN" \
  -H "x-tenant: your-tenant-id"

Después de eliminar, actualiza la configuración de tu SDK para usar el dominio predeterminado de Auris u otro dominio personalizado. Recuerda eliminar también los registros DNS en tu proveedor.

Guías Relacionadas

• Inicio de Sesión Alojado (PKCE) — Configurar el flujo de código de autorización OAuth2
• SSO Empresarial — Federación SAML y OIDC para clientes empresariales
• Marca — Guía completa de personalización de marca