Documentação

Primeiros Passos

Authagonal fornece a cada locatário um servidor OIDC totalmente em conformidade com os padrões. Cada locatário recebe sua própria URL de emissor, documento de discovery e endpoints de token — sem infraestrutura compartilhada entre locatários. Você pode ir do zero a um fluxo de login funcionando em menos de 5 minutos.

Crie um Tenant

Cadastre-se em authagonal.io e escolha um slug para seu tenant. O slug se torna seu domínio emissor: {slug}.authagonal.io. Após criar sua conta, verifique seu endereço de e-mail para ativar o tenant.

Escolha um slug único para seu tenant durante o cadastro

Registre um Cliente

Navegue até Clientes na barra lateral do portal e clique em Criar. Insira um clientId e clientName para seu aplicativo. Em seguida, configure pelo menos uma URI de redirecionamento — é para onde os usuários são enviados após a autenticação. Por exemplo: https://app.example.com/callback.

Registre um novo cliente OAuth no portal

Seu Primeiro Login

A maneira mais rápida de integrar é com oidc-client-ts, uma biblioteca leve de cliente OIDC para aplicações JavaScript e TypeScript.

import { UserManager } from 'oidc-client-ts';

const mgr = new UserManager({
  authority: 'https://acme.authagonal.io',
  client_id: 'my-app',
  redirect_uri: 'https://app.example.com/callback',
  response_type: 'code',
  scope: 'openid profile email',
});

// Redirect to login
mgr.signinRedirect();

// On callback page
const user = await mgr.signinRedirectCallback();
console.log(user.profile); // { sub, email, name, ... }

Se você preferir uma abordagem mínima sem biblioteca, pode usar o fluxo padrão de authorization code do OAuth 2.0 com fetch simples:

// 1. Redirect the user to the authorization endpoint
const authorizeUrl = new URL('https://acme.authagonal.io/connect/authorize');
authorizeUrl.searchParams.set('client_id', 'my-app');
authorizeUrl.searchParams.set('redirect_uri', 'https://app.example.com/callback');
authorizeUrl.searchParams.set('response_type', 'code');
authorizeUrl.searchParams.set('scope', 'openid profile email');
authorizeUrl.searchParams.set('code_challenge', codeChallenge);
authorizeUrl.searchParams.set('code_challenge_method', 'S256');
window.location.href = authorizeUrl.toString();

// 2. On the callback page, exchange the code for tokens
const res = await fetch('https://acme.authagonal.io/connect/token', {
  method: 'POST',
  headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
  body: new URLSearchParams({
    grant_type: 'authorization_code',
    code: new URLSearchParams(window.location.search).get('code')!,
    redirect_uri: 'https://app.example.com/callback',
    client_id: 'my-app',
    code_verifier: codeVerifier,
  }),
});

const tokens = await res.json();
// tokens.id_token, tokens.access_token, tokens.refresh_token

A página de login padrão do seu locatário

Painel

O painel do portal oferece uma visão geral em tempo real do seu locatário. Ele apresenta as métricas mais importantes — crescimento de usuários, atividade de autenticação e navegação rápida para todos os recursos do portal.

Visão Geral

No topo do painel, você verá uma mensagem de boas-vindas junto com a contagem total atual de usuários. Abaixo, um gráfico de Usuários Ativos Diários exibe um histórico de 7 dias de usuários únicos que se autenticaram a cada dia, dando uma visão rápida das tendências de engajamento.

A tela inicial do painel com gráfico de DAU e visão geral de atividades

Métricas de Atividade

O painel de métricas de atividade exibe quatro cartões de estatísticas resumindo os principais eventos de autenticação:

• Logins Bem-sucedidos — total de fluxos de autenticação concluídos
• Logins Falhos — credenciais incorretas, contas bloqueadas ou rejeições de política
• Usuários Ativos — usuários únicos que se autenticaram no período selecionado
• Operações SCIM — eventos de provisionamento de usuários e grupos de IdPs conectados

Use os filtros de intervalo de tempo para alternar entre 24 horas, 3 dias, 7 dias e 30 dias. Todos os cartões de estatísticas e gráficos são atualizados para refletir a janela selecionada.

Métricas de atividade com intervalo de tempo configurável

Navegação Rápida

Abaixo do painel de métricas, cartões de navegação levam diretamente a cada recurso principal: Clientes, Usuários, Grupos, Funções, SSO, SCIM, Marca e Configurações. Cada cartão mostra uma breve descrição para que novos membros da equipe possam se orientar rapidamente.

Clientes

Clientes OAuth representam os aplicativos que autenticam usuários através do seu locatário. Cada cliente tem sua própria configuração de URIs de redirecionamento, escopos, tipos de concessão, tempos de vida de token e política de MFA.

Lista de Clientes

A página de Clientes exibe uma tabela de todos os clientes registrados. Cada linha mostra o clientId, nome de exibição, tipos de concessão permitidos como badges coloridos e se o PKCE está habilitado. Clique em qualquer linha para abrir o editor de configuração completo.

Lista de clientes com badges de tipo de concessão e indicadores de PKCE

Criando um Cliente

Clique em Criar Cliente para registrar um novo aplicativo. Você precisa fornecer dois campos:

• clientId — um identificador único para o cliente (ex: my-spa)
• clientName — um nome de exibição legível

Registre um novo cliente OAuth

Excluindo um Cliente

Para excluir um cliente, abra a configuração do cliente e clique no botão Excluir Cliente na parte inferior da página. Você será solicitado a confirmar antes que o cliente seja permanentemente removido. Todas as sessões ativas e tokens do cliente excluído são imediatamente invalidados.

Referência de Configuração do Cliente

Cada cliente possui um conjunto abrangente de opções de configuração organizadas em várias seções.

Configurações Gerais

URIs

Os campos de URI usam entrada por tags — digite um valor e pressione Enter ou vírgula para adicioná-lo. Clique no X de qualquer tag para removê-la.

Campos de entrada por tags para configurar URIs

Escopos e Tipos de Concessão

Tempos de Vida de Token

Configure tempos de vida de token por cliente

URIs de logout

Clientes podem registrar URIs de logout tanto back-channel quanto front-channel. Ambas são opcionais — configure as que correspondam à forma como seu aplicativo limpa sua sessão.

Política de MFA

Cada cliente pode substituir a política de MFA do tenant com uma configuração por cliente. O dropdown de política de MFA oferece três opções:

Substituição de política de MFA por cliente

SSO Empresarial

O SSO Empresarial permite que seus clientes tragam seu próprio provedor de identidade. Authagonal suporta federação SAML 2.0 e OIDC com roteamento baseado em domínio, para que os usuários sejam automaticamente direcionados ao IdP correto com base no endereço de e-mail.

Roteamento SSO baseado em domínio

Conexões SAML 2.0

Para criar uma conexão SAML, navegue até a página SSO e selecione a aba SAML. Forneça o seguinte:

Quando você salva a conexão, Authagonal busca o documento de metadados e importa o certificado de assinatura do IdP, a URL do endpoint SSO e o formato do identificador de nome. Os metadados são atualizados periodicamente para capturar rotações de certificado.

Crie uma conexão SSO SAML 2.0

Conexões OIDC

Para criar uma conexão de federação OIDC, selecione a aba OIDC e forneça:

Crie uma conexão de federação OIDC

Roteamento de Domínio

O roteamento de domínio redireciona automaticamente os usuários para o provedor de identidade correto com base no domínio de e-mail. Quando um usuário insere seu e-mail na página de login, Authagonal verifica se a parte do domínio (ex: acme.com) corresponde a alguma conexão SSO configurada. Se corresponder, o usuário é redirecionado de forma transparente para o IdP da sua organização.

O roteamento de domínio mapeia domínios de e-mail para provedores de identidade

Provisionamento JIT

Por padrão, quando um usuário faz login via SSO pela primeira vez e ainda não existe no seu locatário, Authagonal cria sua conta automaticamente (provisionamento Just-In-Time). Isso pode ser desabilitado por conexão marcando Desabilitar provisionamento JIT ao criar ou editar a conexão.

Quando o provisionamento JIT está desabilitado, apenas usuários que foram pré-provisionados — via SCIM, pela página de Usuários do portal ou pela API — podem fazer login através dessa conexão. Usuários desconhecidos recebem um erro access_denied e são orientados a contatar seu administrador.

Usuários

A página de Usuários permite gerenciar todos os usuários finais do seu locatário. Você pode buscar usuários, visualizar seus detalhes, criar novas contas e ver como cada usuário foi provisionado.

Busca e Paginação

A barra de busca suporta filtragem por endereço de e-mail ou ID de usuário. A busca tem debounce de 300ms, então os resultados são atualizados conforme você digita sem sobrecarregar a API. Os resultados são paginados em 50 usuários por página — use os controles de navegação na parte inferior da tabela para navegar entre as páginas.

Tabela de Usuários

A tabela de usuários exibe as seguintes colunas para cada usuário:

A lista de usuários com barra de busca e paginação

Criando Usuários

Clique em Criar Usuário para adicionar um novo usuário local. O formulário requer:

Crie um novo usuário local

Idioma preferido

Cada usuário tem um idioma preferido que controla tanto a sua interface hospedada quanto os e-mails transacionais que o Authagonal lhe envia (verificação, redefinição de senha, boas-vindas e mais). Você pode defini-lo ao criar um usuário e alterá-lo a qualquer momento na página de detalhes do usuário. Se um usuário não tiver um idioma preferido definido, o Authagonal recorre ao inglês. O seletor oferece todos os idiomas suportados: inglês, alemão, francês, espanhol, português, vietnamita e chinês simplificado.

Defina o idioma preferido de um usuário na página de detalhes

Detalhes do usuário

Clique em qualquer linha da lista de usuários para abrir sua página de detalhes. A partir daí você pode editar dados do perfil, gerenciar funções, redefinir MFA, revisar atributos personalizados e excluir o usuário.

Perfil

Edite e-mail, nome/sobrenome, telefone, empresa, ID externo e a flag de ativo do usuário. Alterações de e-mail devem permanecer únicas no locatário; a API retorna email_in_use se já estiver em uso.

Funções

Atribua e remova funções definidas na página Funções. A associação a funções aparece nos tokens ID e de acesso quando o cliente tem includeRolesInTokens ativado.

Autenticação multifator

Veja todas as credenciais MFA registradas para o usuário — aplicativo autenticador (TOTP), WebAuthn/passkeys e códigos de recuperação — cada um com timestamps de registro e último uso. Remova credenciais individuais ou redefina toda a MFA. Redefinir força o usuário a se registrar novamente no próximo login.

Atributos personalizados

Dados arbitrários chave/valor anexados ao usuário. As chaves devem ser únicas. Os atributos são expostos via API de perfil de usuário e SCIM, e podem ser mapeados para claims do token de acesso configurando os userClaims de um scope personalizado.

Organização

A organização à qual este usuário pertence. É um identificador seu, em texto livre, emitido como a claim org_id nos tokens do usuário e em /connect/userinfo sob o escopo profile. O Authagonal nunca deriva esse valor: ele é definido pelo seu aplicativo de provisionamento, pela credencial SCIM que criou o usuário, ou manualmente aqui.

