PD-235 — Plan d'implémentation¶

1. Decoupage en composants¶

1.1 Composants infrastructure (Keycloak)¶

1.2 Composants Terraform¶

1.3 Composants Ansible¶

1.4 Secrets HashiCorp Vault¶

Les secrets Keycloak sont stockes dans HashiCorp Vault (INV-05 : pas de secrets en clair).

Principe : Les playbooks Ansible lisent les secrets depuis Vault au deploiement. Aucun secret n'est stocke dans le repository Git ni dans les variables d'environnement en clair.

flowchart LR
    subgraph Vault["HashiCorp Vault"]
        S1[kv/keycloak/prod/admin]
        S2[kv/keycloak/prod/database]
        S3[kv/keycloak/prod/clients/*]
    end

    subgraph Ansible
        P[Playbook keycloak]
    end

    subgraph Keycloak
        K[Keycloak Server]
        DB[(PostgreSQL)]
    end

    P -->|vault lookup| Vault
    P -->|configure| K
    K -->|credentials| DB

1.5 Artefacts de preuve (INV-IAM-10)¶

2. Flux techniques¶

2.1 Flux F1 — Decouverte OIDC¶

sequenceDiagram
    participant C as Consumer (Backend)
    participant K as Keycloak IdP

    C->>K: GET /.well-known/openid-configuration
    K-->>C: Discovery doc (issuer, jwks_uri, endpoints)

    C->>K: GET /protocol/openid-connect/certs
    K-->>C: JWKS (public keys)

Points de verification : - Issuer correspond a l'environnement (INV-IAM-08) - JWKS accessible pour validation hors-ligne (INV-04)

2.2 Flux F2 — Emission d'un token¶

sequenceDiagram
    participant CL as Client
    participant K as Keycloak
    participant EL as Event Logger

    CL->>K: Auth Request (credentials / auth code)

    Note over K: 1. Valider identite<br/>2. Generer JWT<br/>3. Signer (ES256/ES384/RS256)<br/>4. Ajouter claims normatifs

    K->>EL: Log event (TOKEN_ISSUED)
    K-->>CL: JWT Response (access_token)

Claims emis (INV-IAM-04, Annexe B.5) : - iss : Issuer environnement (B.1) - aud : Audience(s) autorisee(s) (B.2) - sub : Identifiant utilisateur - iat : Timestamp emission - exp : Expiration (max 15min, B.6) - tenant : Identifiant tenant - authz : { roles: [...], scopes: [...] }

2.3 Flux F3 — Validation temporelle (INV-IAM-05, B.6)¶

flowchart TD
    subgraph Validation["Validation temporelle (consumer)"]
        T[Token recu] --> C1{iat <= now + skew ?}
        C1 -->|Non| R1[Rejet: TOKEN_NOT_YET_ISSUED]
        C1 -->|Oui| C2{nbf present ?}
        C2 -->|Oui| C3{nbf <= now + skew ?}
        C3 -->|Non| R2[Rejet: TOKEN_NOT_YET_VALID]
        C3 -->|Oui| C4{exp > now - skew ?}
        C2 -->|Non| C4
        C4 -->|Non| R3[Rejet: TOKEN_EXPIRED]
        C4 -->|Oui| OK[Token temporellement valide]
    end

    style skew fill:#f9f,stroke:#333

Parametres (B.6) : - skew = 120 secondes (±2 minutes) - exp - iat <= 900 secondes (15 minutes max)

Mecanisme cote consumer (backend PD-26) : - Configuration clockTolerance: 120 dans le service de validation JWT - Application homogene sur tous les claims temporels (iat, nbf, exp) - Rejet deterministe avec code d'erreur specifique

Observables : - Logs de rejet avec raison temporelle (TOKEN_EXPIRED, TOKEN_NOT_YET_VALID) - Metriques de tokens rejetes par cause temporelle - Tests contractuels TC-NEG-02 (expiration) valident le comportement

2.4 Flux F4 — Indisponibilite IdP (INV-IAM-11)¶

sequenceDiagram
    participant CL as Client
    participant GW as Gateway/Backend
    participant K as Keycloak (DOWN)
    participant EL as Event Logger
    participant HC as Health Check

    Note over GW,K: Detection indisponibilite
    GW->>K: Health probe
    K--xGW: Timeout / Connection refused

    GW->>HC: Update status: IDP_UNAVAILABLE
    GW->>EL: Log SERVICE_UNAVAILABLE (mandatory)

    Note over CL,GW: Requete client
    CL->>GW: Auth Request
    GW-->>CL: HTTP 503 + error_code: "idp_unavailable"

Canaux normatifs de signalisation (INV-IAM-11, spec §6) :

Garanties de determinisme : - Journalisation obligatoire (pas "si possible") lors de detection d'indisponibilite - Code erreur idp_unavailable distinct de invalid_token (401) et forbidden (403) - Health endpoint /health/idp avec refresh <= 30s - Metriques exposees : idp_availability_status, idp_last_successful_check_timestamp

Implementation : - Backend PD-26 : health check periodique vers Keycloak (circuit breaker pattern) - Nginx/Gateway : probe active vers /health/ready de Keycloak - Fallback : si timeout > 5s, signaler immediatement IDP_UNAVAILABLE

3. Mapping invariants → mecanismes¶

4. Mapping criteres d'acceptation → mecanismes¶

5. Mapping tests (TC-*) → mecanismes + observables¶

6. Gestion des erreurs¶

Format de journalisation (INV-IAM-09) :

{
  "event": "LOGIN|TOKEN_ISSUED|TOKEN_DENIED|TOKEN_TEMPORAL_ERROR|SERVICE_UNAVAILABLE",
  "env": "dev|staging|prod",
  "result": "success|failure|unavailable",
  "channel": "auth|idp",
  "ts": "2025-01-06T12:00:00Z"
}

Note INV-IAM-11 : L'evenement SERVICE_UNAVAILABLE avec channel: "idp" est obligatoire lors de detection d'indisponibilite IdP. Ce log constitue l'un des 3 canaux normatifs de signalisation.

Interdits dans les logs : - Tokens JWT complets - Secrets/credentials - Cles cryptographiques - Donnees permettant reconstitution de secrets

7. Impacts securite¶

7.1 Risques identifies¶

7.2 Mesures de securite¶

7.3 Journalisation securisee (INV-IAM-09)¶

Conservation : Minimum 30 jours calendaires

Champs autorises (liste fermee) : - Type d'evenement (auth, emission, refus) - Environnement concerne - Resultat (succes/echec) - Horodatage

Champs interdits : - Tokens JWT - Credentials - Cles cryptographiques - Tout secret

7.4 Fiabilite de la journalisation (mitigation H-07)¶

Problematique : Les event listeners Keycloak peuvent etre asynchrones selon la configuration. En cas de perte de connexion au collecteur de logs, des evenements peuvent etre perdus, violant INV-IAM-09.

Mecanismes de garantie :

flowchart LR
    subgraph Keycloak
        EL[Event Listener]
        BUF[(Buffer local<br/>fichier)]
    end

    subgraph Collecteur
        LOG[Log Aggregator<br/>Loki/ELK]
    end

    subgraph Monitoring
        MON[Prometheus]
        ALT[Alerting]
    end

    EL -->|1. Write| BUF
    BUF -->|2. Forward| LOG
    BUF -.->|retry si echec| LOG
    EL -->|metrics| MON
    MON -->|seuil| ALT

Garanties : - Aucun evenement perdu tant que le buffer local est disponible (disque) - Detection rapide de toute perte via metriques et alertes (< 5 min) - Retention locale de 7 jours en fallback si collecteur indisponible - Audit de reconciliation quotidien pour verifier integrite

Tests associes : - TC-LOG-01 : Verifier que les evenements sont bufferises localement - TC-LOG-02 : Simuler perte collecteur, verifier retry et alerte - TC-LOG-03 : Verifier reconciliation detecte les ecarts

8. Hypotheses techniques¶

9. Points de vigilance (risques, dette, pieges)¶

9.1 Risques techniques¶

9.2 Dette technique acceptee¶

9.3 Pieges d'implementation¶

• Realm names : Ne pas confondre realm name et issuer path
• Flux OIDC (B.7) : Respecter strictement les flux autorises — Authorization Code pour backends applicatifs, Client Credentials pour service-a-service, Authorization Code + PKCE pour frontends. Ne jamais utiliser implicit flow.
• Mappers : Verifier l'ordre des protocol mappers (peut affecter claims)
• Logs : Desactiver default logging qui peut exposer des secrets
• Admin console : Restreindre l'acces (pas d'exposition publique)
• CORS : Configurer precisement pour eviter CSRF
• Vault : Ne jamais stocker de secrets dans les variables Ansible ou Git ; toujours utiliser community.hashi_vault.vault_read
• Client secrets rotation : Synchroniser la rotation entre Keycloak et Vault pour eviter les interruptions de service

10. Hors perimetre¶

• Federation externe (Google, FranceConnect, SAML)
• MFA / authentification forte
• Gestion cycle de vie utilisateurs (KYC, eIDAS)
• Rate limiting / WAF
• High Availability / Clustering
• Disaster Recovery automatise
• Monitoring avance (APM)
• Integration SIEM
• Automatisation rotation cles

11. Architecture cible¶

11.1 Vue d'ensemble¶

flowchart LR
    subgraph External
        C[Consumer<br/>Backend]
    end

    subgraph OVH["OVH Cloud"]
        V[(HashiCorp<br/>Vault)]
        N[Nginx<br/>TLS termination]
        K[Keycloak<br/>Server]
        P[(PostgreSQL<br/>state)]

        N --> K
        K --> P
        K -.->|secrets| V
    end

    C -->|HTTPS| N

11.2 Configuration par environnement¶

11.3 Clients OIDC (Annexe B.7)¶

Note : Conformement a B.7, les backends applicatifs (API principale) utilisent Authorization Code, tandis que les services internes autonomes (services, workers) utilisent Client Credentials. Les frontends utilisent Authorization Code + PKCE.

12. Plan de deploiement¶

12.0 Phase 0 — Provisionnement secrets Vault¶

1. Creer structure kv/keycloak/{env}/ dans Vault
2. Generer et stocker admin password
3. Generer et stocker credentials PostgreSQL
4. Creer policy Vault pour acces Ansible
5. Valider acces secrets depuis runner CI

12.1 Phase 1 — Infrastructure de base¶

1. Provisionner DNS (Terraform)
2. Installer Keycloak sur VM (Ansible + secrets Vault)
3. Configurer TLS (Certbot)
4. Configurer PostgreSQL backend (credentials Vault)

12.2 Phase 2 — Configuration realms¶

1. Creer realms par environnement
2. Configurer algorithmes de signature (B.3)
3. Configurer token lifespan (B.6)
4. Configurer event listeners

12.3 Phase 3 — Configuration clients¶

1. Creer clients OIDC (B.7)
2. Generer client secrets et stocker dans Vault
3. Configurer protocol mappers (claims)
4. Configurer audiences (B.2)
5. Tester emission tokens

12.4 Phase 4 — Documentation et audit¶

1. Generer inventaire infrastructure
2. Rediger runbook exploitation
3. Documenter controle d'acces admin
4. Documenter acces secrets Vault
5. Valider artefacts opposables (INV-IAM-10)

12.5 Phase 5 — Tests et validation¶

1. Executer tests TC-NOM-*
2. Executer tests TC-NEG-*
3. Executer tests TC-INV-*
4. Valider conformite INV-IAM-*
5. Verifier aucun secret en clair dans logs/config (INV-05)

References¶

• Epic : EPIC-193 — Infrastructure Souveraine
• JIRA : PD-235
• Repos : infra
• Specification : PD-235-specification.md
• Tests : PD-235-tests.md
• Relation : PD-26 (backend consumer)