Laqus Platform Authentication Library

Documentação de Integração

Índice

1. Visão Geral
2. Instalação
3. Configuração
4. Conceitos Básicos
5. Uso Básico
6. Exemplos Práticos
7. Arquitetura
8. Referência da API
9. Troubleshooting

Visão Geral

A biblioteca de autenticação da Laqus Platform é um módulo NestJS que facilita a integração de serviços com o sistema de autenticação e autorização da plataforma Laqus. Ela oferece:

• Integração transparente com Keycloak
• Sistema de cache distribuído para tokens e permissões
• Decorators para controle de acesso
• Guards para proteção de rotas
• Gerenciamento automático de contexto de usuário

Fluxo de Autenticação

sequenceDiagram
		participant C as Cliente
		participant A as API
		participant L as LaqusAuth
		participant K as Keycloak
		participant R as Redis Cache

		C->>A: Request + JWT Token
		A->>L: Valida Token
		L->>K: Verifica Assinatura
		L->>R: Busca Permissões
		R-->>L: Retorna Cache
		L-->>A: Autoriza/Nega
		A-->>C: Response

Instalação

npm install @laqus/platform-auth

Configuração

1. Importar o Módulo

import { LaqusPlatformAuthModule } from '@laqus/platform-auth';

@Module({
	imports: [
		LaqusPlatformAuthModule.forRoot({
			keycloakRSA256PublicKey: 'SUA_CHAVE_PUBLICA',
			authMiddlewareAdminClientId: 'ID_DO_CLIENT',
			cache: {
				redisHost: 'localhost',
				redisPort: 6379,
				redisPassword: 'senha',
				authCacheKeysPrefix: 'minhaapp',
				ttl: 3600
			}
		})
	]
})
export class AppModule {}

2. Configurar Guard Global

import { LaqusPlatformGuard } from '@laqus/platform-auth';

async function bootstrap() {
	const app = await NestFactory.create(AppModule);
	app.useGlobalGuards(app.get(LaqusPlatformGuard));
	await app.listen(3000);
}

Conceitos Básicos

Tipos de Usuários

A biblioteca suporta diferentes tipos de usuários:

• REGULAR_USER: Usuários normais autenticados
• API_SVC_ACCOUNT: Contas de serviço
• LAQUS_PLATFORM_ADMIN: Administradores da plataforma
• PUBLIC: Endpoints públicos
• SCIM_FULL: Usuários SCIM

Estrutura de Permissões

graph TD
		A[Tenant] --> B[Groups]
		A --> C[Policies]
		B --> D[Users]
		B --> E[Permissions]
		C --> F[Resources]
		F --> G[Actions]
		E --> H[Allow/Deny]

Uso Básico

1. Proteger Rotas

import { Authorization } from '@laqus/platform-auth';

@Controller('users')
export class UserController {
	@Get()
	@Authorization.isAuthenticated()
	findAll() {
		return this.userService.findAll();
	}

	@Post()
	@Authorization.requireAllOf({
		actions: [UserActions.CREATE],
		policies: [UserPolicies.MANAGE_USERS]
	})
	create(@Body() user: CreateUserDto) {
		return this.userService.create(user);
	}
}

2. Verificar Permissões em Serviços

import { AuthenticatedUserService } from '@laqus/platform-auth';

@Injectable()
export class UserService {
	constructor(private readonly authService: AuthenticatedUserService) {}

	async updateUser(id: string, data: UpdateUserDto) {
		const user = this.authService.getUser();
		// Verificar permissões específicas
		if (!user.hasAction(UserActions.UPDATE)) {
			throw new ForbiddenException();
		}
		// ... resto da lógica
	}
}

Exemplos Práticos

Exemplo 1: CRUD com Diferentes Níveis de Acesso

@Controller('documents')
export class DocumentController {
	// Público - qualquer um pode listar
	@Get()
	@Authorization.isPublic()
	findAll() {
		return this.documentService.findAll();
	}

	// Somente usuários autenticados podem ver detalhes
	@Get(':id')
	@Authorization.isAuthenticated()
	findOne(@Param('id') id: string) {
		return this.documentService.findOne(id);
	}

	// Requer política específica para criar
	@Post()
	@Authorization.requirePolicy({
		name: 'document:create',
		allows: {
			actions: ['create'],
			effect: 'Allow',
			actionPaths: ['documents/*']
		}
	})
	create(@Body() doc: CreateDocumentDto) {
		return this.documentService.create(doc);
	}

	// Requer múltiplas condições
	@Delete(':id')
	@Authorization.requireAllOf({
		actions: [DocumentActions.DELETE],
		roles: [{ name: 'admin' }],
		policies: [DocumentPolicies.MANAGE]
	})
	remove(@Param('id') id: string) {
		return this.documentService.remove(id);
	}
}

Exemplo 2: Service Account

@Controller('integration')
export class IntegrationController {
	@Post('sync')
	@Authorization.set({
		userTypes: [DefaultUserTypes.API_SVC_ACCOUNT],
		actions: [IntegrationActions.SYNC],
		authorizationStrategy: AuthorizationStrategy.ALL
	})
	sync(@Body() data: SyncDto) {
		return this.integrationService.sync(data);
	}
}

Arquitetura

Componentes Principais

graph TB
		A[LaqusPlatformGuard] --> B[AuthorizationContext]
		B --> C[UserAuthorizationContext]
		B --> D[ServiceAccountAuthorizationContext]
		B --> E[AuthMiddlewareAuthorizationContext]
		F[AuthenticatedUserService] --> B
		G[CacheManager] --> H[Redis]
		I[Authorization Decorator] --> A

