OrionID
Entrar Criar conta

Documentação

O Orion ID é um provedor OpenID Connect padrão: qualquer biblioteca OIDC serve.

Entrar com Orion ID (OpenID Connect)

  1. Registre seu app em Meus aplicativos. Começa em modo de desenvolvimento: só você pode entrar com ele.
  2. Configure sua biblioteca OIDC com o documento de descoberta: https://oriondatagroup.com/.well-known/openid-configuration
  3. Redirecione para https://oriondatagroup.com/oauth/authorize com response_type=code, client_id, redirect_uri (exata), scope=openid profile, state, nonce e PKCE (code_challenge + code_challenge_method=S256, obrigatório para todos os apps).
  4. Troque o code em POST https://oriondatagroup.com/oauth/token com grant_type=authorization_code, code_verifier e redirect_uri. Os apps confidenciais se autenticam com client_secret_basic ou client_secret_post.
  5. Valide o id_token (RS256): assinatura com o JWKS (https://oriondatagroup.com/.well-known/jwks.json, escolha a chave por kid), iss, aud = seu client_id, exp e nonce.
  6. Use sub como identificador da pessoa. É estável e não 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 dias, de uso único (cada refresh devolve um novo; reutilizar um antigo revoga toda a sessão desse app). Revogação: POST https://oriondatagroup.com/oauth/revoke (RFC 7009). prompt=none|login|consent suportados.

Exemplo completo e executável: examples/demo-client no repositório.

Permissões (scopes)

ScopeO que concedeExige aprovação
openidConfirmar que é você (identificador anônimo e estável)Não
profileSeu @usuario, nome visível e fotoNão
linksAs redes e o site do seu cartãoNão
emailSeu endereço de e-mail verificadoNão
organizationsAs empresas de que você faz parte e sua função em cada umaSim, por app

A senha nunca é compartilhada. O e-mail e as redes só chegam se a pessoa aceitar na tela de permissão.

O que você recebe

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",                         // só se o cartão for público
 "orion_links": {"instagram": "https://instagram.com/lucia", "web": "https://lucia.example"},   // scope links
 "email": "lucia@example.com", "email_verified": true}   // scope email

Os mesmos dados, como JSON simples, em GET https://oriondatagroup.com/api/v1/me. No id_token, amr diz como a pessoa entrou (mca = aprovado no celular ou por QR, otp = código, hwk = passkey) e acr vale orion:mfa quando houve segunda etapa. Para exigi-la, envie acr_values=orion:mfa.

Ecossistema: entrada única, saída em todos e mensagens

O que faz vários sites parecerem um só. Funciona com qualquer app; o que está marcado como “do grupo” só com os sites que o Orion ID marca assim.

Entrar sem tocar em nada

Quando alguém chegar sem sessão, redirecione para /oauth/authorize com prompt=none. Se a pessoa já tiver o Orion ID aberto e tiver aceitado seu site, volta na hora com um code; se não, volta com error=login_required e você mostra seu botão “Continuar com Orion ID”. Os sites do grupo que pedem só openid profile email links não mostram tela de permissão: a pessoa entra direto (a permissão fica em “Seus sites” e pode ser removida).

Sair

Encerre sua sessão e leve a pessoa a https://oriondatagroup.com/oauth/logout com client_id, post_logout_redirect_uri e state. O Orion ID pergunta se ela também quer sair do Orion ID ou de todos os sites e a devolve a post_logout_redirect_uri, que precisa estar no mesmo site (https e mesmo domínio) que um dos seus endereços de retorno.

Se ela escolher “todos” (ou tocar em “Sair de todos os sites” em Segurança), cada site recebe o webhook session.ended com o sub dela: encerre todas as sessões dessa pessoa no seu site.

Mensagens em Notificações

Seu site pode deixar um aviso na conta do Orion ID de uma pessoa que o usa: um pedido enviado, uma resposta, um lembrete dela. Chega em “Notificações” e, se ela tiver ativado, ao celular. Só texto; o link deve ser do seu site.

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

{"sub": "01JB…", "title": "Pedido enviado", "text": "Seu pedido 1042 sai hoje.", "url": "https://tuweb.com/pedidos/1042", "id": "pedido-1042-enviado"}

201 {"data": {"delivered": true, "duplicate": false}}
  • id é opcional: se você repetir o mesmo, não se duplica (responde 200 com "duplicate": true).
  • Só para pessoas que entraram no seu site com o Orion ID e não removeram o acesso (se não, 404 not_found). Cada pessoa pode silenciar seu site em “Seus sites” (403 messages_muted): pare de enviar para ela.
  • Limites: 20 mensagens por dia por pessoa e 600 por hora para todo o site (429 rate_limited). Use para o que a pessoa gostaria de saber, não para publicidade: um site que abusa perde o acesso.

