Introdução
Empresas que usam Affilentra self‑hosted frequentemente precisam de autenticação central via SSO (SAML ou OIDC) para unificar a gestão de utilizadores, a conformidade e a usabilidade. Este guia mostra como ligar o Affilentra de forma a separar claramente as funções, provisionar utilizadores automaticamente e gerir com segurança os ciclos de vida de sessões e tokens. Prático, orientado por funções e diretamente aplicável.
Visão geral: Por que SSO no Affilentra?
O Affilentra oferece uma arquitetura de funções com três atores centrais: operador de software (gestor da plataforma), comerciantes (Merchants) e parceiros (Publisher/Creator). O SSO traz três vantagens: gestão central de identidade, controlo de acesso consistente e auditorias simplificadas. No modo self‑hosted mantém o controlo total (licença perpétua, sem partilha de receitas) e ainda assim integra com infraestruturas IdP existentes.
Requisitos e decisões de arquitetura
- Escolha o IdP: SAML‑IdP (p.ex. ADFS, Shibboleth) ou OIDC/OAuth‑Provider (p.ex. Keycloak, Auth0, Azure AD).
- Decida o modelo de autenticação: apenas IdP (central) ou modo híbrido (conta local como fallback).
- Prepare caminhos de ligação seguros: HTTPS, certificados atualizados, sincronização de tempo/relogio.
Passos para a integração SAML
1) Troca de metadados: Crie metadados do Service Provider (SP) do Affilentra (EntityID, URL do Assertion Consumer Service, formato NameID desejado) e importe os metadados do IdP para o Affilentra.
2) Assinatura & encriptação: Ative a verificação de assinatura das Assertions e valide os certificados de assinatura do IdP por fingerprint/PEM. Se disponível, utilize Assertions encriptadas.
3) Definir atributos: Peça ao IdP para enviar estes atributos:
- uid ou sub – identificador único do utilizador
- email – contacto/chave primária para matching
- roles ou entitlement – funções/grupos
- givenName / sn – informações para apresentação
4) Mapeamento no Affilentra: Configure no Affilentra como os atributos se tornam funções internas (ver mapeamento de funções mais abaixo). Ative opcionalmente o Just‑In‑Time‑Provisioning, para que novos utilizadores sejam criados automaticamente com permissões base.
5) Testes: Valide o conteúdo da Assertion, as janelas de tempo (NotBefore/NotOnOrAfter) e verifique o logout (iniciado pelo IdP / iniciado pelo SP).
Passos para a integração OIDC
1) Discovery & credenciais: Insira Client‑ID, Client‑Secret e Redirect URI tanto no IdP quanto no Affilentra. Utilize o .well‑known/openid-configuration para automatizar.
2) Scopes & claims: Solicite pelo menos openid e profile/email. Claims adicionais para funções: roles, groups ou claims personalizados via UserInfo.
3) Validação do ID Token: Verifique issuer, audience (client_id), nonce (no Authorization Code Flow opcional se SPA) e assinatura (JWKs).
4) Gestão de tokens: Use Authorization Code Flow com PKCE para clientes web e Refresh Tokens rotativos para sessões longas (veja Token‑Lifecycle).
5) Provisionamento & Mapeamento: Assim que o ID Token / UserInfo estiver disponível, mapeie os claims para contas de utilizador internas tal como no SAML.
Mapeamento de funções: Atribuição precisa no Affilentra
O objetivo: Cada função externa resulta de forma determinística numa função interna com permissões adequadas.
- Operador do software: Atribua esta função apenas se o IdP fornecer o claim admin_level ou uma pertença a um grupo específico. Operadores do software têm permissões de administrador em toda a plataforma – essa atribuição deve ser rigorosamente verificada e limitada a poucos grupos do IdP.
- Comerciante (Merchant): Mapeie grupos do IdP ou um claim merchant_id → conta de comerciante interna. Contas de comerciantes devem estar ligadas a um objeto Merchant separado no Affilentra.
- Parceiro: Funções de parceria (partner, publisher) devem conter um claim partner_id ou affiliation. Parceiros recebem links de tracking pessoais e acesso ao histórico de pagamentos – esse mapeamento é muito granular.
Regras práticas:
- Prioridade em caso de múltiplas funções: Defina uma hierarquia (por ex. Operador do software > Comerciante > Parceiro) ou permita ligação a várias contas.
- Ligação: Utilize sub/uid + email para correspondência. Se já existir uma conta local, ofereça um fluxo de ligação/cross‑match em vez de criar uma nova conta.
- Menor privilégio: Por padrão atribua apenas a função básica; direitos avançados via grupos do IdP ou revisão manual.
Gerir com segurança o ciclo de vida de sessões e tokens
O controlo seguro das sessões é crucial para que o SSO não se torne um ponto fraco.
Access Tokens
- Curta duração: Access Tokens devem ter vida curta (por ex. minutos a poucas horas).
- Validação: Validação server‑side (assinatura, aud, exp) em cada pedido relevante.
Refresh Tokens
- Rotação: Implemente refresh tokens rotativos para que tokens comprometidos fiquem inválidos.
- Armazenamento seguro: Armazene Refresh Tokens apenas do lado do servidor ou em cookies HttpOnly, Secure; evite armazenamento no lado do cliente em webapps.
Sessões
- Armazenamento de sessão server‑side: Prefira um armazenamento de sessão centralizado e encriptado (Redis, DB) em vez de depender apenas de JWT para sessões longas.
- Timeouts Idle vs. Absoluto: Combine um idle‑timeout (por ex. 30–60 min) e um timeout absoluto (por ex. várias horas/dias) conforme os requisitos de segurança.
Logout & Revogação
- RP‑initiated Logout: Implemente redirecionamentos para o endpoint de Logout do IdP e elimine sessões locais.
- IdP‑initiated SLO: Suporte SAML Single Logout ou OIDC Front/Backchannel Logout para uma saída centralizada.
- Token Revocation: Utilize os endpoints de revogação de tokens do IdP, quando necessário em caso de revogação de utilizador ou comprometimento.
Segurança & Operação
- Monitorização & Auditoria: Registe logins, conteúdos de Assertion/ID Token (não sensíveis), revogações de tokens e eventos de provisionamento. Mantenha um rasto de auditoria para rastreabilidade.
- Sincronização de Relógio: Garanta NTP; verificações de autenticação são sensíveis ao tempo.
- Privilégio Mínimo para Admins: Poucas contas com privilégios de plataforma; exigir Autenticação Multi‑Fator (MFA) para administradores.
- Testes: Teste failover (falha do IdP), desvio de tempo, variações de claims e atributos inesperados.
Exemplo prático: Fluxo típico de integração
- Selecionar o IdP e exportar metadados/configuração.
- Criar SP/Cliente na Affilentra, inserir URL de Redirect/ACS, armazenar certificados.
- Configurar mapeamento de atributos na Affilentra: sub → extern_id, email → email, roles → role.
- Ativar Just‑In‑Time Provisioning + definir direitos iniciais.
- Configurar política de Token/Sessão (lifetimes, rotação de refresh, gestão de logout).
- Testar end‑to‑end com pelo menos uma conta de operador de software, comerciante e parceiro.
- Ativar e documentar o logging de auditoria.
Vantagem da Affilentra na Integração SSO
Affilentra (PRO & NETWORK Editionen, self‑hosted, Dauerlizenz) fornece a estrutura de plataforma baseada em papéis e os hooks para provedores SAML/OIDC. A separação clara entre operador de software, comerciante e parceiro facilita o mapeamento de papéis, e a instalação self‑hosted dá‑lhe controlo total sobre o armazenamento de tokens, políticas de sessão e auditorias sem partilha de receitas.
Conclusão e próximo passo
A integração de SAML ou OIDC na Affilentra oferece funcionalidades seguras e escaláveis de Single Sign‑On, preservando a separação de papéis entre operador da plataforma, comerciantes e parceiros. O foco em mapeamento correto de claims/atributos, Access Tokens de curta duração, estratégias seguras de Refresh Tokens e processos abrangentes de auditoria reduz riscos e aumenta a segurança operacional.
Comece agora: Decida a arquitetura de autenticação desejada e escolha o seu ponto de entrada – escolher entrada: https://affilentra.de
Em caso de dúvidas sobre a configuração concreta na sua infraestrutura, a Affilentra oferece suporte técnico de integração para instalações self‑hosted.
Próximo passo
Experimentar a Affilentra
Plataforma unificada que integra de forma transparente a disponibilização de produtos, o rastreio, a validação de conversões, o cálculo de comissões e os pagamentos ao longo de papéis claramente separados; opção de instalação auto-hospedada com licença perpétua sem participação nas receitas; os comerciantes mantêm o controlo sobre produtos, condições e materiais promocionais; os parceiros recebem links de rastreio pessoais e um histórico de pagamentos transparente.