Laqus.Platform.Auth 2.8.1

Laqus Platform Auth

Pacote NuGet para integração de serviços com o sistema de autenticação e autorização da plataforma Laqus.

Setup

Configuração (appsettings)

"LaqusAuth": {
  "AuthMiddlewareApiUrl": "http://localhost:3030/",
  "Cache": {
    "Ttl": 3600,
    "EnableTls": false,
    "RedisUser": "",
    "RedisPassword": "",
    "RedisHost": "localhost",
    "RedisPort": 6379,
    "AuthCacheKeysPrefix": ""
  },
  "Keycloak": {
    "Authority": "http://localhost:9990/realms/laqus-platform",
    "ClientId": "my-tenant-api-client",
    "Issuer": "http://localhost:9990/realms/laqus-platform",
    "ClientSecret": "********************"
  }
}

Registro dos Serviços

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddLaqusAuth(builder.Configuration, option =>
{
    option.AppName = "App Teste";
    option.AuthMiddlewareApiUrl = builder.Configuration["LaqusAuth:AuthMiddlewareApiUrl"];
    option.Options = new AuthOptions
    {
        Authority = builder.Configuration["LaqusAuth:Keycloak:Authority"],
        ClientId = builder.Configuration["LaqusAuth:Keycloak:ClientId"],
        ClientSecret = builder.Configuration["LaqusAuth:Keycloak:ClientSecret"],
        Issuer = builder.Configuration["LaqusAuth:Keycloak:Issuer"],
    };
    option.CacheOptions = new CacheOptions
    {
        Ttl = int.Parse(builder.Configuration["LaqusAuth:Cache:Ttl"] ?? "3600"),
        EnableTls = builder.Configuration["LaqusAuth:Cache:EnableTls"] == "true",
        RedisUser = builder.Configuration["LaqusAuth:Cache:RedisUser"],
        RedisPassword = builder.Configuration["LaqusAuth:Cache:RedisPassword"],
        RedisHost = builder.Configuration["LaqusAuth:Cache:RedisHost"],
        RedisPort = int.Parse(builder.Configuration["LaqusAuth:Cache:RedisPort"]!),
        AuthCacheKeysPrefix = builder.Configuration["LaqusAuth:Cache:AuthCacheKeysPrefix"]
    };
});

Pipeline de Middlewares

var app = builder.Build();
app.UseRouting();

app.UseAuthentication();
app.UseLaqusLegacySSOAuthenticationMiddleware();
app.UseAuthorization();

// Opção 1: Autorização completa + tratamento de erros JWT
app.UseLaqusAuthorization();

// Opção 2: Apenas autorização (sem tratamento de erros JWT)
app.UseLaqusAuthorizationMiddleware();

// Opção 3: Apenas tratamento de erros JWT (sem autorização)
app.UseLaqusJwtErrorHandler();

app.MapControllers();

Usuário Autenticado

Acesse informações do usuário logado via IPlatformAuthService:

public class MyController : ControllerBase
{
    private readonly IPlatformAuthService _platformAuthService;

    public MyController(IPlatformAuthService platformAuthService)
    {
        _platformAuthService = platformAuthService;
    }

    [HttpGet("current-user")]
    [IsAuthenticated]
    public IActionResult GetCurrentUser()
    {
        if (!_platformAuthService.IsUserAuthenticated)
            return Unauthorized();

        return Ok(new
        {
            Token = _platformAuthService.TokenInfo.Token,
            User = _platformAuthService.AuthenticatedUser
        });
    }
}

Autorização por Actions

Actions são permissões granulares baseadas em LRN (Laqus Resource Name) e operações.

• LRN: lrn:laqus:v1::<domínio>/<subdomínio>/<...>/<subdomínio>:<recurso>
• Action: Operação específica (criar, consultar, atualizar, excluir)

As actions estão centralizadas na classe estática PlatformActions:

using Laqus.Platform.Auth.Authorization;

PlatformActions.Securitizacao.Termos.Criar
PlatformActions.Securitizacao.Termos.Consultar
PlatformActions.Securitizacao.Termos.Atualizar
PlatformActions.Securitizacao.Termos.Excluir
PlatformActions.Securitizacao.Termos.ConsultarGlobal
PlatformActions.Securitizacao.Termos.Anexos.Criar
PlatformActions.Escrituracao.Auditoria.Logs.Consultar