Os sites do grupo

https://oriondatagroup.com/.well-known/orion-group.json lista os sites do grupo (nome, endereço, descrição, logo e onde se entra). É pública e pode ser lida pelo navegador: use-a para um menu “Mais do grupo”.

Webhooks

Configure um endereço https na ficha do seu app e avisaremos você destes eventos com uma requisição POST em JSON:

  • authorization.revoked: Uma pessoa retira o acesso do seu app (ou a plataforma o retira).
  • account.deleted: Uma pessoa que usava seu app exclui a conta do Orion ID.
  • account.updated: Uma pessoa que usa seu app muda o nome, a foto, o e-mail ou o cartão (peça /oauth/userinfo de novo).
  • account.secured: Uma pessoa toca em “Não fui eu”: encerre as sessões dela no seu app e peça que entre de novo.
  • session.ended: Uma pessoa sai de todos os lugares pelo Orion ID: encerre também a sessão dela no seu site.
  • ping: teste enviado pelo portal.

Os eventos de conta incluem só o identificador sub da pessoa:

{"id": "evt_01jb…", "type": "authorization.revoked", "created": 1760000000, "client_id": "oid_…", "data": {"sub": "…"}}
  • Assinatura. Cabeçalho Orion-Signature: t=…,v1=…: HMAC-SHA256 de t + "." + corpo com sua chave de assinatura. Compare em tempo constante.
  • Repetições. Rejeite carimbos de tempo com mais de 5 minutos. Cada evento tem um id estável (também no cabeçalho Orion-Delivery): as novas tentativas e os reenvios manuais o repetem, então guarde os processados e ignore os duplicados respondendo 200.
  • Entrega. Responda 2xx em menos de 5 segundos (coloque o trabalho pesado na fila). Se não, tentamos de novo após 1 min, 5 min, 30 min e 2 h. Na ficha do seu app você pode reenviar um evento dos últimos 7 dias.
  • Rede. Só https, portas 443 ou 8443, sem redirecionamentos nem endereços privados. Conectamos ao IP que verificamos, sem resolver o domínio de novo.

Na ficha do seu app, Verificar integração envia três requisições de teste (válida, com assinatura falsa e antiga) com "test": true e diz se o seu servidor aceita só a boa.

Exemplos com bibliotecas comuns

Use sempre uma biblioteca OpenID Connect mantida: ela valida o id_token, o state e o nonce por você. Nos exemplos, 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');

Verificar um 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

Exemplo completo sem dependências em PHP (entrada, duas etapas, renovação, revogação e receptor de webhooks): examples/demo-client no repositório.

Erros e limites

{"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, com Retry-After), server_error (500).

Limites de /api/v1/me: 120 requisições/min por app e pessoa. Cabeçalhos X-RateLimit-Limit e X-RateLimit-Remaining.

Versões e mudanças

  • Sem aviso podemos adicionar endpoints, campos opcionais nas respostas, valores novos em listas abertas (por exemplo, tipos de evento de webhook que você assina explicitamente) e cabeçalhos. Seu código deve ignorar o que não conhece.
  • Mudanças incompatíveis (remover ou renomear campos, mudar tipos ou significados, endurecer validações) só chegam numa versão nova: /api/v2. Nunca dentro de /api/v1.
  • Descontinuação. Uma versão é mantida por pelo menos 12 meses desde que anunciamos sua descontinuação. Durante esse prazo, as respostas levam os cabeçalhos Deprecation e Sunset (RFC 8594) e avisamos por e-mail quem tiver apps ativos.
  • Orion ID segue o OpenID Connect: o documento de descoberta é a referência. As chaves de assinatura são trocadas com sobreposição; escolha sempre por kid e leia o JWKS de novo se não encontrar uma.
  • Segurança. Uma mudança necessária para corrigir uma falha de segurança pode ser aplicada sem prazo; vamos explicá-la na página de status.

Status do serviço e avisos: https://oriondatagroup.com/status.

Boas práticas obrigatórias

  • Valide sempre state e nonce. Use PKCE com S256.
  • Guarde o client secret só no seu servidor. Apps móveis ou SPA devem ser registrados como públicas (sem segredo).
  • As URLs de retorno são comparadas de forma exata. Só HTTPS (ou http://localhost em desenvolvimento).
  • Não guarde access tokens no localStorage; prefira cookies de sessão do seu backend.
  • Quando uma pessoa revoga o acesso, seus tokens deixam de funcionar na hora: trate um 401 como “sessão encerrada”.