Skip to Content

SDK React (@auris/react)

@auris/react v0.1.0

@auris/react fornisce binding React per Auris IAM. Racchiude @auris/js con un context provider, hook per accedere allo stato di autenticazione, controlli permessi, query FGA e contesto dell’organizzazione — oltre a componenti UI pre-costruiti per i pattern più comuni.

Installazione

npm install @auris/react @auris/js

Entrambi i pacchetti sono obbligatori. @auris/react dipende da @auris/js come peer dependency.

AurisProvider

Avvolgi la radice dell’applicazione (o il sottoalbero che necessita di autenticazione) con AurisProvider. Inizializza AurisClient, ripristina qualsiasi sessione esistente dall’archiviazione e fornisce il contesto Auris a tutti i componenti figli.

import { AurisProvider } from '@auris/react'
 
function App() {
  return (
    <AurisProvider
      domain="auth.tuodominio.com"
      clientId="app_xxxxx"
      redirectUri="http://localhost:3000/callback"
      tenant="my-tenant"
      storage="localStorage"
      autoRefresh={true}
    >
      <TuaApp />
    </AurisProvider>
  )
}

Props:

PropTipoObbligatorioDefaultDescrizione
domainstringSì—Il dominio del tenant Auris
clientIdstringSì—Client ID dell’applicazione
redirectUristringCondizionale—URL di callback per i flussi PKCE
tenantstringNo'default'Identificativo tenant
storagestring | TokenStoreNo'localStorage'Strategia di archiviazione token
autoRefreshbooleanNotrueAggiorna automaticamente i token prima della scadenza
scopestringNo'openid profile email'Scope OAuth2 da richiedere
onRedirectCallback(result: AuthResult) => voidNo—Chiamata dopo il successo di handleRedirectCallback()

In un’applicazione Next.js, importa AurisProvider da @auris/nextjs invece di @auris/react. Il pacchetto Next.js ri-esporta tutti i componenti e gli hook React.

Hook

useAuris()

L’hook principale. Restituisce il contesto di autenticazione completo: utente corrente, stato di caricamento, metodi di autenticazione e informazioni sugli errori.

Restituisce:

interface AurisContextValue {
  // Stato
  user: UserInfo | null
  isLoading: boolean
  isAuthenticated: boolean
  error: AurisError | null
 
  // Metodi di autenticazione
  login: (email: string, password: string) => Promise<AuthResult>
  signup: (email: string, password: string, options?: SignupOptions) => Promise<AuthResult>
  logout: (options?: LogoutOptions) => Promise<void>
  loginWithRedirect: (options?: LoginWithRedirectOptions) => Promise<void>
  handleRedirectCallback: () => Promise<AuthResult>
  loginWithMagicLink: (email: string) => Promise<void>
  verifyMagicLink: (token: string) => Promise<AuthResult>
  loginWithSocial: (provider: SocialProvider) => Promise<void>
  refreshToken: () => Promise<AuthResult>
 
  // Accesso al token
  getAccessToken: () => Promise<string | null>
}
import { useAuris } from '@auris/react'
 
function MenuUtente() {
  const { user, isLoading, isAuthenticated, loginWithRedirect, logout } = useAuris()
 
  if (isLoading) return <div>Caricamento...</div>
 
  if (!isAuthenticated) {
    return <button onClick={loginWithRedirect}>Accedi</button>
  }
 
  return (
    <div>
      <span>{user.name}</span>
      <button onClick={() => logout({ returnTo: window.location.origin })}>Esci</button>
    </div>
  )
}

useUser()

Un hook focalizzato che restituisce solo l’utente corrente e il suo stato di caricamento. Usalo quando hai bisogno solo delle informazioni utente e non dei metodi di autenticazione.

Restituisce:

interface UseUserResult {
  user: UserInfo | null
  isLoading: boolean
  error: AurisError | null
}
import { useUser } from '@auris/react'
 
function Avatar() {
  const { user, isLoading } = useUser()
 
  if (isLoading) return <div className="avatar-skeleton" />
  if (!user) return null
 
  return (
    <img
      src={user.picture ?? `https://ui-avatars.com/api/?name=${user.name}`}
      alt={user.name}
    />
  )
}

useAccessToken()

Restituisce la stringa del token di accesso corrente. Aggiorna automaticamente il token se è scaduto e autoRefresh è abilitato.

Restituisce:

interface UseAccessTokenResult {
  token: string | null
  isLoading: boolean
}
import { useAccessToken } from '@auris/react'
 
