Introduction
Companies that deploy Affilentra self-hosted often require centralized authentication via SSO (SAML or OIDC) to unify user management, compliance and user experience. This guide shows how to connect Affilentra so roles are clearly separated, users are provisioned automatically, and session/token lifecycles are securely managed. Practical, role-oriented and directly actionable.
Overview: Why SSO in Affilentra?
Affilentra offers a role architecture with three central actors: software operator (platform operator), merchants and partners (publishers/creators). SSO brings three benefits: centralized identity management, consistent access control and simplified audits. With self-hosted operation you retain full control (perpetual license, no revenue share) while still connecting to existing IdP infrastructures.
Prerequisites and Architectural Decisions
- Choose the IdP: SAML IdP (e.g. ADFS, Shibboleth) or OIDC/OAuth provider (e.g. Keycloak, Auth0, Azure AD).
- Decide the authentication model: IdP-only (central) or hybrid mode (local account as fallback).
- Prepare secure connection paths: HTTPS, up-to-date certificates, time/clock sync.
Steps for SAML Integration
1) Exchange metadata: Create Affilentra Service Provider (SP) metadata (EntityID, Assertion Consumer Service URL, desired NameID format) and import IdP metadata into Affilentra.
2) Signature & encryption: Enable signature verification of assertions and verify IdP signing certificates by fingerprint/PEM. If available, use encrypted assertions.
3) Define attributes: Ask the IdP to send these attributes:
- uid or sub – unique user identifier
- email – contact/primary key for matching
- roles or entitlement – roles/groups
- givenName / sn – display information
4) Mapping in Affilentra: Configure in Affilentra how attributes map to internal roles (see role mapping below). Optionally enable just-in-time provisioning so new users are created automatically with base permissions.
5) Tests: Validate assertion contents, time window (NotBefore/NotOnOrAfter), and check logout (IdP-initiated / SP-initiated).
Steps for OIDC Integration
1) Discovery & credentials: Enter client ID, client secret and redirect URI in the IdP and in Affilentra. Use the .well-known/openid-configuration for automation.
2) Scopes & claims: Request at minimum openid and profile/email. Additional claims for roles: roles, groups or custom claims via the UserInfo endpoint.
3) ID Token validation: Verify issuer, audience (client_id), nonce (for Authorization Code Flow optional if SPA) and signature (JWKs).
4) Token management: Use Authorization Code Flow with PKCE for web clients and rotating refresh tokens for longer sessions (see Token Lifecycle).
5) Provisioning & Mapping: Once ID Token / UserInfo is available, map claims to internal user accounts as with SAML.
Role Mapping: Precise Assignment in Affilentra
The goal: Each external role deterministically maps to an internal role with appropriate permissions.
- Platform Operator: Assign this role only if the IdP provides an admin_level claim or a specific group membership. Platform operators have platform-wide admin rights — this mapping should be strictly audited and limited to a few IdP groups.
- Merchant: Map IdP groups or a merchant_id claim → internal merchant account. Merchant accounts must be bound to a separate Merchant object in Affilentra.
- Partner: Partnership roles (partner, publisher) should include a partner_id or affiliation claim. Partners receive personal tracking links and access to payout history — this mapping should be fine-grained.
Practical rules:
- Priority for multiple roles: Define a hierarchy (e.g. Platform Operator > Merchant > Partner) or allow multi-account linking.
- Linking: Use sub/uid + email for matching. If a local account already exists, offer a link/match workflow instead of creating a new account.
- Least privilege: By default assign only a base role; extended rights via IdP groups or manual review.
Securely Managing Session and Token Lifecycles
Secure session control is critical so that SSO does not become an attack surface.
Access Tokens
- Short-lived: Access tokens should be short-lived (e.g. minutes to a few hours).
- Validation: Server-side validation (signature, aud, exp) on every relevant request.
Refresh Tokens
- Rotation: Implement rotating refresh tokens so compromised tokens become invalid.
- Secure storage: Store refresh tokens only server-side or in HttpOnly, Secure cookies; avoid client-side storage for web apps.
Sessions
- Server-side session store: Prefer a central, encrypted session store (Redis, DB) instead of pure JWTs for long sessions.
- Idle vs. absolute timeout: Combine an idle timeout (e.g. 30–60 min) and an absolute timeout (e.g. several hours/days) according to security requirements.
Logout & Revocation
- RP-initiated Logout: Implement redirects to the IdP Logout Endpoint and clear local sessions.
- IdP-initiated SLO: Support SAML Single Logout or OIDC Front/Backchannel Logout for centralized sign-out.
- Token Revocation: Use the IdP's Token Revocation Endpoints when necessary, e.g., on user revocation or compromise.
Security & Operations
- Monitoring & Audit: Log logins, assertion/ID token contents (non-sensitive), token revocations and provisioning events. Maintain an audit trail for traceability.
- Clock Sync: Ensure NTP; authentication checks are time-sensitive.
- Least Privilege for Admins: Keep only a few accounts with platform-wide rights; enforce Multi-Factor Authentication (MFA) for admins.
- Testing: Test failover (IdP outage), time skew, claim variations and unexpected attributes.
Practical Example: Typical Integration Workflow
- Select the IdP and export metadata/configuration.
- Create an SP/Client in Affilentra, enter Redirect/ACS URL, and upload certificates.
- Configure attribute mapping in Affilentra: sub → extern_id, email → email, roles → role.
- Enable Just-In-Time provisioning + set initial permissions.
- Configure token/session policy (lifetimes, refresh rotation, logout handling).
- End-to-end test with one platform-operator, merchant and partner account each.
- Enable and document audit logging.
Affilentra Advantage in SSO Integration
Affilentra (PRO & NETWORK editions, self-hosted, perpetual license) provides the role-based platform structure and the hooks for SAML/OIDC providers. The clear separation of platform operator, merchant and partner simplifies role mapping, and the self-hosted installation gives you full control over token storage, session policies and audits without revenue sharing.
Conclusion and Next Step
Integrating SAML or OIDC into Affilentra offers secure, scalable Single Sign-On capabilities while preserving role separation between platform operators, merchants and partners. Focusing on correct claim/attribute mapping, short-lived access tokens, secure refresh token strategies and comprehensive audit processes reduces risks and increases operational reliability.
Start now: Decide on the desired authentication architecture and choose your entry point – choose an entry: https://affilentra.de
If you have questions about the specific configuration in your infrastructure, Affilentra offers technical integration support for self-hosted installations.
Next step
Try Affilentra yourself
Unified platform that transparently brings together product provisioning, tracking, conversion validation, commission calculation and payout across clearly separated roles; option for self-hosted installation with a perpetual license without revenue sharing; merchants retain control over products, terms and promotional materials; partners receive personal tracking links and a transparent payout history.