Decorators

[RequireAction] — Protegendo Endpoints

using Laqus.Platform.Auth.Authorization;
using Laqus.Platform.Auth.Decorators;
using Microsoft.AspNetCore.Mvc;

[ApiController]
[Route("api/[controller]")]
public class CadastrosController : ControllerBase
{
    [HttpGet]
    [RequireAction(PlatformActions.Cadastro.Cadastros.ListBase)]
    public async Task<IActionResult> ListCadastros()
    {
        return Ok(await GetCadastros());
    }
}

Múltiplas Actions (AND)

Por padrão, todas as actions devem ser satisfeitas (estratégia ALL):

[HttpPost("cadastros/{id}/approve")]
[RequireAction(
    PlatformActions.Cadastro.Cadastros.Update,
    PlatformActions.Cadastro.Cadastros.Administrar
)]
public async Task<IActionResult> ApproveCadastro(Guid id)
{
    return Ok();
}

Controller vs Método

O atributo pode ser aplicado no controller (afeta todos os métodos) e sobrescrito por método:

[ApiController]
[Route("api/[controller]")]
[RequireAction(PlatformActions.Cadastro.Cadastros.GetBase)]
public class CadastrosController : ControllerBase
{
    [HttpGet]
    public async Task<IActionResult> List()
    {
        // Usa a action do controller: GetBase
        return Ok();
    }

    [HttpPost]
    [RequireAction(PlatformActions.Cadastro.Cadastros.Create)]
    public async Task<IActionResult> Create()
    {
        // Sobrescreve com a action do método: Create
        return Ok();
    }
}

[IsPublic] e [IsAuthenticated]

[HttpPost("login")]
[IsPublic]
public async Task<IActionResult> Login([FromBody] LoginDto dto)
{
    // Endpoint público, sem autenticação
    return Ok();
}

[HttpGet("profile")]
[IsAuthenticated]
public async Task<IActionResult> GetProfile()
{
    // Requer apenas autenticação, sem validação de permissões
    return Ok();
}

Validação Programática

Para lógica condicional complexa, use IPlatformAuthorizationService:

using Laqus.Platform.Auth.LaqusAuthMiddleware.Service;
using Laqus.Platform.Auth.Authorization;

public class CadastrosApplicationService
{
    private readonly IPlatformAuthorizationService _authorizationService;

    public CadastrosApplicationService(
        IPlatformAuthorizationService authorizationService)
    {
        _authorizationService = authorizationService;
    }
}

Action Única

public async Task<IActionResult> ProcessarCadastro(Guid cadastroId)
{
    var hasPermission = await _authorizationService.AuthorizeAsync(
        PlatformActions.Cadastro.Cadastros.Update
    );

    if (!hasPermission)
        throw new ForbiddenException("Usuário sem permissão para atualizar cadastros");

    // Continua processamento...
}

Múltiplas Actions (ALL / ANY)

// Estratégia ALL — todas as actions são necessárias
var hasAll = await _authorizationService.AuthorizeAsync(
    new[]
    {
        PlatformActions.Cadastro.Cadastros.Update,
        PlatformActions.Cadastro.Cadastros.Administrar
    },
    AuthorizationStrategy.ALL
);

// Estratégia ANY — pelo menos uma das actions
var hasAny = await _authorizationService.AuthorizeAsync(
    new[]
    {
        PlatformActions.Cadastro.Cadastros.GetBase,
        PlatformActions.Cadastro.Cadastros.GetDetails
    },
    AuthorizationStrategy.ANY
);

Validação de User Type

using Laqus.Platform.Auth.LaqusAuthMiddleware.Models.Authorization;

var isServiceAccount = await _authorizationService.AuthorizeApiServiceAccountAsync();
var isRegularUser = await _authorizationService.AuthorizeRegularUserAsync();

Exemplo: Resposta Condicional por Permissão

