IAM - Identity and Access Management

O Building Block IAM fornece funcionalidades para gerenciamento de identidade e acesso na Catalisa Platform.

Visão Geral

O IAM é um módulo global, ou seja, não requer escopo de organização para algumas operações (como autenticação). Ele é responsável por:

• Autenticação de usuários e aplicações
• Gerenciamento de usuários
• Gerenciamento de organizações
• Controle de acesso baseado em roles (RBAC)
• Associações usuário-organização-role

Base URL

Ambiente	URL
Staging	https://iam.stg.catalisa.app
Produção	https://api.catalisa.app/iam

Recursos

Recurso	Descrição
OAuth	Autenticação e tokens de acesso
Usuários	Gerenciamento de usuários
Organizações	Gerenciamento de organizações
Roles	Roles e permissões
Associations	Associações usuário-organização

Endpoints

Públicos (sem autenticação)

Método	Endpoint	Descrição
POST	/oauth/token	Obter token de acesso
POST	/api/v1/users/login	Login de usuário

Autenticados

Método	Endpoint	Descrição
POST	/api/v1/users	Criar usuário
GET	/api/v1/users	Listar usuários
GET	/api/v1/users/:id	Obter usuário
PATCH	/api/v1/users/:id	Atualizar usuário
DELETE	/api/v1/users/:id	Excluir usuário
POST	/api/v1/organizations	Criar organização
GET	/api/v1/organizations	Listar organizações
GET	/api/v1/organizations/:id	Obter organização
PATCH	/api/v1/organizations/:id	Atualizar organização
DELETE	/api/v1/organizations/:id	Excluir organização
POST	/api/v1/organizations/:id/client-secret	Definir client secret
GET	/api/v1/roles	Listar roles
GET	/api/v1/roles/:name/permissions	Obter permissões de uma role
GET	/api/v1/permissions	Listar todas as permissões
POST	/api/v1/associations	Atribuir role a usuário
DELETE	/api/v1/associations	Remover role de usuário
GET	/api/v1/users/:id/associations	Listar associações do usuário
GET	/api/v1/organizations/:id/members	Listar membros da organização

Conceitos Importantes

Usuários

Usuários são entidades que podem se autenticar na plataforma. Cada usuário possui:

• Email único
• Senha (hash)
• Status (ativo, inativo, bloqueado, pendente)
• Flag de MFA

Organizações

Organizações representam tenants na plataforma. Tipos disponíveis:

• cliente - Organização cliente
• parceiro - Organização parceira
• dono - Organização proprietária

Roles e Permissões

O sistema utiliza RBAC para controle de acesso. Cada role possui um conjunto de permissões predefinidas.

Associações

Associações vinculam usuários a organizações com uma role específica. Um usuário pode estar associado a múltiplas organizações com diferentes roles.

Exemplo Rápido

Fluxo básico para criar uma organização e adicionar um usuário:

// 1. Obter token de acesso (Client Credentials)
const tokenResponse = await fetch('https://iam.stg.catalisa.app/oauth/token', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    grant_type: 'client_credentials',
    client_id: 'sua-org-id',
    client_secret: 'seu-secret',
  }),
});
const { access_token } = await tokenResponse.json();

// 2. Criar usuário
const userResponse = await fetch('https://iam.stg.catalisa.app/api/v1/users', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${access_token}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    email: 'novo.usuário@empresa.com',
    password: 'senhaSegura123',
  }),
});
const { data: user } = await userResponse.json();

// 3. Associar usuário a organização com role ADMIN
await fetch('https://iam.stg.catalisa.app/api/v1/associations', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${access_token}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    userId: user.id,
    organizationId: 'org-id',
    roleId: 1, // ADMIN
  }),
});

Diagrama de Relacionamentos

Estrutura de Entidades do IAM

O IAM é composto pelas seguintes entidades principais:

Entidades:

• User (Usuário)

  • id: UUID
  • email: String (único)
  • status: ACTIVE/INACTIVE/BLOCKED/PENDING
  • mfaEnabled: Boolean

• Organization (Organização)

  • id: UUID
  • name: String
  • slug: String (único)
  • type: cliente/parceiro/dono
  • status: ACTIVE/INACTIVE
  • clientSecret: String (para OAuth Client Credentials)

• Association (Associação)

  • userId: UUID
  • organizationId: UUID
  • roleId: Integer
  • roleName: String

• Role (Papel)

  • id: Integer
  • name: String (ex: ADMIN, VIEWER, CUSTOMER_MANAGER)
  • permissions: Array de strings

Relacionamentos:

• Um User pode ter múltiplas Associations (N associações por usuário)
• Cada Association vincula:
  • Um User a uma Organization
  • Com um Role específico
• Um User pode estar associado a múltiplas Organizations com diferentes Roles
• Cada Role define um conjunto de permissions predefinidas
• Uma Organization pode ter múltiplos Users associados (via Associations)