← All runbooks in Secrets, PKI & Certificates

medium riskservice affecting~30 min

Runbook: Resolve a Certificate Hostname Mismatch

1 · Prerequisites

Confirm every item is in place before any state change.

The verbatim rejection from the failing client, which normally quotes the exact name it was looking for
A capture of the certificate the endpoint serves for that request, taken with the same server name the client sends
Read access to the client or proxy configuration that decides which name is used for validation
Authority over one of the two possible fixes: changing the name the client requests, or requesting a reissued certificate with a corrected name list
The authoritative list of names this service is meant to answer for, agreed with the service owner rather than inferred from DNS
A second host from which to re-test, so a local resolver quirk cannot be mistaken for a fix

2 · Pre-checks

Read-only diagnostic commands. If any of these don't match expected output, stop and investigate further.

· Confirm the rejection is about the name and not about the path. A name mismatch and an incomplete chain both surface as a generic certificate error in many clients, and they have nothing in common. Read the wording before assuming.
· Confirm which name the client used. Clients validate against the name they were asked to connect to, which is not always the name in the address bar, the Host header, or the DNS record you are looking at.
· Confirm you are reading the certificate that request received. A listener serving several virtual hosts returns a different certificate depending on the server name sent, so a capture taken without that name proves nothing about the failure.
· Confirm the intended name list with the service owner. Adding a name to a certificate is an identity decision. Inferring the list from whatever is failing today produces certificates that accumulate names nobody can justify at renewal.
· Confirm whether anything pins or depends on the current name set. Monitoring probes, service mesh policies and partner integrations may target names you are about to change or remove.
· Confirm the change route before choosing it. Reissuance has a lead time; changing a proxy target does not. Knowing both costs is what makes the decision in step four an engineering choice rather than a preference.

3 · Procedure

Execute each step in order. Verify the expected output of a step before moving to the next.

1Copy the rejection verbatim, including the quoted name. Most clients name the string they were validating against, and that string is the single most useful piece of evidence in this entire class of failure.
2Separate the names that are in play. The DNS name that was resolved, the server name sent in the handshake, the Host header of the request, and, when a proxy is involved, the name the proxy uses towards its upstream. They are configured independently and frequently disagree.
3Capture the certificate for that specific request. Connect with the server name the client sends, so the listener selects the same virtual host it selected for the client.
4Read the subject alternative name and nothing else. openssl x509 -in served.pem -noout -ext subjectAltName lists every identity the certificate carries. This list is the certificate's complete claim about who it is.
5Do not treat the common name as a fallback. Current service identity rules require clients to ignore the common name when identifying a service, and certificates issued by modern automation frequently have no subject at all. If a name appears only in the subject, it is not present for validation purposes.
6Ask the library to perform the comparison. Add -verify_hostname to an openssl verify run against the captured certificate. Wildcard and trailing-dot rules are subtle enough that reading the list and judging by eye is a genuine source of wrong conclusions.
7Establish which side is wrong. Either the certificate is missing a name the service is genuinely supposed to answer for, or a client is asking for a name this service was never meant to serve. Only one of those is fixed by reissuance.
8When the request is wrong, correct the name at its source. A proxy that forwards to an upstream must send the upstream's real name, not the name it received from the customer. Change the configuration, test it, reload, and re-check.
9When the certificate is wrong, gather the full agreed name list before requesting anything. A reissuance that fixes one name and omits another creates a second incident a week later, and consumes issuance budget for nothing.
10Never make the error disappear by weakening verification. Turning off name checking, or trusting any name, converts a precise identity failure into a silent acceptance of whatever answers the address.
11Use address-level redirection for testing, not name-level. Resolving the correct name to a specific address keeps every check enabled while letting you reach one backend. Overriding the name itself disables the property you are trying to test.
12Re-run the original failing request from the client that reported it. A verification performed only on the diagnostic host proves that host is happy, which was never in question.

4 · Verification

Confirm the procedure actually fixed the problem.

✓The failing client completes the request using its normal configuration, with certificate and name checking fully enabled.
✓An offline verify with the hostname option, run against a fresh capture, reports success for the exact name in the original rejection.
✓The subject alternative name list on the served certificate matches the agreed list from the service owner, with no unexplained extra entries.
✓A test from a second host, with its own resolver and trust store, produces the same successful result.
✓If a proxy configuration changed, the upstream name it now sends is confirmed from the proxy configuration itself and from a capture of the upstream handshake.
✓No temporary name override, hosts file entry or verification bypass remains anywhere in the estate.
✓Any monitoring probe that targets one of the affected names has been re-run and reports success.

5 · Rollback

If verification fails, undo the procedure in reverse order.