public async Task<CadastroDto> GetCadastro(Guid cadastroId)
{
    var cadastro = await _cadastroService.GetByIdAsync(cadastroId);
    var dto = _mapper.Map<CadastroDto>(cadastro);

    var canViewSensitiveData = await _authorizationService.AuthorizeAsync(
        PlatformActions.Cadastro.Cadastros.GetDetails
    );

    if (!canViewSensitiveData)
    {
        dto.DadosBancarios = null;
        dto.DocumentosPessoais = null;
    }

    return dto;
}

Gerenciamento de Políticas

Use IAuthMiddlewareUsersProxy (registrado automaticamente por AddLaqusAuth) para gerenciar usuários e permissões via código.

Actions = Permissões granulares por recurso | Policies = Agrupamentos de actions (ex: "Admin", "Reader")

public class UserPermissionService
{
    private readonly IAuthMiddlewareUsersProxy _usersProxy;

    public UserPermissionService(IAuthMiddlewareUsersProxy usersProxy)
    {
        _usersProxy = usersProxy;
    }
}

Atribuir Políticas

using Laqus.Platform.Auth.Authorization;
using Laqus.Platform.Auth.LaqusAuthMiddleware.Proxy.Users.Dtos.Request;

// Por nome
var assignDto = new AssignUserPoliciesDto
{
    PoliciesNames = new[]
    {
        PlatformPolicies.AccountManagement.User.Admin,
        PlatformPolicies.Cadastro.CadastrosEditor
    }
};
await _usersProxy.AssignPoliciesToUserAsync(userId, assignDto);

// Por ID
var assignById = new AssignUserPoliciesDto { PoliciesIds = policyIds };
await _usersProxy.AssignPoliciesToUserAsync(userId, assignById);

// Via grupo
var assignViaGroup = new AssignUserPoliciesDto
{
    GroupId = groupId,
    PoliciesNames = new[] { PlatformPolicies.Cadastro.CadastrosReader }
};
await _usersProxy.AssignPoliciesToUserAsync(userId, assignViaGroup);

Consultar e Remover Políticas

// Consultar
var response = await _usersProxy.GetUserPoliciesAsync(userId);
if (!response.Success)
    throw new InvalidOperationException($"Falha ao buscar políticas: {response.Message}");
var policies = response.Result;

// Remover
using Laqus.Platform.Auth.LaqusAuthMiddleware.Proxy.Users.Dtos.Request;

var removeDto = new RemovePoliciesFromUserDto
{
    PoliciesNames = new[] { PlatformPolicies.Cadastro.CadastrosEditor }
};
await _usersProxy.RemovePoliciesFromUserAsync(userId, removeDto);

Gerenciamento de Status

await _usersProxy.SetUserStatusAsync(userId, active: true);
await _usersProxy.SetUserStatusAsync(userId, active: false);

Exemplo Completo — Onboarding

public class UserOnboardingService
{
    private readonly IAuthMiddlewareUsersProxy _usersProxy;
    private readonly ILogger<UserOnboardingService> _logger;

    public UserOnboardingService(
        IAuthMiddlewareUsersProxy usersProxy,
        ILogger<UserOnboardingService> logger)
    {
        _usersProxy = usersProxy;
        _logger = logger;
    }

    public async Task<Guid> CreateUserWithBasicPermissions(
        string email, string firstName, string lastName)
    {
        _logger.LogInformation("Creating user {Email}", email);

        var createResponse = await _usersProxy.CreateUserAsync(new CreateUserDto
        {
            Email = email, FirstName = firstName,
            LastName = lastName, Enabled = true
        });

        if (!createResponse.Success)
            throw new InvalidOperationException(
                $"Falha ao criar usuário: {createResponse.Message}");

        var userId = createResponse.Result.Id;

        await _usersProxy.AssignPoliciesToUserAsync(userId, new AssignUserPoliciesDto
        {
            PoliciesNames = new[]
            {
                PlatformPolicies.Cadastro.CadastrosReader,
                PlatformPolicies.Cadastro.DocumentosReader
            }
        });

        _logger.LogInformation("User {UserId} created with basic permissions", userId);
        return userId;
    }

    public async Task PromoteToEditor(Guid userId)
    {
        await _usersProxy.AssignPoliciesToUserAsync(userId, new AssignUserPoliciesDto
        {
            PoliciesNames = new[]
            {
                PlatformPolicies.Cadastro.CadastrosEditor,
                PlatformPolicies.Cadastro.DocumentosEditor
            }
        });
        _logger.LogInformation("User {UserId} promoted to editor", userId);
    }

