SDK e Librerie
Auris fornisce librerie client ufficiali per tutte le principali piattaforme e framework. Ogni SDK racchiude lo stesso flusso OAuth2 PKCE sottostante e le REST API, con comodità specifiche per ogni framework.
Confronto SDK
La tabella seguente riassume le funzionalità disponibili in ogni pacchetto.
| Funzionalità | @auris/js | @auris/react | @auris/nextjs | auris/sdk (PHP) | auris-sso (WP) | @auris/cli |
|---|---|---|---|---|---|---|
| Autenticazione | Sì | Sì | Sì | Sì | Sì | N/A |
| OAuth2 PKCE | Sì | Sì | Sì | Sì | Sì | N/A |
| Social Login | Sì | Sì | Sì | No | No | N/A |
| Magic Link | Sì | Sì | Sì | No | No | N/A |
| SMS OTP | Sì | Sì | Sì | No | No | N/A |
| Controllo permessi | Sì | Sì (hook) | Sì (server) | No | No | No |
| Autorizzazione fine-grained | Sì | Sì (hook) | Sì (server) | No | No | No |
| Management API | Sì | No | Sì (server) | No | No | Sì |
| Verifica webhook | Sì | No | No | No | No | No |
| Verifica JWT | Sì | No | Sì (server) | No | No | No |
| Supporto SSR | Sì | No | Sì | Sì | N/A | N/A |
| Edge runtime | Sì | No | Sì (middleware) | No | N/A | N/A |
| Zero dipendenze | Sì | No | No | Sì | No | No |
Quale SDK Scegliere
Usa questo schema decisionale per selezionare il pacchetto giusto per il tuo progetto.
Stai costruendo una Single Page Application browser (React, Vue, JS puro)?
Usa @auris/js per codice framework-agnostico, o @auris/react per hook e componenti specifici per React.
Stai costruendo un’applicazione Next.js?
Usa @auris/nextjs. Ri-esporta @auris/react per i Client Components e aggiunge helper server-side per Server Components, Route Handlers ed Edge Middleware.
Stai costruendo un’applicazione PHP o Laravel?
Usa il pacchetto Composer auris/sdk. È PHP puro senza dipendenze esterne e supporta PHP 7.4 e versioni successive.
Gestisci un sito WordPress?
Usa il plugin WordPress auris-sso. Gestisce il login SSO, il provisioning utenti just-in-time e la mappatura dei ruoli tramite la UI di amministrazione WordPress.
Stai scrivendo script, pipeline CI/CD, o automatizzando la gestione del tenant?
Usa @auris/cli. Installalo globalmente e autenticati una volta — poi usa auris users list, auris logs e altri comandi negli script.
Chiamate API server-to-server (senza utente coinvolto)?
Usa @auris/js con il metodo getM2MToken(), o createManagementClient() in @auris/nextjs/server. Entrambi usano il grant OAuth2 client_credentials.
Installazione
# JavaScript (browser, Node.js, edge runtime)
npm install @auris/js
# React
npm install @auris/react @auris/js
# Next.js (include i pacchetti React e JS)
npm install @auris/nextjs @auris/react @auris/js
# PHP
composer require auris/sdk
# CLI (installazione globale)
npm install -g @auris/cliIl plugin WordPress è distribuito come file .zip. Installalo tramite Plugin → Aggiungi nuovo → Carica plugin nell’admin di WordPress.
Esempi di Avvio Rapido
JavaScript
import { AurisClient } from '@auris/js'
const auris = new AurisClient({
domain: 'auth.tuodominio.com',
clientId: 'app_xxxxx',
redirectUri: 'http://localhost:3000/callback',
})
// Reindirizza l'utente alla pagina di login ospitata
await auris.loginWithRedirect()
// Nella pagina di callback, completa il flusso
const result = await auris.handleRedirectCallback()
console.log(result.user)React
import { AurisProvider, useAuris } from '@auris/react'
function App() {
return (
<AurisProvider domain="auth.tuodominio.com" clientId="app_xxxxx">
<LoginButton />
</AurisProvider>
)
}
function LoginButton() {
const { loginWithRedirect, logout, isAuthenticated, user } = useAuris()
if (isAuthenticated) {
return <button onClick={() => logout()}>Esci ({user.email})</button>
}
return <button onClick={loginWithRedirect}>Accedi</button>
}Next.js
// middleware.ts
import { aurisMiddleware } from '@auris/nextjs/middleware'
export default aurisMiddleware({
protectedPaths: ['/dashboard(.*)'],
loginUrl: '/auth/login',
})
// app/dashboard/page.tsx (Server Component)
import { getSession } from '@auris/nextjs/server'
import { redirect } from 'next/navigation'
export default async function DashboardPage() {
const session = await getSession()
if (!session) redirect('/auth/login')
return <h1>Benvenuto, {session.user.name}</h1>
}PHP
<?php
require 'vendor/autoload.php';
use Auris\AurisClient;
use Auris\AurisConfig;
$config = new AurisConfig(
domain: 'auth.tuodominio.com',
clientId: 'your-client-id',
redirectUri: 'https://tua-app.com/callback.php'
);
$auris = new AurisClient($config);
// login.php
session_start();
header('Location: ' . $auris->getLoginUrl());
exit;
// callback.php
session_start();
$result = $auris->handleCallback($_GET['code'], $_GET['state']);
$_SESSION['user'] = $result->getUser();Compatibilità Versioni
| Pacchetto | Node.js min. | PHP min. | WordPress min. |
|---|---|---|---|
@auris/js | 18.0 | N/A | N/A |
@auris/react | 18.0 | N/A | N/A |
@auris/nextjs | 18.0 | N/A | N/A |
auris/sdk | N/A | 7.4 | N/A |
auris-sso | N/A | 7.4 | 5.0 |
@auris/cli | 18.0 | N/A | N/A |
Tutti gli SDK JavaScript includono sia build ESM (import) che CJS (require), oltre a file di dichiarazione TypeScript. Non richiedono un bundler — puoi usarli direttamente in Node.js o nei browser moderni che supportano i moduli ES.
Tutti i pacchetti seguono il versionamento semantico. Le modifiche che rompono la compatibilità API vengono introdotte solo in bump di versione major e sono documentate nel changelog di ogni pacchetto.
Pagine SDK
SDK zero-dipendenze per browser, Node.js ed edge runtime. Riferimento API completo incluso AurisClient, modulo permessi, modulo FGA, client di gestione, verifica webhook e verifica JWT.
SDK JavaScriptBinding React costruiti su @auris/js. Contesto AurisProvider, hook (useAuris, useUser, usePermissions, useFga, useOrganization) e componenti (AuthGuard, PermissionGate, LoginButton).
SDK ReactIntegrazione completa Next.js con tre entry point: client-side (ri-esporta @auris/react), helper server-side (getSession, withAuth, requirePermission) ed Edge Middleware (aurisMiddleware).
SDK Next.jsImplementazione PHP pura OAuth2 PKCE per PHP 7.4+ senza dipendenze esterne. Include esempi PHP vanilla e una guida all’integrazione Laravel.
SDK PHPPlugin SSO per WordPress con provisioning utenti just-in-time, mappatura dei ruoli configurabile e shortcode per il pulsante di login. Richiede il PHP SDK.
Plugin WordPressStrumento a riga di comando per gestire il tenant Auris. Autenticati una volta, poi gestisci utenti, ruoli, applicazioni e audit log dal terminale o nelle pipeline CI/CD.
Strumento CLI