O link ao lado do campo lista todos que compartilham esse valor, e o mesmo filtro está disponível na API como GET /api/v1/users?organizationId=. Use-o para responder quem pertence a um determinado cliente final sem paginar o diretório inteiro.

Excluir usuário

Remove permanentemente o usuário e todas as suas credenciais MFA. Digite o e-mail do usuário para confirmar — não há como desfazer.

Grupos

Grupos permitem organizar usuários e incluir membros de grupo em tokens. Grupos podem ser criados manualmente no portal ou provisionados automaticamente via SCIM a partir de um provedor de identidade externo.

Lista de Grupos

A página de Grupos mostra todos os grupos do seu locatário com as seguintes informações:

Lista de grupos com indicadores de origem

Criando um Grupo

Clique em Criar Grupo e insira um displayName para o grupo. Nomes de grupos devem ser descritivos e únicos dentro do seu locatário (ex: "Engenharia", "Admins de Faturamento", "Testadores Beta").

Detalhes do Grupo e Membros

Clique em qualquer grupo para abrir a visualização detalhada. Aqui você pode ver todos os membros atuais e gerenciar a associação:

• Adicionar membros — Insira um ID de usuário para adicionar um usuário ao grupo.
• Remover membros — Clique no botão de remover ao lado de qualquer membro para removê-lo individualmente.

Gerencie membros do grupo na visualização detalhada

Grupos em Tokens

Quando includeGroupsInTokens está habilitado em um cliente, o token de ID inclui uma claim groups contendo as associações de grupo do usuário. Cada entrada inclui o id e name do grupo:

{
  "sub": "user-123",
  "email": "[email protected]",
  "groups": [
    { "id": "grp-001", "name": "Engineering" },
    { "id": "grp-002", "name": "Beta Testers" }
  ]
}

Funções

Funções suportam controle de acesso baseado em funções (RBAC) no seu aplicativo. Defina funções no Authagonal, atribua-as a usuários e use a claim roles em tokens para aplicar autorização na lógica do seu aplicativo.

Gerenciando Funções

A página de Funções exibe uma tabela de todas as funções definidas com edição inline. Cada função possui:

Criando uma Função

Clique em Criar Função e forneça um nome e descrição. Nomes de funções devem ser concisos e seguir uma convenção de nomenclatura consistente no seu aplicativo (ex: minúsculas com hífens: billing-admin).

Edição Inline

Funções suportam edição inline diretamente na tabela. Clique no ícone de lápis em qualquer função para entrar no modo de edição — os campos de nome e descrição se tornam editáveis. Modifique os valores e clique no ícone de confirmação para salvar. As alterações entram em vigor imediatamente.

Excluindo uma Função

Clique no ícone de exclusão em qualquer função para removê-la. Você será solicitado a confirmar antes que a função seja permanentemente excluída. Remover uma função não invalida retroativamente tokens existentes — a função estará ausente dos novos tokens emitidos após a exclusão.

Edição inline de funções na tabela de funções

Funções em Tokens

Funções atribuídas a um usuário são incluídas como uma claim roles no token de ID. Seu aplicativo pode ler esta claim para tomar decisões de autorização:

{
  "sub": "user-123",
  "email": "[email protected]",
  "roles": ["admin", "billing-admin"]
}

Provisionamento SCIM

SCIM 2.0 (System for Cross-domain Identity Management) permite provisionamento automático de usuários e grupos a partir de provedores de identidade empresariais como Okta, Azure AD, OneLogin e JumpCloud. Quando configurado, contas de usuários e associações de grupos são automaticamente sincronizadas do IdP de origem para seu locatário Authagonal.

Sincronização de ciclo de vida de usuário SCIM com provisionamento em sistemas de destino

Etapas de Configuração

Siga estas etapas para habilitar o provisionamento SCIM para um cliente:

1. Selecione o aplicativo cliente — Escolha o cliente OAuth ao qual o provisionamento SCIM será associado.
2. Gere um token SCIM — Forneça uma descrição e um período de expiração em dias, depois gere o token.
3. Copie o token imediatamente — O valor bruto do token é exibido apenas uma vez. Copie-o antes de fechar o diálogo.
4. Configure seu IdP — Nas configurações SCIM do seu provedor de identidade, insira a URL base e o token bearer.
5. Teste a sincronização de usuários — Acione uma sincronização de teste do seu IdP e verifique se os usuários aparecem no portal Authagonal.

URL Base SCIM

Configure seu provedor de identidade com a seguinte URL base:

https://{slug}.authagonal.io/scim/v2

Substitua {slug} pelo slug do seu locatário.

Página de configuração SCIM com geração de token

Gerenciamento de Tokens

Tokens SCIM autenticam requisições de provisionamento do seu IdP. Você pode gerenciar múltiplos tokens por cliente:

Para revogar um token, clique no botão Revogar ao lado dele. Tokens revogados permanecem visíveis na lista para fins de auditoria, mas imediatamente param de aceitar requisições.

Gerenciamento de tokens com indicadores de tokens ativos e revogados

Testando Conectividade

Verifique se sua integração SCIM está funcionando consultando o endpoint ServiceProviderConfig:

curl -H "Authorization: Bearer YOUR_TOKEN" \
  https://acme.authagonal.io/scim/v2/ServiceProviderConfig

Uma resposta bem-sucedida retorna um documento JSON descrevendo os recursos SCIM suportados, incluindo operações em lote, filtragem e capacidade de alteração de senha.

O que uma credencial enxerga

Uma credencial SCIM só enxerga os usuários e grupos que ela mesma provisionou. Ler, atualizar ou excluir um usuário criado por outro conector responde 404, a listagem retorna apenas os próprios, e a associação de um grupo só pode nomear usuários provisionados pelo mesmo conector. Contas criadas de qualquer outra forma, por um administrador, por cadastro self-service ou por provisionamento just-in-time via SSO, são completamente invisíveis para o SCIM.

Essa fronteira é por cliente, não por token. Duas credenciais emitidas no mesmo cliente são uma única identidade com dois segredos, e cada uma pode modificar o que a outra criou. Dê um cliente a cada conector que não confie nos demais. O externalId tem o mesmo escopo, então dois conectores podem usar ext-001 para pessoas diferentes sem colidir.

Desprovisionamento

DELETE /scim/v2/Users/{id} desativa a conta e a marca como excluída. O registro é mantido, como a RFC 7644 permite, mas responde 404 a toda operação subsequente e é omitido das listagens. As inscrições de MFA e as associações a grupos do usuário são removidas, o mapeamento de externalId é liberado e todos os tokens emitidos são revogados, de modo que o acesso termina imediatamente, e não na próxima expiração de token.

Se a mesma pessoa for recontratada e recriada depois, ela recebe um novo id de usuário. Identificadores nunca são reciclados: o id é o subject de todos os tokens que você já emitiu, então reutilizá-lo daria silenciosamente ao novo contratado o histórico do titular anterior em cada aplicação que confia nele.

Marcando usuários sincronizados com uma organização

O SCIM não dá ao conector nenhuma forma de dizer qual dos seus clientes finais ele está sincronizando. O SCIM básico não define nenhum atributo de organização, então uma criação de usuário comum informa o nome e o e-mail da pessoa e nada sobre a quem ela pertence. Se vários clientes finais provisionam no seu locatário, os usuários deles chegam indistinguíveis.

Quem responde a isso é a credencial, não a requisição. Ao criar um token SCIM, defina Organização como um identificador seu. Todo usuário provisionado por esse token é marcado com ele, e a partir daí o valor é emitido como a claim org_id nos tokens desse usuário. Emita uma credencial por cliente final no mesmo cliente, e os usuários sincronizados deles saem corretamente atribuídos sem precisar de um registro de cliente para cada um. Deixe o campo em branco e os usuários ficam sem marcação, que é como toda credencial se comportava antes disso existir.

A marcação é aplicada quando o usuário é criado e nunca em uma atualização posterior, então uma sincronização incremental de rotina não consegue mover silenciosamente uma conta existente. Se você também executa um aplicativo de provisionamento, a marcação explícita da credencial prevalece: uma resposta /try só preenche uma organização que ainda está vazia.

Esquemas suportados

Implementamos os esquemas centrais User e Group do SCIM 2.0 (RFC 7643). Os atributos de usuário suportados são userName, name.givenName, name.familyName, displayName, emails, active, externalId e preferredLanguage / locale.

A extensão de usuário corporativo não é implementada, então department, manager, employeeNumber, costCenter, division e organization são aceitos e ignorados em vez de armazenados, tanto em create quanto em replace e PATCH. Entra e Okta mapeiam alguns deles por padrão, então você não precisa removê-los do seu mapeamento de atributos. Para atribuir um usuário a um dos seus clientes finais, defina a organização na credencial SCIM: o atributo corporativo organization é afirmado pelo provedor de identidade do seu cliente final e, deliberadamente, não vira o org_id dele.

Scopes OAuth

Os scopes permitem que clientes solicitem partes específicas dos dados ou permissões de um usuário. O Authagonal suporta tanto scopes padrão OIDC quanto scopes personalizados que você define para suas APIs.

Scopes integrados

Scopes personalizados

Defina seus próprios scopes na página Scopes. Cada scope descreve uma permissão ou recurso que um cliente pode solicitar (por exemplo, billing.read, orders.write).

Claims personalizados nos tokens

Claims personalizados têm duas metades. A fonte são dados por usuário: cada AuthUser tem um dicionário customAttributes que você pode preencher via Portal (Usuários → usuário → Atributos personalizados), via SCIM ou via um hook de provisionamento TCC. A liberação é por scope: a lista userClaims de cada scope nomeia as chaves permitidas a sair do servidor.

Quando um cliente solicita scopes, o Authagonal percorre os scopes concedidos, une suas listas userClaims e emite apenas essas chaves dos customAttributes do usuário. Chaves desconhecidas são silenciosamente descartadas — um cliente não pode ler um atributo adivinhando o nome. Claims OIDC padrão (sub, email, name, etc.) seguem a especificação e não estão sujeitos à lista de permissões.

# 1. On the user (Portal → Users → {user} → Custom Attributes)
department = "engineering"
employee_id = "E-1042"
seat_tier = "enterprise"

# 2. On a custom scope (Portal → Scopes → projects.read)
name        = "projects.read"
userClaims  = ["department", "seat_tier"]   # <-- whitelist

# 3. Client requests scope=openid projects.read
# Decoded access token (relevant fields only):
{
  "sub": "u-9b…",
  "scope": "openid projects.read",
  "department": "engineering",
  "seat_tier":  "enterprise"
  // employee_id is NOT emitted — it's not in the whitelist for any granted scope.
}

Atribuindo scopes a clientes

Adicione scopes permitidos na aba Clientes → Scopes e Grants. Um cliente só pode solicitar scopes que lhe foram concedidos; scopes desconhecidos são rejeitados com invalid_scope.

Marca

Personalize a aparência das páginas de login do seu tenant. As configurações de marca permitem combinar a experiência de autenticação com a identidade visual do seu produto — desde logotipos e cores até substituições avançadas de CSS.

Aparência

Configurações de aparência com visualização de cores em tempo real

Informações de Contato

Opções da Página de Login

