Inicio rápido

Esta guía te lleva paso a paso por la integración de la autenticación de Auris en tu aplicación desde cero. Al final tendrás un flujo de inicio de sesión funcional que redirige a los usuarios a la página de inicio de sesión alojada por Auris, gestiona el callback y muestra la información del usuario autenticado.

Tiempo estimado: 5–10 minutos.

Requisitos previos

Node.js 20+ (para integraciones con JavaScript, React y Next.js)
PHP 7.4+ con Composer (para integraciones PHP)
Una cuenta Auris — regístrate en la URL de tu Consola Auris
Un proyecto de aplicación existente al que quieras añadir autenticación

Paso 1: Crear una aplicación en la consola

Antes de instalar ningún SDK, registra tu aplicación en Auris para que reciba un Client ID.

Inicia sesión en la Consola Auris.
Ve a Aplicaciones en la barra lateral.
Haz clic en Crear aplicación.
Selecciona el tipo de aplicación:
- WEB — para aplicaciones basadas en navegador (React, Next.js, Vue, Angular, renderizado en servidor)
- MOBILE — para aplicaciones nativas iOS o Android
- M2M — para integraciones servidor a servidor o herramientas CLI (sin inicio de sesión de usuario)
Introduce un nombre descriptivo para tu aplicación (p. ej., Mi App - Desarrollo).
Añade tu URI de redirección — la URL a la que Auris redirigirá tras un inicio de sesión exitoso:
- Desarrollo local: http://localhost:3000/callback
- Producción: https://tudominio.com/callback
Haz clic en Crear.

Tras la creación, copia tu Client ID desde la página de detalle de la aplicación. Lo necesitarás en los siguientes pasos.

Nunca expongas tu Client Secret en JavaScript del lado del navegador. Para los tipos de

aplicación WEB y MOBILE, Auris usa PKCE (Proof Key for Code Exchange) y no requiere un

client secret. Los client secrets solo se usan para aplicaciones M2M (client_credentials)

que se ejecutan en el servidor.

Paso 2: Instalar el SDK

Elige el SDK que se corresponda con tu stack. Todos los paquetes están publicados en npm (JavaScript/TypeScript) o Packagist (PHP).

Next.js


 
npm install @auris/nextjs @auris/react @auris/js

React


 
npm install @auris/react @auris/js

JavaScript


 
npm install @auris/js

PHP


 
composer require auris/sdk

@auris/nextjs re-exporta todo desde @auris/react y @auris/js, por lo que solo necesitas

una ruta de importación en un proyecto Next.js.

Paso 3: Configurar Auris

Inicializa el cliente Auris con el dominio de tu tenant y el Client ID de la aplicación.

Next.js

Añade AurisProvider a tu layout.tsx raíz. El provider gestiona el almacenamiento de tokens, el refresco y el contexto de estado de autenticación para todos los componentes hijos.


 
// app/layout.tsx
 
import { AurisProvider } from '@auris/nextjs'
 
 
 
export default function RootLayout({
 
  children,
 
}: {
 
  children: React.ReactNode
 
}) {
 
  return (
 
    <html lang="en">
 
      <body>
 
        <AurisProvider
 
          domain="https://auth.tudominio.com"
 
          clientId="TU_CLIENT_ID"
 
          redirectUri="http://localhost:3000/callback"
 
        >
 
          {children}
 
        </AurisProvider>
 
      </body>
 
    </html>
 
  )
 
}

Luego añade el middleware de Auris para proteger rutas. Crea o actualiza middleware.ts en la raíz del proyecto:


 
// middleware.ts
 
import { aurisMiddleware } from '@auris/nextjs/middleware'
 
 
 
export default aurisMiddleware({
 
  domain: process.env.AURIS_DOMAIN!,
 
  clientId: process.env.AURIS_CLIENT_ID!,
 
  // Rutas que requieren autenticación
 
  protectedPaths: ['/dashboard', '/settings', '/profile'],
 
  // Rutas que omiten las comprobaciones de autenticación (el callback OAuth debe ser público)
 
  publicPaths: ['/callback', '/login', '/'],
 
})
 
 
 
export const config = {
 
  matcher: ['/((?!_next/static|_next/image|favicon.ico).*)'],
 
}

React

Envuelve la raíz de tu aplicación con AurisProvider:


 
// src/main.tsx (o src/index.tsx)
 
import React from 'react'
 
import ReactDOM from 'react-dom/client'
 
import { AurisProvider } from '@auris/react'
 
import App from './App'
 
 
 
ReactDOM.createRoot(document.getElementById('root')!).render(
 
  <React.StrictMode>
 
    <AurisProvider
 
      domain="https://auth.tudominio.com"
 
      clientId="TU_CLIENT_ID"
 
      redirectUri="http://localhost:3000/callback"
 
    >
 
      <App />
 
    </AurisProvider>
 
  </React.StrictMode>
 
)

