AppAccessPolicy: identifiers, verificação selecionada e authenticators disponíveis naquele ambiente.Bullgate Access · documentação técnica
Políticas do Access
Onde cada decisão é configurada, quais combinações são aceitas e como a policy altera cadastro, login, telefone, verificação e ações oferecidas ao aplicativo.
Verificado no códigoManifesto v1Por environmentAtualizado em 04/09/2026
“Policy” não significa qualquer regra do sistemaO código possui duas policies formais:
AppAccessPolicy e AccessVerificationPolicy. Permissões e invariantes de segurança também controlam comportamento, mas possuem contratos e escopos diferentes.Mapa de autoridade
Quatro níveis que não devem ser misturados
Escolher o nível errado pode habilitar um método de login para todos os ambientes ou dar autoridade administrativa ao backend do produto.
AccessVerificationPolicy: prazos, tentativas, rate limit, cooldown e duração de grant.Policy persistida
AppAccessPolicy
Pertence a um AppEnvironment. Development, staging e production podem oferecer métodos diferentes mesmo quando usam o mesmo app ou realm.
IdentifierAccessPolicy
Existe separadamente para e-mail e telefone.
enabled: o identifier participa do ambiente.required: o cadastro não pode concluir sem ele.verification: define se a posse precisa ser comprovada e por qual provider.
AuthenticatorAccessPolicy
Habilita de forma independente os authenticators da fase atual.
passwordgoogleapple
Realm e environment cumprem papéis diferentesO realm é o namespace de identities e de unicidade dos identifiers. O environment escolhe a policy e os clientes autorizados que operam sobre esse realm.
Bootstrap
Configuração completa da fase atual
A policy entra no manifesto versionado e sem segredos. Reexecutar o bootstrap reaplica a policy ao environment existente.
Trecho do manifesto
"accessPolicy": {
"identifiers": {
"email": {
"enabled": true,
"required": true,
"verification": { "enabled": false }
},
"phone": {
"enabled": true,
"required": false,
"verification": {
"enabled": true,
"provider": "twilio-verify"
}
}
},
"authenticators": {
"password": true,
"google": true,
"apple": false
}
}Exemplo BAYBO DevelopmentE-mail obrigatório sem verificação, telefone opcional verificado pelo Twilio Verify, senha e Google habilitados e Apple desabilitado.
Parâmetro por parâmetro
Policy de e-mail e telefone
| Campo | Tipo | Efeito | Regra atual |
|---|---|---|---|
email.enabled | boolean | Habilita e-mail como identifier no environment. | Senha, Google e Apple dependem também deste campo. |
email.required | boolean | Declara e-mail obrigatório na policy. | As rotas diretas de e-mail/senha já exigem o campo no payload. |
email.verification.enabled | boolean | Exigirá prova de posse do e-mail. | Não implementado: o bootstrap rejeita true. |
email.verification.provider | string? | Seleciona adapter de entrega/verificação. | Nenhum provider de e-mail é aceito na fase 1. |
phone.enabled | boolean | Inclui telefone na continuação do cadastro. | false evita o step de telefone. |
phone.required | boolean | Controla se o flow oferece skipRegistration. | Só pode ser true quando telefone está habilitado. |
phone.verification.enabled | boolean | Escolhe OTP ou coleta sem verificação. | true usa challenge; false usa submitPhone. |
phone.verification.provider | string? | Provider do challenge de telefone. | Quando habilitado, somente twilio-verify. |
Entrada na identity
Authenticators e suas dependências
Habilitar o authenticator é necessário, mas não suficiente: as rotas atuais também dependem de e-mail habilitado.
| Campo | Rota disponível quando | Comportamento desabilitado |
|---|---|---|
authenticators.password | email.enabled && password | Cadastro e login por e-mail/senha retornam authenticator-disabled. |
authenticators.google | email.enabled && google | Login Google é recusado mesmo que o token do provider seja válido. |
authenticators.apple | email.enabled && apple | Login Apple é recusado mesmo que o token do provider seja válido. |
Authenticator social não faz auto-linkUm e-mail coincidente não prova que duas identities são a mesma pessoa. Conflito de unicidade retorna
email-taken; vínculo entre providers exige fluxo explícito.Validação
Combinações aceitas e rejeitadas
| Configuração | Status | Motivo |
|---|---|---|
| Identifier desabilitado, não obrigatório e sem verificação | Aceita | Remove aquele identifier do environment. |
Identifier desabilitado e required: true | Rejeitada | Algo ausente não pode ser obrigatório. |
| Identifier desabilitado e verificação habilitada | Rejeitada | Não existe identifier para verificar. |
Verificação desabilitada com provider | Rejeitada | Provider só pode existir quando a verificação está ligada. |
Verificação habilitada sem provider | Rejeitada | Uma verificação ativa precisa selecionar adapter. |
Telefone verificado por provider diferente de twilio-verify | Rejeitada | Provider ainda não implementado. |
| Verificação de e-mail habilitada | Rejeitada | Contrato futuro; ainda não há execução. |
| Todos os authenticators desabilitados | Representável | O domínio aceita, mas o environment fica sem método de entrada da fase atual. |
Limites operacionais da instância
AccessVerificationPolicy
É montada pela configuração do host do Bullgate Access. Na fase atual, não pertence a um environment específico.
| Chave | Padrão | Uso | Validação |
|---|---|---|---|
CodeLifetimeMinutes | 10 | Validade do código de verificação. | Maior que zero. |
MaxAttempts | 5 | Tentativas do OTP e do e-mail anterior no conflito atual. | Maior que zero. |
MaxRequestsPerHourPerIdentity | 5 | Limite de solicitações recentes por identity. | Maior que zero. |
ResendCooldownSeconds | 120 | Espera mínima antes de reenviar. | Zero ou maior. |
ResolutionGrantLifetimeMinutes | 15 | Validade máxima do grant de resolução. | Maior que zero. |
TestBypassEnabled | false | Ativa telefone e código fixos somente para testes. | Exige telefone E.164 e código de seis dígitos ASCII. |
TestPhone / TestCode | null | Valores do bypass quando ele está habilitado. | Não são policy de produção. |
Configuração do host
"Verification": {
"CodeLifetimeMinutes": 10,
"MaxAttempts": 5,
"MaxRequestsPerHourPerIdentity": 5,
"ResendCooldownSeconds": 120,
"ResolutionGrantLifetimeMinutes": 15,
"TestBypassEnabled": false
}Bypass é infraestrutura de testeNunca habilite
TestBypassEnabled em produção nem publique TestPhone e TestCode em manifesto, aplicativo, log ou documentação pública de ambiente.Policy → comportamento
Como a configuração muda o AccessFlow
Telefone desligado
O cadastro pode concluir sem abrir collectPhone. Não existe ação de telefone.
Telefone sem verificação
O flow oferece submitPhone. Número já usado retorna phone-already-in-use; não abre resolução.
Telefone com verificação
O flow oferece request, confirmação e reenvio. Conflito após OTP pode abrir resolvePhoneConflict.
Telefone opcional
skipRegistration acompanha coleta, OTP e conflito enquanto a policy permitir.
Telefone obrigatório
O flow omite skipRegistration. A UI não deve inventar uma saída.
Authenticator desligado
A rota correspondente falha de forma explícita; o frontend não deve oferecer aquele método.
A ação oferecida é a autoridade finalMesmo conhecendo a policy, o aplicativo executa somente IDs e tipos presentes em
flow.actions. A policy explica o comportamento; o snapshot autoriza a ação.Integration client
Permissões não são AppAccessPolicy
Cada backend recebe somente as capacidades server-to-server declaradas. Valores desconhecidos são rejeitados e nada é acrescentado automaticamente.
| Permissão definida | Autoridade | Disponibilidade atual |
|---|---|---|
access:flows:execute | Cadastro, login social/direto e AccessFlow. | Usada pela API do produto. |
access:sessions:introspect | Introspecção de sessão opaca. | Usada pela API do produto. |
access:sessions:revoke-current | Revogação da sessão apresentada. | Usada pelo logout do produto. |
access:identities:read | Leitura administrativa de identities. | Definida no catálogo; não pertence ao client api do exemplo. |
access:identities:block | Bloqueio administrativo. | Definida no catálogo; sem endpoint público atual no Access API. |
access:identities:unblock | Desbloqueio administrativo. | Definida no catálogo; sem endpoint público atual no Access API. |
access:sessions:revoke-all | Revogação global das sessões da identity. | Definida no catálogo; sem endpoint público atual no Access API. |
Separe operação de produto e administraçãoO integration client do BFF não deve receber permissões administrativas “para o futuro”. Um backoffice terá identidade de máquina própria e escopo explícito.
Não configurável
Regras que nenhuma policy pode enfraquecer
Estas são garantias do domínio ou do protocolo. Não devem aparecer como checkbox de environment.
Identidade e vínculo
IdentityIdé o subject estável.- E-mail e telefone são identifiers mutáveis.
- Identifiers são únicos por scheme dentro do realm.
- Coincidência de e-mail não faz auto-link.
- A fase 1 não cria e-mail alternativo.
Sessão e cliente
- Registration não autoriza o produto.
- Product só nasce após conclusão válida.
- Credencial de integração nunca entra no aplicativo.
- Native client precisa estar previamente cadastrado.
- Falha operacional não prova logout.
Flow e concorrência
requestIdé idempotente por payload.revisionimpede ação sobre estado antigo.- Somente
flow.actionsautoriza execução. - Ownership é revalidado dentro da transação.
Resolução
- A regra da fase 1 ainda é fixa no código.
- Telefone + conhecimento do e-mail anterior autoriza somente a transferência do telefone.
- Não há merge ou recuperação silenciosa.
Operação
Alterar policy sem criar comportamento ambíguo
- Altere o manifesto versionado do environment correto; não edite o banco manualmente.
- Valide providers e combinações contra a versão instalada do Access.
- Reexecute o bootstrap: a
accessPolicyé reaplicada ao environment existente. - Confirme que o BFF possui apenas as permissões necessárias; isso é configuração separada.
- Atualize a UI para mostrar métodos habilitados, mas continue obedecendo ao snapshot do flow.
- Teste cadastro novo, sessão Registration pendente, login existente e conflito de telefone no ambiente alterado.
Não existe versionamento próprio da policy na fase atual
manifestVersion: 1 versiona o formato do manifesto, não cria histórico de AppAccessPolicy. Não presuma que flows ativos mantêm para sempre a configuração anterior.Contrato vigente e roadmap
O que pode ser configurado hoje
Implementado
- E-mail como identifier.
- Senha, Google e Apple por environment.
- Telefone desligado, opcional ou obrigatório.
- Telefone sem verificação ou com Twilio Verify.
- Limites operacionais de código, tentativa, rate limit e cooldown.
- Permissões explícitas do integration client.
Futuro
- Verificação de e-mail e seus adapters.
- Login sem senha por magic link ou código único.
- Providers adicionais de telefone.
- Passkeys, 2FA e step-up por ação.
ResolutionPolicyversionada e configurável.
Ativar contrato futuro não antecipa implementaçãoNa versão atual, o bootstrap rejeita verificação de e-mail e provider de telefone desconhecido. Não existe fallback silencioso nem simulação de sucesso.