Login alojado (Authorization Code + PKCE)
El Login Alojado de Auris es el método de autenticación recomendado para aplicaciones web y móviles. Usa el flujo OAuth2 Authorization Code con PKCE (Proof Key for Code Exchange, RFC 7636) para autenticar usuarios de forma segura sin exponer secretos de cliente en el código del frontend.
La página de inicio de sesión alojada está completamente gestionada por Auris e incluye autenticación por email/contraseña, inicio de sesión social, magic links, SMS OTP y WebAuthn — todo en un único flujo. Respeta la configuración de marca de tu tenant y admite múltiples idiomas.
La protección PKCE se aplica por defecto en todos los flujos de código de autorización de Auris. El método de challenge plain no está permitido — solo se acepta S256.
Cómo funciona
Generar los parámetros PKCE
Tu aplicación genera un code_verifier aleatorio criptográficamente (43-128 caracteres) y deriva un code_challenge a partir de él usando hash SHA-256: code_challenge = BASE64URL(SHA256(code_verifier)).
Redirigir a la página de inicio de sesión alojada
Tu aplicación redirige el navegador del usuario al endpoint de autorización de Auris con el code_challenge, client_id, redirect_uri, state y opcionalmente scope, locale, login_hint, prompt y screen_hint.
El usuario se autentica
El usuario completa la autenticación en la página alojada de Auris. Si se requiere autenticación multifactor (por rol, puntuación de riesgo o política del tenant), se solicita al usuario un segundo factor dentro del mismo flujo alojado.
Recibir el código de autorización
Tras una autenticación exitosa, Auris redirige de vuelta a tu redirect_uri con un code de autorización de corta duración y el parámetro state original para la validación CSRF.
Intercambiar el código por tokens
Tu aplicación envía el code y el code_verifier (no el challenge) al endpoint de tokens de Auris. Auris verifica que SHA256(code_verifier) coincide con el code_challenge almacenado y emite un access_token, refresh_token y id_token.
Requisitos previos
Antes de implementar el login alojado, necesitas una aplicación registrada en la Consola Auris:
- Ve a Consola → Aplicaciones y haz clic en Crear aplicación
- Selecciona el tipo de aplicación Web
- En URLs de callback permitidas, añade tu
redirect_uri(p. ej.,http://localhost:3000/callback) - Anota tu Client ID — lo usarás en la configuración del SDK
- No uses un Client Secret en aplicaciones frontend — PKCE lo reemplaza
La redirect_uri usada en tiempo de ejecución debe coincidir exactamente con una de las URIs registradas en la Consola. Auris rechaza cualquier redirección a una URI no registrada.
Implementación
React
import { AurisProvider, useAuris } from '@auris/react'
// Envuelve la raíz de tu app con AurisProvider
function App() {
return (
<AurisProvider
domain="auth.tudominio.com"
clientId="tu-client-id"
redirectUri="http://localhost:3000/callback"
>
<MyApp />
</AurisProvider>
)
}
// Componente de botón de inicio de sesión
function LoginButton() {
const { loginWithRedirect, logout, isAuthenticated, user, isLoading } = useAuris()
if (isLoading) return <p>Cargando...</p>
if (isAuthenticated) {
return (
<div>
<p>Bienvenido, {user.name}</p>
<button onClick={() => logout({ returnTo: window.location.origin })}>
Cerrar sesión
</button>
</div>
)
}
return <button onClick={loginWithRedirect}>Iniciar sesión</button>
}
// Página de callback — gestiona la redirección de vuelta desde Auris
// Coloca esto en la ruta de tu redirectUri
import { useEffect } from 'react'
import { useAuris } from '@auris/react'
import { useNavigate } from 'react-router-dom'
function CallbackPage() {
const { handleRedirectCallback } = useAuris()
const navigate = useNavigate()
useEffect(() => {
handleRedirectCallback().then(() => {
navigate('/dashboard')
})
}, [])
return <p>Completando inicio de sesión...</p>
}
// AuthGuard — protege rutas que requieren autenticación
import { AuthGuard } from '@auris/react'
function ProtectedPage() {
return (
<AuthGuard>
<h1>Esta página requiere autenticación</h1>
</AuthGuard>
)
}Opciones de personalización
Los siguientes parámetros de consulta se pueden pasar a loginWithRedirect() para personalizar la experiencia del login alojado:
| Parámetro | Tipo | Descripción |
|---|---|---|
locale | string | Anula el idioma de la UI. Compatibles: en, it, de, fr, es |
login_hint | string | Rellena previamente el campo de email con una dirección conocida |
prompt | login | none | login fuerza la reautenticación. none devuelve un error si no hay sesión activa |
screen_hint | signup | Abre directamente el formulario de registro en lugar del formulario de inicio de sesión |
connection | string | Fuerza un alias de conexión SSO específico (omite el formulario de inicio de sesión) |
// Ejemplos
await auris.loginWithRedirect({
login_hint: '[email protected]',
screen_hint: 'signup',
locale: 'es',
})
// Forzar reautenticación (ignorar sesión existente)
await auris.loginWithRedirect({ prompt: 'login' })
// Comprobar sesión en silencio (devuelve error si no está autenticado)
await auris.loginWithRedirect({ prompt: 'none' })Gestión de tokens
Token de acceso
El token de acceso es un JWT firmado con RS256 (o HS256 si está configurado). Contiene claims estándar (iss, sub, exp, iat) más claims específicos de Auris (roles, type y cualquier claim personalizado configurado para la aplicación).
Los tokens de acceso son válidos durante la duración configurada en tu tenant (por defecto: 60 minutos).
Token de refresco
Los tokens de refresco son de larga duración y permiten obtener nuevos tokens de acceso sin interacción del usuario. El SDK gestiona el refresco automáticamente cuando autoRefresh: true está establecido.
// Refresco manual de token
const newToken = await auris.refreshToken()
// Obtener token de acceso — se refresca automáticamente si expiró (cuando autoRefresh: true)
const accessToken = await auris.getAccessToken()Almacenamiento de tokens
Por defecto, el SDK almacena los tokens en localStorage. Para aplicaciones que requieren mayor seguridad, puedes usar un adaptador de almacenamiento basado en cookies:
import { AurisClient, CookieStorage } from '@auris/js'
const auris = new AurisClient({
domain: 'auth.tudominio.com',
clientId: 'tu-client-id',
redirectUri: 'http://localhost:3000/callback',
storage: new CookieStorage({ secure: true, sameSite: 'Lax' }),
})Consideraciones de seguridad
Aplicación de PKCE S256 — Auris solo acepta S256 como método de code challenge. El método plain se rechaza en el endpoint de autorización.
Validación de URI de redirección — La redirect_uri en la solicitud de intercambio de tokens debe coincidir exactamente con la URI registrada en la Consola. No se permiten coincidencias parciales ni comodines.
Parámetro state — El SDK genera un valor state aleatorio criptográficamente para cada solicitud de autorización y lo valida en el callback. Esto previene ataques CSRF. No desactives la validación del state.
Códigos de autorización de corta duración — Los códigos de autorización expiran tras 5 minutos y solo se pueden usar una vez. Cualquier intento de reutilizar un código resulta en un rechazo e invalidación de los tokens ya emitidos para esa sesión.
Códigos de un solo uso — El intercambio de código se realiza en una transacción atómica. Si un código se intercambia dos veces (p. ej., por un doble envío), la segunda solicitud se rechaza y los tokens emitidos del primer intercambio se revocan.
Endpoints de la API
/api/oauth/authorizeInicia el flujo de código de autorización. Valida client_id, redirect_uri, parámetros PKCE y crea una sesión OAuth. Devuelve la URL de la página de inicio de sesión alojada.
/api/auth/tokenIntercambia un código de autorización por tokens (grant_type=authorization_code). También gestiona los tipos de grant client_credentials y refresh_token.
/.well-known/openid-configurationDocumento de descubrimiento OIDC. Contiene todas las URLs de endpoints, tipos de grant soportados, algoritmos de firma y tipos de claims.
/.well-known/jwks.jsonJSON Web Key Set (JWKS). Contiene las claves públicas para verificar las firmas de los tokens de acceso. Se almacena en caché durante 1 hora.
Variables de entorno
# Requeridas para la integración con Next.js
NEXT_PUBLIC_AURIS_DOMAIN=auth.tudominio.com
NEXT_PUBLIC_AURIS_CLIENT_ID=tu-client-id
NEXT_PUBLIC_APP_URL=http://localhost:3000
# Opcional — para verificación JWT en el servidor sin llamada de red
AURIS_JWKS_URL=https://auth.tudominio.com/.well-known/jwks.jsonGuías relacionadas
- Inicio de sesión social — Añade Google, GitHub y otros proveedores
- Magic Links — Autenticación por email sin contraseña
- SMS OTP — Autenticación por teléfono y 2FA
- Passkeys / WebAuthn — Autenticación biométrica y con llave de seguridad
- SSO empresarial — Federación SAML 2.0 y OIDC
- Credenciales de cliente M2M — Autenticación servidor a servidor
The hosted login page is fully managed by Auris and includes email/password authentication, social login, magic links, SMS OTP, and WebAuthn — all in a single flow. It respects your tenant branding configuration and supports multiple locales.
PKCE protection is enforced by default on all Auris authorization code flows. The plain challenge method is not permitted — only S256 is accepted.
How It Works
Generate PKCE parameters
Your application generates a cryptographically random code_verifier (43-128 characters) and derives a code_challenge from it using SHA-256 hashing: code_challenge = BASE64URL(SHA256(code_verifier)).
Redirect to the hosted login page
Your application redirects the user’s browser to the Auris authorization endpoint with the code_challenge, client_id, redirect_uri, state, and optionally scope, locale, login_hint, prompt, and screen_hint.
User authenticates
The user completes authentication on the Auris hosted page. If multi-factor authentication is required (by role, risk score, or tenant policy), the user is prompted for a second factor within the same hosted flow.
Receive the authorization code
On successful authentication, Auris redirects back to your redirect_uri with a short-lived authorization code and the original state parameter for CSRF validation.
Exchange the code for tokens
Your application sends the code and code_verifier (not the challenge) to the Auris token endpoint. Auris verifies that SHA256(code_verifier) matches the stored code_challenge and issues an access_token, refresh_token, and id_token.
Prerequisites
Before implementing hosted login, you need an application registered in the Auris Console:
- Go to Console → Applications and click Create Application
- Select the Web application type
- Under Allowed Callback URLs, add your
redirect_uri(e.g.,http://localhost:3000/callback) - Note your Client ID — you will use this in SDK configuration
- Do not use a Client Secret in frontend applications — PKCE replaces it
The redirect_uri used at runtime must exactly match one of the URIs registered in the Console. Auris rejects any redirect to an unregistered URI.
Implementation
React
import { AurisProvider, useAuris } from '@auris/react'
// Wrap your app root with AurisProvider
function App() {
return (
<AurisProvider
domain="auth.yourdomain.com"
clientId="your-client-id"
redirectUri="http://localhost:3000/callback"
>
<MyApp />
</AurisProvider>
)
}
// Login button component
function LoginButton() {
const { loginWithRedirect, logout, isAuthenticated, user, isLoading } = useAuris()
if (isLoading) return <p>Loading...</p>
if (isAuthenticated) {
return (
<div>
<p>Welcome, {user.name}</p>
<button onClick={() => logout({ returnTo: window.location.origin })}>
Log out
</button>
</div>
)
}
return <button onClick={loginWithRedirect}>Log in</button>
}
// Callback page — handles the redirect back from Auris
// Place this at your redirectUri path
import { useEffect } from 'react'
import { useAuris } from '@auris/react'
import { useNavigate } from 'react-router-dom'
function CallbackPage() {
const { handleRedirectCallback } = useAuris()
const navigate = useNavigate()
useEffect(() => {
handleRedirectCallback().then(() => {
navigate('/dashboard')
})
}, [])
return <p>Completing sign in...</p>
}
// AuthGuard — protect routes that require authentication
import { AuthGuard } from '@auris/react'
function ProtectedPage() {
return (
<AuthGuard>
<h1>This page requires authentication</h1>
</AuthGuard>
)
}Customization Options
The following query parameters can be passed to loginWithRedirect() to customize the hosted login experience:
| Parameter | Type | Description |
|---|---|---|
locale | string | Override the UI locale. Supported: en, it, de, fr, es |
login_hint | string | Pre-fill the email field with a known address |
prompt | login | none | login forces re-authentication. none returns an error if no active session |
screen_hint | signup | Opens the registration form directly instead of the login form |
connection | string | Force a specific SSO connection alias (bypasses login form) |
// Examples
await auris.loginWithRedirect({
login_hint: '[email protected]',
screen_hint: 'signup',
locale: 'it',
})
// Force re-authentication (ignore existing session)
await auris.loginWithRedirect({ prompt: 'login' })
// Silently check session (returns error if not authenticated)
await auris.loginWithRedirect({ prompt: 'none' })Token Handling
Access Token
The access token is a JWT signed with RS256 (or HS256 if configured). It contains standard claims (iss, sub, exp, iat) plus Auris-specific claims (roles, type, and any custom claims configured for the application).
Access tokens are valid for the duration configured on your tenant (default: 60 minutes).
Refresh Token
Refresh tokens are long-lived and allow obtaining new access tokens without user interaction. The SDK handles refresh automatically when autoRefresh: true is set.
// Manual token refresh
const newToken = await auris.refreshToken()
// Get access token — auto-refreshes if expired (when autoRefresh: true)
const accessToken = await auris.getAccessToken()Token Storage
By default, the SDK stores tokens in localStorage. For applications requiring higher security, you can use a cookie-based storage adapter:
import { AurisClient, CookieStorage } from '@auris/js'
const auris = new AurisClient({
domain: 'auth.yourdomain.com',
clientId: 'your-client-id',
redirectUri: 'http://localhost:3000/callback',
storage: new CookieStorage({ secure: true, sameSite: 'Lax' }),
})Security Considerations
PKCE S256 enforcement — Auris only accepts S256 as the code challenge method. The plain method is rejected at the authorization endpoint.
Redirect URI validation — The redirect_uri in the token exchange request must exactly match the URI registered in the Console. Partial matches and wildcards are not permitted.
State parameter — The SDK generates a cryptographically random state value for every authorization request and validates it on callback. This prevents CSRF attacks. Do not disable state validation.
Short-lived authorization codes — Authorization codes expire after 5 minutes and can only be used once. Any attempt to reuse a code results in a rejection and invalidation of any tokens already issued for that session.
Single-use codes — Code exchange is performed in an atomic transaction. If a code is exchanged twice (e.g., due to a double-submit), the second request is rejected and the issued tokens from the first exchange are revoked.
API Endpoints
/api/oauth/authorizeInitiates the authorization code flow. Validates client_id, redirect_uri, PKCE parameters, and creates an OAuth session. Returns the hosted login page URL.
/api/auth/tokenExchanges an authorization code for tokens (grant_type=authorization_code). Also handles client_credentials and refresh_token grant types.
/.well-known/openid-configurationOIDC Discovery document. Contains all endpoint URLs, supported grant types, signing algorithms, and claim types.
/.well-known/jwks.jsonJSON Web Key Set (JWKS). Contains public keys for verifying access token signatures. Cached for 1 hour.
Environment Variables
# Required for Next.js integration
NEXT_PUBLIC_AURIS_DOMAIN=auth.yourdomain.com
NEXT_PUBLIC_AURIS_CLIENT_ID=your-client-id
NEXT_PUBLIC_APP_URL=http://localhost:3000
# Optional — for server-side JWT verification without network call
AURIS_JWKS_URL=https://auth.yourdomain.com/.well-known/jwks.jsonRelated Guides
- Social Login — Add Google, GitHub, and other providers
- Magic Links — Passwordless email authentication
- SMS OTP — Phone-based authentication and 2FA
- Passkeys / WebAuthn — Biometric and hardware key authentication
- Enterprise SSO — SAML 2.0 and OIDC federation
- M2M Client Credentials — Server-to-server authentication