Controle quais elementos aparecem na página de login do seu tenant:

Exemplo de página de login com marca personalizada aplicada

CSS personalizado

Para controle total sobre a aparência da página de login, forneça a URL de um arquivo CSS nas configurações de marca. O arquivo é carregado após os estilos padrão, então suas regras têm prioridade.

Modo escuro

O app de login inclui temas claro, escuro e do sistema. Os usuários escolhem em um seletor na página de login; a escolha persiste entre sessões. Quando em system, a SPA acompanha prefers-color-scheme em tempo real.

Valores claros são declarados em :root; substituições escuras ficam restritas a .dark. O branding do locatário via customCssUrl sempre prevalece — suas cores permanecem independentemente do tema do usuário.

Configurações

Configure políticas de segurança, webhooks e configurações de ambiente em todo o tenant. Estas configurações se aplicam globalmente a todos os clientes, a menos que sejam substituídas no nível do cliente.

Política de Senha

Defina os requisitos de complexidade de senha para todos os usuários do seu locatário:

Configuração de política de senha

Política de MFA

A política de MFA do tenant define o comportamento padrão de autenticação multifator. Clientes individuais podem substituir esta configuração.

Sessão e Bloqueio

Controle a duração da sessão e o comportamento de bloqueio de conta:

Configuração de sessão e bloqueio

Webhooks

Webhooks permitem reagir a eventos de autenticação em tempo real. Dois eventos (onUserAuthenticated, onTokenIssued) são aplicáveis — por padrão disparam de forma assíncrona e não bloqueiam o usuário, mas você pode ativar a aplicação por evento para que uma resposta não 2xx ou um corpo {"allow": false} rejeite a ação. Os demais eventos são notificações — sempre fire-and-forget, nunca bloqueiam.

Configurações adicionais de webhook:

Configuração de eventos de webhook

Verificar webhooks

Assim que qualquer URL de webhook é configurada, o Authagonal gera um segredo de assinatura por tenant (um valor whsec_… exibido somente leitura em Configurações → Webhooks). Cada entrega de saída traz um cabeçalho X-Authagonal-Signature: t=<unix>,v1=<hex>, onde v1 é HMAC-SHA256(secret, "{t}.{body}") calculado sobre o corpo bruto da requisição. Recalcule-o no seu endpoint e compare em tempo constante para confirmar que a requisição realmente veio do Authagonal e não foi adulterada — e rejeite entregas cujo t seja antigo demais para bloquear repetições.

import crypto from 'node:crypto';

// rawBody MUST be the exact bytes Authagonal sent — verify before any JSON re-serialization.
function verifyAuthagonalWebhook(signatureHeader, rawBody, signingSecret) {
  const parts = Object.fromEntries(signatureHeader.split(',').map((p) => p.split('=')));
  const { t, v1 } = parts;

  // Replay protection: reject deliveries older than 5 minutes.
  if (Math.abs(Date.now() / 1000 - Number(t)) > 300) return false;

  const expected = crypto
    .createHmac('sha256', signingSecret)
    .update(`${t}.${rawBody}`)
    .digest('hex');

  return v1.length === expected.length &&
    crypto.timingSafeEqual(Buffer.from(v1), Buffer.from(expected));
}

Janela de Manutenção

Defina uma janela de manutenção preferida para operações disruptivas, como rotações de certificado e atualizações de infraestrutura. Escolha uma hora UTC (0–23) — o portal também exibe o horário equivalente no seu fuso horário local por conveniência.

Cadastro e acesso

Quem pode se tornar usuário no seu locatário, e sob quais condições essa pessoa pode entrar.

Retenção de usuários inativos

Opcionalmente desative e depois exclua contas que ficaram sem uso, para que um diretório não acumule identidades dormentes para sempre. Ambos ficam desativados a menos que você os configure, e a exclusão é permanente.

Exportação de auditoria e backups remotos

Duas formas de tirar os seus dados de forma agendada, em vez de sob demanda. A exportação de auditoria envia cada dia completo de eventos de auditoria para uma URL que você indicar, assinada para que você verifique que veio de nós, servindo para alimentar um SIEM ou um arquivo de conformidade. Os backups remotos enviam cópias dos seus backups diários e semanais para um destino que você controla, sem autenticação, com autenticação básica ou com um bearer token. Ambos são configurados em Configurações e ficam sob a sua guarda, independentes dos backups que nós mantemos.

Ambiente Sandbox

O ambiente sandbox é um clone completo do seu locatário de produção, disponível em uma URL separada. Use-o para testar alterações de configuração, integrações SSO e endpoints de webhook sem afetar usuários em produção.

O sandbox está acessível em {slug}-sandbox.authagonal.io.

Controles do ambiente sandbox

Faturamento

Gerencie sua assinatura e faturamento pela página de Faturamento do portal. Esta página oferece uma visão geral do seu plano atual e fornece acesso ao portal de faturamento do Stripe para gerenciar métodos de pagamento, faturas e alterações de plano.

Informações da Assinatura

A página de faturamento exibe os detalhes da sua assinatura atual de forma resumida. Você verá um badge de status indicando o estado da sua assinatura — active, trialing, past_due, canceled ou unpaid — junto com o nome do plano, o período de faturamento atual (datas de início e fim) e se sua assinatura está configurada para cancelar no final do período atual.

Gerenciar Assinatura

Clique no botão Gerenciar Assinatura para abrir o portal de faturamento do Stripe em uma nova janela. De lá, você pode atualizar seus métodos de pagamento, visualizar e baixar faturas, alterar seu plano ou cancelar sua assinatura.

Se nenhuma assinatura existir ainda, um call-to-action Configurar Faturamento é exibido, que o guia na seleção de um plano e inserção dos dados de pagamento.

A página de faturamento exibe os detalhes da assinatura atual e fornece acesso ao Stripe

Domínios Personalizados

Sirva suas páginas de autenticação a partir do seu próprio domínio (ex: auth.seudominio.com) em vez do padrão {slug}.authagonal.io. Domínios personalizados proporcionam aos seus usuários uma experiência de autenticação contínua e com sua marca.

Adicionando um Domínio

Insira o hostname que deseja usar no formulário de adição de domínio (ex: auth.seudominio.com). Após adicionado, o domínio aparecerá na sua lista de domínios com o status pending_verification.

Verificação de DNS

Crie um registro CNAME apontando seu domínio para {slug}.authagonal.io. Quando o registro DNS estiver configurado, clique em Verificar para checar a propagação de DNS.

auth.yourdomain.com.  CNAME  acme.authagonal.io.

Certificados TLS

Quando seu domínio for verificado, você precisará de um certificado TLS para que os usuários possam se conectar com segurança via HTTPS. Authagonal suporta duas opções:

Automático (cert-manager) — Authagonal provisiona e renova certificados TLS automaticamente usando cert-manager. Esta é a opção recomendada para a maioria dos usuários. Nenhuma configuração adicional é necessária.

Traga o Seu (BYO) — Faça upload do seu próprio certificado e chave privada em formato PEM. Esta opção é útil se sua organização exige certificados de uma autoridade certificadora específica. A expiração do certificado é monitorada para que você possa renová-lo antes de expirar.

Status do Domínio

Cada domínio exibe um badge de status indicando seu estado atual: pending_verification (DNS ainda não confirmado), verified (DNS confirmado, TLS pendente), active (totalmente operacional) ou failed (problema de configuração detectado).

A lista de domínios exibe cada domínio personalizado e seu status atual

Faça upload do seu próprio certificado TLS e chave privada em formato PEM

Configuração de e-mail

Configure como seu locatário envia e-mails transacionais — verificação, redefinição de senha e notificações de MFA. Escolha entre o remetente compartilhado padrão, um domínio personalizado verificado via Resend ou seu próprio servidor SMTP.

E-mails localizados

Os e-mails transacionais são enviados no idioma preferido do destinatário. Os e-mails de verificação, redefinição de senha, conta existente, boas-vindas, cobrança e convite de administrador têm modelos em sete idiomas: inglês, alemão, francês, espanhol, português, vietnamita e chinês simplificado. Quando não existe um modelo para o idioma do destinatário, o e-mail recorre ao inglês.

O idioma é resolvido a partir da preferência armazenada do destinatário no momento do envio. Essa preferência pode vir de vários lugares:

• Cadastro e registro — capturado do idioma que o usuário escolheu nas telas de login hospedadas.
• A página de Usuários do portal — definida por um administrador ao criar ou editar um usuário.
• O provisionamento SCIM — mapeado do preferredLanguage do IdP quando os usuários são sincronizados via SSO.
• A página de conta de autoatendimento — escolhida pelo próprio usuário em /login/account.

Provedores de e-mail

Identidade do remetente

O e-mail e o nome do remetente são compartilhados entre todos os modos de provedor. O e-mail do remetente é obrigatório; o nome do remetente volta para o nome do locatário quando vazio.

Domínio personalizado Resend

Verifique seu domínio de envio com o Resend uma vez e então use-o como endereço From para este locatário. Os registros DNS TXT (SPF, DKIM) são fornecidos pela página Domínios; o Resend os valida automaticamente.

SMTP personalizado

Traga seu próprio servidor SMTP — útil para relays internos, provedores não cobertos pelo Resend ou fixação regulatória.

Domínio de envio personalizado

Ao usar o provedor Resend, você pode registrar seu próprio domínio para que os e-mails venham da sua marca (por exemplo, [email protected]) em vez de @authagonal.io.

1. Vá para Configurações → E-mail e selecione o provedor Domínio personalizado Resend.
2. Digite o nome do seu domínio e clique em Registrar.
3. Adicione os registros DNS exibidos (DKIM, SPF e return path) ao DNS do seu domínio.
4. Clique em Verificar — assim que o DNS propagar (normalmente 1–10 minutos), o status do domínio mudará para verificado.

Testes

Use o botão Enviar e-mail de teste em Configurações → E-mail para verificar sua configuração. Um e-mail de teste será enviado ao endereço de administrador usando as configurações salvas.

Registro de Auditoria

O Registro de Auditoria fornece um registro somente leitura de todas as ações administrativas realizadas no seu locatário. Cada alteração feita pelo portal ou API é capturada com contexto completo, proporcionando um rastro completo para conformidade e resolução de problemas.

Colunas do Registro

Ações Rastreadas

As seguintes ações administrativas são registradas no registro de auditoria:

O registro de auditoria fornece um registro completo de todas as ações administrativas

Backups

O Authagonal faz backup automático dos dados do seu locatário a cada hora. Os backups incluem todos os usuários, grupos, funções, clientes, conexões SSO, tokens SCIM, marca e configurações. Você pode ver o histórico de backup e baixar o backup completo mais recente na página Backups.

Como os backups funcionam

• Um backup completo é executado uma vez por dia, capturando todas as tabelas do shard de armazenamento do seu locatário.
• Backups incrementais são executados a cada hora, capturando apenas as linhas que mudaram desde o último backup.
• Os backups são armazenados no Azure Blob Storage com a mesma identidade gerenciada usada pelo seu locatário.
• Registros excluídos são rastreados via tombstones e incluídos em backups para completude de auditoria.

Baixando backups

