OrionID
Entrar Crear cuenta

Documentación

Orion ID es un proveedor OpenID Connect estándar: cualquier biblioteca OIDC sirve.

Inicio de sesión con Orion ID (OpenID Connect)

  1. Registra tu app en Mis aplicaciones. Empieza en modo desarrollo: solo tú puedes iniciar sesión con ella.
  2. Configura tu biblioteca OIDC con el documento de descubrimiento: https://oriondatagroup.com/.well-known/openid-configuration
  3. Redirige a https://oriondatagroup.com/oauth/authorize con response_type=code, client_id, redirect_uri (exacta), scope=openid profile, state, nonce y PKCE (code_challenge + code_challenge_method=S256, obligatorio para todas las apps).
  4. Canjea el code en POST https://oriondatagroup.com/oauth/token con grant_type=authorization_code, code_verifier y redirect_uri. Las apps confidenciales se autentican con client_secret_basic o client_secret_post.
  5. Valida el id_token (RS256): firma con el JWKS (https://oriondatagroup.com/.well-known/jwks.json, elige la clave por kid), iss, aud = tu client_id, exp y nonce.
  6. Usa sub como 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)

ScopeQué daRequiere aprobación
openidConfirmar que eres tú (identificador anónimo y estable)No
profileTu @usuario, nombre visible y fotoNo
linksLas redes y la web de tu tarjetaNo
emailTu dirección de correo electrónico verificadaNo
organizationsLas empresas de las que formas parte y tu papel en cada unaSí, 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}}
  • id es 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 de t + "." + cuerpo con tu clave de firma. Compara en tiempo constante.
  • Repeticiones. Rechaza marcas de tiempo de más de 5 minutos. Cada evento tiene un id estable (también en la cabecera Orion-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 Deprecation y Sunset (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 kid y 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 state y nonce. 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».