JavaScript

Crea una instancia de AurisClient. Mantenla como singleton — créala una vez y expórtala.


 
// lib/auris.ts
 
import { AurisClient } from '@auris/js'
 
 
 
export const auris = new AurisClient({
 
  domain: 'https://auth.tudominio.com',
 
  clientId: 'TU_CLIENT_ID',
 
  redirectUri: 'http://localhost:3000/callback',
 
})

PHP


 
<?php
 
// config/auris.php (o incluir en el bootstrap de la app)
 
require_once __DIR__ . '/vendor/autoload.php';
 
 
 
use Auris\AurisClient;
 
use Auris\AurisConfig;
 
 
 
$config = new AurisConfig(
 
    'https://auth.tudominio.com',        // domain
 
    'TU_CLIENT_ID',                      // clientId
 
    'http://localhost:8000/callback.php' // redirectUri
 
    // clientSecret por defecto '' — no es necesario para apps WEB/PKCE
 
);
 
 
 
$auris = new AurisClient($config);

Reemplaza https://auth.tudominio.com con la URL real de tu tenant Auris y TU_CLIENT_ID con el Client ID del Paso 1.

Paso 4: Añadir un botón de inicio de sesión

Inicia el flujo de inicio de sesión redirigiendo al usuario a la página de inicio de sesión alojada por Auris.

Next.js


 
// components/LoginButton.tsx
 
'use client'
 
 
 
import { useAuris } from '@auris/nextjs'
 
 
 
export function LoginButton() {
 
  const { loginWithRedirect } = useAuris()
 
 
 
  return (
 
    <button onClick={() => loginWithRedirect()}>
 
      Iniciar sesión
 
    </button>
 
  )
 
}

Para enviar al usuario a una página específica tras la autenticación, guarda el destino antes de redirigir y léelo de vuelta en tu página de callback:


 
sessionStorage.setItem('returnTo', '/dashboard')
 
loginWithRedirect()

React


 
// components/LoginButton.tsx
 
import { useAuris } from '@auris/react'
 
 
 
export function LoginButton() {
 
  const { loginWithRedirect } = useAuris()
 
 
 
  return (
 
    <button onClick={() => loginWithRedirect()}>
 
      Iniciar sesión
 
    </button>
 
  )
 
}

JavaScript


 
// Inicia el inicio de sesión — esto redirige el navegador a la página de inicio de sesión de Auris
 
import { auris } from './lib/auris'
 
 
 
document.getElementById('login-button')?.addEventListener('click', async () => {
 
  await auris.loginWithRedirect()
 
})

PHP


 
<?php
 
// login.php
 
require_once 'config/auris.php';
 
 
 
// Redirige el navegador a la página de inicio de sesión alojada por Auris.
 
// El challenge PKCE y el state CSRF se generan y almacenan automáticamente.
 
header('Location: ' . $auris->getLoginUrl());
 
exit;

O obtén la URL para renderizarla como etiqueta anchor:


 
$loginUrl = $auris->getLoginUrl();
 
echo '<a href="' . htmlspecialchars($loginUrl) . '">Iniciar sesión</a>';

Paso 5: Gestionar el callback

Después de que el usuario se autentique, Auris lo redirige de vuelta a tu redirectUri con un código de autorización. Tu aplicación debe intercambiar este código por tokens.

Next.js

Crea una página de callback en la ruta que coincida con tu redirectUri. El SDK @auris/nextjs gestiona el intercambio de código automáticamente cuando detecta el parámetro code en la URL.


 
// app/callback/page.tsx
 
'use client'
 
 
 
import { useEffect } from 'react'
 
import { useRouter } from 'next/navigation'
 
import { useAuris } from '@auris/nextjs'
 
 
 
export default function CallbackPage() {
 
  const { isAuthenticated, isLoading, error } = useAuris()
 
  const router = useRouter()
 
 
 
  useEffect(() => {
 
    // AurisProvider completa el intercambio de código automáticamente al montarse.
 
    // Cuando la sesión está lista, sal de la página de callback.
 
    if (!isLoading && isAuthenticated) {
 
      router.replace('/dashboard')
 
    }
 
  }, [isLoading, isAuthenticated, router])
 
 
 
  if (error) {
 
    return <p>Error al iniciar sesión: {error.message}</p>
 
  }
 
 
 
  return <p>Completando inicio de sesión...</p>
 
}

React


 
// src/pages/Callback.tsx
 
import { useEffect } from 'react'
 
import { useNavigate } from 'react-router-dom'
 
import { useAuris } from '@auris/react'
 
 
 
