OrionID
Accedi Crea un account

Documentazione

Orion ID è un provider OpenID Connect standard: va bene qualsiasi libreria OIDC.

Accesso con Orion ID (OpenID Connect)

  1. Registra la tua app in Le mie applicazioni. Parte in modalità sviluppo: solo tu puoi accedere con essa.
  2. Configura la tua libreria OIDC con il documento di discovery: https://oriondatagroup.com/.well-known/openid-configuration
  3. Reindirizza a https://oriondatagroup.com/oauth/authorize con response_type=code, client_id, redirect_uri (esatto), scope=openid profile, state, nonce e PKCE (code_challenge + code_challenge_method=S256, obbligatorio per tutte le app).
  4. Scambia il code su POST https://oriondatagroup.com/oauth/token con grant_type=authorization_code, code_verifier e redirect_uri. Le app confidenziali si autenticano con client_secret_basic o client_secret_post.
  5. Convalida l’id_token (RS256): firma con il JWKS (https://oriondatagroup.com/.well-known/jwks.json, scegli la chiave per kid), iss, aud = il tuo client_id, exp e nonce.
  6. Usa sub come identificatore della persona. È stabile e non rivela nulla.
GET https://oriondatagroup.com/oauth/authorize?response_type=code&client_id=oid_…&redirect_uri=https%3A%2F%2Ftuweb.com%2Fcallback
    &scope=openid%20profile&state=…&nonce=…&code_challenge=…&code_challenge_method=S256

POST https://oriondatagroup.com/oauth/token
Content-Type: application/x-www-form-urlencoded
grant_type=authorization_code&code=…&redirect_uri=…&client_id=oid_…&code_verifier=…

200 {"token_type":"Bearer","expires_in":900,"access_token":"eyJ…","refresh_token":"def…","id_token":"eyJ…"}

Access token: 15 min. Refresh token: 30 giorni, monouso (ogni refresh ne restituisce uno nuovo; riutilizzarne uno vecchio revoca l’intera sessione di quell’app). Revoca: POST https://oriondatagroup.com/oauth/revoke (RFC 7009). prompt=none|login|consent supportati.

Esempio completo ed eseguibile: examples/demo-client nel repository.

Permessi (scope)

ScopeCosa concedeRichiede approvazione
openidConfermare che sei tu (identificatore anonimo e stabile)No
profileIl tuo @utente, nome visualizzato e fotoNo
linksI social e il sito della tua cardNo
emailIl tuo indirizzo e-mail verificatoNo
organizationsLe aziende di cui fai parte e il tuo ruolo in ognunaSì, per app

La password non viene mai condivisa. L’e-mail e i social arrivano solo se la persona lo accetta nella schermata di autorizzazione.

Cosa ricevi

GET https://oriondatagroup.com/oauth/userinfo        Authorization: Bearer eyJ…

{"sub": "01JB…", "preferred_username": "lucia", "name": "Lucía", "picture": "https://oriondatagroup.com/avatars/lucia?v=…",
 "profile": "https://oriondatagroup.com/@lucia",                         // solo se la sua card è pubblica
 "orion_links": {"instagram": "https://instagram.com/lucia", "web": "https://lucia.example"},   // scope links
 "email": "lucia@example.com", "email_verified": true}   // scope email

Gli stessi dati, come JSON semplice, su GET https://oriondatagroup.com/api/v1/me. Nell’id_token, amr indica come è entrata la persona (mca = approvato sul telefono o con QR, otp = codice, hwk = passkey) e acr vale orion:mfa quando c’è stato un secondo passaggio. Per richiederlo, invia acr_values=orion:mfa.

Ecosistema: accesso unico, uscita ovunque e messaggi

Ciò che fa sembrare più siti un unico sito. Funziona con qualsiasi app; ciò che è indicato come «del gruppo» solo con i siti che Orion ID contrassegna così.

Accedere senza premere nulla

Quando arriva qualcuno senza sessione, reindirizza a /oauth/authorize con prompt=none. Se ha già Orion ID aperto e aveva accettato il tuo sito, torna subito con un code; altrimenti torna con error=login_required e mostri il tuo pulsante «Continua con Orion ID». I siti del gruppo che chiedono solo openid profile email links non mostrano la schermata di autorizzazione: la persona entra direttamente (l’autorizzazione resta in «I tuoi siti» e si può togliere).

Esci

Chiudi la tua sessione e porta la persona a https://oriondatagroup.com/oauth/logout con client_id, post_logout_redirect_uri e state. Orion ID le chiede se vuole uscire anche da Orion ID o da tutti i siti, e la riporta a post_logout_redirect_uri, che deve essere sullo stesso sito (https e stesso dominio) di uno dei tuoi indirizzi di ritorno.

Se sceglie «tutti» (o preme «Esci da tutti i siti» in Sicurezza), ogni sito riceve il webhook session.ended con il suo sub: chiudi tutte le sessioni di quella persona nel tuo sito.

Messaggi in Notifiche

Il tuo sito può lasciare un avviso nell’account Orion ID di una persona che lo usa: un ordine spedito, una risposta, un suo promemoria. Arriva in «Notifiche» e, se l’ha attivato, sul telefono. Solo testo; il link deve essere del tuo sito.

POST https://oriondatagroup.com/api/v1/messages
Authorization: Basic base64(client_id:client_secret)
Content-Type: application/json

{"sub": "01JB…", "title": "Ordine spedito", "text": "Il tuo ordine 1042 parte oggi.", "url": "https://tuweb.com/pedidos/1042", "id": "pedido-1042-enviado"}

201 {"data": {"delivered": true, "duplicate": false}}
  • id è facoltativo: se ripeti lo stesso, non viene duplicato (risponde 200 con "duplicate": true).
  • Solo a persone che sono entrate nel tuo sito con Orion ID e non gli hanno tolto l’accesso (altrimenti 404 not_found). Ogni persona può silenziare il tuo sito in «I tuoi siti» (403 messages_muted): smetti di scriverle.
  • Limiti: 20 messaggi al giorno per persona e 600 all’ora per tutto il sito (429 rate_limited). Usalo per ciò che la persona vorrebbe sapere, non per la pubblicità: un sito che ne abusa perde l’accesso.

I siti del gruppo

https://oriondatagroup.com/.well-known/orion-group.json elenca i siti del gruppo (nome, indirizzo, descrizione, logo e dove si accede). È pubblica e si può leggere dal browser: usala per un menu «Altro dal gruppo».

Webhooks

Imposta un indirizzo https nella scheda della tua app e ti avviseremo di questi eventi con una richiesta POST in JSON:

  • authorization.revoked: Una persona revoca l’accesso alla tua app (o lo revoca la piattaforma).
  • account.deleted: Una persona che usava la tua app elimina il suo account Orion ID.
  • account.updated: Una persona che usa la tua app cambia nome, foto, e-mail o card (richiedi di nuovo /oauth/userinfo).
  • account.secured: Una persona preme «Non sono stato io»: chiudi le sue sessioni nella tua app e chiedile di accedere di nuovo.
  • session.ended: Una persona esce ovunque da Orion ID: chiudi anche la sua sessione nel tuo sito.
  • ping: prova inviata dal portale.

Gli eventi dell’account includono solo l’identificatore sub della persona:

{"id": "evt_01jb…", "type": "authorization.revoked", "created": 1760000000, "client_id": "oid_…", "data": {"sub": "…"}}
  • Firma. Intestazione Orion-Signature: t=…,v1=…: HMAC-SHA256 di t + "." + corpo con la tua chiave di firma. Confronta in tempo costante.
  • Ripetizioni. Rifiuta i timestamp più vecchi di 5 minuti. Ogni evento ha un id stabile (anche nell’intestazione Orion-Delivery): i nuovi tentativi e i reinvii manuali lo ripetono, quindi salva quelli già elaborati e ignora i duplicati rispondendo 200.
  • Consegna. Rispondi 2xx in meno di 5 secondi (metti in coda il lavoro pesante). Altrimenti riproviamo dopo 1 min, 5 min, 30 min e 2 h. Dalla scheda della tua app puoi reinviare un evento degli ultimi 7 giorni.
  • Rete. Solo https, porte 443 o 8443, senza reindirizzamenti né indirizzi privati. Ci colleghiamo all’IP che abbiamo verificato, senza risolvere di nuovo il dominio.

Nella scheda della tua app, Controlla l’integrazione invia tre richieste di prova (valida, con firma falsa e vecchia) con "test": true e ti dice se il tuo server accetta solo quella buona.

Esempi con librerie comuni

Usa sempre una libreria OpenID Connect mantenuta: convalida l’id_token, lo state e il nonce per te. Negli esempi, ISSUER è https://oriondatagroup.com.

Node.js · openid-client

import { Issuer, generators } from 'openid-client';

const orion = await Issuer.discover(ISSUER);
const client = new orion.Client({ client_id: 'oid_…', client_secret: 'kius_…', redirect_uris: ['https://tuweb.com/callback'], response_types: ['code'] });

// /login
const code_verifier = generators.codeVerifier();
const state = generators.state(), nonce = generators.nonce();
req.session.oidc = { code_verifier, state, nonce };
res.redirect(client.authorizationUrl({ scope: 'openid profile', state, nonce,
  code_challenge: generators.codeChallenge(code_verifier), code_challenge_method: 'S256' }));

// /callback
const tokens = await client.callback('https://tuweb.com/callback', client.callbackParams(req), req.session.oidc);
const { sub, acr, amr } = tokens.claims();   // sub: identificador estable de la persona

Python · Authlib (Flask)

from authlib.integrations.flask_client import OAuth

oauth = OAuth(app)
oauth.register('orion', server_metadata_url=ISSUER + '/.well-known/openid-configuration',
               client_id='oid_…', client_secret='kius_…',
               client_kwargs={'scope': 'openid profile', 'code_challenge_method': 'S256'})

@app.route('/login')
def login():
    return oauth.orion.authorize_redirect(url_for('callback', _external=True))

@app.route('/callback')
def callback():
    token = oauth.orion.authorize_access_token()   # valida state, nonce y firma
    person = token['userinfo']                     # person['sub'], person['acr']

PHP · jumbojett/openid-connect-php

$oidc = new Jumbojett\OpenIDConnectClient(ISSUER, 'oid_…', 'kius_…');
$oidc->setRedirectURL('https://tuweb.com/callback');
$oidc->setCodeChallengeMethod('S256');
$oidc->addScope(['profile']);
$oidc->authenticate();                      // redirige y, a la vuelta, valida el id_token
$sub = $oidc->getVerifiedClaims('sub');

Verificare un webhook

// Node.js (Express): usa el cuerpo sin procesar
app.post('/orion/webhook', express.raw({ type: 'application/json' }), (req, res) => {
  const sig = Object.fromEntries((req.get('Orion-Signature') || '').split(',').map(p => p.split('=')));
  const expected = crypto.createHmac('sha256', SECRET).update(`${sig.t}.${req.body}`).digest('hex');
  const valid = sig.v1?.length === expected.length && crypto.timingSafeEqual(Buffer.from(sig.v1), Buffer.from(expected));
  if (!valid || Math.abs(Date.now() / 1000 - Number(sig.t)) > 300) return res.sendStatus(400);
  const event = JSON.parse(req.body);
  if (alreadyProcessed(event.id)) return res.sendStatus(200);
  queue.add(event); res.sendStatus(200);
});

# Python
def valid(header: str, body: bytes, secret: str) -> bool:
    p = dict(part.split('=', 1) for part in header.split(','))
    expected = hmac.new(secret.encode(), p['t'].encode() + b'.' + body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, p.get('v1', '')) and abs(time.time() - int(p['t'])) <= 300

Esempio completo senza dipendenze in PHP (accesso, due passaggi, rinnovo, revoca e ricevitore di webhook): examples/demo-client nel repository.

Errori e limiti

{"error": {"code": "insufficient_scope", "message": "El token no tiene los permisos necesarios.", "details": {"required": ["openid"]}}}

Codici: validation_failed (422), invalid_token / unauthenticated (401), insufficient_scope / forbidden (403), not_found (404), rate_limited (429, con Retry-After), server_error (500).

Limiti di /api/v1/me: 120 richieste/min per app e persona. Intestazioni X-RateLimit-Limit e X-RateLimit-Remaining.

Versioni e modifiche

  • Senza preavviso possiamo aggiungere endpoint, campi facoltativi nelle risposte, nuovi valori in liste aperte (per esempio tipi di evento webhook a cui ti iscrivi esplicitamente) e intestazioni. Il tuo codice deve ignorare ciò che non conosce.
  • Modifiche incompatibili (rimuovere o rinominare campi, cambiare tipi o significati, rendere più severe le validazioni) arrivano solo in una nuova versione: /api/v2. Mai dentro /api/v1.
  • Dismissione. Una versione viene mantenuta almeno 12 mesi dall’annuncio della sua dismissione. Durante quel periodo le risposte portano le intestazioni Deprecation e Sunset (RFC 8594) e avvisiamo via e-mail chi ha app attive.
  • Orion ID segue OpenID Connect: il documento di discovery è il riferimento. Le chiavi di firma ruotano con sovrapposizione; scegli sempre per kid e rileggi il JWKS se non ne trovi una.
  • Sicurezza. Una modifica necessaria per correggere una falla di sicurezza può essere applicata senza preavviso; la spiegheremo nella pagina di stato.

Stato del servizio e avvisi: https://oriondatagroup.com/status.

Buone pratiche obbligatorie

  • Convalida sempre state e nonce. Usa PKCE con S256.
  • Conserva il client secret solo sul tuo server. Le app mobili o SPA devono essere registrate come pubbliche (senza segreto).
  • Gli URL di ritorno vengono confrontati in modo esatto. Solo HTTPS (o http://localhost in sviluppo).
  • Non salvare gli access token in localStorage; preferisci i cookie di sessione del tuo backend.
  • Quando una persona revoca l’accesso, i tuoi token smettono subito di funzionare: tratta un 401 come «sessione terminata».