Documentação
O Orion ID é um provedor OpenID Connect padrão: qualquer biblioteca OIDC serve.
Entrar com Orion ID (OpenID Connect)
- Registre seu app em Meus aplicativos. Começa em modo de desenvolvimento: só você pode entrar com ele.
- Configure sua biblioteca OIDC com o documento de descoberta:
https://oriondatagroup.com/.well-known/openid-configuration - Redirecione para
https://oriondatagroup.com/oauth/authorizecomresponse_type=code,client_id,redirect_uri(exata),scope=openid profile,state,noncee PKCE (code_challenge+code_challenge_method=S256, obrigatório para todos os apps). - Troque o
codeemPOST https://oriondatagroup.com/oauth/tokencomgrant_type=authorization_code,code_verifiereredirect_uri. Os apps confidenciais se autenticam comclient_secret_basicouclient_secret_post. - Valide o
id_token(RS256): assinatura com o JWKS (https://oriondatagroup.com/.well-known/jwks.json, escolha a chave porkid),iss,aud= seu client_id,expenonce. - Use
subcomo 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)
| Scope | O que concede | Exige aprovação |
|---|---|---|
openid | Confirmar que é você (identificador anônimo e estável) | Não |
profile | Seu @usuario, nome visível e foto | Não |
links | As redes e o site do seu cartão | Não |
email | Seu endereço de e-mail verificado | Não |
organizations | As empresas de que você faz parte e sua função em cada uma | Sim, 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 det + "." + corpocom sua chave de assinatura. Compare em tempo constante. - Repetições. Rejeite carimbos de tempo com mais de 5 minutos. Cada evento tem um
idestável (também no cabeçalhoOrion-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
DeprecationeSunset(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
kide 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
stateenonce. 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”.