export function CallbackPage() {
 
  const { isAuthenticated, isLoading, error } = useAuris()
 
  const navigate = useNavigate()
 
 
 
  useEffect(() => {
 
    // AurisProvider completa el intercambio de código automáticamente al montarse.
 
    // Cuando la sesión está lista, sal de la página de callback.
 
    if (!isLoading && isAuthenticated) {
 
      navigate('/dashboard', { replace: true })
 
    }
 
  }, [isLoading, isAuthenticated, navigate])
 
 
 
  if (error) {
 
    return <p>Error al iniciar sesión: {error.message}</p>
 
  }
 
 
 
  return <p>Completando inicio de sesión...</p>
 
}

JavaScript


 
// callback.ts — ejecuta este script en tu página de callback
 
import { auris } from './lib/auris'
 
 
 
async function handleCallback() {
 
  await auris.handleRedirectCallback()
 
  // Guarda el destino deseado en sessionStorage antes de loginWithRedirect() si lo necesitas
 
  window.location.replace('/dashboard')
 
}
 
 
 
handleCallback()

PHP


 
<?php
 
// callback.php
 
require_once 'config/auris.php';
 
 
 
use Auris\AurisException;
 
 
 
session_start();
 
 
 
try {
 
    // Intercambia el código de autorización por tokens.
 
    // Valida el state CSRF y envía el code verifier PKCE automáticamente.
 
    $tokens = $auris->handleCallback($_GET['code'], $_GET['state']);
 
 
 
    // Almacena los tokens en la sesión
 
    $_SESSION['auris_access_token'] = $tokens->accessToken;
 
    $_SESSION['auris_refresh_token'] = $tokens->refreshToken;
 
 
 
    // Redirige a la app
 
    header('Location: /dashboard.php');
 
    exit;
 
} catch (AurisException $e) {
 
    // Gestiona el fallo de autenticación (state no coincidente o error del endpoint de tokens)
 
    echo 'Autenticación fallida: ' . htmlspecialchars($e->getMessage());
 
}

Paso 6: Mostrar información del usuario

Una vez autenticado, recupera y muestra el perfil del usuario actual.

Next.js


 
// app/dashboard/page.tsx
 
'use client'
 
 
 
import { useUser, useAuris } from '@auris/nextjs'
 
 
 
export default function DashboardPage() {
 
  const { user, isLoading } = useUser()
 
  const { isAuthenticated } = useAuris()
 
 
 
  if (isLoading) {
 
    return <p>Cargando...</p>
 
  }
 
 
 
  if (!isAuthenticated) {
 
    return <p>No has iniciado sesión.</p>
 
  }
 
 
 
  return (
 
    <div>
 
      <h1>Bienvenido, {user?.firstName ?? user?.email}</h1>
 
      <p>Email: {user?.email}</p>
 
      <p>Roles: {user?.roles?.join(', ')}</p>
 
    </div>
 
  )
 
}

Para componentes de servidor, usa getSession en su lugar:


 
// app/dashboard/page.tsx (componente de servidor)
 
import { getSession } from '@auris/nextjs/server'
 
import { redirect } from 'next/navigation'
 
 
 
export default async function DashboardPage() {
 
  const session = await getSession({
 
    domain: process.env.AURIS_DOMAIN!,
 
    clientId: process.env.AURIS_CLIENT_ID!,
 
  })
 
 
 
  if (!session) {
 
    // Redirige al inicio de sesión si el middleware no gestiona esta ruta
 
    redirect('/login')
 
  }
 
 
 
  return (
 
    <div>
 
      <h1>Bienvenido, {session.firstName}</h1>
 
    </div>
 
  )
 
}

React


 
// src/components/UserProfile.tsx
 
import { useUser, useAuris } from '@auris/react'
 
 
 
export function UserProfile() {
 
  const { user, isLoading } = useUser()
 
  const { isAuthenticated } = useAuris()
 
 
 
  if (isLoading) {
 
    return <p>Cargando...</p>
 
  }
 
 
 
  if (!isAuthenticated || !user) {
 
    return <p>No has iniciado sesión.</p>
 
  }
 
 
 
  return (
 
    <div>
 
      <h1>Bienvenido, {user.firstName ?? user.email}</h1>
 
      <p>Email: {user.email}</p>
 
      <p>Roles: {user.roles?.join(', ')}</p>
 
    </div>
 
  )
 
}

JavaScript


 
// dashboard.ts
 
import { auris } from './lib/auris'
 
 
 
async function renderDashboard() {
 
  const user = await auris.getUser()
 
 
 
  if (!user) {
 
    // No autenticado — redirige al inicio de sesión
 
    await auris.loginWithRedirect()
 
    return
 
  }
 
 
 
  document.getElementById('user-name')!.textContent =
 
    user.firstName ?? user.email ?? 'Usuario'
 
  document.getElementById('user-email')!.textContent = user.email ?? ''
 
}
 
 
 
renderDashboard()

PHP


 
<?php
 
