Autenticação e autorização

Métodos de autenticação

A Glossia oferece dois métodos de autenticação, dependendo do contexto.

Sessões no navegador

Ao entrar pela interface web, a Glossia usa autenticação baseada em sessão. A autenticação é realizada por meio de um provedor externo (GitHub ou GitLab) usando a biblioteca Assent. Após uma autenticação bem-sucedida, um cookie de sessão é definido e usado nas solicitações subsequentes.

Tokens Bearer (OAuth 2.1)

Para acessar a API, como pela CLI ou por outras ferramentas, a Glossia implementa OAuth 2.1 com o fluxo de código de autorização e PKCE. Os clientes obtêm um token Bearer e o incluem no cabeçalho Authorization:

Authorization: Bearer <access_token>

Fluxo do OAuth 2.1

1. Registro dinâmico de clientes

Os clientes se registram chamando POST /oauth/register com seus metadados. Esse processo segue a RFC 7591.

{
  "client_name": "My Tool",
  "redirect_uris": ["http://localhost:8080/callback"],
  "grant_types": ["authorization_code"]
}

O servidor retorna client_id e client_secret.

2. Solicitação de autorização

O cliente redireciona o usuário para /oauth/authorize com os parâmetros de PKCE:

GET /oauth/authorize?response_type=code&client_id=<id>&redirect_uri=<uri>&code_challenge=<challenge>&code_challenge_method=S256&state=<state>

PKCE é obrigatório para todos os clientes. Somente o método de desafio S256 é compatível.

3. Troca de tokens

Após a aprovação do usuário, o cliente troca o código de autorização por tokens em POST /oauth/token:

POST /oauth/token
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code&code=<code>&redirect_uri=<uri>&client_id=<id>&code_verifier=<verifier>

A resposta inclui um token de acesso e, opcionalmente, um token de atualização.

4. Atualização do token

Quando um token de acesso expirar, use o token de atualização:

POST /oauth/token
Content-Type: application/x-www-form-urlencoded

grant_type=refresh_token&refresh_token=<token>&client_id=<id>&client_secret=<secret>

Escopos

Os escopos controlam quais ações um token pode realizar. Eles seguem o padrão object:action.

Modelo de autorização

A Glossia aplica duas camadas à API REST e ao servidor MCP:

1. Verificação de escopo: o token de acesso deve incluir o escopo object:action necessário.
2. Política no nível do recurso: o usuário atual deve estar autorizado para o recurso específico por meio de Glossia.Policy.

Os escopos representam a capacidade máxima de um token. O sistema de políticas aplica a permissão efetiva para um recurso específico.

Funções

Permissões das funções

Endpoints de descoberta

A Glossia publica metadados em URLs padronizadas e conhecidas para que os clientes possam descobrir os endpoints automaticamente.

Metadados do servidor de autorização OAuth (RFC 8414)

GET /.well-known/oauth-authorization-server

Retorna o emissor, os endpoints, os escopos compatíveis, os tipos de concessão e os métodos de desafio de código.

Metadados do recurso protegido (RFC 9728)

GET /.well-known/oauth-protected-resource

Retorna o identificador do recurso, os servidores de autorização, os escopos compatíveis e os métodos de autenticação por token portador.

Limitação de taxa

Os endpoints OAuth têm limitação de taxa por endereço IP:

Quando o limite de taxa é atingido, o servidor retorna HTTP 429 (Muitas solicitações).