Skip to Content

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:

  1. Ve a Consola → Aplicaciones y haz clic en Crear aplicación
  2. Selecciona el tipo de aplicación Web
  3. En URLs de callback permitidas, añade tu redirect_uri (p. ej., http://localhost:3000/callback)
  4. Anota tu Client ID — lo usarás en la configuración del SDK
  5. 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

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ámetroTipoDescripción
localestringAnula el idioma de la UI. Compatibles: en, it, de, fr, es
login_hintstringRellena previamente el campo de email con una dirección conocida
promptlogin | nonelogin fuerza la reautenticación. none devuelve un error si no hay sesión activa
screen_hintsignupAbre directamente el formulario de registro en lugar del formulario de inicio de sesión
connectionstringFuerza 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

POST/api/oauth/authorize

Inicia 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.

POST/api/auth/token

Intercambia un código de autorización por tokens (grant_type=authorization_code). También gestiona los tipos de grant client_credentials y refresh_token.

GET/.well-known/openid-configuration

Documento de descubrimiento OIDC. Contiene todas las URLs de endpoints, tipos de grant soportados, algoritmos de firma y tipos de claims.

GET/.well-known/jwks.json

JSON 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.json

Guías relacionadas

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:

  1. Go to Console → Applications and click Create Application
  2. Select the Web application type
  3. Under Allowed Callback URLs, add your redirect_uri (e.g., http://localhost:3000/callback)
  4. Note your Client ID — you will use this in SDK configuration
  5. 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

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:

ParameterTypeDescription
localestringOverride the UI locale. Supported: en, it, de, fr, es
login_hintstringPre-fill the email field with a known address
promptlogin | nonelogin forces re-authentication. none returns an error if no active session
screen_hintsignupOpens the registration form directly instead of the login form
connectionstringForce 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

POST/api/oauth/authorize

Initiates the authorization code flow. Validates client_id, redirect_uri, PKCE parameters, and creates an OAuth session. Returns the hosted login page URL.

POST/api/auth/token

Exchanges an authorization code for tokens (grant_type=authorization_code). Also handles client_credentials and refresh_token grant types.

GET/.well-known/openid-configuration

OIDC Discovery document. Contains all endpoint URLs, supported grant types, signing algorithms, and claim types.

GET/.well-known/jwks.json

JSON 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.json