Trust model#
AckNexa enforces role checks and organization scope in the API, with tenant-aware database relationships as a second boundary. Sessions and API credentials are represented by hashes at rest; passwords use bcrypt. The Web proxy uses an HttpOnly session cookie and checks the configured browser origin for mutations.
TLS and private CA#
- Terminate browser/integration traffic at the customer's TLS ingress with certificates covering the exact private DNS names.
- Mount the customer trust bundle for Go with SSL_CERT_FILE and for the Web runtime with NODE_EXTRA_CA_CERTS.
- Production PostgreSQL URLs require sslmode=verify-full and the appropriate sslrootcert path.
- Use authenticated TLS NATS seed URLs and certificates matching those hostnames.
- Keep verification enabled. Do not use TLS verification bypasses as a private-CA workaround. Restart workloads after relevant trust/secret changes.
Secrets management#
Use customer-controlled secret files, Kubernetes Secrets, or an internal secret manager. External Secrets is optional and need not connect to a public service. Protect Kubernetes Secrets with appropriate RBAC and encryption at rest; protect Compose secret files and their parent directory on the host.
| Setting | Purpose |
|---|---|
| ACKNEXA_CONFIG_KEY | Stable base64-encoded 32-byte key for encrypted organization provider configuration. |
| ACKNEXA_SETUP_TOKEN | Operator-issued first-run setup authorization. |
| DATABASE_URL / NATS_URL | Customer state-service credentials and endpoints. |
| SMTP_PASSWORD / OIDC_CLIENT_SECRET | Optional internal service authentication. |
| VOICE_GATEWAY_TOKEN | Optional customer voice-bridge bearer token. |
| FCM_SERVICE_ACCOUNT_FILE / PUSH_RELAY_CREDENTIAL | Optional Firebase service account for Android push, and optional push-relay credential. |
Supported sensitive settings accept a corresponding _FILE form, including the settings above and selected APNs/Twilio secrets. Set either the value or the file, not both. Files are loaded at startup; rotation requires a restart. Keep ACKNEXA_CONFIG_KEY in an independently protected recovery copy.
Single sign-on and directory sign-in#
Organization administrators configure SSO (OpenID Connect, for example Keycloak, Microsoft Entra ID or Okta) and LDAP / Active Directory sign-in under Identity, with optional automatic account creation and group mappings. Unverified emails are refused. LDAP uses ldaps:// or StartTLS, never a clear-text password, and accepts a pasted private CA certificate. Client secrets and bind passwords are sealed with ACKNEXA_CONFIG_KEY and never returned by the API. Organization-level SSO needs PUBLIC_API_URL and PUBLIC_BASE_URL so callback URLs are known.
Operators can instead configure one issuer for the whole deployment with the OIDC_* environment variables. That client must put the organization slug in the acknexa_organization claim (or the claim named by OIDC_ORGANIZATION_CLAIM), because one client serves every organization. Control who can change those claims in the IdP.
SSO is optional, not a dependency on a public identity service. Keep a local break-glass administrator. Identity rebinding requires an approved operator procedure; the Web UI does not yet manage it.
Notification egress#
Tenant-configured SMTP and HTTPS webhooks require operator-approved DNS hosts. Private destinations additionally require explicit NOTIFICATION_PRIVATE_CIDRS. DNS answers are checked and the validated address is dialed; loopback, link-local/metadata destinations and redirects remain restricted. Environment-configured operator endpoints are a separate trusted boundary and need firewall policy. Ticketing connections are limited to TICKETING_HOSTS, and audit syslog streams to AUDIT_SYSLOG_HOSTS.
Shared responsibility#
- Operate hardened container hosts, ingress, database/broker authentication, network policies and encrypted backups.
- Keep sensitive tokens and customer payloads out of logs, tickets and public documentation.
- Review access when people change teams or leave the organization.
- Do not expose metrics or database ports as unauthenticated public services.
- Report a suspected vulnerability in AckNexa to security@acknexa.com, never in a public issue. Include the affected version or image digest, a description and impact, and reproduction steps, but no customer data. No PGP key is published yet; if the details need encryption, say so in a short first email. For anything else, write to hello@acknexa.com.