Clique em "Baixar mais recente" para obter um arquivo ZIP contendo o backup completo mais recente mesclado com todos os backups incrementais subsequentes. Cada tabela é exportada como um arquivo JSONL (um objeto JSON por linha).

Apps de Provisionamento

Os apps de provisionamento são serviços seus, chamados pelo Authagonal sempre que um usuário é criado, para que possam configurar uma conta, atribuir uma licença, decidir a qual organização o usuário pertence ou recusar o cadastro por completo.

Como Funciona

Quando um usuário é criado, o Authagonal chama a URL de callback do seu app de provisionamento usando o padrão TCC (Try/Confirm/Cancel). Todos os apps precisam aceitar na fase Try antes que qualquer um deles seja confirmado, de modo que vários sistemas downstream possam concordar, ou um possa vetar, sem deixar para trás contas criadas pela metade.

Quando o provisionamento é executado

O provisionamento é executado em todo caminho que cria um usuário, não apenas no cadastro self-service. Combinações de app e usuário já provisionadas são ignoradas, então um app vê cada usuário uma única vez.

A requisição Try

O Authagonal envia este JSON por POST para <code>{callbackUrl}/try</code>. Campos sem valor são omitidos em vez de enviados como null.

Um usuário que chega por SSO é o caso comum que vale a pena prever: ele ainda não tem organização, e federated_connection informa de qual dos seus clientes ele veio.

{
  "transactionId": "8f14e45fceea167a5a36dedd4bea2543",
  "userId": "0f6b1c8e-3d2a-4f51-9e77-2c1a4b5d6e7f",
  "email": "[email protected]",
  "firstName": "Ada",
  "lastName": "Lovelace",
  "customAttributes": {
    "federated_connection": "acme-okta"
  }
}

A resposta Try

Seu app responde com 200 e um corpo JSON. O corpo não é apenas uma confirmação de recebimento: é assim que um app downstream atribui a organização e os atributos que acabam nos tokens do usuário.

{
  "approved": true,
  "organizationId": "org_acme",
  "customAttributes": { "org_role": "member" }
}

Marcando usuários com a organização certa

Decida a organização aqui, em um único lugar, em vez de em cada caminho de criação. Um usuário SSO carrega federated_connection, que identifica a conexão que o autenticou e, portanto, o cliente, e continua correto quando um mesmo cliente federa vários domínios de e-mail. Um usuário convidado não tem conexão, então identifique-o pelo convite que você emitiu. Os dois caminhos chegam a /try antes de o usuário existir, então uma única lógica cobre ambos e não há duas regras para divergirem.

// POST {callbackUrl}/try
app.post('/provisioning/try', async (req, res) => {
  const { email, customAttributes } = req.body;

  // An SSO user carries the connection that vouched for them. That is the
  // customer, and it stays right when one customer has several domains.
  const connection = customAttributes?.federated_connection;

  const org = connection
    ? await orgByConnection(connection)
    : await orgByPendingInvite(email);

  if (!org) return res.json({ approved: false, reason: 'No organization for this user' });

  // Stamped on the user and emitted as org_id on every token from now on.
  res.json({ approved: true, organizationId: org.id });
});

Adicionando um App de Provisionamento

Para adicionar um app de provisionamento, forneça um nome, uma URL de callback e uma chave de API opcional. A chave de API é enviada como token Bearer no cabeçalho Authorization de cada requisição de webhook, permitindo que seu app autentique requisições do Authagonal.

Testes

Clique em Testar ao lado de qualquer app de provisionamento para enviar uma requisição de teste à sua URL de callback. Os resultados do teste exibem o código de status HTTP e o corpo da resposta, ajudando você a verificar se seu app está recebendo e processando webhooks corretamente.

Teste apps de provisionamento para verificar a entrega e o tratamento de resposta de webhooks

Limites do Plano

O número máximo de apps de provisionamento é configurável por locatário, com um limite padrão de 6. Este limite pode ser ajustado por um administrador se seu fluxo de trabalho exigir alvos de provisionamento adicionais.

Equipe

A página de Equipe gerencia os administradores do portal — as pessoas que podem acessar e configurar seu locatário através do portal de gerenciamento. Todos os membros da equipe têm acesso administrativo completo a todos os aspectos da configuração do seu locatário.

Lista de Administradores

A lista de administradores exibe o nome, endereço de e-mail e data de adição de cada membro da equipe. Um indicador "Você" é exibido ao lado da linha do usuário atual para que você possa identificar facilmente sua própria conta.

Convidando Administradores

Para convidar um novo membro da equipe, forneça o endereço de e-mail, nome e uma senha temporária (mínimo de 8 caracteres). O usuário convidado faz login com a senha temporária e deve alterá-la no primeiro acesso.

Campos do convite

Convites de administrador criam um usuário totalmente provisionado — sem ida e volta de e-mail.

Removendo Administradores

Clique em Remover ao lado de qualquer membro da equipe para revogar seu acesso. Um diálogo de confirmação é exibido antes que a remoção seja finalizada. Você não pode remover a si mesmo — deve haver sempre pelo menos um administrador na equipe.

Gerencie administradores do portal na página de Equipe

Suporte

Abra um ticket de suporte com a equipe Authagonal sem sair do portal. Cada ticket é uma conversa encadeada, então você e nossa equipe ficam alinhados desde o primeiro relato até a resolução.

Seus tickets

A página de suporte lista todos os tickets que você abriu, com a atividade mais recente primeiro. Use o badge de status para ver rapidamente o que está aguardando você e o que está aguardando a gente.

Seus tickets de suporte com assunto, status, prioridade e última atividade

• Cada linha mostra o assunto, o status atual (aberto, pendente, resolvido ou fechado), a prioridade e o horário da última atividade.
• Clique em Novo ticket para abrir um e, em seguida, dê a ele um assunto, uma prioridade e sua primeira mensagem.
• Badges de status com cores facilitam varrer a lista em busca de tickets que precisam da sua atenção.

Uma conversa de ticket

Ao abrir um ticket, você vê a conversa completa. As respostas aparecem em ordem e novas mensagens da nossa equipe surgem sem recarregar a página.

Uma conversa de ticket entre você e a equipe Authagonal

• As mensagens encadeadas entre você e a equipe Authagonal são exibidas em ordem cronológica.
• Responda ali mesmo e anexe arquivos para compartilhar logs, capturas de tela ou configuração.
• A conversa é atualizada ao vivo, então uma resposta da nossa equipe aparece assim que é enviada.
• Se você responder ao e-mail de notificação em vez disso, sua mensagem é encadeada automaticamente.

Central de suporte para os seus usuários

Separada do suporte que você recebe de nós, o Authagonal pode operar uma central de suporte para os seus usuários finais. Eles abrem tickets a partir das páginas de conta, no host com a marca do seu próprio locatário, e a sua equipe responde pelo portal.

Ela existe porque as pessoas que não conseguem entrar são exatamente as pessoas que não conseguem chegar a uma ferramenta de suporte que exige entrar. A central fica ao lado das telas de login, então um usuário bloqueado ainda tem um caminho, e todo ticket chega já vinculado a uma conta real do seu diretório, e não a um endereço qualquer que alguém digitou.

Como ativar

Abra Configurações no portal e ative o portal de suporte. Nada fica visível para os seus usuários até que você faça isso.

O que os seus usuários veem

Usuários autenticados têm uma área de suporte nas páginas de conta, no host do seu locatário, com a sua marca. Eles podem abrir um ticket, ver tudo o que já abriram e responder dentro da conversa. As respostas da sua equipe também chegam por e-mail, então o usuário não precisa ficar conferindo.

Com os tickets anônimos ativados, alguém que não consegue entrar ainda pode abrir um. A pessoa informa um endereço de e-mail e a mensagem, e recebe de volta um link privado para a conversa. Esse link é a única forma de entrar, então trate-o como uma credencial: ele é impossível de adivinhar, e qualquer pessoa que o tenha pode ler e responder aquela conversa.

A caixa de entrada dos operadores

A sua equipe responde pela Caixa de entrada de suporte no portal. É um lugar separado dos seus próprios tickets conosco, e está disponível para a função tenant:support e superiores, então você pode dar a um agente acesso à central sem lhe dar o resto do portal.

Os usuários escrevem no próprio idioma

Um ticket é armazenado no idioma em que o usuário o escreveu, e cada pessoa na conversa o lê no dela. O seu agente vê a mensagem traduzida para o idioma do portal dele, o usuário vê a sua resposta traduzida para o idioma dele, e o texto original é sempre mantido ao lado. O idioma é detectado a partir da primeira mensagem e fixado no ticket. As traduções são calculadas uma vez por idioma e reaproveitadas, então uma conversa longa não se traduz de novo.

Fusos horários

Um ticket registra o fuso horário a partir do qual o usuário o abriu. Cada mensagem passa a mostrar o horário local dele ao lado do seu, então uma resposta às 14:32 aparece como as 02:32 que ela realmente eram para quem estava esperando. Nada é mostrado quando o fuso é desconhecido, como em um ticket que chegou por e-mail, ou quando ele coincide com o seu.

Webhooks

Defina uma URL de webhook de suporte para receber os eventos de ticket conforme eles acontecem, seja para disparar um alerta ou para espelhar tickets no seu próprio sistema. Os payloads são assinados, então você pode verificar que vieram de nós.

Importar e migrar

Migre um sistema de identidade existente para o seu locatário Authagonal. Duas fontes são suportadas — Duende IdentityServer (um banco de dados SQL Server) e Auth0 (a Management API). Cada uma executa uma prévia somente leitura para que você revise exatamente o que será copiado antes de confirmar.

Importação do Duende IdentityServer

Migre clientes, scopes, usuários e papéis de um banco SQL Server do Duende IdentityServer existente para o seu locatário Authagonal. A importação roda em duas fases — prévia e commit — para que você revise o que será copiado antes de qualquer alteração.

O que é importado

O importador lê o ConfigurationDb do Duende e as tabelas do ASP.NET Identity e grava as linhas mapeadas no seu locatário. Artefatos de curta duração como persisted grants, device codes e chaves de assinatura são ignorados.

Prévia antes do commit

Cole sua string de conexão do ConfigurationDb / IdentityDb do Duende e clique em Executar prévia. A prévia abre uma conexão somente-leitura e conta cada linha que seria importada — nenhuma gravação ocorre.

• Contagens de entidades para clientes, scopes, usuários, papéis e atribuições de papéis.
• Avisos de substituição quando o locatário de destino já tem clientes, papéis ou scopes correspondentes.
• Avisos para tabelas desconhecidas e colunas não mapeadas para que você saiba o que será descartado.

Painel de prévia com contagens e avisos

Hashes de senha

O Duende armazena senhas em ASP.NET Identity V3 (PBKDF2). O PasswordHasher do Authagonal verifica esse formato diretamente e re-hasheia para o formato nativo no primeiro login bem-sucedido — os usuários mantêm suas senhas existentes sem fluxo de redefinição.

Reconciliação de ID de usuário

Se um usuário já existente neste locatário tiver o mesmo e-mail de um registro recebido, a importação gira o userId dessa conta para o sub de origem antes de importar, de modo que as funções, logins e claims importados se anexem à conta existente e os aplicativos que já referenciam o usuário pelo seu sub de origem continuem a resolver após o cutover. A senha e o perfil existentes da conta são preservados; as funções de origem são mescladas por cima. A prévia lista todas as contas que serão reconciliadas antes de você confirmar.

