Onboarding tenant — playbook A→Z (SaaS et on-prem)

Audience : équipe Customer Success VitaKYC (CSM), équipe DSI tenant banque/fintech, sponsor compliance tenant.

Pages liées : Sanctions admin UI, Runbook SRE Sanctions, Mobile SDK, DPIA, BCP/DR.

Mode SaaS : déploiement géré par VitaKYC sur cloud souverain Tunisie (Sotetel) ou région UE (OVH/Scaleway). Mode on-prem : déploiement chez le tenant avec accompagnement VitaKYC.

Ce document fixe le playbook d’onboarding d’un nouveau tenant VitaKYC, de la signature contrat jusqu’au go-live production. Il s’adresse à un CSM VitaKYC qui pilote l’intégration et au DSI tenant qui finance / valide les étapes.

1. Calendrier type

Semaine 1-2   : Cadrage + pré-requis
Semaine 3-4   : Provisioning + setup infra
Semaine 5-6   : Configuration métier (CPS, listes, règles)
Semaine 7-8   : Tests d'intégration + formation agents
Semaine 9     : Pilote shadow (1 % traffic)
Semaine 10    : Pilote 5 % traffic
Semaine 11    : Ramp-up 25 % puis 100 %
Semaine 12    : Stabilisation + signature PV de réception

Segment tenant	Durée typique	Effort jours/personne VitaKYC	Effort jours/personne tenant
Fintech / startup (1-3 produits)	6-8 semaines	CSM 15 j + ingé 8 j	DSI 10 j + compliance 5 j
Banque retail tier-2 MENA	8-12 semaines	CSM 25 j + ingé 20 j	DSI 30 j + compliance 15 j
Banque tier-1 / multi-pays	12-16 semaines	CSM 40 j + ingé 35 j + archi 10 j	DSI 60 j + compliance 30 j + ops 20 j
PSP / e-money	6-10 semaines	CSM 20 j + ingé 12 j	DSI 15 j + compliance 8 j

2. Pré-requis tenant

2.1 Hardware (mode on-prem)

Profil	RAM totale	vCPU	Stockage	GPU	Réseau
Léger (≤ 100 K vérifs/an, listes publiques only)	24 GB	8 vCPU	200 GB SSD	non	100 Mbps
Standard (≤ 1 M vérifs/an, DJ activé)	64 GB	16 vCPU	1 TB SSD	non	500 Mbps
Banque tier-1 (≥ 5 M vérifs/an, HA 3 nœuds)	192 GB (3×64)	48 vCPU (3×16)	3 TB SSD	optionnel pour ML	1 Gbps + redondance
Banque tier-1 multi-pays	384 GB+	96 vCPU+	6 TB+	recommandé	10 Gbps

Détails par sous-service (mode standard) :

kafka: 8 GB heap, 200 GB SSD pour 30 j retention
postgres: 8 GB shared_buffers, 500 GB SSD HA 1 primary + 1 replica
opensearch (sanctions DJ): 16 GB heap, 30 GB SSD
vault: 4 GB heap, 50 GB SSD
temporal: 4 GB heap, 50 GB SSD
bio-svc + ocr-svc + face-match-svc + tx-monitoring-svc + form-runtime + case-mgmt + sanctions + risk-matrix + webhook-svc: 4 GB heap chacun

2.2 Réseau

Sortant Internet (mode SaaS) : *.vitakyc.io ports 443 (API REST + webhooks), 9092 (Kafka mTLS)
Mode on-prem : air-gap supporté pour le cœur. Sortant requis seulement pour : MAJ listes sanctions free (HTTPS publiques), SDK Web CDN si activé, providers liveness commerciaux (si configurés)
Latence interne entre core banking et tx-monitoring-svc : ≤ 50 ms (sinon impact SLA streaming)
DNS : sous-domaine tenant délégué (kyc.{banque}.tn CNAME vers tenant.vitakyc.io en SaaS, ou nœud interne en on-prem)
Certificats : tenant fournit cert wildcard pour *.kyc.{banque}.tn ou utilise Let’s Encrypt managé

2.3 IdP (SSO + MFA)

VitaKYC supporte OIDC standard. Tenant doit fournir :