function useAuthenticatedFetch() {
  const { token } = useAccessToken()
 
  return async function fetch(url: string, init?: RequestInit) {
    return window.fetch(url, {
      ...init,
      headers: {
        ...init?.headers,
        Authorization: `Bearer ${token}`,
      },
    })
  }
}

usePermissions(permissions)

Verifica se l’utente corrente ha uno o tutti i permessi specificati. Chiama l’API Auris una volta per ciclo di render quando la lista dei permessi cambia.

Firma:

usePermissions(permissions: string[]): UsePermissionsResult

Restituisce:

interface UsePermissionsResult {
  has: (permission: string) => boolean
  hasAll: boolean   // true se l'utente ha tutti i permessi nell'array
  hasAny: boolean   // true se l'utente ha almeno un permesso nell'array
  isLoading: boolean
  error: AurisError | null
}
import { usePermissions } from '@auris/react'
 
function AzioniAdmin() {
  const { has, hasAny, isLoading } = usePermissions(['manage:users', 'delete:content'])
 
  if (isLoading) return <Spinner />
 
  return (
    <div>
      {has('manage:users') && <button>Gestisci Utenti</button>}
      {has('delete:content') && <button>Elimina Contenuto</button>}
      {!hasAny && <p>Non hai il permesso di eseguire azioni amministrative.</p>}
    </div>
  )
}

useCheckPermission(permission)

Verifica un singolo permesso. Restituisce un risultato booleano. Più semplice di usePermissions() quando hai bisogno di un solo controllo.

Firma:

useCheckPermission(permission: string): UseCheckPermissionResult

Restituisce:

interface UseCheckPermissionResult {
  allowed: boolean
  isLoading: boolean
  error: AurisError | null
}
import { useCheckPermission } from '@auris/react'
 
function BottoneElimina({ documentId }: { documentId: string }) {
  const { allowed, isLoading } = useCheckPermission('delete:documents')
 
  if (isLoading || !allowed) return null
 
  return (
    <button onClick={() => eliminaDocumento(documentId)}>Elimina</button>
  )
}

useOrganization()

Restituisce il contesto dell’organizzazione corrente per le applicazioni B2B multi-tenant. L’organizzazione attiva viene risolta dai claim del token di accesso dell’utente.

Restituisce:

interface UseOrganizationResult {
  organization: Organization | null
  members: OrganizationMember[]
  isLoading: boolean
  error: AurisError | null
}
 
interface Organization {
  id: string
  name: string
  slug: string
  logoUrl?: string
  metadata: Record<string, unknown>
}
 
interface OrganizationMember {
  userId: string
  email: string
  name: string
  role: 'OWNER' | 'ADMIN' | 'MEMBER' | 'VIEWER'
  joinedAt: string
}
import { useOrganization } from '@auris/react'
 
function IntestazionOrg() {
  const { organization, isLoading } = useOrganization()
 
  if (isLoading || !organization) return null
 
  return (
    <div>
      {organization.logoUrl && <img src={organization.logoUrl} alt={organization.name} />}
      <h1>{organization.name}</h1>
    </div>
  )
}

useFga()

Accedi ai controlli di autorizzazione Fine-Grained da un componente React. Restituisce funzioni check e listObjects supportate dal modulo FGA di @auris/js.

Restituisce:

interface UseFgaResult {
  check: (input: FgaCheckInput) => Promise<FgaCheckResult>
  listObjects: (input: FgaListObjectsInput) => Promise<string[]>
  isLoading: boolean
}
import { useFga } from '@auris/react'
import { useUser } from '@auris/react'
 
function AzioniDocumento({ documentId }: { documentId: string }) {
  const { user } = useUser()
  const { check } = useFga()
  const [puoModificare, setPuoModificare] = React.useState(false)
 
  React.useEffect(() => {
    if (!user) return
    check({
      objectType: 'document',
      objectId: documentId,
      relation: 'editor',
      subjectType: 'user',
      subjectId: user.id,
    }).then((r) => setPuoModificare(r.allowed))
  }, [user, documentId])
 
  return puoModificare ? <button>Modifica</button> : null
}

Componenti

AuthGuard

Avvolge un sottoalbero e reindirizza gli utenti non autenticati alla pagina di login. Mentre lo stato di autenticazione è in caricamento, renderizza la prop fallback (o nulla).

Props:

PropTipoDefaultDescrizione
loginUrlstring'/login'URL a cui reindirizzare gli utenti non autenticati
fallbackReact.ReactNodenullRenderizzato mentre lo stato di autenticazione è in caricamento
childrenReact.ReactNode—Contenuto da renderizzare per gli utenti autenticati
import { AuthGuard } from '@auris/react'
 
// Proteggi un'intera pagina
function PaginaProtetta() {
  return (
    <AuthGuard loginUrl="/auth/login" fallback={<ScheletroPageina />}>
      <h1>Questo contenuto richiede autenticazione</h1>
      <DashboardUtente />
    </AuthGuard>
  )
}

PermissionGate

Renderizza condizionalmente i suoi figli in base al fatto che l’utente corrente abbia un permesso specificato. Renderizza la prop fallback (o nulla) quando il controllo del permesso fallisce o è in caricamento.

Props:

PropTipoDefaultDescrizione
permissionstring—Stringa del permesso da verificare (obbligatorio)
fallbackReact.ReactNodenullRenderizzato quando l’utente non ha il permesso
childrenReact.ReactNode—Renderizzato quando l’utente ha il permesso
import { PermissionGate } from '@auris/react'
 
function PaginaFatture() {
  return (
    <div>
      <h1>Fatture</h1>
      <ListaFatture />
 
      <PermissionGate
        permission="create:invoices"
        fallback={<p>Non hai il permesso di creare fatture.</p>}
      >
        <BottoneCreaFattura />
      </PermissionGate>
 
      <PermissionGate permission="export:invoices">
        <BottoneEsporta />
      </PermissionGate>
    </div>
  )
}

LoginButton

Un pulsante pre-costruito che chiama loginWithRedirect(). Accetta tutte le props HTML standard del pulsante più un override opzionale label.

import { LoginButton } from '@auris/react'
 
function Intestazione() {
  return (
    <nav>
      <LoginButton label="Accedi con Auris" className="btn btn-primary" />
    </nav>
  )
}

LogoutButton

Un pulsante pre-costruito che chiama logout() con un URL returnTo opzionale.

import { LogoutButton } from '@auris/react'
 
function MenuUtente() {
  return (
    <LogoutButton
      returnTo={window.location.origin}
      label="Esci"
      className="btn btn-secondary"
    />
  )
}

Esempio Completo

Una SPA React completa con login, contenuto protetto, controllo dei permessi e logout:

import React from 'react'
import { AurisProvider, AuthGuard, PermissionGate, useAuris, usePermissions } from '@auris/react'
 
// 1. Avvolgi la tua app alla radice
export default function App() {
  return (
    <AurisProvider
      domain={import.meta.env.VITE_AURIS_DOMAIN}
      clientId={import.meta.env.VITE_AURIS_CLIENT_ID}
      redirectUri={`${window.location.origin}/callback`}
    >
      <Router>
        <Route path="/" element={<PaginaHome />} />
        <Route path="/callback" element={<PaginaCallback />} />
        <Route path="/dashboard" element={<PaginaDashboard />} />
      </Router>
    </AurisProvider>
  )
}
 
// 2. Pagina callback — gestisce il redirect da Auris
function PaginaCallback() {
  const { handleRedirectCallback } = useAuris()
  const navigate = useNavigate()
 
  React.useEffect(() => {
    handleRedirectCallback().then(() => navigate('/dashboard'))
  }, [])
 
  return <p>Completamento accesso in corso...</p>
}
 
// 3. Dashboard protetta con sezioni a controllo permessi
function PaginaDashboard() {
  return (
    <AuthGuard loginUrl="/" fallback={<p>Verifica credenziali...</p>}>
      <ContenutoDashboard />
    </AuthGuard>
  )
}
 
function ContenutoDashboard() {
  const { user, logout } = useAuris()
  const { has, isLoading } = usePermissions(['view:reports', 'manage:users'])
 
  return (
    <div>
      <header>
        <h1>Dashboard</h1>
        <span>Connesso come {user?.email}</span>
        <button onClick={() => logout({ returnTo: window.location.origin })}>Esci</button>
      </header>
 
      <main>
        <PermissionGate permission="view:reports">
          <SezioneReport />
        </PermissionGate>
 
        <PermissionGate
          permission="manage:users"
          fallback={<p>Hai bisogno dei diritti admin per gestire gli utenti.</p>}
        >
          <GestioneUtenti />
        </PermissionGate>
      </main>
    </div>
  )
}

Correlati

Architettura