    public async Task RevokeEditorPermissions(Guid userId)
    {
        await _usersProxy.RemovePoliciesFromUserAsync(userId, new RemovePoliciesFromUserDto
        {
            PoliciesNames = new[]
            {
                PlatformPolicies.Cadastro.CadastrosEditor,
                PlatformPolicies.Cadastro.DocumentosEditor
            }
        });
        _logger.LogInformation("Editor permissions revoked from user {UserId}", userId);
    }
}

Tratamento de Erros e Personalização

Respostas de Erro

A biblioteca retorna JSON estruturado com os códigos HTTP apropriados:

Formato da resposta:

{
  "codigo": "AUTH_REQUIRED",
  "mensagem": "Autenticação necessária",
  "detalhes": "Esta operação requer que você esteja autenticado."
}

Personalização de Mensagens

builder.Services.AddLaqusAuthorization(options =>
{
    options.ErrorMessages.AuthenticationRequired = "Autenticação necessária";
    options.ErrorMessages.AuthenticationRequiredDetails = "Você precisa estar logado para acessar este recurso.";
    options.ErrorMessages.InsufficientPermissions = "Permissão negada";
    options.ErrorMessages.ActionRequired = "Permissão insuficiente";
    options.ErrorMessages.TokenInvalid = "Token inválido";
    options.ErrorMessages.TokenInvalidDetails = "O token fornecido é inválido ou mal-formado.";
    options.ErrorMessages.TokenExpired = "Sua sessão expirou";
    options.ErrorMessages.TokenExpiredDetails = "Por favor, faça login novamente.";
});

Todas as propriedades personalizáveis:

🔐 Redis ACL (Redis 6+ / Valkey)

A partir da versão 2.8.0, a lib suporta autenticação Redis via ACL (AUTH username password).

🆕 Propriedade RedisUser

🧩 Como funciona

CacheOptions.RedisUser
        ↓
connection string: ,user=<username>
        ↓
ConfigurationOptions.Parse(...)
        ↓
ConfigurationOptions.User
        ↓
Redis/Valkey: AUTH <username> <password>

📝 Exemplo de configuração

"Cache": {
  "RedisUser": "laqus-auth",
  "RedisPassword": "my-secret",
  "RedisHost": "valkey.internal",
  "RedisPort": 6379
}

✅ Retrocompatibilidade

• RedisUser = null ou "" → comportamento idêntico ao anterior (sem user= na connection string)
• Nenhuma alteração necessária para consumidores existentes

⚠️ Pontos de Atenção

1. LRN Case-Sensitive — Use exatamente como definido em PlatformActions.
2. Decorators vs Programática — Decorators para proteção de rotas; programática para lógica condicional complexa.
3. Validação em Runtime — Ocorre no middleware, antes do controller. Sem overhead no método.
4. Cache (Redis) — Permissões são cacheadas. Configure o TTL adequado e considere-o ao validar alterações recentes.
5. Performance — AuthorizeAsync consulta cache, mas evite chamadas excessivas em loops.
6. Idempotência — Atribuir a mesma política múltiplas vezes não gera erro.
7. Transações — Operações de atribuição/remoção de políticas são individuais. Implemente compensação se necessário.
8. Permissões para gerenciar políticas — O usuário precisa de PlatformActions.AccountManagement.User.Policies.Assign e .Unassign.
9. Exception Handling — Lance exceções específicas (ForbiddenException, UnauthorizedException). Trate HttpRequestException ao comunicar com o Auth Middleware.
10. Testing — Use tokens JWT válidos ou mocke IPlatformAuthService.
11. Logging — Sempre logue operações de atribuição/remoção de permissões para auditoria.

Checklist Rápido

Autorização por Actions:

• using Laqus.Platform.Auth.Authorization; e using Laqus.Platform.Auth.Decorators;
• [RequireAction(PlatformActions...)] nos endpoints
• [IsAuthenticated] ou [IsPublic] onde aplicável

Gerenciamento de Políticas:

• Injetar IAuthMiddlewareUsersProxy
• Usar constantes de PlatformPolicies
• Tratamento de erros e logging