Registar clientes OAuth

Cada serviço que fala com o Access Management precisa de um cliente OAuth e de um service account ligado a esse cliente. O chart regista-os automaticamente quando m2m.autoRegister.enabled: true — esta página é para o registo manual: apps fora do stack, depuração, ou quando o Job falha.

Convenções desta página

Substitui <domainapi> pelo teu domínio de APIs e <domain> pelo das UIs. Os UUIDs mostrados são exemplos — o teu ambiente devolve outros.

0. Obter o token M2M — pré-requisito de tudo

Usa-se o cliente seeded, que tem as permissões igrp.client.* e igrp.service_account.* através do service account seeded. O client_id e o client_secret são os do Secret igrp-access-management-oauth-client (ou o valor de oauth.oauthClient.clientSecret nos values).

TOKEN=$(curl -sk -X POST https://<domainapi>/igrp-access-management/oauth2/token \
  -d "grant_type=client_credentials&client_id=<oauthClient.clientId>&client_secret=<oauthClient.clientSecret>" \
  | sed 's/.*"access_token":"\([^"]*\)".*/\1/')
echo "${TOKEN:0:20}..."

Se o token vier vazio

O fluxo OAuth2 do Spring Authorization Server exige o gateway HTTPS, com o issuer correcto. Autenticar pelo URL de Service interno (http://igrp-access-management:8080) não emite token.

1. Registar um backend — sem redirects

Um backend só precisa de client_credentials: não há browser, não há callback.

curl -sk -X POST https://<domainapi>/igrp-access-management/api/clients \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" -d '{
  "clientId": "igrp-process-studio-api",
  "clientName": "iGRP Process Studio API",
  "active": true,
  "requirePkce": false,
  "accessTokenTtl": 3600,
  "refreshTokenTtl": 86400,
  "authorizationCodeTtl": 300,
  "scopes": ["openid"],
  "grantTypes": ["client_credentials"]
}'

A resposta traz o clientSecret UMA única vez

Devolve id (o UUID interno) e clientSecret. O secret só é devolvido na criação — guarda-o imediatamente. Se o perderes, tens de apagar e recriar o cliente.

2. Registar um frontend — com redirects

Um frontend acrescenta os callbacks, o authorization_code e o scope profile, que traz o nome e os atributos do utilizador no id_token.

curl -sk -X POST https://<domainapi>/igrp-access-management/api/clients \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" -d '{
  "clientId": "igrp-process-management-ui",
  "clientName": "iGRP Process Management UI",
  "active": true,
  "requirePkce": false,
  "accessTokenTtl": 3600,
  "refreshTokenTtl": 86400,
  "authorizationCodeTtl": 300,
  "scopes": ["openid", "email", "profile"],
  "grantTypes": ["authorization_code", "refresh_token", "client_credentials"],
  "redirectUris": [
    "https://<domain>/apps/<app>/api/auth/callback/igrp-auth",
    "http://localhost:3000/api/auth/callback/igrp-auth"
  ],
  "postLogoutRedirectUris": [
    "https://<domain>/apps/<app>/login",
    "http://localhost:3000/login"
  ]
}'

O redirectUri tem de bater exactamente com o NEXTAUTH_URL

O callback é sempre <NEXTAUTH_URL>/callback/igrp-auth. Se o NEXTAUTH_URL da app não terminar em /api/auth, ou não incluir o basePath, o login falha com redirect_uri inválido.

O localhost:3000 serve o desenvolvimento local. Deixa-o fora dos clientes de produção.

3. Criar o service account

Sem service account, o token M2M do cliente não consegue usar os endpoints do Access Management.

curl -sk -X POST https://<domainapi>/igrp-access-management/api/service-accounts \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" -d '{
  "name": "igrp-process-studio-api",
  "description": "iGRP Process Studio API Service Account",
  "active": true,
  "oauthClientId": "<UUID-devolvido-no-POST-do-cliente>",
  "roleIds": [],
  "permissionIds": []
}'