Executando a importação

Clique em Iniciar importação após revisar a prévia. A fase de commit grava clientes, scopes, usuários, papéis e referências de login externo nos stores do locatário. Linhas duplicadas de clientId, scope name, email e role name são ignoradas — o importador é seguro para re-executar.

O que não é importado

• Persisted grants, device codes, sessões server-side — curta duração, regenerados automaticamente.
• Chaves de assinatura — o Authagonal emite suas próprias chaves por tenant.
• Colunas e tabelas personalizadas — qualquer coisa fora do schema padrão do Duende é sinalizada como aviso para você saber que esses dados foram descartados.
• Clientes desativados — importados desativados; reative-os na página Clientes quando estiver pronto.

Importar do Auth0

Conecte a Authagonal à Management API do seu locatário Auth0 e traga suas aplicações, APIs, papéis, usuários e conexões corporativas. Os IDs de usuário e de aplicação importados são preservados, então as referências existentes de sub e client_id continuam resolvendo após o corte.

O que você vai precisar

Crie uma aplicação Machine-to-Machine no Auth0 autorizada para a Management API, com estes scopes de leitura: read:users, read:clients, read:resource_servers, read:roles, read:connections, read:client_grants. Cole o domínio, o client ID e o client secret dela no formulário de importação — eles são usados apenas para a importação.

O que é importado

Senhas

A Management API do Auth0 nunca retorna hashes de senha. Se você tiver a exportação em massa de senhas assistida pelo suporte do Auth0 (NDJSON), forneça-a — os hashes bcrypt são importados na íntegra e seus usuários mantêm as senhas sem redefinição. Esse arquivo também traz o conjunto completo de usuários, removendo o limite de 1.000 usuários da listagem da API do Auth0. Sem ele, os usuários são importados como perfis e definem uma nova senha no primeiro login.

Referência da API

Cada locatário expõe um servidor OIDC em conformidade com os padrões em https://{slug}.authagonal.io. Todos os endpoints seguem as especificações OAuth 2.0 e OpenID Connect. Esta referência cobre todos os endpoints com os quais sua aplicação pode precisar interagir.

Fluxo de Authorization Code com PKCE

OIDC Discovery & JWKS

O documento de discovery permite que bibliotecas de cliente OIDC se configurem automaticamente. Nenhuma autenticação é necessária para nenhum dos endpoints.

GET /.well-known/openid-configuration

Retorna o documento de Configuração do Provedor OpenID. A resposta inclui todos os metadados que seu cliente precisa para interagir com este locatário.

GET /.well-known/openid-configuration/jwks

Retorna o JSON Web Key Set usado para verificar assinaturas de tokens. A resposta contém um array keys com chaves públicas RSA, cada uma incluindo os campos kty, use, kid, alg, n e e.

curl https://acme.authagonal.io/.well-known/openid-configuration

Endpoint de Autorização

GET /connect/authorize

Inicia um fluxo de authorization code. O usuário deve ter uma sessão ativa ou será redirecionado para a página de login. Em caso de sucesso, o usuário é redirecionado de volta para sua aplicação com um authorization code.

Resposta de sucesso: Redirecionamento 302 para redirect_uri com parâmetros de query code e state.

Resposta de erro: Redirecionamento 302 com parâmetros de query error, error_description e state.

Pushed Authorization Requests (PAR)

RFC 9126. Em vez de colocar todos os parâmetros de autorização na URL, seu cliente os envia por POST para /connect/par com autenticação de cliente normal e recebe de volta uma request_uri opaca e de curta duração. O navegador então visita /connect/authorize?client_id=...&request_uri=... — nada mais entra no histórico do navegador, logs do servidor ou cabeçalhos Referer, e o servidor já verificou a integridade dos parâmetros sob autenticação do cliente.

POST /connect/par

A autenticação do cliente é a mesma de /connect/token: HTTP Basic com client_id/client_secret ou credenciais codificadas no formulário. Clientes públicos publicam sem segredo. O corpo carrega os mesmos parâmetros que você enviaria normalmente para /connect/authorize; o próprio request_uri é rejeitado (encadear um PAR é proibido pelo §2.1 da especificação). Retorna 201 Created.

Resposta

Na chamada seguinte GET /connect/authorize?client_id=…&request_uri=…, todos os outros parâmetros são puxados do payload enviado e quaisquer parâmetros de query extras são ignorados. O client_id na chamada de autorização deve corresponder ao cliente que enviou a solicitação. Uma vez consumida (ou após expires_in), a request_uri é removida do armazenamento.

# 1. Push parameters (server returns request_uri + expires_in)
curl -X POST https://acme.authagonal.io/connect/par \
  -u "my-app:CLIENT_SECRET" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "response_type=code" \
  -d "redirect_uri=https://app.example.com/callback" \
  -d "scope=openid profile email" \
  -d "state=$(openssl rand -hex 16)" \
  -d "code_challenge=YOUR_CODE_CHALLENGE" \
  -d "code_challenge_method=S256"

# 2. Send the user to /authorize with only client_id + request_uri
# https://acme.authagonal.io/connect/authorize?client_id=my-app&request_uri=urn:ietf:params:oauth:request_uri:abc123...

Endpoint de Token

POST /connect/token

Troca credenciais por tokens. As requisições devem usar Content-Type: application/x-www-form-urlencoded. A autenticação do cliente pode ser fornecida via HTTP Basic auth (Authorization: Basic base64(client_id:client_secret)) ou como parâmetros no corpo do formulário (client_id + client_secret).

Concessão de Authorization Code

Concessão de Refresh Token

Concessão de Client Credentials

Concessão de Device Code

Resposta do token:

curl -X POST https://acme.authagonal.io/connect/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=authorization_code" \
  -d "code=AUTHORIZATION_CODE" \
  -d "redirect_uri=https://app.example.com/callback" \
  -d "client_id=my-app" \
  -d "code_verifier=YOUR_CODE_VERIFIER"

Endpoint UserInfo

GET /connect/userinfo

Retorna claims sobre o usuário autenticado. Requer um access token válido com o escopo openid.

curl https://acme.authagonal.io/connect/userinfo \
  -H "Authorization: Bearer ACCESS_TOKEN"

Token Introspection (RFC 7662)

POST /connect/introspect

Valida um token e retorna seus metadados. Requer credenciais de cliente (Basic auth ou parâmetros no corpo do formulário).

Resposta de token ativo:

Resposta de token inativo: { "active": false }

curl -X POST https://acme.authagonal.io/connect/introspect \
  -u "my-app:CLIENT_SECRET" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "token=ACCESS_OR_REFRESH_TOKEN"

Revogação de Token (RFC 7009)

POST /connect/revocation

Revoga um token emitido anteriormente. Requer credenciais de cliente.

O endpoint sempre retorna 200 OK, mesmo para tokens inválidos ou já revogados, conforme a especificação RFC 7009.

Autorização de Dispositivo (RFC 8628)

POST /connect/deviceauthorization

Inicia o fluxo de autorização de dispositivo para dispositivos com restrição de entrada (CLIs, smart TVs, dispositivos IoT). O dispositivo exibe um código para o usuário, que então aprova a requisição em um dispositivo separado com navegador.

Resposta:

Fluxo de aprovação: O usuário visita a verification_uri, insere o user_code e aprova a requisição. Enquanto isso, o dispositivo faz polling no endpoint de token com o device_code.

Códigos de erro de polling:

curl -X POST https://acme.authagonal.io/connect/deviceauthorization \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "client_id=my-cli" \
  -d "scope=openid profile email"

Encerrar Sessão / Logout

GET POST /connect/endsession

Encerra a sessão do usuário atual, aciona o logout por back-channel para todos os clientes com um BackChannelLogoutUri registrado e revoga todas as concessões.

Se um post_logout_redirect_uri válido for fornecido e corresponder a uma URI registrada, o usuário recebe um redirecionamento 302. Caso contrário, uma resposta JSON confirma que a sessão foi encerrada.

Referência da API SCIM 2.0

Authagonal suporta o protocolo SCIM 2.0 para provisionamento automatizado de usuários e grupos. Provedores de identidade como Okta, Azure AD e OneLogin podem usar esta API para manter seu locatário Authagonal sincronizado com seu diretório corporativo.

URL Base: https://{slug}.authagonal.io/scim/v2

Autenticação: Todas as requisições requerem um token Bearer. Gere um token SCIM no portal em Configurações > Provisionamento SCIM.

Cabeçalhos comuns:

Endpoints de listagem suportam paginação via parâmetros de query startIndex (base 1) e count (máx. 200), e filtragem via o parâmetro filter (ex: userName eq "[email protected]").

Usuários

GET /scim/v2/Users — Lista usuários com paginação e filtragem opcionais.

GET /scim/v2/Users/{id} — Obtém um único usuário pelo ID de usuário Authagonal.

POST /scim/v2/Users — Cria um novo usuário. Retorna 201 Created.

PUT /scim/v2/Users/{id} — Substituição completa de um recurso de usuário. Todos os campos devem ser fornecidos.

PATCH /scim/v2/Users/{id} — Atualização parcial usando SCIM PatchOp.

DELETE /scim/v2/Users/{id} — Exclui suavemente o usuário (desativa a conta e revoga todos os tokens). Retorna 204 No Content.

curl -X POST https://acme.authagonal.io/scim/v2/Users \
  -H "Authorization: Bearer SCIM_TOKEN" \
  -H "Content-Type: application/scim+json" \
  -d '{
    "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"],
    "userName": "[email protected]",
    "name": {
      "givenName": "Jane",
      "familyName": "Smith"
    },
    "displayName": "Jane Smith",
    "active": true,
    "externalId": "ext-12345"
  }'

Grupos

GET /scim/v2/Groups — Lista todos os grupos com paginação e filtragem opcionais.

GET /scim/v2/Groups/{id} — Obtém um único grupo por ID, incluindo sua lista de membros.

POST /scim/v2/Groups — Cria um novo grupo. Retorna 201 Created.

PUT /scim/v2/Groups/{id} — Substituição completa de um recurso de grupo (incluindo sua lista de membros).

PATCH /scim/v2/Groups/{id} — Atualização parcial para adicionar ou remover membros do grupo.

DELETE /scim/v2/Groups/{id} — Exclui permanentemente o grupo. Retorna 204 No Content.

curl -X PATCH https://acme.authagonal.io/scim/v2/Groups/GROUP_ID \
  -H "Authorization: Bearer SCIM_TOKEN" \
  -H "Content-Type: application/scim+json" \
  -d '{
    "schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"],
    "Operations": [
      {
        "op": "add",
        "path": "members",
        "value": [
          { "value": "USER_ID_1" },
          { "value": "USER_ID_2" }
        ]
      }
    ]
  }'

Portal API (automação)

A Portal API permite que o seu próprio backend automatize tudo o que pode fazer no portal — gerir usuários, clients, grupos, funções, escopos, conexões SSO e configurações — usando uma credencial máquina-a-máquina. É a mesma API que a interface do portal chama.