↶If a proxy or client was changed to send a different upstream name, restore the previous value, test the configuration, and reload. The previous value should be recorded in the change note before the edit, not recovered from memory.
↶If a new certificate with a revised name list was deployed, restore the previous certificate and key pair from the copy taken before installation and reload the service.
↶If a DNS record was altered to point a name at a different service, revert it and allow for the cache lifetime, which is the part of this rollback that is not instantaneous.
↶If a name was removed from a certificate and something unexpected depended on it, reissue with the name restored rather than reverting a proxy to hide the gap.
↶Remove every hosts file entry, resolver override and test alias created during the investigation, on every host where one was made.
↶Record which of the two possible causes was pursued and why the rollback was needed, so the second attempt starts from the other branch rather than repeating the first.

6 · Escalation

When the runbook isn't enough, contact:

· The name in the rejection is one nobody recognises as belonging to this service: escalate to the service owner and to security, because a client is being directed somewhere unexpected.
· The certificate is correct and the client is correct, and the mismatch appears only through an intermediary: escalate to the network team, since something is terminating or rewriting the connection between them.
· The agreed name list cannot be settled between the requesting team and the service owner: escalate to the platform owner rather than issuing a certificate that encodes an unresolved disagreement.
· The certificate is issued by a managed platform that derives names automatically: escalate to that platform team, because the name list is not yours to edit.
· A wildcard is being proposed to make the problem go away: escalate the design decision, since a wildcard broadens what a single private key can impersonate and that is not a change to make during an incident.

A hostname mismatch is the one TLS failure that is genuinely an identity failure. The certificate is valid, the chain is complete, the authority is trusted, and the client still refuses, because the party that answered is not the party it asked for. That is the check working exactly as designed, and the only two honest outcomes are to correct the certificate or to correct the request.

The distinction that decides everything else on this page: identity lives in the subject alternative name, and only there. The common name inside the subject is not a fallback, is not consulted by a conforming client, and on certificates issued by modern automation is often absent entirely. If the name a client asks for is not in the subject alternative name list, the certificate does not claim that name, no matter what the subject line says.

The second thing worth holding on to is that several distinct names are usually in play at once, and they are configured in different places. Most of the time in this runbook is spent finding out which of them the failing client actually used.

When this runbook applies, and when it does not

It applies when a client rejects a certificate because the name it requested is not present, and the connection is otherwise sound.

It does not apply when:

Validation failed at the chain or the anchor. Those stop before the name is ever considered, and the name is then a distraction.
The certificate has expired. An expired certificate is refused regardless of its names, and reading the name list first sends the call in the wrong direction.
The failure is a mutual TLS rejection of a client certificate. Client identity is usually matched on a different field entirely, and none of the checks below apply to it.
The client deliberately connects by address with no name. That is a design problem in the caller, not a certificate defect, and the fix is to give the caller a name to ask for.

Blast radius

Action	Reversible?	What it costs if wrong
Capturing the certificate for one request	Yes	Nothing beyond a log entry
Reading the name list offline	Yes	Nothing
Changing the upstream name a proxy sends	Yes, if the previous value was recorded	Traffic is validated against a name the upstream does not hold, which fails everything rather than some things
Altering a DNS record to move a name	Slowly	Cache lifetimes mean the mistake persists after the record is corrected
Reissuing with a revised name list	No, the old certificate remains issued	A name omitted in the request becomes a second incident, and issuance budget is consumed either way
Disabling name verification anywhere	No	The service now accepts whatever answers the address, which is precisely the attack the check prevents

Step 1 - Establish which name the client actually used

Four names can differ, and each is configured somewhere else:

The name that was resolved. What DNS returned for the address the client dialled.
The server name sent in the handshake. What selects the virtual host, and what a conforming client validates against.
The Host header. Application-layer routing, invisible to certificate validation.
The upstream name a proxy uses. When a reverse proxy makes its own onward connection, it validates against a name of its own choosing, which by default may not be the name the customer used.

Write down all four before reading any certificate. The rejection message usually quotes the one that mattered:

Read-only / SafeA client naming the exact string it validated against

$ curl -sS https://wrong.lab.example/

curl: (60) SSL: no alternative certificate subject name matches target hostname 'wrong.lab.example'

Illustrative output

Note the wording. The client did not say the certificate is invalid. It said no alternative name matched, which is a statement about the name list and a confirmation that the rest of validation succeeded.

Step 2 - Read the name list the certificate carries

Read-only / SafeEvery identity this certificate claims— The subject alternative name list is the complete claim; nothing outside it counts.

$ openssl x509 -in served.pem -noout -ext subjectAltName

X509v3 Subject Alternative Name:
  DNS:app.lab.example, DNS:www.app.lab.example

Illustrative output

This certificate claims two names. A request for wrong.lab.example is correctly refused, and no amount of chain or trust store work will change that.

Step 3 - Why the common name cannot rescue you

The habit of reading the subject line and expecting a client to accept it is a decade out of date. Current service identity rules state that the common name relative distinguished name must not be used to identify a service, and that other relative distinguished names in the subject must not be used either. A certificate authority may still emit a common name, and when it does, the baseline requirements oblige it to be a character-for-character copy of one of the subject alternative name entries, which makes it decorative rather than authoritative.

The clearest demonstration is a certificate issued by an automated authority, which carries no subject at all:

subject=
issuer=CN=Pebble Intermediate CA 03d090
serial=3DC74918D250C7E9
notBefore=Aug 26 21:31:04 2026 GMT
notAfter=Nov 24 21:31:03 2026 GMT

X509v3 Subject Alternative Name: critical
    DNS:web.lab.example

There is no common name to fall back to. The subject field is an empty sequence, and because it is empty the profile requires the subject alternative name extension to be marked critical, which is exactly what happened. Identity lives entirely in that one extension. Any tooling in your estate that still parses a common name to decide what a certificate is for is reading a field that may not exist.

Step 4 - Let the library do the comparison

Read-only / SafeThe same certificate, checked against a name it holds and a name it does not

$ openssl verify -CAfile root.crt -untrusted srv-ca.crt -verify_hostname app.lab.example app.crt

app.crt: OK

Illustrative output

Against a name the certificate does not carry, the same command reports the failure with its own error number:

error 62 at 0 depth lookup: hostname mismatch

Delegating the comparison matters because the matching rules are less obvious than they look:

Pattern in the certificate	Matches	Does not match
`app.lab.example`	Exactly that name	Any subdomain of it
`*.lab.example`	One label in the leftmost position, such as `app.lab.example`	The bare `lab.example`, and anything with two labels such as `a.b.lab.example`
A name with a trailing dot in the request	Implementation dependent	Do not rely on it either way; normalise before comparing
An address the client dialled numerically	An entry of IP address type	A DNS entry that happens to contain the same digits

Step 5 - Decide which side is wrong, then fix that side

What the evidence shows	Conclusion	Action
The name is one the service is agreed to answer for, and it is absent from the list	The certificate is wrong	Gather the full agreed name list, then reissue and deploy once
The name belongs to a different service	The request is wrong	Correct the caller or the routing so it asks for the right service
A proxy validates against the customer-facing name while the upstream holds its own name	The proxy configuration is wrong	Set the upstream name explicitly on the proxy
The name is correct but the listener returned a different virtual host	No server name was sent	Fix the client or proxy so it sends the server name

When the fault is a reverse proxy validating its upstream against the wrong name, the correction is a configuration change on the proxy rather than a new certificate:

proxy_ssl_server_name on;
proxy_ssl_name           app.lab.example;
proxy_ssl_verify         on;
proxy_ssl_trusted_certificate /etc/ssl/certs/ca-certificates.crt;

Test the configuration, reload, and capture the upstream handshake again. The proxy should now present the upstream’s own name and accept the certificate the upstream already holds.

Step 6 - Confirm from the client that reported it

Re-run the original request from the original client, with no extra options. Then repeat from a second host with a different resolver, so that a cached answer on the first host cannot be mistaken for a repaired certificate. Finally, re-run any monitoring probe that targets the affected name, since probes commonly carry their own name configuration and will keep alerting on a stale value.

Common pitfalls

Symptom	Cause	Action
The certificate list looks correct but the client still refuses	The client is validating a different name from the one you tested	Recover the exact string from the client rejection and test that string
It works from the diagnostic host only	A hosts file entry or a resolver override left over from testing	Remove every override and test from a clean host
A wildcard certificate refuses a two-label subdomain	Wildcards match one label, in the leftmost position only	Add the specific name or restructure the naming, and do not widen the wildcard
The apex name fails while subdomains work	The wildcard does not cover the bare domain	Include the apex explicitly in the name list
A tool reports the wrong service name	It parses the common name, which may be absent or decorative	Change the tool to read the subject alternative name

Verification

The fix is proven when the client that raised the incident completes its normal request with name checking enabled, and an offline verify with the hostname option succeeds for the exact string quoted in the original rejection. Take that verify against a fresh capture rather than against the file you edited, because the capture is the independent channel and the file is not. Confirm the name list on the served certificate matches the list agreed with the service owner, with nothing extra. Repeat from a second host with its own resolver and trust store, re-run any monitoring probe that targets the name, and confirm that no hosts entry, alias or verification bypass survives anywhere in the estate.

Rollback

Restore the previous upstream name on any proxy or client that was changed, using the value recorded in the change note rather than recollection, then test the configuration and reload. If a revised certificate was deployed, reinstall the previous certificate and key pair from the copy taken before installation and reload the service. If a DNS record was moved, revert it and account for the cache lifetime, which is the slow part of this rollback. If a name was removed and something undisclosed depended on it, reissue with the name restored rather than reverting a proxy to conceal the gap. Remove every temporary alias created during the investigation, on every host where one was made, and record which of the two branches was pursued so a second attempt begins from the other one.

1 · Prerequisites

2 · Pre-checks

3 · Procedure

4 · Verification

5 · Rollback

6 · Escalation

When this runbook applies, and when it does not

Blast radius

Step 1 - Establish which name the client actually used

Step 2 - Read the name list the certificate carries

Step 3 - Why the common name cannot rescue you

Step 4 - Let the library do the comparison

Step 5 - Decide which side is wrong, then fix that side

Step 6 - Confirm from the client that reported it

Common pitfalls

Verification

Rollback

References