Skip to Content

Avvio Rapido

Questa guida ti accompagna nell’integrazione dell’autenticazione Auris nella tua applicazione da zero. Al termine, avrai un flusso di login funzionante che reindirizza gli utenti alla pagina di login hosted di Auris, gestisce il callback e mostra le informazioni dell’utente autenticato.

Tempo stimato: 5–10 minuti.

Prerequisiti

  • Node.js 20+ (per integrazioni JavaScript, React e Next.js)
  • PHP 7.4+ con Composer (per integrazioni PHP)
  • Un account Auris — registrati all’URL della tua Console Auris
  • Un progetto applicativo esistente a cui vuoi aggiungere l’autenticazione

Passo 1: Crea un’Applicazione nella Console

Prima di installare qualsiasi SDK, registra la tua applicazione con Auris in modo che riceva un Client ID.

  1. Accedi alla Console Auris.
  2. Naviga su Applicazioni nella barra laterale.
  3. Clicca su Crea Applicazione.
  4. Seleziona il tipo di applicazione:
    • WEB — per app basate su browser (React, Next.js, Vue, Angular, server-rendered)
    • MOBILE — per app native iOS o Android
    • M2M — per integrazioni server-to-server o CLI (nessun login utente)
  5. Inserisci un nome visualizzato per la tua applicazione (es. La Mia App - Sviluppo).
  6. Aggiungi il tuo Redirect URI — l’URL a cui Auris reindirizzerà dopo un login riuscito:
    • Sviluppo locale: http://localhost:3000/callback
    • Produzione: https://tuo-dominio.com/callback
  7. Clicca su Crea.

Dopo la creazione, copia il tuo Client ID dalla pagina di dettaglio dell’applicazione.

Non esporre mai il tuo Client Secret nel JavaScript lato browser. Per i tipi di applicazione WEB e MOBILE, Auris usa PKCE (Proof Key for Code Exchange) e non richiede un client secret. I client secret sono usati solo per applicazioni M2M (client_credentials) in esecuzione lato server.

Passo 2: Installa l’SDK

Scegli l’SDK che corrisponde al tuo stack.

# Next.js
npm install @auris/nextjs @auris/react @auris/js
 
# React
npm install @auris/react @auris/js
 
# JavaScript vanilla
npm install @auris/js
 
# PHP
composer require auris/sdk

Passo 3: Configura Auris

Next.js — Aggiungi AurisProvider al tuo layout.tsx root:

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

Aggiungi il middleware Auris per proteggere le route:

// middleware.ts
import { aurisMiddleware } from '@auris/nextjs/middleware'
 
export default aurisMiddleware({
  domain: process.env.AURIS_DOMAIN!,
  clientId: process.env.AURIS_CLIENT_ID!,
  // Route che richiedono autenticazione
  protectedPaths: ['/dashboard', '/settings', '/profile'],
  // Route che saltano del tutto i controlli di autenticazione (il callback OAuth deve essere pubblico)
  publicPaths: ['/callback', '/login', '/'],
})
 
export const config = {
  matcher: ['/((?!_next/static|_next/image|favicon.ico).*)'],
}

React — Avvolgi l’app con AurisProvider:

import { AurisProvider } from '@auris/react'
// ...
<AurisProvider domain="https://auth.tuo-dominio.com" clientId="IL_TUO_CLIENT_ID" redirectUri="...">
  <App />
</AurisProvider>

PHP:

<?php
require_once __DIR__ . '/vendor/autoload.php';
use Auris\AurisClient;
use Auris\AurisConfig;
 
$config = new AurisConfig(
    'https://auth.tuo-dominio.com',      // domain
    'IL_TUO_CLIENT_ID',                  // clientId
    'http://localhost:8000/callback.php' // redirectUri
    // clientSecret di default è '' — non serve per le app WEB/PKCE
);
$auris = new AurisClient($config);

Passo 4: Aggiungi un Pulsante di Login

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

Passo 5: Gestisci il Callback

Dopo l’autenticazione, Auris reindirizza alla tua redirectUri con un codice di autorizzazione.

// 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 lo scambio del codice automaticamente al mount.
    // Quando la sessione è pronta, lascia la pagina di callback.
    if (!isLoading && isAuthenticated) {
      router.replace('/dashboard')
    }
  }, [isLoading, isAuthenticated, router])
 
  if (error) {
    return <p>Accesso non riuscito: {error.message}</p>
  }
 
  return <p>Completamento accesso in corso...</p>
}

Passo 6: Mostra le Informazioni Utente

// 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>Caricamento...</p>
  if (!isAuthenticated) return <p>Non sei autenticato.</p>
 
  return (
    <div>
      <h1>Benvenuto, {user?.firstName ?? user?.email}</h1>
      <p>Email: {user?.email}</p>
      <p>Ruoli: {user?.roles?.join(', ')}</p>
    </div>
  )
}

Passo 7: Aggiungi un Pulsante di Logout

'use client'
import { useAuris } from '@auris/nextjs'
 
export function LogoutButton() {
  const { logout } = useAuris()
  return (
    <button onClick={() => logout()}>
      {/* Gestisci il redirect post-logout nel router */}
      Esci
    </button>
  )
}

Variabili d’Ambiente

# .env.local
 
# Lato client: usate da AurisProvider nel bundle del browser
NEXT_PUBLIC_AURIS_DOMAIN=https://auth.tuo-dominio.com
NEXT_PUBLIC_AURIS_CLIENT_ID=il_tuo_client_id
 
# Lato server: usate da aurisMiddleware e getSession — mai esposte al browser
AURIS_DOMAIN=https://auth.tuo-dominio.com
AURIS_CLIENT_ID=il_tuo_client_id
 
# Solo per client M2M lato server (non esporre mai nel browser)
AURIS_CLIENT_SECRET=il_tuo_client_secret

Le variabili d’ambiente con prefisso NEXT_PUBLIC_ vengono incorporate nel bundle del browser e sono pubbliche. Solo domain e clientId dovrebbero essere pubblici. Non esporre mai AURIS_CLIENT_SECRET con un prefisso NEXT_PUBLIC_.

Prossimi Passi

Architettura