URL Base: https://portal-api.<your-domain>/api/v1. As requisições autenticam-se com um token de acesso Bearer; o locatário é obtido a partir do token, não do URL.

Criando uma credencial de API

No portal, abra Clients → Create API credential, escolha um nível de acesso e dê-lhe um nome. O Authagonal gera um client OAuth client_credentials configurado para a Portal API e retorna um client ID e um secret.

Níveis de acesso

Obtendo um token

Troque a credencial por um token de acesso no endpoint de token do seu tenant de administração — https://<your-tenant>.<your-domain>/connect/token — e depois envie o token como cabeçalho Bearer para a Portal API. Os tokens são válidos por uma hora.

# 1. Exchange the credential for an access token (your tenant's token endpoint)
curl -X POST https://acme.authagonal.io/connect/token \
  -d grant_type=client_credentials \
  -d client_id=api-3f2a... \
  -d client_secret=YOUR_CLIENT_SECRET \
  -d scope=tenant:admin

# Response: { "access_token": "ey...", "token_type": "Bearer", "expires_in": 3600 }

# 2. Call the Portal API with the access token
curl https://portal-api.authagonal.io/api/v1/users \
  -H "Authorization: Bearer $ACCESS_TOKEN"

Endpoints

Todos os caminhos são relativos à URL base e exigem um token de acesso Bearer. O escopo ao lado de cada grupo é o nível de acesso mínimo que a credencial precisa. Os endpoints de listagem aceitam os parâmetros de consulta startIndex e count.

GET/api/v1/clients— Listar clientes OAuth.

GET/api/v1/clients/{id}— Obter um único cliente por ID.

POST/api/v1/clients— Criar um cliente. Retorna o ID do cliente e, para clientes confidenciais, um segredo de uso único.

PUT/api/v1/clients/{id}— Atualizar um cliente (URIs de redirecionamento, tipos de concessão, tempos de vida de token, requisitos PKCE/PAR).

DELETE/api/v1/clients/{id}— Excluir um cliente.

POST/api/v1/clients/api-credential— Gerar uma credencial de API do Portal máquina a máquina.

GET/api/v1/users— Listar usuários. Suporta count, search (prefixo de e-mail ou nome), organizationId para filtrar por uma organização e after para paginação por cursor.

GET/api/v1/users/count— Número total de usuários do inquilino.

GET/api/v1/users/stats/mfa— Estatísticas de inscrição em MFA.

GET/api/v1/users/{id}— Obter um único usuário.

POST/api/v1/users— Criar um usuário com e-mail e senha.

PUT/api/v1/users/{id}— Atualizar um usuário (perfil, e-mail, estado ativado/bloqueado, organizationId).

DELETE/api/v1/users/{id}— Excluir um usuário.

GET/api/v1/users/{id}/mfa— Get a user's enrolled MFA methods.

DELETE/api/v1/users/{id}/mfa— Reset a user's MFA enrollment.

GET/api/v1/roles— Listar funções.

POST/api/v1/roles— Criar uma função.

DELETE/api/v1/roles/{id}— Excluir uma função.

POST/api/v1/roles/assign— Atribuir uma função a um usuário.

POST/api/v1/roles/unassign— Remover uma função de um usuário.

GET/api/v1/groups— Listar grupos.

GET/api/v1/groups/{id}— Obter um grupo com seus membros.

POST/api/v1/groups— Criar um grupo.

POST/api/v1/groups/{id}/members— Adicionar membros a um grupo.

DELETE/api/v1/groups/{groupId}/members/{userId}— Remover um membro de um grupo.

DELETE/api/v1/groups/{id}— Excluir um grupo.

GET/api/v1/group-role-mappings— Listar os mapeamentos de grupo para função (funções concedidas na emissão do token conforme a associação ao grupo).

GET/api/v1/scopes— Listar escopos de API.

POST/api/v1/scopes— Criar um escopo.

DELETE/api/v1/scopes/{name}— Excluir um escopo.

GET/api/v1/saml/connections— Listar conexões SAML.

POST/api/v1/saml/connections— Criar uma conexão SAML.

DELETE/api/v1/saml/connections/{id}— Excluir uma conexão SAML.

GET/api/v1/oidc/connections— Listar conexões OIDC.

POST/api/v1/oidc/connections— Criar uma conexão OIDC.

DELETE/api/v1/oidc/connections/{id}— Excluir uma conexão OIDC.

GET/api/v1/sso/domains— Listar os domínios roteados para conexões SSO (descoberta de home-realm).

GET/api/v1/branding— Obter a personalização do inquilino (cores, logotipo, idiomas suportados).

PUT/api/v1/branding— Atualizar a personalização do inquilino.

GET/api/v1/settings— Obter as configurações do inquilino (webhooks, cadastro público, política de tokens).

PUT/api/v1/settings— Atualizar as configurações do inquilino.

POST/api/v1/settings/webhook-secret/regenerate— Rotacionar o segredo de assinatura do webhook.

POST/api/v1/settings/test-email— Enviar um e-mail de teste com a configuração de e-mail atual.

GET/api/v1/custom-domains— Listar domínios de login personalizados e seu status de verificação.

POST/api/v1/custom-domains— Adicionar um domínio personalizado.

POST/api/v1/custom-domains/{domain}/verify— Disparar a verificação de DNS de um domínio personalizado.

DELETE/api/v1/custom-domains/{domain}— Remover um domínio personalizado.

GET/api/v1/email/domains— Listar domínios de e-mail do remetente.

GET/api/v1/audit— Consultar o registro de auditoria do inquilino.

Exemplo: criar um usuário

curl -X POST https://portal-api.authagonal.io/api/v1/users \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]",
    "password": "S3cure-temp-passw0rd",
    "firstName": "Ada",
    "lastName": "Lovelace"
  }'

# 200 OK
# { "userId": "8f3a...", "email": "[email protected]" }

Telas de Login

Estas são as telas hospedadas que seus usuários finais veem no servidor de auth do seu tenant. A Authagonal entrega todas as telas prontas para uso, então você ganha uma experiência de login completa e segura sem construir nenhuma interface. Esta página percorre cada tela e mostra quais configurações do portal a controlam.

Entrar

• Fluxo em duas etapas, e-mail primeiro: o usuário digita o e-mail e clica em Continuar, então o campo de senha aparece.
• Botões de single sign-on "Continuar com {provider}" aparecem automaticamente quando há conexões SSO.
• Links de esqueci a senha e criar conta, cada um podendo ser exibido ou ocultado.
• Captcha opcional Cloudflare Turnstile para deter tentativas de login automatizadas.

Controlado no admin do portal

• Marca define o logotipo, a cor, o nome do aplicativo, o e-mail de suporte e o CSS personalizado.
• Exiba ou oculte os links de esqueci a senha e cadastro (Marca).
• Conexões SSO adicionam os botões de login social (página de SSO).
• Tempo de vida da sessão e limites de bloqueio (Configurações → Segurança).

Cadastro

• Coleta nome e sobrenome (opcional), e-mail e uma senha.
• Uma checklist de política de senha ao vivo é atualizada conforme o usuário digita, deixando os requisitos claros antes do envio.
• Captcha opcional Cloudflare Turnstile.
• Um link "Entrar" para usuários que já têm uma conta.

Controlado no admin do portal

• Exiba ou oculte o link de cadastro (Marca).
• A política de senha do seu tenant orienta a checklist.
• Marca estiliza a tela inteira.

Esqueci a senha

• O usuário digita o e-mail e então vê uma confirmação neutra de "verifique seu e-mail".
• A tela nunca revela se uma conta existe, o que frustra a sondagem por enumeração de contas.
• Um link "Voltar para entrar" leva o usuário de volta à tela de login.

Controlado no admin do portal

• Exiba ou oculte o link de esqueci a senha (Marca).
• A entrega de e-mail do seu tenant envia a mensagem de redefinição.
• Marca estiliza a tela inteira.

Redefinir senha

• Campos de nova senha e confirmar senha com uma checklist de requisitos ao vivo, regra por regra.
• Um estado claro de link inválido ou expirado quando o token de redefinição não é mais válido.
• Um estado de sucesso confirmando que a senha foi alterada.

Controlado no admin do portal

• A política de senha do seu tenant orienta a checklist.
• Marca estiliza a tela inteira.

Desafio de MFA

• Um seletor de método entre app autenticador, passkey e código de recuperação.
• Um campo TOTP de 6 dígitos que é enviado automaticamente assim que todos os dígitos são inseridos.
• Entrada de código de recuperação para usuários que perderam o acesso ao seu autenticador.
• Um botão de passkey para verificação baseada em hardware.

Controlado no admin do portal

• A política de MFA é definida por aplicação (Clientes → Segurança).
• Qualquer usuário com um fator cadastrado é sempre desafiado, independentemente da política.

Configuração de MFA

• Mostra o status dos métodos cadastrados para que o usuário saiba o que já está configurado.
• Configuração do autenticador via QR code, com chave manual como alternativa e uma etapa de confirmação.
• Cadastro de passkey para autenticação baseada em hardware.
• Geração de códigos de recuperação para recuperação de conta.
• Um pular opcional quando o MFA é por autoatendimento em vez de obrigatório.

Controlado no admin do portal

• A política de MFA é definida por aplicação; Obrigatório força a configuração no login (Clientes → Segurança).
• Marca estiliza a tela inteira.

Autorização de dispositivo

• Um campo centralizado de entrada do código do usuário para o código exibido no dispositivo.
• Uma etapa de aprovação para autorizar o dispositivo.
• Uma tela intermediária de login quando o usuário ainda não está autenticado.
• Uma confirmação de aprovação depois que o dispositivo é autorizado.

Controlado no admin do portal

• Habilite a concessão device-code na aplicação (Clientes → Tipos de concessão).
• Defina o tempo de vida do device-code (Clientes → Tokens).

Consentimento

• Mostra o logotipo e o nome do cliente solicitante.
• Uma lista por escopo com rótulos amigáveis e legíveis para cada permissão.
• Botões Permitir e Negar para conceder ou recusar acesso.
• Um rodapé com dica de consentimento explicando o que a decisão significa.

Controlado no admin do portal

• Ative Exigir consentimento por aplicação (Clientes → Segurança).
• O logotipo, o nome e a URL vêm dos próprios metadados da aplicação.
• Marca pinta o cartão de consentimento.

Apps conectados (concessões)

• Lista todos os apps que o usuário autorizou, com seu nome, escopos e data de concessão.
• Revogue o acesso de um app, com uma etapa de confirmação antes de entrar em vigor.
• Um estado vazio amigável quando o usuário não autorizou nenhum app.

Controlado no admin do portal

• A lista é preenchida pelas aplicações que exigem consentimento.
• Marca estiliza a tela inteira.

Conta

Uma página de conta de autoatendimento hospedada em /login/account onde os usuários autenticados gerenciam o próprio perfil e idioma preferido, sem precisar de acesso ao portal.

• Editar nome e sobrenome, empresa e telefone; o endereço de e-mail é exibido somente leitura.
• Escolher um idioma preferido entre os idiomas suportados; a interface mostra a prévia da escolha instantaneamente e a mantém ao salvar.
• O idioma salvo controla a interface hospedada do usuário e o idioma dos e-mails transacionais que ele recebe.