Referência da API

Decorators

@Authorization

• set(auth: LaqusPermissionSet): Configuração detalhada de permissões
• requireAllOf(auth: LaqusPermissionSet): Requer todas as condições
• requireAnyOf(auth: LaqusPermissionSet): Requer qualquer condição
• requirePolicy(...policy: IPermissionPolicy[]): Requer políticas específicas
• requireSuperAdmin(): Requer super admin
• isPublic(): Endpoint público
• isAuthenticated(): Requer apenas autenticação
• requireSCIM(): Requer acesso SCIM

Interfaces

ILaqusAuthOptions

interface ILaqusAuthOptions {
	keycloakRSA256PublicKey: string;
	authMiddlewareAdminClientId: string;
	cache: ICacheOptions;
}

ICacheOptions

interface ICacheOptions {
	ttl?: number;
	redisPassword: string;
	redisHost: string;
	redisPort: number;
	authCacheKeysPrefix: string;
}

Troubleshooting

Problemas Comuns

1. Token Inválido

   • Verifique se o token está sendo enviado corretamente no header
   • Formato: Authorization: Bearer <token>
   • Verifique se a chave pública do Keycloak está correta

2. Permissões Negadas

   • Verifique se o usuário possui as policies necessárias
   • Confirme se as actions estão corretamente definidas
   • Verifique os logs do Redis para problemas de cache

3. Problemas de Cache

   • Verifique a conexão com Redis
   • Confirme se as chaves de cache estão corretas
   • Verifique o TTL das chaves

Logs Úteis

// Ativar logs detalhados
@Module({
	imports: [
		LaqusPlatformAuthModule.forRoot({
			...config,
			debug: true
		})
	]
})

Melhores Práticas

1. Segurança

   • Sempre use HTTPS em produção
   • Mantenha as chaves seguras
   • Implemente rate limiting

2. Performance

   • Configure TTL do cache adequadamente
   • Use policies em vez de checks individuais
   • Agrupe permissões relacionadas

3. Organização

   • Mantenha policies bem documentadas
   • Use constantes para actions
   • Centralize configurações de autorização

Fluxo detalhado de verificação

stateDiagram-v2
		[*] --> TokenReceived

		TokenReceived --> ValidateToken: JWT Token
		ValidateToken --> CheckCache: Token Válido
		ValidateToken --> Unauthorized: Token Inválido

		CheckCache --> LoadFromCache: Cache Hit
		CheckCache --> FetchFromKeycloak: Cache Miss

		FetchFromKeycloak --> UpdateCache: Dados Obtidos
		UpdateCache --> ValidatePermissions: Cache Atualizado
		LoadFromCache --> ValidatePermissions: Dados do Cache

		ValidatePermissions --> CheckUserType: Validar Tipo
		CheckUserType --> CheckPolicies: Tipo OK
		CheckUserType --> Forbidden: Tipo Inválido

		CheckPolicies --> CheckActions: Policies OK
		CheckPolicies --> Forbidden: Policies Inválidas

		CheckActions --> CheckRoles: Actions OK
		CheckActions --> Forbidden: Actions Inválidas

		CheckRoles --> Authorized: Roles OK
		CheckRoles --> Forbidden: Roles Inválidas

		Authorized --> [*]: Acesso Permitido
		Unauthorized --> [*]: 401 Unauthorized
		Forbidden --> [*]: 403 Forbidden

Coding Style

• Usar preferencialmente inglês (código e commits)

Publicação do package e versões

Este projeto está usando versionamento semântico (SemVer). O SemVer segue o padrão: MAJOR.MINOR.PATCH:

• MAJOR: quando faz mudanças incompatíveis na API
• MINOR: quando adiciona funcionalidade mantendo compatibilidade
• PATCH: quando corrige bugs mantendo compatibilidade

Commits

Ao fazer seus PRs, use os prefixos corretos nas mensagens de commit:

# Nova funcionalidade (MINOR)
git commit -m "feat: adicionando novo método de cache"

# Correção de bug (PATCH)
git commit -m "fix: corrigindo timeout do cache"

# Breaking change (MAJOR)
git commit -m "feat!: refatorando API de cache

BREAKING CHANGE: método cache.get() agora é assíncrono"

Prefixos comuns:

• feat: Nova funcionalidade (MINOR)
• fix: Correção de bug (PATCH)
• docs: Documentação (não gera versão)
• style: Formatação (não gera versão)
• refactor: Refatoração (não gera versão)
• perf: Melhorias de performance (PATCH)
• test: Testes (não gera versão)
• chore: Tarefas de build/admin (não gera versão)

Breaking Changes:

• Adicione ! após o tipo
• E/ou adicione um footer BREAKING CHANGE: descrição

Com esse padrão, o semantic-release vai:

1. Analisar os commits desde a última release
2. Determinar a próxima versão automaticamente
3. Gerar changelog
4. Publicar no npm
5. Criar tag no git

Pull Requests

No título dos Pull Requests, seguir o mesmo padrão do versionamento semântico:

# Para novas funcionalidades (MINOR):
feat: adicionado cache
feat: implementado novo método de autenticação
feat: adicionado suporte a redis

# Para correções (PATCH):
fix: ajuste no timeout na conexão
fix: ajuste de memory leak no cache
fix: ajustes na validação de data

# Para breaking changes (MAJOR):
feat!: refatora API de autenticação
fix!: altera retorno dos métodos de cache
chore!: atualiza versão do Node para 18

# Para alterações que não geram versão:
docs: atualização do README
chore: atualização de dependências
test: adicionados testes de integração

Build da lib para uso local

$ npm run build:lib