OrionID
Se connecter S’inscrire

Documentation

Orion ID est un fournisseur OpenID Connect standard : n’importe quelle bibliothèque OIDC convient.

Connexion avec Orion ID (OpenID Connect)

  1. Enregistrez votre app dans Mes applications. Elle démarre en mode développement : vous seul pouvez vous y connecter.
  2. Configurez votre bibliothèque OIDC avec le document de découverte : https://oriondatagroup.com/.well-known/openid-configuration
  3. Redirigez vers https://oriondatagroup.com/oauth/authorize avec response_type=code, client_id, redirect_uri (exacte), scope=openid profile, state, nonce et PKCE (code_challenge + code_challenge_method=S256, obligatoire pour toutes les apps).
  4. Échangez le code sur POST https://oriondatagroup.com/oauth/token avec grant_type=authorization_code, code_verifier et redirect_uri. Les apps confidentielles s’authentifient avec client_secret_basic ou client_secret_post.
  5. Validez l’id_token (RS256) : signature avec le JWKS (https://oriondatagroup.com/.well-known/jwks.json, choisissez la clé par kid), iss, aud = votre client_id, exp et nonce.
  6. Utilisez sub comme identifiant de la personne. Il est stable et ne révèle rien.
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 tokens : 15 min. Refresh tokens : 30 jours, à usage unique (chaque refresh en renvoie un nouveau ; réutiliser un ancien révoque toute la session de cette app). Révocation : POST https://oriondatagroup.com/oauth/revoke (RFC 7009). prompt=none|login|consent pris en charge.

Exemple complet et exécutable : examples/demo-client dans le dépôt.

Autorisations (scopes)

ScopeCe que ça donneNécessite une approbation
openidConfirmer que c’est vous (identifiant anonyme et stable)Non
profileVotre @utilisateur, nom affiché et photoNon
linksLes réseaux et le site de votre carteNon
emailVotre adresse e-mail vérifiéeNon
organizationsLes entreprises dont vous faites partie et votre rôle dans chacuneOui, par app

Le mot de passe n’est jamais partagé. L’adresse e-mail et les réseaux n’arrivent que si la personne l’accepte sur l’écran d’autorisation.

Ce que vous recevez

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",                         // seulement si sa carte est publique
 "orion_links": {"instagram": "https://instagram.com/lucia", "web": "https://lucia.example"},   // scope links
 "email": "lucia@example.com", "email_verified": true}   // scope email

Les mêmes données, en JSON simple, sur GET https://oriondatagroup.com/api/v1/me. Dans l’id_token, amr indique comment la personne s’est connectée (mca = approuvé sur son téléphone ou par QR, otp = code, hwk = passkey) et acr vaut orion:mfa quand il y a eu une deuxième étape. Pour l’exiger, envoyez acr_values=orion:mfa.

Écosystème : connexion unique, déconnexion partout et messages

Ce qui fait que plusieurs sites semblent n’en faire qu’un. Fonctionne avec n’importe quelle app ; ce qui est marqué « du groupe » seulement avec les sites qu’Orion ID marque ainsi.

Se connecter sans cliquer

Quand quelqu’un arrive sans session, redirigez vers /oauth/authorize avec prompt=none. Si la personne a déjà Orion ID ouvert et avait accepté votre site, elle revient aussitôt avec un code ; sinon, elle revient avec error=login_required et vous affichez votre bouton « Continuer avec Orion ID ». Les sites du groupe qui ne demandent que openid profile email links n’affichent pas d’écran d’autorisation : la personne entre directement (l’autorisation figure dans « Vos sites » et peut être retirée).

Se déconnecter

Fermez votre session et envoyez la personne vers https://oriondatagroup.com/oauth/logout avec client_id, post_logout_redirect_uri et state. Orion ID lui demande si elle veut aussi se déconnecter d’Orion ID ou de tous les sites, puis la renvoie vers post_logout_redirect_uri, qui doit être sur le même site (https et même domaine) qu’une de vos adresses de retour.

Si elle choisit « partout » (ou appuie sur « Se déconnecter de tous les sites » dans Sécurité), chaque site reçoit le webhook session.ended avec son sub : fermez toutes les sessions de cette personne sur votre site.

Messages dans Notifications

Votre site peut laisser un avis dans le compte Orion ID d’une personne qui l’utilise : une commande expédiée, une réponse, un rappel qui la concerne. Il arrive dans « Notifications » et, si elle l’a activé, sur son téléphone. Texte uniquement ; le lien doit être sur votre site.

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

{"sub": "01JB…", "title": "Commande expédiée", "text": "Votre commande 1042 part aujourd’hui.", "url": "https://tuweb.com/pedidos/1042", "id": "pedido-1042-enviado"}