Controlado no admin do portal

• Branding estiliza toda a tela.
• O mesmo idioma preferido pode ser editado por um administrador na página de Usuários do portal.

Fluxos de Autenticação

Os fluxos de autenticação cobrem como os usuários finais interagem com seu locatário Authagonal — fazendo login, se cadastrando, redefinindo senhas e configurando MFA. Esses endpoints são usados pela página de login hospedada e podem ser chamados diretamente se você estiver construindo uma UI de login personalizada.

Login

POST /api/auth/login

Autentica um usuário com e-mail e senha. Em caso de sucesso, assina um cookie de sessão e retorna o perfil do usuário. Se o MFA estiver configurado, a resposta indica que um segundo fator é necessário antes que a sessão seja totalmente estabelecida.

Corpo da requisição:

{
  "email": "[email protected]",
  "password": "correct-horse-battery-staple"
}

Resposta de sucesso:

Resposta de MFA obrigatório: Quando o usuário tem MFA inscrito, a resposta inclui mfaRequired: true junto com um challengeId e um array methods listando os métodos MFA disponíveis.

Resposta de configuração de MFA obrigatória: Quando o locatário exige MFA mas o usuário ainda não se inscreveu, a resposta inclui mfaSetupRequired: true com um setupToken para o fluxo de inscrição.

Respostas de erro:

Verificação de SSO: Se o domínio de e-mail do usuário tem uma conexão SSO configurada, o endpoint de login retorna sso_required com um redirectUrl. O cliente deve redirecionar o usuário para o provedor SSO.

Bloqueio de conta: Após maxFailedAttempts tentativas de login consecutivas com falha, a conta é bloqueada por lockoutDurationMinutes. Ambos os valores são configuráveis nas configurações do locatário.

Cadastro

POST /api/auth/register

Cria uma nova conta de usuário. Um e-mail de verificação é enviado automaticamente — o usuário deve verificar seu e-mail antes de poder fazer login.

Corpo da requisição:

{
  "email": "[email protected]",
  "password": "a-strong-password-here",
  "firstName": "Jane",
  "lastName": "Smith"
}

Sucesso: 201 Created com o userId da nova conta. Registrar-se com um e-mail já existente também retorna 201: nunca revelamos se um e-mail está cadastrado (para evitar enumeração de contas) e, em vez disso, avisamos o titular real da conta por e-mail.

Respostas de erro:

Redefinição de Senha

POST /api/auth/forgot-password

Solicita um e-mail de redefinição de senha. O endpoint sempre retorna uma resposta de sucesso independentemente de o e-mail existir, para prevenir enumeração de e-mails.

{
  "email": "[email protected]"
}

POST /api/auth/reset-password

Redefine a senha do usuário usando o token do link de e-mail.

{
  "token": "RESET_TOKEN_FROM_EMAIL",
  "newPassword": "new-strong-password"
}

Efeitos colaterais de uma redefinição de senha bem-sucedida:

• O contador de tentativas de login com falha é zerado
• Todos os refresh tokens existentes são revogados
• Um novo security stamp é gerado (invalidando todas as sessões existentes)

Configuração e Verificação de MFA

Authagonal suporta três métodos de MFA: TOTP (aplicativos autenticadores), WebAuthn (chaves de segurança e biometria) e códigos de recuperação de uso único.

Configuração TOTP

POST /api/auth/mfa/totp/setup — Retorna uma URI de dados de QR code e uma chave de entrada manual. O usuário escaneia o QR code com seu aplicativo autenticador (Google Authenticator, Authy, 1Password, etc.) e confirma a inscrição.

POST /api/auth/mfa/totp/confirm — Confirma a inscrição TOTP validando um código de 6 dígitos do aplicativo autenticador.

{
  "code": "123456"
}

Configuração WebAuthn

POST /api/auth/mfa/webauthn/setup — Retorna opções de criação de credencial para a API WebAuthn. O navegador chama navigator.credentials.create() com essas opções.

POST /api/auth/mfa/webauthn/confirm — Confirma a inscrição WebAuthn enviando a resposta de attestation do navegador.

Códigos de Recuperação

POST /api/auth/mfa/recovery/generate — Gera 10 códigos de recuperação de uso único com 8 caracteres. Cada código pode ser usado exatamente uma vez para ignorar o MFA.

Verificação de MFA

POST /api/auth/mfa/verify — Completa o desafio de MFA após um login com senha bem-sucedido.

Status do MFA

GET /api/auth/mfa/status — Retorna os métodos de MFA atualmente inscritos do usuário.

Fluxo de Login SSO

Authagonal suporta conexões SSO baseadas em SAML 2.0 e OIDC. O roteamento baseado em domínio detecta automaticamente qual provedor SSO usar com base no endereço de e-mail do usuário.

Verificação de SSO

GET /api/auth/[email protected]

Fluxo SAML

O usuário é redirecionado para GET /saml/{connectionId}/login que envia uma SAML AuthnRequest para o provedor de identidade. O IdP autentica o usuário e envia uma resposta SAML de volta para o endpoint Assertion Consumer Service (ACS). Authagonal valida a asserção, cria ou atualiza o usuário e assina um cookie de sessão.

Os metadados SAML para configurar seu IdP estão disponíveis em GET /saml/{connectionId}/metadata.

Fluxo OIDC

O usuário é redirecionado para GET /oidc/{connectionId}/login que redireciona para o provedor de identidade de origem com PKCE. Após o usuário se autenticar, o callback em /oidc/callback troca o authorization code, valida o token de ID e cria ou atualiza o usuário.

Provisionamento JIT: Tanto os fluxos SAML quanto OIDC suportam provisionamento just-in-time. Se o usuário ainda não existir no locatário, ele é criado automaticamente a partir das claims do provedor de identidade. Se já existir, seus atributos de perfil são atualizados para corresponder aos valores mais recentes do provedor.

Backend-for-Frontend (BFF)

Um BFF mantém os tokens OAuth completamente fora do navegador. Sua aplicação de página única não guarda nada além de um cookie de sessão httpOnly, e um cliente confidencial no seu próprio backend executa o fluxo OpenID Connect e mantém os tokens no servidor.

Tudo o que uma aplicação de página única consegue ler, o cross-site scripting consegue roubar, e isso inclui um token de acesso em memória e um refresh token no localStorage. Guardar tokens no navegador também limita o tempo de vida deles, porque um refresh token de longa duração ao alcance de scripts é um risco permanente. A best current practice do IETF OAuth 2.0 for Browser-Based Apps recomenda esse padrão exatamente por esse motivo.

Em troca, você ganha uma sessão que sobrevive a um recarregamento de página sem nenhum token à vista, a renovação tratada para você no servidor, revogação imediata através do logout back-channel, e um proxy autenticado, de modo que sua API nunca precisa interpretar um token que o navegador poderia ter adulterado.

Crie o cliente

No portal, abra Clients e escolha Criar app BFF. Informe a URL base de onde seu aplicativo é servido, por exemplo https://app.acme.com, e o Authagonal registra para você um cliente confidencial corretamente configurado, em vez de deixar que você monte um por conta própria:

Conecte ao seu backend

Dois runtimes são suportados e se comportam de forma idêntica: Authagonal.Bff para .NET e @authagonal/bff para Node, este último com adaptadores para Express e Next.js. Aponte qualquer um deles para os valores que o portal acabou de fornecer.

// dotnet add package Authagonal.Bff
builder.Services.AddAuthagonalBff(o =>
{
    o.Authority    = "https://acme.authagonal.io";       // your tenant auth host
    o.ClientId     = builder.Configuration["Bff:ClientId"]!;
    o.ClientSecret = builder.Configuration["Bff:ClientSecret"]!;
    o.Scope        = ["openid", "profile", "email", "offline_access"];
    o.PostLogoutRedirectUri = "https://app.acme.com/";
});

var app = builder.Build();

app.UseForwardedHeaders();   // required behind a proxy or ingress, see the note below
app.MapAuthagonalBff();
app.MapFallbackToFile("index.html");   // your SPA
app.Run();

// npm install @authagonal/bff
import express from 'express';
import { authagonalBff } from '@authagonal/bff/express';

const app = express();

app.use(authagonalBff({
  authority: 'https://acme.authagonal.io',
  clientId: process.env.BFF_CLIENT_ID,
  clientSecret: process.env.BFF_CLIENT_SECRET,
  scope: ['openid', 'profile', 'email', 'offline_access'],
  postLogoutRedirectUri: 'https://app.acme.com/',
}));

app.listen(8080);

Endpoints

Montados sob /bff por padrão. Eles precisam ser servidos a partir da mesma origem da sua SPA, porque o cookie de sessão é httpOnly e same-origin: coloque-os atrás do mesmo hostname, e não em um domínio de API separado.

A partir do navegador

Toda requisição que não seja de navegação precisa levar um cabeçalho anti-forgery estático. Ele protege contra cross-site request forgery junto com o atributo SameSite do cookie: um envio de formulário cross-site não consegue definir um cabeçalho personalizado, então uma requisição sem ele é recusada.

const me = await fetch('/bff/user', {
  headers: { 'X-Authagonal-Bff': '1' },
}).then(r => r.json());

if (!me.isAuthenticated) {
  // Navigate, do not fetch: this is a redirect to your identity provider.
  window.location.href = '/bff/login?returnUrl=' + encodeURIComponent(location.pathname);
}

Faça login e logout navegando, e não com fetch: location.href = '/bff/login'. Essas rotas respondem com um redirecionamento para o seu provedor de identidade, e uma cadeia de redirecionamentos não é algo que o fetch consiga seguir de forma útil.

Chamando a sua API

