Ligar o Auth0
O Auth0 envia eventos para o Identiguard através de um log stream. Cria-se primeiro o tenant no Identiguard e depois cria-se o stream no Auth0 com o endpoint e o token que o Identiguard fornece.
O Identiguard não precisa de credenciais da API do Auth0, e não guarda nenhuma. Não cria nada no tenant do Auth0.
Antes de começar
Seção intitulada “Antes de começar”O que é necessário:
- Acesso ao dashboard do Auth0 com permissão para criar streams em Monitoring.
- A função de admin no workspace do Identiguard. Os membros e os visualizadores veem Only workspace admins can create tenants. (só os admins do workspace podem criar tenants) e um botão Admin Access Required desativado.
- O domínio canónico do tenant, como
acme.eu.auth0.com. Não utilize um domínio personalizado. - Uma vaga de tenant livre no plano. Consulte o limite de tenants do plano.
Os três tokens
Seção intitulada “Os três tokens”Um tenant do Auth0 no Identiguard pode ter até três endpoints separados. Cada um tem o seu próprio token. Cada token é mostrado uma única vez.
| Token | Para que serve | Quando o recebe | Se o perder |
|---|---|---|---|
| Token do log stream | Eventos de log do Auth0. Todos os tenants do Auth0 têm um. | No ecrã que aparece depois de criar o tenant | Não pode ser emitido de novo. Elimine o tenant e crie-o de novo. |
| Token do metric stream | Tráfego de API para a página Métricas de API do Auth0. Opcional, beta. | Na criação, ou mais tarde a partir da página API Metrics | Não existe ecrã para emitir um novo. Contacte a equipa de produto. |
| Token dos Action logs | Linhas de log enviadas pelas suas próprias Actions do Auth0. Opcional. | Apenas na criação | Não existe ecrã para emitir um novo. Contacte a equipa de produto. |
1. Criar o tenant no Identiguard
Seção intitulada “1. Criar o tenant no Identiguard”- Abra o workspace e vá a Tenants.
- Em Create a tenant, localize o cartão Auth0 (legenda Customer identity) e escolha Connect. Abre-se a página Add New Auth0 Tenant.
- Em Setup Method, escolha como vai criar o log stream:
- Manual: o Identiguard fornece um endpoint de ingestão e um token. O log stream é criado por si no dashboard do Auth0.
- Deploy via Terraform: o Identiguard gera uma configuração Terraform que é aplicada por si.
- Em Basic Details, preencha os campos da tabela abaixo.
- Em Event Subscriptions, verifique os tipos de evento. O conjunto recomendado já está assinalado quando a página abre.
- Apenas com Deploy via Terraform: em Obscure Log Stream Data, escolha se o Auth0 oculta dados pessoais. Consulte Ocultar dados pessoais.
- Opcionalmente, assinale Set up a metric stream now e Set up Action logs now.
- Escolha Create Auth0 Tenant. O botão indica Creating… enquanto o Identiguard trabalha.
Os campos
Seção intitulada “Os campos”| Secção | Campo | Regras |
|---|---|---|
| Setup Method | Manual ou Deploy via Terraform | Manual está selecionado por predefinição. Não é possível alterá-lo depois da criação. |
| Basic Details | Tenant Name | Obrigatório. 100 caracteres ou menos. Sem quebras de linha nem caracteres de controlo. |
| Basic Details | Customer Name | Obrigatório. O campo sugere nomes de clientes já utilizados no workspace. |
| Basic Details | Auth0 Domain | Obrigatório. O domínio canónico do tenant, como acme.eu.auth0.com. Sem caminho, sem espaços, e não um domínio personalizado. Não é possível alterá-lo depois da criação. |
| Basic Details | Environment | Obrigatório. Production ou Development. |
| Event Subscriptions | Subscribed Event Types | Pelo menos um. O contador mostra N of M selected. |
| Obscure Log Stream Data | Obfuscation method, Log data to obscure | Apenas Terraform. Se escolher um método, assinale pelo menos um campo. |
| Metric stream (distintivo Beta) | Set up a metric stream now | Opcional. Desligado por predefinição. O formulário diz Can also be set up later. (também pode ser configurado mais tarde) |
| Metric stream | Set up Action logs now | Opcional. Desligado por predefinição. Não pode ser ligado mais tarde a partir de nenhum ecrã. |
Não existem campos Client ID nem Client Secret para o Auth0.
Escolher os tipos de evento
Seção intitulada “Escolher os tipos de evento”O Auth0 publica 185 códigos de eventos de log. Cada um aparece como uma descrição seguida do respetivo código entre parênteses.
- O conjunto recomendado está assinalado quando a página abre.
- Select Recommended substitui toda a sua seleção pelo conjunto recomendado. Deixa de fora os códigos de grande volume e os códigos que o Auth0 não documenta.
- Search event types… filtra a lista por código ou por descrição.
- Select All assinala todos os códigos. Enquanto pesquisa, passa a Select All Visible.
- Clear All desmarca tudo.
A lista controla o que o Identiguard guarda. Não configura o stream no Auth0. Com a configuração manual, selecione por si, no stream do Auth0, as categorias de eventos correspondentes.
2. Copiar os valores
Seção intitulada “2. Copiar os valores”Depois da criação, o formulário é substituído por um ecrã de configuração. Não é reencaminhado para a página Tenants.
O ecrã mostra o alerta Tenant <name> created. Next, create the stream(s) in Auth0. (tenant criado; a seguir, crie o stream ou os streams no Auth0) e Copy these values now. They are shown once. (copie estes valores agora; são mostrados uma única vez)
| Painel | Valores | Mostrado quando |
|---|---|---|
| Log stream | Endpoint URL, Authorization token (shown once) | Sempre |
| Metric stream (distintivo Beta) | OTLP endpoint URL, Bearer token (shown once) | Assinalou Set up a metric stream now |
| Action logs | Endpoint URL, Token (shown once), o excerto de código da Action | Assinalou Set up Action logs now |
identiguard.tf |
A configuração Terraform, com Copy configuration | O método de configuração é Deploy via Terraform |
terraform.tfvars (mostrado uma única vez) |
O token de ingestão, com Copy ingestion token | O método de configuração é Deploy via Terraform |
Cada valor tem um botão Copy. Um toast confirma com “<label> copied to clipboard” (copiado para a área de transferência). Quando todos os valores estiverem guardados, escolha Back to Tenants.
3. Criar o log stream no Auth0
Seção intitulada “3. Criar o log stream no Auth0”- No Auth0, vá a Monitoring → Streams → Create Stream e escolha Custom Webhook.
- Introduza o Endpoint URL do Identiguard como payload URL.
- Introduza o Authorization token do Identiguard como valor do cabeçalho
Authorization. - Selecione as categorias de eventos que correspondem aos tipos de evento que assinalou no Identiguard.
- Guarde o stream.
Terraform
Seção intitulada “Terraform”- Copie
identiguard.tfcom Copy configuration e adicione-o ao seu próprio projeto Terraform do Auth0. - Copie o valor de
terraform.tfvarscom Copy ingestion token. O token é uma variável Terraform. Não está dentro deidentiguard.tf. - Execute
terraform apply.
Pode ver identiguard.tf de novo mais tarde, na página Edit do tenant. O token nunca volta a ser mostrado. Consulte Gerir tenants.
4. Verificar que os eventos chegam
Seção intitulada “4. Verificar que os eventos chegam”Inicie sessão em qualquer aplicação do tenant e depois abra Dashboard no Identiguard. O início de sessão aparece em Real-time events em poucos segundos.
Ocultar dados pessoais
Seção intitulada “Ocultar dados pessoais”O Auth0 pode ocultar campos escolhidos antes de os eventos saírem do tenant.
Com Deploy via Terraform, a secção Obscure Log Stream Data aparece no formulário de criação. Não aparece para Manual.
- Escolha um Obfuscation method:
- None - stream in clear text (nenhum, envio em texto simples)
- XXHash - replace with a unique string (Recommended by Auth0) (substituir por uma cadeia de caracteres única, recomendado pelo Auth0)
- Mask - replace with ***** (substituir por asteriscos)
- Se escolheu XXHash ou Mask, assinale os campos em Log data to obscure: First name, Last name, Username, Email, Phone, Address. Select all e Clear all assinalam ou desmarcam os seis. Assinale pelo menos um.
Escolha XXHash em vez de Mask se ainda quiser correlacionar eventos do mesmo utilizador (ocultado). A escolha é escrita na configuração Terraform gerada.
Com a configuração Manual, defina Obscure log stream data no stream, no dashboard do Auth0.
Metric stream (beta)
Seção intitulada “Metric stream (beta)”Um metric stream acrescenta o tráfego de API à página API Metrics do tenant e ao cartão Auth0 API metrics no Dashboard. Requer um plano do Auth0 que suporte Metric Streams, normalmente o Enterprise. O provider Terraform do Auth0 não suporta metric streams, por isso este stream é sempre criado manualmente.
Num tenant novo:
- No formulário de criação, assinale Set up a metric stream now.
- Depois da criação, copie o OTLP endpoint URL e o Bearer token (shown once) do painel Metric stream.
- No Auth0, vá a Monitoring → Streams → Create Stream e escolha Metric Stream do tipo HTTP.
- Introduza o OTLP endpoint URL.
- Escolha Bearer Token como método de autenticação e cole o token. Cole apenas o token. O Auth0 acrescenta por si a palavra
Bearer.
Num tenant existente, a configuração está na página API Metrics, não na página Edit. Consulte Métricas de API do Auth0.
Não existe ecrã para desligar um metric stream nem para emitir um novo token.
Action logs
Seção intitulada “Action logs”As linhas de log das suas próprias Actions do Auth0 podem chegar ao Identiguard. Cada linha torna-se um evento.
- No formulário de criação, assinale Set up Action logs now.
- Depois da criação, copie o Endpoint URL, o Token (shown once) e o Action snippet do painel Action logs.
- No Auth0, vá a Actions → Library e abra a Action a partir da qual quer registar logs.
- Adicione o token como um segredo com o nome
IDENTIGUARD_TOKEN. - Adicione o excerto de código à Action e chame-o onde quiser uma linha de log.
O que deve saber antes de utilizar:
- Níveis. Uma linha enviada no nível
errorabre um incidente no Identiguard, por isso reserveerrorpara falhas reais. As linhas no nívelinfonão são aceites até esse nível ser ligado, e não existe ecrã para isso. - Dados pessoais. O ecrã de configuração indica: “Identiguard stores whatever your Action sends. Auth0’s “Obscure log stream data” setting does not apply to this endpoint, and Identiguard cannot mask or filter these lines. It is the integrator’s responsibility to ensure no personal data is placed in the message or data fields.” (o Identiguard guarda tudo o que a sua Action enviar; a definição “Obscure log stream data” do Auth0 não se aplica a este endpoint, e o Identiguard não pode mascarar nem filtrar estas linhas; cabe ao integrador garantir que não são colocados dados pessoais nos campos message ou data) Certifique-se de que a pessoa que escreve a Action sabe disto.
- A entrega é feita na medida do possível. Os inícios de sessão nunca esperam pelo Identiguard. Uma linha que ainda esteja a ser enviada quando a Action termina perde-se.
Depois da criação
Seção intitulada “Depois da criação”- Para alterar os eventos que o Identiguard guarda, consulte Alterar os eventos que um tenant envia. Isto não altera nada no Auth0.
- A página Edit do tenant mostra o domínio, o método de configuração e o endpoint do log stream como valores só de leitura. Consulte Gerir tenants.
- Não há credenciais para rodar. Consulte Rodar credenciais.
Workspaces em período de avaliação
Seção intitulada “Workspaces em período de avaliação”Um tenant do Auth0 só pode ser utilizado num único período de avaliação do Identiguard. Se o tenant já tiver sido utilizado noutro período de avaliação, o Identiguard cria-o na mesma, mas não aceita os seus eventos. A página Tenants mostra então a faixa Some tenants are not being monitored on this trial (alguns tenants não estão a ser monitorizados neste período de avaliação) com o nome do tenant. Consulte Estado de saúde dos tenants.
Resolução de problemas
Seção intitulada “Resolução de problemas”Os erros de campo aparecem a vermelho por baixo do campo. Os outros erros aparecem como um toast vermelho. Um toast que começa por Failed to create tenant: (falha ao criar o tenant) vem do servidor.
Validação do formulário
Seção intitulada “Validação do formulário”| O que vê | Porquê | O que fazer |
|---|---|---|
| “Only workspace admins can create tenants.” e um botão Admin Access Required desativado | A sua função é membro ou visualizador | Peça a um admin do workspace que crie o tenant. |
| “Tenant name cannot be empty”, “Tenant name must be 100 characters or fewer” ou “Tenant name cannot contain line breaks or control characters” (o nome do tenant não pode estar vazio, tem de ter 100 caracteres ou menos, ou não pode conter quebras de linha nem caracteres de controlo) | O nome do tenant não cumpre uma regra | Corrija o nome. |
| “Customer name is required” (o nome do cliente é obrigatório) | Customer Name está em branco | Introduza o cliente. |
| “Auth0 domain is required” (o domínio do Auth0 é obrigatório) | Auth0 Domain está em branco | Introduza o domínio canónico. |
| “Enter the canonical Auth0 tenant domain (e.g., acme.eu.auth0.com)” (introduza o domínio canónico do tenant do Auth0) | O domínio tem um caminho ou um espaço, ou não é um domínio | Introduza apenas o domínio canónico, não um domínio personalizado nem um URL. |
| “Environment is required” (o ambiente é obrigatório) | Nenhum ambiente está escolhido | Escolha Production ou Development. |
| “At least one event type must be selected” (tem de estar selecionado pelo menos um tipo de evento) | Nada está assinalado | Assinale pelo menos um tipo, ou escolha Select Recommended. |
| “Invalid event type submitted” (foi enviado um tipo de evento inválido) | A página enviou um código que não está na lista permitida | Recarregue a página e selecione de novo. |
| “Select at least one field to obscure, or choose None” (selecione pelo menos um campo a ocultar, ou escolha None) | Configuração por Terraform. Escolheu XXHash ou Mask mas não assinalou nenhum campo. | Assinale pelo menos um campo, ou escolha None - stream in clear text. |
Erros de criação
Seção intitulada “Erros de criação”| O que vê | Porquê | O que fazer |
|---|---|---|
| “Failed to create tenant: The <Plan> plan allows up to N tenants per workspace, and this workspace already has M. Upgrade the plan to add more.” (o plano permite até N tenants por workspace, e este workspace já tem M; atualize o plano para adicionar mais) | O workspace atingiu o limite de tenants do plano | Elimine um tenant de que já não precise, ou atualize o plano. Consulte Planos e faturação. |
| “The tenant was created, but no ingestion endpoint was returned. Delete the tenant and try again.” (o tenant foi criado, mas não foi devolvido nenhum endpoint de ingestão; elimine o tenant e tente de novo) | O tenant foi guardado mas falta o endpoint ou o token | Elimine esse tenant na página Tenants e crie-o de novo. |
| “Failed to create tenant: Failed to store Auth0 tenant.” (falha ao guardar o tenant do Auth0) | Não foi possível guardar o tenant | Tente de novo. Escale se se repetir. |
| “Forbidden: You do not have permission to create tenants.” (proibido: não tem permissão para criar tenants) | A sua função mudou enquanto a página estava aberta | Peça a um admin do workspace. |
| “Failed to create tenant: Bad Request” (pedido inválido) | O servidor rejeitou o formulário | Verifique de novo todos os campos. Escale se continuar. |
| “Failed to create tenant: API error” ou “An unexpected error occurred: …” (erro da API, ou ocorreu um erro inesperado) | Um erro inesperado | Tente de novo e depois escale para a equipa de produto. |
| “Failed to create tenant: Server configuration error…” (erro de configuração do servidor) | Um problema da plataforma | Escale para um operador da plataforma. |
| “Could not copy; select the text and copy it manually.” (não foi possível copiar; selecione o texto e copie-o manualmente) | O browser bloqueou o acesso à área de transferência | Selecione o valor com o rato e copie-o manualmente. |
Depois da criação
Seção intitulada “Depois da criação”| O que vê | Porquê | O que fazer |
|---|---|---|
| Nenhum evento depois de criar o stream, e nenhuma mensagem | O token foi colado de forma errada, o stream está em pausa no Auth0, ou o evento é de um tipo que não está assinalado no Identiguard | No Auth0, verifique o estado do stream e o respetivo valor de Authorization. No Identiguard, verifique os tipos assinalados em Event Subscriptions. |
| Perdeu o token do log stream | O token é mostrado uma única vez e não pode ser emitido de novo | Elimine o tenant e crie-o de novo. Consulte Rodar credenciais. |
| Faixa Some tenants are not being monitored on this trial | Este tenant do Auth0 já foi utilizado noutro período de avaliação do Identiguard. Os seus eventos não são aceites. | Escolha Go to the Billing page e escolha um plano, ou contacte o suporte do Identiguard. |
| API Metrics mostra Stale ou “nothing received yet” (ainda nada recebido) | O metric stream não está a entregar dados | Consulte Métricas de API do Auth0. |
| As linhas de uma Action não chegam | O segredo IDENTIGUARD_TOKEN está em falta ou errado, a linha está no nível info, ou a linha perdeu-se quando a Action terminou |
Verifique o segredo na Action. Envie uma linha de teste no nível warn. |
| Os eventos continuam a aparecer como falhas no estado do stream do Auth0 depois de ter eliminado o tenant | O stream no Auth0 ainda aponta para um endpoint revogado | Elimine o stream no Auth0, ou execute terraform destroy. |