Documentación
Orion ID es un proveedor OpenID Connect estándar: cualquier biblioteca OIDC sirve.
Inicio de sesión con Orion ID (OpenID Connect)
- Registra tu app en Mis aplicaciones. Empieza en modo desarrollo: solo tú puedes iniciar sesión con ella.
- Configura tu biblioteca OIDC con el documento de descubrimiento:
https://oriondatagroup.com/.well-known/openid-configuration - Redirige a
https://oriondatagroup.com/oauth/authorizeconresponse_type=code,client_id,redirect_uri(exacta),scope=openid profile,state,noncey PKCE (code_challenge+code_challenge_method=S256, obligatorio para todas las apps). - Canjea el
codeenPOST https://oriondatagroup.com/oauth/tokencongrant_type=authorization_code,code_verifieryredirect_uri. Las apps confidenciales se autentican conclient_secret_basicoclient_secret_post. - Valida el
id_token(RS256): firma con el JWKS (https://oriondatagroup.com/.well-known/jwks.json, elige la clave porkid),iss,aud= tu client_id,expynonce. - Usa
subcomo identificador de la persona. Es estable y no revela nada.
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 días, de un solo uso (cada refresh devuelve uno nuevo; reutilizar uno antiguo revoca toda la sesión de esa app). Revocación: POST https://oriondatagroup.com/oauth/revoke (RFC 7009). prompt=none|login|consent soportados.
Ejemplo completo y ejecutable: examples/demo-client en el repositorio.
Permisos (scopes)
| Scope | Qué da | Requiere aprobación |
|---|---|---|
openid | Confirmar que eres tú (identificador anónimo y estable) | No |
profile | Tu @usuario, nombre visible y foto | No |
links | Las redes y la web de tu tarjeta | No |
email | Tu dirección de correo electrónico verificada | No |
organizations | Las empresas de las que formas parte y tu papel en cada una | Sí, por app |
Nunca se comparte la contraseña. El correo y las redes solo llegan si la persona lo acepta en la pantalla de permiso.
Qué recibes
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 si su tarjeta es pública
"orion_links": {"instagram": "https://instagram.com/lucia", "web": "https://lucia.example"}, // scope links
"email": "lucia@example.com", "email_verified": true} // scope email
Los mismos datos, como JSON sencillo, en GET https://oriondatagroup.com/api/v1/me. En el id_token, amr dice cómo entró la persona (mca = aprobado en su móvil o con QR, otp = código, hwk = passkey) y acr vale orion:mfa cuando hubo segundo paso. Para exigirlo, envía acr_values=orion:mfa.
Ecosistema: entrada única, salida en todas y mensajes
Lo que hace que varias webs se sientan una sola. Funciona con cualquier app; lo marcado como «del grupo» solo con las webs que Orion ID marca así.
Entrar sin pulsar nada
Al llegar alguien sin sesión, redirige a /oauth/authorize con prompt=none. Si ya tiene Orion ID abierto y había aceptado tu web, vuelve al instante con un code; si no, vuelve con error=login_required y muestras tu botón «Continuar con Orion ID». Las webs del grupo que piden solo openid profile email links no muestran pantalla de permiso: la persona entra directamente (el permiso queda en «Tus webs» y puede quitarlo).
Cerrar sesión
Cierra tu sesión y lleva a la persona a https://oriondatagroup.com/oauth/logout con client_id, post_logout_redirect_uri y state. Orion ID le pregunta si cierra también Orion ID o todas las webs, y la devuelve a post_logout_redirect_uri, que tiene que estar en la misma web (https y mismo dominio) que una de tus direcciones de retorno.
Si elige «todas» (o pulsa «Salir de todas las webs» en Seguridad), cada web recibe el webhook session.ended con su sub: cierra todas las sesiones de esa persona en tu web.
Mensajes en Avisos
Tu web puede dejar un aviso en la cuenta de Orion ID de una persona que la usa: un pedido enviado, una respuesta, un recordatorio suyo. Le llega a «Avisos» y, si lo tiene activado, al móvil. Solo texto; el enlace debe ser de tu web.
POST https://oriondatagroup.com/api/v1/messages
Authorization: Basic base64(client_id:client_secret)
Content-Type: application/json
{"sub": "01JB…", "title": "Pedido enviado", "text": "Tu pedido 1042 sale hoy.", "url": "https://tuweb.com/pedidos/1042", "id": "pedido-1042-enviado"}
201 {"data": {"delivered": true, "duplicate": false}}
ides opcional: si repites el mismo, no se duplica (responde 200 con"duplicate": true).- Solo a personas que han entrado en tu web con Orion ID y no le han quitado el acceso (si no,
404 not_found). Cada persona puede silenciar tu web en «Tus webs» (403 messages_muted): deja de enviarle. - Límites: 20 mensajes al día por persona y 600 por hora para toda la web (
429 rate_limited). Úsalo para lo que la persona querría saber, no para publicidad: una web que abusa pierde el acceso.
Las webs del grupo
https://oriondatagroup.com/.well-known/orion-group.json lista las webs del grupo (nombre, dirección, descripción, logo y dónde se entra). Es pública y se puede leer desde el navegador: úsala para un menú «Más del grupo».
Webhooks
Configura una dirección https en la ficha de tu app y te avisaremos de estos eventos con una petición POST en JSON:
authorization.revoked: Una persona retira el acceso de tu app (o lo retira la plataforma).account.deleted: Una persona que usaba tu app elimina su cuenta de Orion ID.account.updated: Una persona que usa tu app cambia su nombre, su foto, su correo o su tarjeta (vuelve a pedir /oauth/userinfo).account.secured: Una persona pulsa «No fui yo»: cierra sus sesiones en tu app y pídele que vuelva a entrar.session.ended: Una persona cierra sesión en todas partes desde Orion ID: cierra también su sesión en tu web.ping: prueba enviada desde el portal.
Los eventos de cuenta solo incluyen el identificador sub de la persona:
{"id": "evt_01jb…", "type": "authorization.revoked", "created": 1760000000, "client_id": "oid_…", "data": {"sub": "…"}}
- Firma. Cabecera
Orion-Signature: t=…,v1=…: HMAC-SHA256 det + "." + cuerpocon tu clave de firma. Compara en tiempo constante. - Repeticiones. Rechaza marcas de tiempo de más de 5 minutos. Cada evento tiene un
idestable (también en la cabeceraOrion-Delivery): los reintentos y los reenvíos manuales lo repiten, así que guarda los procesados e ignora los duplicados respondiendo 200. - Entrega. Responde 2xx en menos de 5 segundos (encola el trabajo pesado). Si no, reintentamos a 1 min, 5 min, 30 min y 2 h. Desde la ficha de tu app puedes reenviar un evento de los últimos 7 días.
- Red. Solo https, puertos 443 u 8443, sin redirecciones ni direcciones privadas. Conectamos a la IP que comprobamos, sin volver a resolver el dominio.
En la ficha de tu app, Comprobar integración envía tres peticiones de prueba (válida, con firma falsa y antigua) con "test": true y te dice si tu servidor acepta solo la buena.
Ejemplos con bibliotecas habituales
Usa siempre una biblioteca OpenID Connect mantenida: valida el id_token, el state y el nonce por ti. En los ejemplos, ISSUER es 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');
Verificar 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
Ejemplo completo sin dependencias en PHP (inicio de sesión, dos pasos, renovación, revocación y receptor de webhooks): examples/demo-client en el repositorio.
Errores y límites
{"error": {"code": "insufficient_scope", "message": "El token no tiene los permisos necesarios.", "details": {"required": ["openid"]}}}
Códigos: validation_failed (422), invalid_token / unauthenticated (401), insufficient_scope / forbidden (403), not_found (404), rate_limited (429, con Retry-After), server_error (500).
Límites de /api/v1/me: 120 peticiones/min por app y persona. Cabeceras X-RateLimit-Limit y X-RateLimit-Remaining.
Versiones y cambios
- Sin aviso podemos añadir endpoints, campos opcionales en las respuestas, valores nuevos en listas abiertas (por ejemplo, tipos de evento de webhook a los que te suscribes de forma explícita) y cabeceras. Tu código debe ignorar lo que no conoce.
- Cambios incompatibles (quitar o renombrar campos, cambiar tipos o significados, endurecer validaciones) solo llegan en una versión nueva:
/api/v2. Nunca dentro de/api/v1. - Retirada. Una versión se mantiene al menos 12 meses desde que anunciamos su retirada. Durante ese plazo las respuestas llevan las cabeceras
DeprecationySunset(RFC 8594) y avisamos por correo a quien tenga apps activas. - Orion ID sigue OpenID Connect: el documento de descubrimiento es la referencia. Las claves de firma rotan con solapamiento; elige siempre por
kidy vuelve a leer el JWKS si no encuentras uno. - Seguridad. Un cambio necesario para corregir un fallo de seguridad puede aplicarse sin plazo; lo explicaremos en la página de estado.
Estado del servicio y avisos: https://oriondatagroup.com/status.
Buenas prácticas obligatorias
- Valida siempre
stateynonce. Usa PKCE con S256. - Guarda el client secret solo en tu servidor. Las apps móviles o SPA deben registrarse como públicas (sin secreto).
- Las URLs de retorno se comparan de forma exacta. Solo HTTPS (o http://localhost en desarrollo).
- No guardes access tokens en localStorage; prefiere cookies de sesión de tu backend.
- Cuando una persona revoca el acceso, tus tokens dejan de funcionar al instante: trata un 401 como «sesión terminada».