oauthClientId é o UUID, não a string do clientId

É o campo id devolvido no POST /api/clients — um UUID na forma xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx, não a string igrp-process-studio-api. É o erro mais comum deste procedimento.

As listas roleIds e permissionIds ficam vazias: as permissões são atribuídas depois, se o sync delas precisar.

4. Guardar o secret no namespace

kubectl -n <ns> create secret generic igrp-<serviço>-oauth-client \
  --from-literal=client-id='igrp-<serviço>' \
  --from-literal=client-secret='<devolvido no registo>'

Aspas simples não são opcionais

O clientSecret pode começar por -, e aí o shell interpreta-o como uma flag.

5. Actualizar os redirects de um cliente existente

curl -sk -X PUT https://<domainapi>/igrp-access-management/api/clients/<UUID> \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" -d '{
  "clientId": "igrp-process-management-ui",
  "clientName": "iGRP Process Management UI",
  "active": true,
  "scopes": ["openid", "email", "profile"],
  "grantTypes": ["authorization_code", "refresh_token", "client_credentials"],
  "redirectUris": ["... a lista COMPLETA ..."],
  "postLogoutRedirectUris": ["... a lista COMPLETA ..."]
}'

O PUT substitui o objecto inteiro

Envia sempre a lista completa de redirectUris e postLogoutRedirectUris. O que não for enviado é removido.

Para o cliente OIDC partilhado, o chart tem o Job default-client-uri-sync (oauth.defaultClient.redirectUriSync.enabled), que funde os URIs em vez de os substituir — é o caminho seguro em GitOps.

6. Referência — listar, ver, apagar

# listar todos os clientes
curl -sk https://<domainapi>/igrp-access-management/api/clients \
  -H "Authorization: Bearer $TOKEN"

# ver um cliente
curl -sk https://<domainapi>/igrp-access-management/api/clients/<UUID> \
  -H "Authorization: Bearer $TOKEN"

# apagar (ex.: para re-registar e obter um clientSecret novo)
curl -sk -X DELETE https://<domainapi>/igrp-access-management/api/clients/<UUID> \
  -H "Authorization: Bearer $TOKEN"

Smoke test

O novo cliente tem de conseguir obter token, e o JWT tem de trazer o service account ligado:

curl -sk -X POST https://<domainapi>/igrp-access-management/oauth2/token \
  -d "grant_type=client_credentials&client_id=<novo-client>&client_secret=<novo-secret>"

7. Armadilhas

Sintoma	Causa
`403` em `GET /api/clients` com um token que parece válido	O catálogo de permissões não foi semeado — o service account seeded tem 0 permissões. O Job `catalog-seed` (`catalogSeed.enabled`, default `true`) deteta o 403 e reinicia o Access Management uma vez.
Token M2M vem vazio	Autenticaste pelo Service interno em HTTP. Usa o gateway HTTPS.
`redirect_uri` inválido no login	O `redirectUri` registado não bate exactamente com `<NEXTAUTH_URL>/callback/igrp-auth`.
O service account não dá acesso a nada	Puseste o `clientId` em string no `oauthClientId` em vez do UUID.
Perdeste o `clientSecret`	Só é devolvido na criação. Apaga o cliente e regista de novo, ou usa `autoRegister.forceRecreate: true`.

Registar clientes OAuth

0. Obter o token M2M — pré-requisito de tudoCopy Anchor Link

1. Registar um backend — sem redirectsCopy Anchor Link

2. Registar um frontend — com redirectsCopy Anchor Link

3. Criar o service accountCopy Anchor Link

4. Guardar o secret no namespaceCopy Anchor Link

5. Actualizar os redirects de um cliente existenteCopy Anchor Link

6. Referência — listar, ver, apagarCopy Anchor Link

Smoke testCopy Anchor Link

7. ArmadilhasCopy Anchor Link

On this page