// dashboard.php
 
require_once 'config/auris.php';
 
 
 
use Auris\AurisException;
 
 
 
session_start();
 
 
 
if (empty($_SESSION['auris_access_token'])) {
 
    header('Location: /login.php');
 
    exit;
 
}
 
 
 
// Refresca el token de acceso si ha expirado
 
if ($auris->isTokenExpired($_SESSION['auris_access_token'])) {
 
    try {
 
        $refreshed = $auris->refreshToken($_SESSION['auris_refresh_token']);
 
        $_SESSION['auris_access_token'] = $refreshed->accessToken;
 
    } catch (AurisException $e) {
 
        header('Location: /login.php');
 
        exit;
 
    }
 
}
 
 
 
try {
 
    // Valida el token y obtiene el perfil del usuario
 
    $user = $auris->getUser($_SESSION['auris_access_token']);
 
} catch (AurisException $e) {
 
    header('Location: /login.php');
 
    exit;
 
}
 
?>
 
<h1>Bienvenido, <?= htmlspecialchars($user->firstName ?? $user->email) ?></h1>
 
<p>Email: <?= htmlspecialchars($user->email) ?></p>

Paso 7: Añadir un botón de cierre de sesión

Next.js


 
'use client'
 
 
 
import { useAuris } from '@auris/nextjs'
 
 
 
export function LogoutButton() {
 
  const { logout } = useAuris()
 
 
 
  return (
 
    <button onClick={() => logout()}>
 
      {/* Gestiona la redirección post-logout en tu router */}
 
      Cerrar sesión
 
    </button>
 
  )
 
}

React


 
import { useAuris } from '@auris/react'
 
 
 
export function LogoutButton() {
 
  const { logout } = useAuris()
 
 
 
  return (
 
    <button onClick={() => logout()}>
 
      {/* Gestiona la redirección post-logout en tu router */}
 
      Cerrar sesión
 
    </button>
 
  )
 
}

JavaScript


 
import { auris } from './lib/auris'
 
 
 
document.getElementById('logout-button')?.addEventListener('click', () => {
 
  // Gestiona la redirección post-logout en tu router
 
  auris.logout()
 
})

PHP


 
<?php
 
// logout.php
 
require_once 'config/auris.php';
 
 
 
use Auris\AurisException;
 
 
 
session_start();
 
 
 
// Revoca el token de acceso y termina la sesión de Auris en el servidor
 
if (!empty($_SESSION['auris_access_token'])) {
 
    try {
 
        $auris->logout($_SESSION['auris_access_token']);
 
    } catch (AurisException $e) {
 
        // Token ya inválido o revocado — se puede ignorar sin problema
 
    }
 
}
 
 
 
// Limpia la sesión local
 
session_destroy();
 
 
 
header('Location: /');
 
exit;

Variables de entorno

Almacena la configuración de Auris en variables de entorno, no en el código fuente:


 
# .env.local
 
 
 
# Lado del cliente: usadas por AurisProvider en el bundle del navegador
 
NEXT_PUBLIC_AURIS_DOMAIN=https://auth.tudominio.com
 
NEXT_PUBLIC_AURIS_CLIENT_ID=tu_client_id_aqui
 
 
 
# Lado del servidor: usadas por aurisMiddleware() y getSession() — nunca expuestas al navegador
 
AURIS_DOMAIN=https://auth.tudominio.com
 
AURIS_CLIENT_ID=tu_client_id_aqui
 
 
 
# Solo para clientes M2M del lado del servidor (nunca expongas esto en el navegador)
 
AURIS_CLIENT_SECRET=tu_client_secret_aqui
 
 
 
# Para la verificación JWT sin una llamada de red (opcional, recomendado por rendimiento)
 
AURIS_JWKS_URL=https://auth.tudominio.com/.well-known/jwks.json

Luego úsalas en la configuración de tu provider:


 
<AurisProvider
 
  domain={process.env.NEXT_PUBLIC_AURIS_DOMAIN!}
 
  clientId={process.env.NEXT_PUBLIC_AURIS_CLIENT_ID!}
 
  redirectUri={`${process.env.NEXT_PUBLIC_APP_URL}/callback`}
 
>

Las variables de entorno con el prefijo NEXT_PUBLIC_ se incrustan en el bundle del navegador

y son públicas. Solo el domain y el clientId deben ser públicos. Nunca expongas

AURIS_CLIENT_SECRET con el prefijo NEXT_PUBLIC_. Las variables AURIS_DOMAIN y

AURIS_CLIENT_ID sin prefijo son solo del servidor y nunca se envían al navegador.

Próximos pasos

Ahora que tienes un flujo básico de inicio de sesión funcionando, explora las funciones más relevantes para tu aplicación:

Métodos de autenticación

Autorización

Gestión de usuarios

SDKs y API