Permissões e ações

Toda autorização na Platform 2 é expressa em ações: cadeias no formato <tag do app>:<recurso>.<verbo>, como billing:event.create ou acme-invoices:invoice.read. Quem decide se um principal — uma pessoa ou um aplicativo — pode executar uma ação em uma área de trabalho é a Gestão de Identidade e Acesso (GIA) daquela área de trabalho. Seu app não mantém uma lista própria de usuários e permissões: ele pergunta ao Console.

Ações implementadas e consumidas

	Quem declara	Formato	Para quê
Ações implementadas	O seu app, na aba Permissões ou com `iugu app permissions set --implemented …`	Sem prefixo (`invoice.create`); o Console acrescenta a tag: `acme-invoices:invoice.create`	São as permissões que os administradores das áreas de trabalho distribuem aos membros (papéis e políticas) e que o seu backend verifica antes de atender uma requisição.
Ações consumidas	O seu app	Com prefixo, de outros apps (`billing:event.create`)	Ao instalar o app, a área de trabalho aceita uma política gerenciada que concede ao app exatamente essas ações. É o que permite ao seu backend chamar a Central de Cobranças ou outro app em nome da área de trabalho.

Warning

Mudar as ações consumidas de um app já instalado faz cada área de trabalho instalada precisar aceitar as novas permissões (o Console mostra a pendência; pela CLI, iugu app resync). Acrescente ações antes de precisar delas e evite renomear.

Só aparecem como consumíveis as ações de apps que a área de trabalho tem instalados. A CLI lista o catálogo com iugu catalog actions --q <texto> — por tag, por parte do nome da ação, pelo nome completo tag:ação ou por vários termos (todos precisam casar).

Quem é o principal

Principal	`sub` do token	Como obtém o token
Uma pessoa	`user:<id>`	Fluxo OAuth 2.1 do seu app (`/authorize` → `/token` com PKCE). O token carrega a área de trabalho e o nível de autenticação da sessão.
O seu app agindo por si	`app:<id do app>`	`POST https://identity.iugu.com/token` com `grant_type=client_credentials`, `client_id`/`client_secret` e `audience=Iugu.Platform.<id do app de destino>`. O app só pode o que a política gerenciada concedeu na área de trabalho.
Um principal temporário	`temp:<id>`	Criado pela CLI para testes (`iugu test-principal create --name qa`), com papéis ⊆ os de quem o criou e validade de 1 hora.

Verificar a autorização no seu backend

Seu backend recebe requisições com um token de acesso (JWT). Antes de atender:

Valide o token: assinatura pelas chaves em https://identity.iugu.com/.well-known/jwks.json, iss = https://identity.iugu.com/, typ = at+JWT, exp no futuro e aud contendo Iugu.Platform.<id do seu app>. Um token emitido para outro app não serve para o seu.
Pergunte ao Console o que o principal pode fazer na área de trabalho da requisição:

curl -X POST https://identity.iugu.com/verify \
  -H "Authorization: Bearer <token do SEU app (client_credentials)>" \
  -H "Content-Type: application/json" \
  -d '{
        "workspace_id": "<id curto da área de trabalho>",
        "principals": ["user:1hC4SaHg52IMbtwb35Xb7a"],
        "actions": ["acme-invoices:invoice.create", "acme-invoices:invoice.read"]
      }'

A resposta é um mapa de cada ação para true ou false:

{ "acme-invoices:invoice.create": true, "acme-invoices:invoice.read": true }

principals aceita uma cadeia ou uma lista; cada item pode ser só o sub ou um objeto { "principal": "user:…", "ip_address": "…", "certificate_thumbprint": "…" } para que o Console também aplique o filtro por IPs e o certificado do cliente.
Verifique o sub do token — a pessoa ou o app em nome de quem a requisição é feita. O client_id do token diz qual cliente a enviou (o Workflow, o Iugu for AI, a sua própria interface): registre-o para fins de atribuição, mas nunca autorize por ele.
A referência completa está em /verify; os dados da pessoa vêm de /userinfo.

Info

Um único POST /verify pode checar várias ações e vários principais. Faça a verificação a cada requisição — papéis mudam, apps são desinstalados e o Console é a fonte da verdade — e guarde o resultado apenas pelo tempo de uma requisição.

Níveis de integração (contexto de autenticação)

Algumas operações merecem uma prova recente de que há uma pessoa presente: um segundo fator agora, não uma sessão aberta ontem. O Console exprime isso em três níveis, que o app pede no login com acr_values=urn:iugu:grant_scopes:<nível> e que a aba Permissões limita (Nível de integração = os níveis que o app está autorizado a pedir):

Nível	`acr_values`	O que a pessoa prova	Janela
Acesso a Informações	`urn:iugu:grant_scopes:informations`	Sessão válida. É o padrão de toda sessão e o nível a que ela volta depois de uma elevação.	sessão
Gerenciamento de Configurações	`urn:iugu:grant_scopes:config`	Segundo fator recente (o login nativo com MFA já abre esta janela).	10 min
Movimentação de Valores	`urn:iugu:grant_scopes:transfers`	Senha e segundo fator, agora.	1 min

Regras que valem para todos os apps:

Um código de autorização emitido acima de Acesso a Informações consome a janela: a sessão volta ao nível padrão e a próxima operação elevada, de qualquer app, pede um novo fator. Peça o nível alto só na operação que precisa dele.
Pedir um nível que a aba Permissões não autoriza devolve o erro OAuth unmet_authentication_requirements.
No seu backend, o nível do token vem na claim acr. Se ele for insuficiente para a operação, responda 401 com WWW-Authenticate: Bearer error="insufficient_user_authentication", acr_values="urn:iugu:grant_scopes:config" (RFC 9470): clientes como o Iugu for AI transformam essa resposta em um pedido de confirmação à pessoa e repetem a chamada.
Tokens de app (client_credentials) não têm nível: um app agindo por si nunca satisfaz config ou transfers.

Papéis, políticas e o que o administrador vê

Na área de trabalho, as ações implementadas do seu app aparecem para o administrador em Políticas (com curingas: acme-invoices:invoice.*, acme-invoices:*) e são agrupadas em Permissões (papéis) atribuídas aos Membros. Em Aplicativos o administrador vê as ações consumidas que o seu app recebeu ao ser instalado e pode revê-las.

Info

Dê nomes às ações pelo recurso e pelo verbo, na granularidade que o administrador vai querer distribuir: invoice.read para quem só consulta, invoice.create para quem emite, settings.edit para quem configura. Descrições curtas no seu manifesto de ações (Expor ações) ajudam o administrador a decidir.

Testar sem usuários reais

iugu test-principal create --name qa --json          # principal temporário, 1 h, papéis ⊆ os seus
iugu verify --principal temp:<id> --action acme-invoices:invoice.create --json
iugu app token --exec "curl -sS -H 'Authorization: Bearer {token}' https://identity.iugu.com/userinfo"

iugu app token emite um token de curta duração do seu app para exercitar /verify e /userinfo; com --exec o token nunca aparece no terminal. Em Políticas o administrador também pode testar uma política contra um principal e uma ação antes de salvá-la.

Back

Criar um aplicativo

Forward

Expor ações

This page