Certificate authentication
Certificate authentication
Logship accepts externally issued X.509 client certificates. The browser or OS retains the private key. Logship validates the certificate against explicitly configured CA certificates and resolves an administrator-provisioned identity binding.
Configuration
Configure backend.services.accountsService.identity in the application configuration file (including a file selected by LS_CONFIG_PATH):
{
"publicBackendUrl": "https://logship.example.com",
"frontendUrl": "https://app.example.com",
"authentication": { "allowedMethods": 7, "allowApiTokens": true },
"certificates": {
"enable": true,
"publicUrl": "https://certificate.example.com:8443",
"listenPort": 8443,
"serverCertificatePath": "/etc/logship/certificate-login.pfx",
"serverCertificatePassword": "",
"checkRevocation": true,
"trusts": [{
"id": "corporate",
"rootCertificatePaths": ["/etc/logship/corporate-root.pem"],
"intermediateCertificatePaths": ["/etc/logship/corporate-issuing.pem"]
}]
}
}Use the existing identity encryption-key configuration for login transactions. Server PFX files contain server private keys; CA PEM files contain public certificates only. Configure the same trust and identity settings on every backend host. Restart hosts after changing CA files or transport configuration.
Upgrade every backend and catalog host before enabling authentication restrictions or certificate-only provisioning. Older hosts do not enforce the new policies; do not serve a restricted deployment through a mixture of old and new hosts.
The dedicated HTTPS listener requests a certificate during the TLS handshake. The ordinary login endpoint remains usable without a certificate. Browsers control certificate selection and may remember a selection; cancelling selection can display a browser TLS error. Return to the ordinary login page to retry or choose another method.
Authentication method masks are password 1, OIDC 2, and certificate 4; combine them by addition (7 permits all). System and account administrators can restrict these through the authentication requirements controls. Account restrictions apply only when accessing that account. Deployment settings are an upper bound. API tokens have a separate allow/deny setting and do not count as interactive certificate authentication.
Provisioning a certificate-only user
Add the following fields to a provisioned user, alongside the existing ID, profile, permissions, and account memberships:
{
"enabledAuthenticationMethods": 4,
"certificates": [{
"trustId": "corporate",
"kind": 0,
"value": "alice@example.com"
}]
}No password is required or generated. Existing users remain unchanged unless overwrite is enabled. Credential settings and user updates commit together; disabling password authentication removes the stored password. Provision a password explicitly when intentionally restoring password login.
Binding kinds are SAN email 0, SAN UPN 1, SAN URI 2, and SHA-256 certificate fingerprint 3. Values match exactly; fingerprints use uppercase hexadecimal without separators. The profile email and certificate common name are never implicit identity bindings. A binding belongs to only one user. Multiple bindings support rotation, and an ambiguous certificate match is rejected.
A SAN binding survives renewal when the external CA preserves the identity and configured trust relationship. Fingerprint bindings must be updated for every replacement certificate. System administrators manage bindings under the user's Security Settings. Account administrators manage account requirements under account settings.
Provision account requirements with the optional authentication object on a provisioned account. Existing account overwrite rules apply.
Reverse proxies
Set forwarded to true and configure trustedProxyAddresses and trustedProxyCertificateFingerprints. Addresses are the actual backend TCP peers, before forwarded-header processing. Fingerprints are SHA-256 hashes of proxy TLS client certificates.
The proxy must:
- Require and validate the browser's client certificate and proof of private-key possession.
- Connect to Logship's dedicated HTTPS listener using its pinned TLS client certificate and validate Logship's server certificate.
- Remove any incoming
X-Logship-Client-Certificateheader and replace it with the base64-encoded DER browser certificate. - Forward the certificate-login callback to that listener. Configure intermediate certificates on Logship; the forwarded leaf is not a trust anchor.
Logship independently validates the forwarded certificate. Untrusted proxy peers, missing proxy client certificates, and unconfigured fingerprints are rejected.
Validation and recovery
Certificates require client-authentication EKU, signing usage, valid dates, and a chain to a configured root. Revocation checking fails closed. Private PKIs without reachable revocation infrastructure must explicitly set checkRevocation to false. Successful session chain checks are cached for at most 30 seconds and never past certificate expiry. Binding and policy changes are read from shared storage during authorization.
Certificate login produces a bearer session, not a continuously mTLS-bound session. Session lifetime is capped at certificate expiry. Removing the binding prevents subsequent certificate-session access. CA rotation supports overlapping roots in one stable trust configuration.
Test the intended login method before removing an administrator's existing access. Policy updates require recent authentication and must permit the administrator's current method. Legacy SSO recovery administrators retain their existing password recovery protection. For deployment-level lockout, restore the previous configuration and restart; use intentional user provisioning to restore credentials where necessary.
Older sessions without authentication provenance continue to work under unrestricted policies. Applying restrictions requires those sessions to authenticate again.