Quem entrou, no código

A cada requisição, a plataforma entrega à aplicação a identidade de quem entrou, assinada. O SDK a confere e devolve a pessoa; em outra linguagem, a conferência é a mesma e está descrita abaixo.

TypeScript e Node

npm install @nnumbers/zero

import { NNumbers, UnauthenticatedError } from '@nnumbers/zero/app'

const nn = NNumbers.init()                     // lê as variáveis NNUMBERS_*

app.get('/api/me', async (req, res) => {
  res.json({ user: await nn.auth.user(req) })  // a pessoa, ou null
})

app.get('/painel', async (req, res) => {
  try {
    const user = await nn.auth.requireUser(req, req.url)
    res.send(`Olá, ${user.name ?? user.username}`)
  } catch (e) {
    if (e instanceof UnauthenticatedError) return res.redirect(e.loginPath)
    throw e
  }
})

API	O que faz
NNumbers.init()	o contexto da aplicação: appId, org e auth
nn.auth.user(req)	quem entrou, ou null
nn.auth.requireUser(req, returnTo)	como user, mas sem pessoa lança UnauthenticatedError com o loginPath que volta a returnTo
nn.auth.loginPath(returnTo)	o caminho do login; destino fora da aplicação vira /
nn.auth.logoutPath	o caminho da saída (POST)

Erro	Código	Quando
AppConfigurationError	ORGANIZATION_IAM_NOT_ENABLED	a aplicação roda sem a capacidade ligada, ou fora do Zero
UnauthenticatedError	USER_SESSION_REQUIRED	a rota exige alguém e ninguém entrou
IdentityAssertionError	IDENTITY_ASSERTION_INVALID	chegou uma identidade que não confere — nunca vira pessoa

user aceita a requisição do Node, a Request do fetch ou um objeto de cabeçalhos. Há um exemplo completo, sem framework, em examples/organization-iam no repositório do SDK.

Em outra linguagem

A identidade chega no cabeçalho X-NNumbers-Identity: um JWS compacto, algoritmo ES256, typ nn-identity+jwt. Confira sempre, em toda requisição — um cabeçalho sem assinatura conferida não prova nada:

1. A assinatura, com as chaves públicas do endereço em NNUMBERS_IDENTITY_JWKS. Guarde as chaves por alguns minutos e busque de novo quando chegar um kid desconhecido.
2. iss igual a NNUMBERS_IDENTITY_ISSUER.
3. aud igual a NNUMBERS_APP_ID — a identidade entregue a outra aplicação não vale aqui.
4. org igual a NNUMBERS_ORG_ID.
5. exp e nbf: a identidade vale por 5 minutos.

Sem o cabeçalho, a requisição é anônima. Com o cabeçalho e qualquer conferência falhando, recuse — nunca trate como pessoa.

Claim	O que é
sub	o identificador da pessoa no IAM da organização
org, org_slug	a organização
iam	o endereço do IAM da organização
sid	a referência da sessão
name, email, email_verified, preferred_username	quando a conta os tem
iat, nbf, exp, jti	o prazo e o identificador desta identidade

As variáveis da plataforma

Com a capacidade ligada, a publicação injeta:

Variável	O que é
NNUMBERS_APP_ID	o id desta aplicação (svc_…)
NNUMBERS_ORG_ID, NNUMBERS_ORG_SLUG	a organização do projeto
NNUMBERS_IDENTITY_ISSUER	o emissor da identidade
NNUMBERS_IDENTITY_JWKS	o endereço das chaves públicas — alcançável só de dentro da plataforma
NNUMBERS_BROKER_URL	onde a aplicação pede a credencial da pessoa para o QueryMesh — alcançável só de dentro da plataforma

O prefixo NNUMBERS_ é da plataforma: a configuração do serviço não aceita variável com ele.

Próximos passos

• Ligar o login da organização
• SDKs
• Variáveis e secrets