# aristocrat-enterprise-apps/helix-authentication-extension architecture

> Architecture diagram of the GitHub repository aristocrat-enterprise-apps/helix-authentication-extension, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-30). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/aristocrat-enterprise-apps/helix-authentication-extension
- Repository: https://github.com/aristocrat-enterprise-apps/helix-authentication-extension

## Overview

##### Project type and purpose
- This is a Helix Server “login hook” extension written in Lua (loginhook/main.lua + ExtUtils.lua) that integrates the Helix Core Server (P4D) with an external Helix Authentication Service and an upstream Identity Provider (IdP) supporting OpenID Connect or SAML.
- It’s packaged with configuration scripts (bin/configure-login-hook.sh), container definitions (containers/**), test harnesses (test/**), Docker Compose (docker-compose.yml) and Kubernetes manifests (kubernetes/**) to aid development, testing, and production deployment.

##### File structure
- Top-level:
- bin/ – shell scripts to install/configure the hook on P4D
- containers/ – Dockerfiles and helper scripts to spin up various P4D server images (basic-p4d, p4d, swarm, region-specific demos)
- docker-compose.yml – orchestrates P4D containers and (optionally) the Helix Authentication Service for local testing
- kubernetes/ – YAMLs for Deployments (helix-p4d), Services, PVCs/PVs, and Secrets (loginhook certs)
- loginhook/ – the Lua-based hook extension plus TLS certificates and a manifest.json describing it to P4D
- test/ – Node.js based automated tests that launch P4D in containers, exercise SSL and non-SSL paths, and validate hook behavior
- docs/ – Administrator and developer guides, LDAP and architecture decision records

##### README
- Describes the extension’s SSO workflow: P4 clients authenticate via Helix Auth Service → IdP → ticket back to Helix Server.
- Lists prerequisites (Helix Server ≥2019.1, Helix Authentication Service running externally).
- Refers to docs for installation, LDAP integration, and container/Kubernetes deployment.

##### Main components
a. Helix Core Server (P4D)
- Runs with the login hook configured (via bin script or Kubernetes Secret + Deployment patch).
- Loads loginhook/main.lua on user login attempts.
b. Loginhook Extension
- Lua code (loginhook/main.lua + ExtUtils.lua).
- Uses client.crt/key and CA cert to talk TLS to Helix Authentication Service.
c. Helix Authentication Service (external)
- Redirect endpoint for SSO, orchestrates IdP exchanges.
d. Identity Provider (OpenID Connect or SAML 2.0)
- Performs actual user authentication.
e. Perforce Clients (P4, P4V, etc.)
- Initiate login; receive tickets post-authentication.
f. Container & Orchestration Layer
- Docker Compose for local dev/testing (containers/** + docker-compose.yml).
- Kubernetes Deployments, Services, Secrets, PVCs for production.

##### Relationships and data flow
1) P4 Client → P4D (login request)
2) P4D → invokes loginhook (Lua)
3) loginhook → HTTPS → Helix Authentication Service
4) Auth Service ↔ user’s browser ↔ Identity Provider (OIDC/SAML redirect dance)
5) Auth Service → token/assertion → loginhook
6) loginhook → returns ticket to P4D → P4 Client

##### Architectural patterns & design principles
- Plugin/hook architecture: seamless extension of P4D authentication flow.
- Separation of concerns: P4D handles ticketing, Auth Service handles SSO protocol, IdP handles identity.
- Containerization for reproducible environments.
- Infrastructure as code: Docker Compose + Kubernetes manifests.
- Automated testing through Node.js scripts targeting multiple OS container images.

##### Detail
- How bin/configure-login-hook.sh patches P4D config to point at the loginhook manifest.
- Loginhook/manifest.json registering the hook name and entrypoint.
- Kubernetes Secret mounting loginhook/*.key, client.crt, ca.crt into the P4D Pod.
- Call out the AWK scripts in containers/ for runtime config adjustments in Docker builds.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Subgraphs
    subgraph "P4 Ecosystem"
        P4Client["Perforce Clients (P4, P4V)"]:::p4
        P4D["Helix Core Server (P4D)"]:::p4
    end

    subgraph "Login Hook Extension"
        LHook["Loginhook Extension"]:::ext
        LMain["main.lua"]:::ext
        LUtil["ExtUtils.lua"]:::ext
        LManifest["manifest.json"]:::ext
        LCerts["client.crt / client.key / ca.crt"]:::ext
        BScript["configure-login-hook.sh"]:::ext
    end

    subgraph "External Services"
        AuthService["Helix Authentication Service"]:::external
        IdP["Identity Provider (OIDC/SAML)"]:::external
    end

    subgraph "Container & Orchestration" 
        DockerCompose["Docker Compose"]:::infra
        K8s["Kubernetes"]:::infra
    end

    %% Flows
    P4Client -->|"login request"| P4D
    P4D -->|"invoke hook"| LHook
    LHook -->|"HTTPS request"| AuthService
    AuthService -->|"redirect dance"| IdP
    IdP -->|"token/assertion"| AuthService
    AuthService -->|"response"| LHook
    LHook -->|"ticket"| P4D
    P4D -->|"ticket"| P4Client

    %% Hook composition
    LHook --> LMain
    LHook --> LUtil
    LHook --> LManifest
    LHook --> LCerts
    LHook --> BScript

    %% Infra linkage
    DockerCompose --> P4D
    DockerCompose --> AuthService
    K8s --> P4D

    %% Click Events
    click P4D "https://github.com/aristocrat-enterprise-apps/helix-authentication-extension/tree/master/containers/p4d/Dockerfile"
    click P4D "https://github.com/aristocrat-enterprise-apps/helix-authentication-extension/blob/master/containers/p4d/run.sh"
    click P4D "https://github.com/aristocrat-enterprise-apps/helix-authentication-extension/blob/master/docker-compose.yml"
    click P4D "https://github.com/aristocrat-enterprise-apps/helix-authentication-extension/blob/master/kubernetes/deployments/helix-p4d.yaml"
    click LMain "https://github.com/aristocrat-enterprise-apps/helix-authentication-extension/blob/master/loginhook/main.lua"
    click LUtil "https://github.com/aristocrat-enterprise-apps/helix-authentication-extension/blob/master/loginhook/ExtUtils.lua"
    click LManifest "https://github.com/aristocrat-enterprise-apps/helix-authentication-extension/blob/master/loginhook/manifest.json"
    click LCerts "https://github.com/aristocrat-enterprise-apps/helix-authentication-extension/blob/master/loginhook/client.crt"
    click LCerts "https://github.com/aristocrat-enterprise-apps/helix-authentication-extension/blob/master/loginhook/client.key"
    click LCerts "https://github.com/aristocrat-enterprise-apps/helix-authentication-extension/blob/master/loginhook/ca.crt"
    click BScript "https://github.com/aristocrat-enterprise-apps/helix-authentication-extension/blob/master/bin/configure-login-hook.sh"
    click AuthService "https://github.com/aristocrat-enterprise-apps/helix-authentication-extension/blob/master/docker-compose.yml"

    %% Styles
    classDef p4 fill:#b8e994,stroke:#2d572c,color:#000;
    classDef ext fill:#74b9ff,stroke:#1d3f7a,color:#000;
    classDef external fill:#ffeaa7,stroke:#a27c12,color:#000;
    classDef infra fill:#dfe6e9,stroke:#636e72,color:#000;
```