O BFF pode encaminhar a sua API sob o caminho base dele e anexar o token de acesso da sessão no percurso. O navegador envia um cookie, a sua API recebe um bearer token que valida normalmente, e nada desse token fica visível para a página nem pode ser forjado por ela. Registre um upstream e as requisições para /bff/api/** chegam nele autenticadas. Deixe a lista vazia e o proxy fica completamente desativado.

o.Upstreams.Add(new BffUpstream
{
    Prefix        = "/orders",                        // matches /bff/api/orders/**
    TargetBaseUrl = "https://api.internal.acme.com",
    StripPrefix   = false,                            // keep /orders in the forwarded path
});

WebSockets

Um handshake de WebSocket não consegue carregar um cabeçalho personalizado nem um bearer token, então nem o cabeçalho anti-forgery nem o proxy ajudam. Ative os tickets e a SPA pode chamar GET /bff/ws-ticket, colocar o ticket de uso único e curta duração na URL de conexão, e fazer a sua API resgatá-lo. Gere um imediatamente antes de cada conexão: ele é excluído no primeiro uso e expira em segundos.

Entregando um token ao navegador, deliberadamente

O sentido de um BFF é que o navegador não guarda nenhum token, então isto é opcional e restrito. Existe para o único caso que o modelo de cookie não alcança: um resource server em outra origem, como um app que você incorpora em um iframe, que precisa ser chamado com um bearer. Ativado, GET /bff/token?resource=… retorna um token trocado: o token da sessão reduzido a um único recurso da lista de permitidos e vinculado a qualquer parâmetro de contexto também permitido. O navegador nunca vê o token da própria sessão, e o que ele recebe tem vida curta e uma única audiência. Uma requisição que nomeie um recurso fora da lista de permitidos é recusada, e é isso que impede que isso vire uma fábrica de tokens de uso geral.

Atendendo vários locatários com um só BFF

Defina um parâmetro de query de locatário e uma única implantação atende muitos locatários: /bff/login?slug=acme seleciona o locatário, um resolver fornece a authority e as credenciais de cliente daquele locatário, a chave viaja no cookie de correlação até a sessão, e o logout back-channel resolve o locatário a partir do emissor do token. O resolver padrão mantém o comportamento de locatário único idêntico byte a byte, então você não paga nada por isso a menos que use.

Opções que vale conhecer

O conjunto completo. O pacote Node espelha essas opções em camelCase, então BasePath é basePath e assim por diante.

Opere o seu portal a partir de um assistente de IA

Conecte um assistente de IA ao seu locatário e peça a ele as coisas que você faria clicando pelo portal: encontrar um usuário que não consegue fazer login, verificar se ele ainda tem um segundo fator, convidar alguém, ver quem tem uma função de administrador.

É uma conexão OAuth comum, não uma chave de API. Cada pessoa faz login como ela mesma e aprova o acesso, então um assistente consegue fazer exatamente o que aquela pessoa consegue fazer no portal, e nada além disso. Nada de novo é criado que possa vazar, e revogar um assistente não mexe em nenhum dos outros.

Como ativar

Abra Configurações e ative o acesso de assistente de IA. Ele fica desativado até você fazer isso e, enquanto está desativado, o endpoint não existe, em vez de apenas recusar. Depois de ativado, o painel mostra a URL para colar no seu cliente de IA:

https://portal-api.authagonal.io/api/v1/mcp/{your-tenant}

O que um assistente pode fazer

Exatamente o que a pessoa que o conectou pode fazer, decidido a cada chamada com base no token dela. Um agente tenant:support recebe as ferramentas de diagnóstico e do dia a dia; as ferramentas de administrador não ficam apenas escondidas dele, elas são recusadas se forem chamadas pelo nome. Tudo o que é restrito dentro do portal continua restrito: mudar o endereço de e-mail de um usuário exige a função de administrador lá, e exige aqui também.

Como é uma concessão comum, você a gerencia do jeito comum. Revogue-a e o assistente para de funcionar imediatamente, e não na próxima expiração do token. Tudo o que um assistente faz é gravado no seu registro de auditoria como a pessoa em nome de quem ele agiu, então a trilha é a mesma que você já lê.

As ferramentas

Vinte nesta versão. O seu cliente de IA decide quais ativar, então você pode entregar a um assistente apenas as ferramentas de leitura, se for só isso que você quer que ele faça.

O que ainda não está incluído

Excluir usuários, criar ou editar conexões de SSO, faturamento, backups e segredos de cliente estão todos ausentes desta versão. A exclusão pertence à sua fila de apagamento, e não ao lado dela; uma conexão de SSO é grande o bastante para que uma edição errada tranque do lado de fora a empresa inteira, então essas ficam somente leitura por enquanto; e uma ferramenta que devolvesse um segredo de cliente o colocaria na transcrição de um assistente. Conte para nós quais dessas você quer e em que ordem.

Autenticação de servidor MCP

Se você expõe um servidor Model Context Protocol, o Authagonal pode ser o servidor de autorização por trás dele. Um assistente de IA se conecta, a pessoa por trás dele faz login e concede o acesso, e o seu servidor recebe um token bearer normal, que você valida como o de qualquer outra API.

A alternativa é uma chave de API colada na configuração de um assistente, ou seja, uma credencial sem nenhum usuário por trás dela, sem expiração, sem etapa de consentimento e sem forma de revogar um conector sem rotacionar a chave para todo mundo. Fazer isso como OAuth significa que a concessão pertence a uma pessoa identificada, fica visível no seu registro de auditoria e pode ser revogada pelo portal sem mexer em mais nada.

Como a conexão acontece

Toda a troca é conduzida por discovery, então um cliente em conformidade não precisa de nada configurado além da URL do seu servidor.

Nada nessa sequência é específico do Authagonal: é a especificação de autorização do MCP, construída sobre a RFC 9728 para os metadados do recurso, a RFC 8414 para descobrir o servidor de autorização, a RFC 7591 para o registro e a RFC 8707 para nomear o recurso. Um conector que segue a especificação funciona sem precisar de nenhum tratamento especial para nós.

Deixe os conectores se registrarem sozinhos

Um conector que você nunca viu não tem como usar um cliente que você criou à mão, então ele registra um em tempo de execução. Isso vem desativado por padrão. Ative o registro dinâmico de clientes em Configurações e o endpoint de registro aparece no seu documento de discovery; deixe desativado e o endpoint não é anunciado e recusa as requisições. Ativá-lo abre o registro apenas para o seu locatário, nunca para o de mais ninguém.

O que o seu servidor MCP implementa

Duas coisas pequenas, e depois ele é um resource server comum. Primeiro, publique os metadados de recurso protegido apontando o seu locatário como servidor de autorização. Sirva-os no caminho well-known e, se o seu endpoint MCP estiver em um subcaminho, também na forma com o sufixo de caminho, já que os clientes tentam as duas.

GET https://your-app.example/.well-known/oauth-protected-resource

{
  "resource": "https://your-app.example/mcp",
  "authorization_servers": ["https://acme.authagonal.io"],
  "bearer_methods_supported": ["header"],
  "scopes_supported": ["mcp"]
}

Segundo, quando uma chamada chegar sem um token válido, responda 401 com um cabeçalho WWW-Authenticate apontando para esses metadados. É esse cabeçalho que transforma uma recusa em uma conexão: sem ele o cliente não tem como descobrir onde se autenticar e simplesmente falha.

// Validate the connector's token like any other resource server.
builder.Services.AddAuthentication().AddJwtBearer("McpBearer", o =>
{
    o.Authority = "https://acme.authagonal.io";              // your tenant
    o.TokenValidationParameters.ValidAudience = "https://your-app.example/mcp";
});

// Unauthenticated? Point the connector at the metadata rather than just refusing.
http.Response.Headers.WWWAuthenticate =
    "Bearer resource_metadata=\"https://your-app.example/.well-known/oauth-protected-resource\"";
return Results.Unauthorized();

Escopos, planos e revogação

Defina um escopo para a sua API MCP, adicione-o aos escopos de registro permitidos, e ele aparece na tela de consentimento para que o usuário veja o que está aprovando. O token carrega as funções do usuário e as claims que você configurou, então o seu servidor pode decidir o que essa pessoa específica pode fazer, em vez de tratar todos os conectores igual.

Como é uma concessão OAuth comum, a revogação funciona do jeito comum: encontre o usuário, revogue as sessões dele ou a concessão, e o conector para de funcionar imediatamente, e não na próxima expiração do token. O registro de auditoria guarda o registro do cliente, o consentimento e a emissão, então você consegue ver qual assistente pediu o quê e quando.

Crie uma interface de login personalizada

Substitua as telas de login, registro, redefinição de senha e MFA hospedadas pela Authagonal pela sua própria interface, enquanto a Authagonal continua cuidando da autenticação, MFA, SSO, sessões e emissão de tokens. Dois caminhos: use nossa biblioteca de componentes React ou chame a API de autenticação diretamente de qualquer framework. É opcional — primeiro ative Custom login UI nas configurações do locatário.

Pré-requisito: um domínio personalizado no seu domínio raiz

A sessão de login é um cookie first-party, então sua interface e o servidor de autenticação da Authagonal devem compartilhar um domínio registrável. Aponte um domínio de autenticação personalizado para a Authagonal no mesmo domínio raiz em que seu aplicativo é executado — por exemplo, autenticação em login.acme.com, aplicativo em app.acme.com. A configuração Custom login UI permanece desativada até que exista um domínio personalizado ativo.

Adicione também a origem da sua interface (por exemplo, https://app.acme.com) às Allowed CORS origins do seu cliente OAuth — a mesma lista que você define para a troca de tokens.

React: @authagonal/login

npm i @authagonal/login entrega a lógica de autenticação e a interface em um único pacote — o mesmo sobre o qual o login hospedado da Authagonal é construído. Escolha sua altitude:

• Aplicativo completo — adicione App e personalize o tema via branding.
• Componha páginas — use LoginPage, MfaChallengePage, ResetPasswordPage… dentro do seu próprio layout.
• Primitivos + lógica — crie suas próprias telas com AuthLayout/Button/Input e o cliente da API (login, mfaVerify, forgotPassword, …).

import { AuthLayout, Input, Button, login, ApiRequestError } from '@authagonal/login';

function MyLogin() {
  async function onSubmit(email: string, password: string) {
    try {
      const res = await login({ email, password });        // POST /login (sets the session cookie)
      if (res.mfaRequired) {/* render your MFA step → mfaVerify(...) */}
      else window.location.href = res.returnUrl;            // hand off to /connect/authorize
    } catch (e) {
      if (e instanceof ApiRequestError) {/* show e.message */}
    }
  }
  return <AuthLayout>{/* your own markup + <Input/> <Button/> */}</AuthLayout>;
}

Qualquer framework: chame a API de autenticação

Não usa React? Chame os endpoints do fluxo de autenticação diretamente (em /api/auth) e, em seguida, repasse para o fluxo OIDC padrão /connect/authorize. Envie credentials: 'include' para que o cookie de sessão seja armazenado.

# 1. Authenticate (browser fetch — credentials:'include' so the session cookie is stored)
curl -i -X POST https://login.acme.com/api/auth/login \
  -H "Content-Type: application/json" \
  -H "Origin: https://app.acme.com" \
  --data '{"email":"[email protected]","password":"..."}'
# (handle {"mfaRequired":true} → POST /api/auth/mfa/verify, then continue)

# 2. Hand off to the OAuth flow — top-level navigation to the authorize endpoint with PKCE:
# https://login.acme.com/connect/authorize?client_id=my-app&redirect_uri=...&response_type=code
#   &scope=openid%20profile%20email&code_challenge=...&code_challenge_method=S256
# The session cookie (same-site) authenticates the user; you get back a code → exchange at /connect/token.

Planos e Limites

Authagonal oferece quatro níveis de plano. Todos os planos incluem todos os recursos — a única diferença é o limite de Usuários Ativos Mensais (MAU) e o preço de excedente.

Níveis de Plano

Usuários Ativos Mensais (MAU)

Um Usuário Ativo Mensal é qualquer usuário único que se autentica com sucesso pelo menos uma vez durante um mês de faturamento. Usuários provisionados via SCIM que não fizeram login não contam para o total de MAU.

Excedente — Se seu plano suporta excedente, usuários além do limite de MAU são cobrados pela taxa por usuário mostrada na tabela de planos acima. Você pode definir um limite de excedente para limitar seu gasto máximo no período de faturamento.

Aplicação — Se seu plano não suporta excedente (Starter), usuários além do limite de MAU não podem fazer login até o próximo período de faturamento ou até você fazer upgrade para um plano que suporte excedente.