How aristocrat-enterprise-apps/helix-authentication-extension works
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.