Identification Failures in Hanami with Mutual Tls

Identification failures occur when a server cannot reliably confirm the identity of a client. In Hanami applications using Mutual TLS (mTLS), the client presents a certificate during the TLS handshake and Hanami validates it. If the validation is incomplete or misconfigured, the application may accept an invalid or missing client certificate and still treat the request as authenticated. This creates an identification failure because the server proceeds with an unverified principal, allowing unauthorized clients to access protected endpoints.

Mutual TLS-specific identification failures in Hanami often stem from configuration gaps or inconsistent enforcement across routes. For example, if only a subset of endpoints enforce client certificate validation, an attacker can route requests to the less restrictive paths. Hanami relies on the underlying Rack and Ruby TLS libraries; if the server is configured to request but not require a client certificate (verify_mode set to optional rather than peer), the certificate may be present but not validated. In such cases, the identity derived from the certificate is not trusted, but the application may still use request metadata (such as headers) that were intended to be populated only after successful mTLS verification.

Operational risks are amplified when mTLS is used alongside other mechanisms like API tokens or session cookies. An identification failure may allow an attacker to bypass token validation by leveraging a trusted network path or a misconfigured reverse proxy that terminates TLS before passing traffic to Hanami. Because Hanami treats the request as authenticated when the certificate is accepted, the attacker can perform actions under a presumed identity without possessing a valid certificate. This is especially dangerous in microservice architectures where services communicate over mTLS and assume peer identity based on certificate presence rather than strict validation.

Real-world scenarios include services that skip hostname verification or accept certificates signed by any trusted CA without checking the intended use or revocation status. For instance, a Hanami service that only checks that a certificate is signed by a known CA but does not verify the Common Name (CN) or Subject Alternative Name (SAN) may accept a certificate issued for another service. This enables lateral movement within a network where mTLS is broadly trusted. The OWASP API Security Top 10 category Identification and Authentication Failures maps directly to these risks, as improper identity verification undermines access control decisions.

During scanning, middleBrick evaluates whether the server properly requires and validates client certificates, checking for indicators such as incomplete certificate chains, weak signature algorithms, and missing revocation checks. The tool also cross-references runtime behavior against the OpenAPI specification to detect discrepancies between documented authentication requirements and actual implementation. Without strict mTLS enforcement, even well-designed authorization checks may rely on an incorrect identity, leading to privilege escalation or unauthorized data access.

Remediation focuses on enforcing strict client certificate validation in Hanami's configuration and ensuring consistent application across all routes. The following code examples demonstrate how to configure Hanami with proper mTLS settings using Puma as the application server, including required client certificate verification, chain validation, and hostname checks.

# config/puma.rb
# Set minimum TLS version and require client certificates
if ENV["RACK_ENV"] == "production"
  ssl_bind "0.0.0.0", "8443", {
    key: "path/to/server.key",
    cert: "path/to/server.crt",
    ca_file: "path/to/ca_bundle.crt",
    verify_mode: "peer"
  }
end

The verify_mode: "peer" setting ensures that the server requests and validates the client certificate during the TLS handshake. Using a CA bundle file allows Hanami to validate the client certificate chain against a trusted root. This configuration should be applied consistently across all environments that require mTLS, and environment checks prevent accidental use of strict validation in development where certificates may not be available.

In addition to server configuration, Hanami applications should enforce authorization based on verified certificate attributes rather than trusting unvalidated metadata. For example, extracting identity information from the client certificate after successful validation ensures that access control decisions use trusted data.

# app/services/client_identity.rb
class ClientIdentity
  def self.from_env(env)
    # Extract certificate subject fields after successful mTLS validation
    cert_dn = env["SSL_CLIENT_CERT"]
    return nil unless cert_dn

    cert = OpenSSL::X509::Certificate.new(cert_dn)
    {
      subject: cert.subject.to_s,
      serial: cert.serial.to_s,
      issuer: cert.issuer.to_s
    }
  rescue OpenSSL::X509::CertificateError
    nil
  end
end

This approach assumes that the web server has already validated the certificate and made its details available via environment variables such as SSL_CLIENT_CERT. By constructing an identity object only after validation, Hanami avoids relying on unverified request properties. The service returns nil when the certificate cannot be parsed, allowing the application to reject the request rather than proceed with an unknown identity.

Finally, ensure that reverse proxies and load balancers preserve mTLS verification and do not terminate TLS in a way that disables client certificate validation. If TLS is re-encrypted between the proxy and Hanami, the proxy must forward client certificate metadata securely and Hanami must be configured to trust that metadata only when it originates from a trusted source. Combining strict server-side validation with verified proxy headers mitigates identification failures across the full request path.