201 {"data": {"delivered": true, "duplicate": false}}
  • id est facultatif : si vous répétez le même, rien n’est dupliqué (répond 200 avec "duplicate": true).
  • Uniquement aux personnes qui se sont connectées à votre site avec Orion ID et ne lui ont pas retiré l’accès (sinon 404 not_found). Chaque personne peut mettre votre site en sourdine dans « Vos sites » (403 messages_muted) : cessez de lui écrire.
  • Limites : 20 messages par jour et par personne et 600 par heure pour tout le site (429 rate_limited). Utilisez-le pour ce que la personne voudrait savoir, pas pour de la publicité : un site qui en abuse perd l’accès.

Les sites du groupe

https://oriondatagroup.com/.well-known/orion-group.json liste les sites du groupe (nom, adresse, description, logo et où se connecter). C’est public et lisible depuis le navigateur : utilisez-le pour un menu « Plus du groupe ».

Webhooks

Indiquez une adresse https sur la fiche de votre app et nous vous signalerons ces événements par une requête POST en JSON :

  • authorization.revoked: Une personne retire l’accès à votre app (ou la plateforme le retire).
  • account.deleted: Une personne qui utilisait votre app supprime son compte Orion ID.
  • account.updated: Une personne qui utilise votre app change son nom, sa photo, son adresse e-mail ou sa carte (redemandez /oauth/userinfo).
  • account.secured: Une personne appuie sur « Ce n’était pas moi » : fermez ses sessions dans votre app et demandez-lui de se reconnecter.
  • session.ended: Une personne se déconnecte partout depuis Orion ID : fermez aussi sa session sur votre site.
  • ping: test envoyé depuis le portail.

Les événements de compte n’incluent que l’identifiant sub de la personne :

{"id": "evt_01jb…", "type": "authorization.revoked", "created": 1760000000, "client_id": "oid_…", "data": {"sub": "…"}}
  • Signature. En-tête Orion-Signature: t=…,v1=… : HMAC-SHA256 de t + "." + corps avec votre clé de signature. Comparez en temps constant.
  • Rejeux. Refusez les horodatages de plus de 5 minutes. Chaque événement a un id stable (aussi dans l’en-tête Orion-Delivery) : les nouvelles tentatives et les renvois manuels le répètent, alors conservez ceux déjà traités et ignorez les doublons en répondant 200.
  • Livraison. Répondez 2xx en moins de 5 secondes (mettez le travail lourd en file d’attente). Sinon, nous réessayons après 1 min, 5 min, 30 min et 2 h. Depuis la fiche de votre app, vous pouvez renvoyer un événement des 7 derniers jours.
  • Réseau. https uniquement, ports 443 ou 8443, sans redirections ni adresses privées. Nous nous connectons à l’IP vérifiée, sans résoudre à nouveau le domaine.

Sur la fiche de votre app, Vérifier l’intégration envoie trois requêtes de test (valide, avec fausse signature et ancienne) avec "test": true et vous dit si votre serveur n’accepte que la bonne.

Exemples avec des bibliothèques courantes

Utilisez toujours une bibliothèque OpenID Connect maintenue : elle valide l’id_token, le state et le nonce pour vous. Dans les exemples, ISSUER vaut 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');

Vérifier 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

Exemple complet sans dépendances en PHP (connexion, deux étapes, renouvellement, révocation et récepteur de webhooks) : examples/demo-client dans le dépôt.

Erreurs et limites

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

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

Limites de /api/v1/me : 120 requêtes/min par app et par personne. En-têtes X-RateLimit-Limit et X-RateLimit-Remaining.

Versions et changements

  • Sans préavis nous pouvons ajouter des endpoints, des champs facultatifs dans les réponses, de nouvelles valeurs dans des listes ouvertes (par exemple des types d’événements webhook auxquels vous vous abonnez explicitement) et des en-têtes. Votre code doit ignorer ce qu’il ne connaît pas.
  • Changements incompatibles (supprimer ou renommer des champs, changer des types ou des significations, durcir des validations) n’arrivent que dans une nouvelle version : /api/v2. Jamais dans /api/v1.
  • Abandon. Une version est maintenue au moins 12 mois après l’annonce de son abandon. Pendant ce délai, les réponses portent les en-têtes Deprecation et Sunset (RFC 8594) et nous prévenons par e-mail les personnes ayant des apps actives.
  • Orion ID suit OpenID Connect : le document de découverte fait référence. Les clés de signature tournent avec chevauchement ; choisissez toujours par kid et relisez le JWKS si vous n’en trouvez pas.
  • Sécurité. Un changement nécessaire pour corriger une faille de sécurité peut être appliqué sans délai ; nous l’expliquerons sur la page d’état.

État du service et avis : https://oriondatagroup.com/status.

Bonnes pratiques obligatoires

  • Validez toujours state et nonce. Utilisez PKCE avec S256.
  • Gardez le client secret uniquement sur votre serveur. Les apps mobiles ou SPA doivent être enregistrées comme publiques (sans secret).
  • Les URL de retour sont comparées de façon exacte. HTTPS uniquement (ou http://localhost en développement).
  • Ne stockez pas les access tokens dans localStorage ; préférez les cookies de session de votre backend.
  • Quand une personne révoque l’accès, vos tokens cessent de fonctionner immédiatement : traitez un 401 comme « session terminée ».