← API per sviluppatori Per sviluppatori

Accedi con Astrina

Astrina è il broker di accesso unico per l'ecosistema. Configura i tuoi fornitori di accesso sociale una sola volta in Astrina; ogni sito li riutilizza — nessuna app OAuth per sito, nessun SDK del fornitore.

Come funziona il flusso

Quattro salti, e il tuo sito non tocca mai un fornitore

Il sito invia il visitatore ad Astrina

Un link con il tuo client_id, l'indirizzo di ritorno e un valore di stato.

Il visitatore sceglie un account

Qualsiasi fornitore abilitato in Astrina — nessuna app OAuth da parte tua.

Astrina restituisce un codice monouso

Il codice torna al tuo callback e scade in cinque minuti.

Il tuo server lo scambia per un profilo

Un POST server-to-server restituisce sub, email, nome e avatar.

Mostra il diagramma della richiesta
  Site  ──(1) redirect──▶  astrina.io/auth/authorize.php  ──▶  provider (Google…)
   ▲                                    │                              │
   └──(3) ?code=…&state=… ◀──── astrina.io/auth/cb.php ◀──(2) callback ─┘
   │
   └──(4) POST code ──▶ astrina.io/auth/token.php ──▶ { sub, email, name, avatar }

Configurazione dell'owner una tantum (nell'amministrazione di Astrina)

  1. Abilita i fornitori nel pannello di controllo (accesso proprietario).
  2. Per ogni fornitore, crea un'app OAuth nella console di quel fornitore e registra esattamente questo URI di reindirizzamento:
    Googlehttps://astrina.io/auth/cb.php?provider=google
    Yandexhttps://astrina.io/auth/cb.php?provider=yandex
    Applehttps://astrina.io/auth/cb.php?provider=apple
    Telegram@BotFather → /setdomain → astrina.io
  3. Incolla il Client ID + Secret di ciascuna app (Telegram: nome utente bot + token bot), seleziona Abilitato, Salva.
  4. Sotto Client sites, registra ciascun sito (nome + URL di reindirizzamento consentiti). Copia il client_id + client_secret mostrato una sola volta.

Integrazione per sito (3 passaggi)

  1. Copia sdk.php nel sito e imposta quattro costanti:
    define('ASTRINA_CLIENT_ID',     'astr_xxxxxxxx');
    define('ASTRINA_CLIENT_SECRET', '…');   // server-side only, never in JS
    define('ASTRINA_REDIRECT_URI',  'https://mysite/auth/astrina-callback.php');
    require '/path/to/sdk.php';
  2. Aggiungi i pulsanti ovunque — un pulsante "Accedi con Astrina" (mostra il selettore), o una fila di pulsanti diretti del fornitore (un clic su Google salta direttamente in Google, senza pagina di selezione):
    <!-- one button → Astrina chooser -->
    <a class="btn" href="<?= htmlspecialchars(AstrinaID::loginUrl()) ?>">Log in with Astrina</a>
    
    <!-- OR: direct per-provider buttons + the "Secured by Astrina ID" note -->
    <?= AstrinaID::buttonsHtml() ?>
    
    <!-- OR: hand-rolled, straight to one provider -->
    <a href="<?= htmlspecialchars(AstrinaID::loginUrl('google')) ?>">Continue with Google</a>

    buttonsHtml() recupera i fornitori che hai abilitato in Astrina e rende esattamente quelli, ciascuno collegato in profondità al fornitore.

  3. Crea la pagina di callback (astrina-callback.php) all'URL di reindirizzamento:
    require 'config.php';           // defines the constants + sdk.php
    $u = AstrinaID::handleCallback();
    if (!$u) { header('Location: /login?e=1'); exit; }
    // key your local user on ($u['provider'], $u['sub']) — NOT email
    $local = find_or_create_user($u['provider'], $u['sub'], $u['email'], $u['name'], $u['avatar']);
    login($local); header('Location: /'); exit;

Questo è tutto — nessuna app OAuth per sito, nessun SDK del fornitore. Aggiungere un nuovo fornitore in seguito è una modifica di una riga in Astrina; ogni sito lo ottiene automaticamente.

Note

sub è un id stabile e opaco per identità. Tratta l'email come informativa (Telegram non ne fornisce; gli utenti possono cambiarla).

La risposta del token porta anche un id_token (JWT HS256 firmato con il tuo client secret) se preferisci verificare localmente invece di fidarti del JSON.

I codici sono monouso e scadono in 5 minuti; state è controllato sia dall'SDK che da Astrina.

Riferimento in testo semplice: README.md · scarica sdk.php