Dokumentation
Orion ID ist ein standardmäßiger OpenID-Connect-Anbieter: Jede OIDC-Bibliothek funktioniert.
Anmelden mit Orion ID (OpenID Connect)
- Registriere deine App unter Meine Apps. Sie startet im Entwicklungsmodus: Nur du kannst dich damit anmelden.
- Richte deine OIDC-Bibliothek mit dem Discovery-Dokument ein:
https://oriondatagroup.com/.well-known/openid-configuration - Leite zu
https://oriondatagroup.com/oauth/authorizeweiter mitresponse_type=code,client_id,redirect_uri(exakt),scope=openid profile,state,nonceund PKCE (code_challenge+code_challenge_method=S256, Pflicht für alle Apps). - Tausche den
codebeiPOST https://oriondatagroup.com/oauth/tokenmitgrant_type=authorization_code,code_verifierundredirect_uriein. Vertrauliche Apps authentifizieren sich mitclient_secret_basicoderclient_secret_post. - Validiere das
id_token(RS256): Signatur mit dem JWKS (https://oriondatagroup.com/.well-known/jwks.json, wähle den Schlüssel nachkid),iss,aud= deine client_id,expundnonce. - Verwende
subals Kennung der Person. Sie ist dauerhaft und verrät nichts.
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 Tage, einmalig verwendbar (jeder Refresh liefert einen neuen; wird ein alter wiederverwendet, wird die ganze Sitzung dieser App widerrufen). Widerruf: POST https://oriondatagroup.com/oauth/revoke (RFC 7009). prompt=none|login|consent werden unterstützt.
Vollständiges, lauffähiges Beispiel: examples/demo-client im Repository.
Berechtigungen (Scopes)
| Scope | Was sie erlaubt | Erfordert Genehmigung |
|---|---|---|
openid | Bestätigen, dass du es bist (anonyme, dauerhafte Kennung) | Nein |
profile | Dein @benutzer, Anzeigename und Foto | Nein |
links | Die Netzwerke und die Website deiner Karte | Nein |
email | Deine bestätigte E-Mail-Adresse | Nein |
organizations | Die Unternehmen, denen du angehörst, und deine Rolle in jedem | Ja, pro App |
Das Passwort wird nie geteilt. Die E-Mail-Adresse und die Netzwerke kommen nur an, wenn die Person es auf dem Berechtigungsbildschirm akzeptiert.
Was du erhältst
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", // nur wenn ihre Karte öffentlich ist
"orion_links": {"instagram": "https://instagram.com/lucia", "web": "https://lucia.example"}, // scope links
"email": "lucia@example.com", "email_verified": true} // scope email
Dieselben Daten als einfaches JSON unter GET https://oriondatagroup.com/api/v1/me. Im id_token gibt amr an, wie sich die Person angemeldet hat (mca = auf dem Handy oder per QR bestätigt, otp = Code, hwk = Passkey), und acr ist orion:mfa, wenn es einen zweiten Schritt gab. Um ihn zu verlangen, sende acr_values=orion:mfa.
Ökosystem: einmal anmelden, überall abmelden und Nachrichten
Was mehrere Websites wie eine wirken lässt. Funktioniert mit jeder App; was als „der Gruppe“ markiert ist, nur mit den Websites, die Orion ID so kennzeichnet.
Anmelden ohne Klick
Wenn jemand ohne Sitzung ankommt, leite zu /oauth/authorize mit prompt=none weiter. Wenn die Person Orion ID schon geöffnet und deine Website akzeptiert hatte, kommt sie sofort mit einem code zurück; sonst kommt sie mit error=login_required zurück, und du zeigst deinen Button „Weiter mit Orion ID“. Websites der Gruppe, die nur openid profile email links anfordern, zeigen keinen Berechtigungsbildschirm: Die Person kommt direkt hinein (die Berechtigung steht unter „Deine Websites“ und kann entfernt werden).
Abmelden
Beende deine Sitzung und schicke die Person zu https://oriondatagroup.com/oauth/logout mit client_id, post_logout_redirect_uri und state. Orion ID fragt, ob sie sich auch bei Orion ID oder bei allen Websites abmelden will, und schickt sie zurück zu post_logout_redirect_uri, das auf derselben Website liegen muss (https und gleiche Domain) wie eine deiner Weiterleitungsadressen.
Wählt sie „überall“ (oder tippt unter Sicherheit auf „Von allen Websites abmelden“), erhält jede Website den Webhook session.ended mit ihrer sub: Beende alle Sitzungen dieser Person auf deiner Website.
Nachrichten unter Benachrichtigungen
Deine Website kann im Orion-ID-Konto einer Person, die sie nutzt, eine Benachrichtigung hinterlassen: eine versandte Bestellung, eine Antwort, eine eigene Erinnerung. Sie erscheint unter „Benachrichtigungen“ und, wenn eingeschaltet, auf dem Handy. Nur Text; der Link muss zu deiner Website gehören.
POST https://oriondatagroup.com/api/v1/messages
Authorization: Basic base64(client_id:client_secret)
Content-Type: application/json
{"sub": "01JB…", "title": "Bestellung versandt", "text": "Deine Bestellung 1042 geht heute raus.", "url": "https://tuweb.com/pedidos/1042", "id": "pedido-1042-enviado"}
201 {"data": {"delivered": true, "duplicate": false}}
idist optional: Wenn du dieselbe wiederholst, wird nichts doppelt angelegt (antwortet 200 mit"duplicate": true).- Nur an Personen, die sich mit Orion ID bei deiner Website angemeldet und den Zugang nicht entzogen haben (sonst
404 not_found). Jede Person kann deine Website unter „Deine Websites“ stummschalten (403 messages_muted): Schick ihr dann nichts mehr. - Limits: 20 Nachrichten pro Tag und Person und 600 pro Stunde für die ganze Website (
429 rate_limited). Nutze es für das, was die Person wissen möchte, nicht für Werbung: Eine Website, die es missbraucht, verliert den Zugang.
Die Websites der Gruppe
https://oriondatagroup.com/.well-known/orion-group.json listet die Websites der Gruppe auf (Name, Adresse, Beschreibung, Logo und Anmeldeadresse). Sie ist öffentlich und im Browser lesbar: Verwende sie für ein Menü „Mehr aus der Gruppe“.
Webhooks
Hinterlege eine https-Adresse auf der Seite deiner App, und wir melden dir diese Ereignisse mit einer POST-Anfrage in JSON:
authorization.revoked: Eine Person widerruft den Zugang deiner App (oder die Plattform widerruft ihn).account.deleted: Eine Person, die deine App genutzt hat, löscht ihr Orion-ID-Konto.account.updated: Eine Person, die deine App nutzt, ändert Namen, Foto, E-Mail-Adresse oder Karte (frage /oauth/userinfo erneut ab).account.secured: Eine Person tippt auf „Das war ich nicht“: Beende ihre Sitzungen in deiner App und bitte sie, sich erneut anzumelden.session.ended: Eine Person meldet sich über Orion ID überall ab: Beende auch ihre Sitzung auf deiner Website.ping: Test aus dem Portal gesendet.
Konto-Ereignisse enthalten nur die sub-Kennung der Person:
{"id": "evt_01jb…", "type": "authorization.revoked", "created": 1760000000, "client_id": "oid_…", "data": {"sub": "…"}}
- Signatur. Header
Orion-Signature: t=…,v1=…: HMAC-SHA256 vont + "." + Bodymit deinem Signaturschlüssel. Vergleiche in konstanter Zeit. - Wiederholungen. Lehne Zeitstempel ab, die älter als 5 Minuten sind. Jedes Ereignis hat eine stabile
id(auch im HeaderOrion-Delivery): Wiederholungen und manuelle Neuzustellungen wiederholen sie, also speichere die verarbeiteten und ignoriere Duplikate, indem du 200 antwortest. - Zustellung. Antworte in weniger als 5 Sekunden mit 2xx (stelle schwere Arbeit in eine Warteschlange). Sonst versuchen wir es nach 1 Min., 5 Min., 30 Min. und 2 Std. erneut. Auf der Seite deiner App kannst du ein Ereignis der letzten 7 Tage erneut zustellen.
- Netz. Nur https, Ports 443 oder 8443, ohne Weiterleitungen und ohne private Adressen. Wir verbinden uns mit der geprüften IP, ohne die Domain erneut aufzulösen.
Auf der Seite deiner App sendet Integration prüfen drei Testanfragen (gültig, mit gefälschter Signatur und veraltet) mit "test": true und sagt dir, ob dein Server nur die richtige akzeptiert.
Beispiele mit gängigen Bibliotheken
Verwende immer eine gepflegte OpenID-Connect-Bibliothek: Sie validiert id_token, state und nonce für dich. In den Beispielen ist ISSUER gleich 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');
Einen Webhook prüfen
// 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
Vollständiges PHP-Beispiel ohne Abhängigkeiten (Anmeldung, zwei Schritte, Erneuerung, Widerruf und Webhook-Empfänger): examples/demo-client im Repository.
Fehler und Limits
{"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, mit Retry-After), server_error (500).
Limits für /api/v1/me: 120 Anfragen/Min. pro App und Person. Header X-RateLimit-Limit und X-RateLimit-Remaining.
Versionen und Änderungen
- Ohne Hinweis können wir Endpunkte, optionale Felder in Antworten, neue Werte in offenen Listen (zum Beispiel Webhook-Ereignistypen, die du ausdrücklich abonnierst) und Header hinzufügen. Dein Code muss ignorieren, was er nicht kennt.
- Inkompatible Änderungen (Felder entfernen oder umbenennen, Typen oder Bedeutungen ändern, Validierungen verschärfen) kommen nur in einer neuen Version:
/api/v2. Nie innerhalb von/api/v1. - Abkündigung. Eine Version wird mindestens 12 Monate nach der Ankündigung ihrer Abkündigung unterstützt. In dieser Zeit tragen die Antworten die Header
DeprecationundSunset(RFC 8594), und wir benachrichtigen alle mit aktiven Apps per E-Mail. - Orion ID folgt OpenID Connect: Das Discovery-Dokument ist maßgeblich. Die Signaturschlüssel rotieren mit Überlappung; wähle immer nach
kidund lies das JWKS erneut, wenn du keinen findest. - Sicherheit. Eine Änderung, die nötig ist, um eine Sicherheitslücke zu schließen, kann ohne Frist kommen; wir erklären sie auf der Statusseite.
Dienststatus und Hinweise: https://oriondatagroup.com/status.
Verbindliche Best Practices
- Validiere immer
stateundnonce. Verwende PKCE mit S256. - Bewahre das Client Secret nur auf deinem Server auf. Mobile Apps oder SPAs müssen als öffentlich (ohne Secret) registriert werden.
- Weiterleitungs-URLs werden exakt verglichen. Nur HTTPS (oder http://localhost in der Entwicklung).
- Speichere Access Tokens nicht in localStorage; nutze lieber Sitzungscookies deines Backends.
- Wenn jemand den Zugang widerruft, funktionieren deine Tokens sofort nicht mehr: Behandle eine 401 als „Sitzung beendet“.