IdP URL (https://idp.banque.tn/.well-known/openid-configuration)
Client ID + secret (créés par tenant pour VitaKYC)
Mapping rôles : groupes IdP → rôles VitaKYC (agent_l1, agent_l2, mlro, dsi_admin, auditor, developer)
MFA obligatoire pour rôles ≥ L2 (TOTP, WebAuthn, ou push mobile selon IdP)

Si tenant n’a pas d’IdP : VitaKYC fournit Keycloak managé.

2.4 Données de référence

Tenant doit fournir avant la fin de S2 :

Liste des produits / segments client (ex retail, pro, crédit, leasing, jeune, expat) — chacun aura sa policy de risk + son form
Catalogue de pays où le tenant opère + liste interne high-risk countries (en supplément des listes publiques)
Catalogue de professions + classification interne high-risk (PEP local, professions liées à argent liquide, etc.)
Liste agents compliance : nom, email, rôle (L1/L2/MLRO), skills (PEP, FATCA, CRYPTO, RETAIL, CORPORATE, TRANSACTION)
Politique d’escalade : seuils SLA + 4-eyes thresholds + montant transaction → escalade
Branding : logo SVG transparent ≥ 200×60 px, palette HSL, police custom optionnelle
i18n : langues activées tenant (FR/AR/EN par défaut MENA)

3. Étape 1 — Cadrage (semaine 1-2)

3.1 Atelier de cadrage initial (1/2 journée)

Participants : CSM VitaKYC + DSI tenant + sponsor compliance + 1 représentant ops/SRE.

Agenda :

Confirmation périmètre : modules activés (KYC, AML batch, AML streaming, sanctions, biométrie, e-signature)
Mode déploiement : SaaS / on-prem / hybride
Volume cible : vérifs/jour, transactions/jour, comptes actifs
Intégration core banking : Temenos / Finastra / Mambu / Sopra / autre, format (REST API, fichiers batch CSV/SWIFT, Kafka)
Workflows tenant-specific : segments client + parcours différenciés
Contraintes réglementaires : BCT (TN) / ACPR (FR) / DGI / autres
Calendrier go-live cible : date business critique (ex prochain audit BCT, lancement produit)

3.2 Document de cadrage signé

Sortie : vitakyc-onboarding-{tenantId}.md co-signé. Contenu :

Modules activés + tarification
SLA de support
Calendrier détaillé S1-S12
RACI (cf §10)
Points d’attention identifiés
Risques + mitigation

3.3 Pré-requis envoyés au tenant

CSM envoie via mail signé un document tenant-prerequisites.md avec checklist hardware/réseau/IdP/données de référence (cf §2). Tenant doit valider avant fin S2.

4. Étape 2 — Provisioning + setup infra (semaine 3-4)

4.1 Mode SaaS

Côté VitaKYC :

Création tenant dans tenant-management-svc (UUID + métadonnées)
Provisioning Postgres schema + RLS policies + seed data
Provisioning OpenSearch index sanctions_{tenantId}
Provisioning Kafka topics partitionnés tenantId
Provisioning Vault paths tenant/{tenantId}/* + génération keys (KEK + Ed25519 signing keys + webhook secret + tenant API keys)
Configuration DNS + cert TLS (Let’s Encrypt managé)
Setup SSO via OIDC tenant (test auth round-trip)
Création comptes initiaux : 1 admin DSI + 2 agents test
Setup monitoring tenant : dashboards Grafana cluster + métriques tenant-isolated

Côté tenant :

DNS CNAME kyc.banque.tn → tenant.vitakyc.io validé
Whitelist IPs sortant *.vitakyc.io ports 443
Création groupes IdP (vitakyc_agent_l1, …, vitakyc_dsi_admin)
Test login agent via SSO → écran VitaKYC

Validation S4 : agent admin tenant peut se connecter via SSO et voir le dashboard vide.

4.2 Mode on-prem

Côté tenant :

Hardware provisionné selon profil (cf §2.1)
OS installé : Ubuntu 22.04 LTS ou RHEL 9
Kubernetes ou Docker Swarm installé (recommandé K8s)
Storage class SSD configurée (Longhorn / Rook-Ceph / OpenEBS)
Réseau interne configuré (CNI Calico ou Cilium)
DNS interne tenant kyc.banque.tn résolvant vers ingress controller

Côté VitaKYC :

Helm chart vitakyc-core v1.x livré au tenant via tarball signé GPG
Installation guidée : helm install vitakyc-core ... (template values.yaml prérempli avec choix segments)
Vault mode HA initialisé : vault operator init -recovery-shards=5 (5 shards, 3 requis pour unseal)
Postgres bootstrap + migrations Flyway
Smoke tests : vitakyc-cli health-check doit retourner OK sur tous services
Mode air-gap : push images Docker via pct push ou registry interne tenant

Validation S4 : vitakyc-cli system-info retourne version + config + health OK.

5. Étape 3 — Configuration métier (semaine 5-6)

5.1 CPS — Client Profile Schema initial

CSM + intégrateur tenant définissent le ClientProfileSchema initial via UI form designer (cf CPS spec) :

Variables canoniques par segment (retail, corporate, etc.)
Catalogue d’enums (BCT_PROFESSION_CODES, ISO3166, segments tenant)
Mapping aux champs core banking (T24 fields → CPS paths)

5.2 Form Designer — formulaires KYC initiaux

Pour chaque segment, créer un form via UI Designer :

Étapes (identité, doc, biométrie, FATCA, consentement, signature)
Champs avec mapping CPS obligatoire (cf ADR-026)
Règles de visibilité conditionnelle
Traductions FR/AR/EN
Branding logo + couleurs
Publication v1.0.0 avec dual-control

Templates pré-livrés : retail TN, fintech wallet, crédit conso, corporate, expat. CSM personnalise selon tenant.

5.3 Risk Matrix — politique de risque initiale

CSM aide tenant à définir :

5 dimensions (client, geo, product, channel, aml_screening)
Pondérations (somme = 1.0 enforced)
Thresholds LOW/STANDARD/HIGH/PROHIBITED
Overrides (mustProhibit OFAC + pays sanctionnés, mustHigh PEP + adverse media)
Backtest sur 1 000 dossiers historiques tenant (si disponibles)
Publication en SHADOW pendant S6-S7, switch ACTIVE en S8

Référence : Playbook Risk Matrix BCT.

5.4 Sanctions screening — listes activées

Activer les listes publiques par défaut (OFAC SDN, UN, EU, UK, World Bank, OpenSanctions)
Si tenant a souscrit DJ : activer adapter Dow Jones (cf ADR-030 — détails à fournir par tenant)
Configurer thresholds par typologie (cf Sanctions admin UI 12.3)
Force refresh initial des 7 listes
Cron calendar planifié dimanche 02:00 + delta quotidien 06:00

5.5 AML rules

Activer les 5 typologies MVP (structuring, velocity, threshold high-risk, pass-through, aggregate WIRE)
Calibrer thresholds par tenant (montant, période, ratio baseline)
Mode SHADOW pendant 14 j minimum (cf ADR-031)
Backtest 6 mois historique tx tenant
Dual-control activation S+10

5.6 Webhooks

Configurer URLs côté tenant pour les 6 event types (cf Webhooks spec)
Générer secret HMAC tenant
Test endpoint via POST /v1/webhooks/test pour valider chaque URL
Déploiement code de vérification HMAC côté tenant (Node/Python/Java/PHP selon stack)

5.7 Case Management

Créer agents profiles (skills, seniority, max load)
Configurer SLA par priorité (URGENT 1h, HIGH 4h, STANDARD 24h, LOW 7j)
Configurer 4-eyes policy (montant > seuil, PEP, URGENT, REJECTED toujours)
Configurer escalade ladder (75 % NOTIFY_AGENT, 100 % NOTIFY_MANAGER, 125 % AUTO_ESCALATE_L2, 200 % AUTO_ESCALATE_MLRO)

5.8 Mobile SDK (si activé)

Choix tenant resolution mode : SaaS embedded / on-prem gateway / PWA fallback / hybride (cf ADR-024)
Distribution SDK : NPM tenant package, Maven enterprise, Swift PM enterprise
Cert pinning configuration
App banque rebranded ou app standalone selon choix

6. Étape 4 — Tests d’intégration + formation (semaine 7-8)

6.1 Tests E2E

Test parcours client complet : capture identité → bio → AML screening → risk evaluation → case si HIGH → décision agent
Test cross-tenant isolation (RLS Postgres + index OpenSearch séparés)
Test resilience : kill un pod, vérifier reprise sans perte de données
Test webhook : émis, retry sur 503, FAILED après 24 h
Test 4-eyes : impossible de bypasser
Test audit chain : verify integrity sur 1 000 events
Test backup/restore : snapshot OpenSearch + Postgres PITR
Load test : 1 000 vérifs/min, 10 000 tx/s sur tx-monitoring

6.2 Formation agents

Public	Durée	Sujet
Agent L1 (5-15 personnes)	4 h	UI Workflow 11 (Review Queue) + Workflow 13 (AML alerts) + procédure interne tenant
Agent L2 + MLRO	6 h	+ 4-eyes confirmation + escalade + génération STR goAML
DSI admin	4 h	UI Workflows 12 + 4 (Sanctions admin + Form Designer) + monitoring
Compliance officer	4 h	Risk Matrix + Sanctions config + audit search + reporting BCT
Auditeur interne	2 h	UI lecture seule + chaîne de hash + export PDF

Sortie : tous les agents ont un compte créé + ont validé le parcours formation (badge interne).

6.3 Documentation tenant

CSM fournit :

Manuel utilisateur agents (PDF FR/AR/EN, ~50 pages)
Manuel admin DSI (PDF, ~30 pages)
Quick reference cards (1 page A4) par rôle
Vidéos formation 5-10 min par workflow

7. Étape 5 — Pilote (semaine 9-11)

7.1 Phase shadow (S9, ~1 % traffic)

Tenant active VitaKYC en parallèle de son système actuel
Tx réel envoyées en double : système actuel produit la décision, VitaKYC fait shadow
Comparaison verdict système actuel vs VitaKYC sur 100-500 cas
Calibration finale des thresholds Risk Matrix + Sanctions
Ajustement règles AML

Critère de succès S9 : ≥ 95 % concordance verdict ; faux positifs < 8 %.

7.2 Phase 5 % traffic (S10)

5 % du nouveau parcours KYC routé vers VitaKYC (selon hash client_id par exemple)
Monitoring temps réel (Grafana cluster)
Daily standup tenant + VitaKYC pour analyser les cas litigieux
Ajustements à la volée

Critère de succès S10 : 0 incident P1 ; SLA respect ≥ 90 % ; satisfaction agents NPS ≥ 7/10.

7.3 Phase ramp-up 25 % puis 100 % (S11)

Bascule 25 % → 50 % → 100 % sur 1 semaine
Système actuel gardé en standby (rollback possible 24 h)
Communication interne tenant aux équipes commerciales

Critère de succès S11 : tous les KPI cibles atteints, signature PV de réception.

8. Étape 6 — Stabilisation + signature PV (semaine 12)

Signature PV de Réception Définitive (PVRD) par DSI + sponsor compliance + CSM
Bascule du support de “Customer Success” (Tier 1 setup) vers “Support production” (Tier 2 ops)
Définition du modèle de support continu :
- SLA P1 (réponse < 15 min, résolution < 1 h pour banque tier-1)
- SLA P2 (1 h / 4 h)
- SLA P3 (4 h / 24 h)
- SLA P4 (24 h / 5 j)
Calendrier des revues récurrentes :
- Daily standup tenant ↔ VitaKYC (S+13 → S+16)
- Weekly review (S+13 → fin trimestre 1)
- Monthly business review (steady state)
- Quarterly review trimestrielle avec KPIs business

9. Checklist consolidée (60 items)

Cadrage S1-S2

Atelier de cadrage tenu (DSI + sponsor compliance + CSM + ingé)
Document de cadrage signé
Pré-requis envoyés au tenant (hardware/réseau/IdP/données)
Calendrier détaillé validé
RACI signé (cf §10)

Provisioning S3-S4

Configuration métier S5-S6

Tests + formation S7-S8

Pilote S9-S11

Phase shadow ≥ 95 % concordance
Phase 5 % traffic 0 incident P1
Phase ramp-up 25 % → 50 % → 100 %
SLA respect ≥ 90 %
Satisfaction agents NPS ≥ 7/10
DPIA tenant validé (cf DPIA)
BCP/DR testé (cf BCP/DR)

Go-live S12

PV de Réception Définitive signé
Bascule vers support production
SLA support défini
Daily/Weekly/Monthly cadence définie
Premier rapport BCT généré (si applicable)
Post-mortem onboarding rédigé

10. RACI VitaKYC ↔ Tenant

Activité	VitaKYC CSM	VitaKYC Ingé	DSI tenant	Compliance tenant	Ops tenant
Cadrage initial	A	C	R	R	C
Pré-requis hardware/réseau	I	C	R/A	C	R
Provisioning SaaS	R/A	C	I	I	I
Provisioning on-prem	C	A	R	I	R
Setup SSO	C	C	R/A	I	C
CPS initial	A	C	C	R	I
Form Designer initial	A	C	C	R	I
Risk Matrix initiale	A	C	I	R/A	I
Configuration AML	A	C	I	R/A	I
Webhooks setup	C	C	R/A	I	C
Tests E2E	C	A	R	C	R
Formation agents	R/A	C	I	C	I
Pilote shadow	C	C	A	R	R
Ramp-up 100 %	C	C	A	R	R
Support production	A	R	C	C	C
Reporting BCT	C	I	C	R/A	I

R = Responsable / A = Approbateur / C = Consulté / I = Informé.

11. SLA support après go-live

Sévérité	Définition	Réponse cible	Résolution cible
P1 critique	service inutilisable, audit chain rompue, RGPD breach, fuite PII	15 min (24/7)	1 h (banque tier-1) / 4 h (autres)
P2 élevé	dégradation majeure, > 30 % vérifs en erreur, SLA breach	1 h	4 h
P3 medium	bug fonctionnel, dégradation mineure	4 h	24 h
P4 faible	demande d’évolution, question	24 h	5 jours ouvrés

Disponibilité contractuelle : 99,5 % MVP, 99,9 % V2 (banque tier-1). Pénalités si dépassement (cf contrat).

12. Points d’attention typiques

Risque	Mitigation
Données core banking pas exhaustives (champs obligatoires CPS manquants)	Atelier dédié S3 avec ingés tenant + plan de complétion progressive
IdP tenant exotique (LDAP propriétaire, AD legacy)	Évaluation S2, prévoir Keycloak managé en relais si besoin
Volume sous-estimé	Audit S2 avec données réelles 30 j tenant, ajustement profil hardware
Lenteur décisionnelle compliance tenant	Sponsor compliance dédié + agenda fixe de validation par sprint
Personnalisation excessive demandée	Charte “no fork” : custom toléré via configuration, jamais via patch code
Pression go-live trop tôt	Ne pas céder sur la phase shadow 14 j minimum — risque audit BCT
Refus on-prem du air-gap (ouverture Internet sortant requise pour DJ)	Documenter clairement les contraintes en cadrage

13. Templates fournis

Repo vitakyc-onboarding-templates accessible aux CSM :

prerequisites-tenant.md — checklist pré-requis tenant
cadrage-document.md — template document de cadrage
raci.xlsx — RACI pré-rempli à adapter
helm-values-{profile}.yaml — values Helm par profil (light/standard/tier-1)
runbook-go-live.md — runbook go-live S+12
agent-training-l1.pptx + agent-training-l2.pptx — slides formation
tenant-onboarding-pvrd.md — template PV de Réception Définitive
quick-reference-cards.zip — cartes A4 par rôle FR/AR/EN

14. Calendrier détaillé S1-S12 (Gantt simplifié)

S1   ████░░░░  cadrage initial
S2   ████░░░░  pré-requis tenant
S3        ████  provisioning infra
S4         ████  setup IdP + DNS + smoke tests
S5            ████  CPS + forms initiaux
S6             ████  Risk Matrix + AML rules SHADOW + sanctions
S7                 ████  tests E2E
S8                  ████  formation agents
S9                      ██░░  shadow 1%
S10                       ██░░  pilote 5%
S11                          ████  ramp-up 25 → 50 → 100%
S12                              ████  stabilisation + PVRD

15. Références

Sanctions admin UI — UI compliance
Runbook SRE Sanctions — ops post go-live
Mobile SDK — modes deployment
DPIA — analyse impact RGPD
BCP/DR — continuité d’activité
Webhooks — config tenant
Form Designer UX + moteur — configuration parcours
CPS — modèle de variables canoniques
Risk Matrix + Playbook BCT
Pipeline biométrique
Case Management
AML Streaming Engine
ADRs : ADR-002 multi-tenant RLS, ADR-009 i18n RTL, ADR-010 SDKs, ADR-012 zero-downtime upgrades

Playbook onboarding tenant — version 1.0 (2026-04-27). Itéré après chaque go-live tenant.