starred/uptime-kuma

Fork 0

mirror of https://github.com/louislam/uptime-kuma.git synced 2026-03-02 22:57:00 -05:00

x.509 SSL Client Certificate Authentication #76

New issue

Closed

opened 2026-02-28 01:33:58 -05:00 by deekerman · 19 comments

deekerman commented

2026-02-28 01:33:58 -05:00

Owner

Originally created by @abstractvector on GitHub (Jul 31, 2021).

I have several web (HTTPS) services that are served with an SSL certificate signed by a custom CA. Furthermore, access is then controlled by x.509 client certificates - in other words, the visitor is prompted to provide a client SSL certificate signed by an appropriate CA.

At the moment, it's impossible to monitor these with uptime-kuma. Even if I provide the root CA, the connection will still be rejected as the uptime ping doesn't send a client certificate with the request, along the lines of:

curl --cacert <ca.crt> --cert <client.cert> --key <client.key> https://secure.example.com/

A desirable solution would allow for attaching a custom root CA, client certificate and client key (or .p12 / .pfx bundle) for each monitor that would be used for HTTPS pings.

Originally created by @abstractvector on GitHub (Jul 31, 2021). I have several web (HTTPS) services that are served with an SSL certificate signed by a custom CA. Furthermore, access is then controlled by x.509 client certificates - in other words, the visitor is prompted to provide a client SSL certificate signed by an appropriate CA. At the moment, it's impossible to monitor these with uptime-kuma. Even if I provide the root CA, the connection will still be rejected as the uptime ping doesn't send a client certificate with the request, along the lines of: `curl --cacert <ca.crt> --cert <client.cert> --key <client.key> https://secure.example.com/` A desirable solution would allow for attaching a custom root CA, client certificate and client key (or `.p12` / `.pfx` bundle) for each monitor that would be used for HTTPS pings.

deekerman

2026-02-28 01:33:58 -05:00

closed this issue
added the
feature-request

A:monitor

type:enhance-existing
labels

deekerman commented

2026-02-28 01:34:05 -05:00

Author

Owner

@louislam commented on GitHub (Jul 31, 2021):

Similar feature "Ignore TLS Error" will be available in the next release.

@louislam commented on GitHub (Jul 31, 2021): Similar feature "Ignore TLS Error" will be available in the next release.

deekerman commented

2026-02-28 01:34:05 -05:00

Author

Owner

@abstractvector commented on GitHub (Aug 1, 2021):

Yeah, I saw that feature and that’ll be great for allowing custom CAs but doesn’t address the mTLS angle to this. In node this would be a case of using a custom https.Agent and providing the cert and key parameters.

@abstractvector commented on GitHub (Aug 1, 2021): Yeah, I saw that feature and that’ll be great for allowing custom CAs but doesn’t address the mTLS angle to this. In node this would be a case of using a custom `https.Agent` and providing the `cert` and `key` parameters.

deekerman commented

2026-02-28 01:34:05 -05:00

Author

Owner

@cruscio commented on GitHub (Sep 7, 2021):

+1'd above - been looking for a maintained statping alternative and one of the features many don't have is mTLS authentication for both HTTPS and TCP/TLS (e.g. Kafka Brokers in my case). I can open a new issue for TCP if that's out of scope for this one.

@cruscio commented on GitHub (Sep 7, 2021): +1'd above - been looking for a maintained statping alternative and one of the features many don't have is [mTLS authentication](https://github.com/statping/statping/issues/597) for both HTTPS _and TCP/TLS_ (e.g. [Kafka Brokers](https://docs.confluent.io/platform/current/kafka/configure-mds/mutual-tls-auth-rbac.html) in my case). I can open a new issue for TCP if that's out of scope for this one.

deekerman commented

2026-02-28 01:34:05 -05:00

Author

Owner

@gaby commented on GitHub (Sep 7, 2021):

+1 for adding this feature. It would be very beneficial for enterprise environments.

@gaby commented on GitHub (Sep 7, 2021): +1 for adding this feature. It would be very beneficial for enterprise environments.

deekerman commented

2026-02-28 01:34:05 -05:00

Author

Owner

@techmagellc commented on GitHub (Oct 18, 2021):

I did find a solution to the "custom CA" part of this. Change your pm2 line to this:

pm2 start server/server.js --node-args="--use-openssl-ca" --name uptime-kuma

Assuming you've put the CA's root cert in the system trusted certs, that will allow it to work. It doesn't solve the mTLS issue however.

@techmagellc commented on GitHub (Oct 18, 2021): I did find a solution to the "custom CA" part of this. Change your pm2 line to this: pm2 start server/server.js --node-args="--use-openssl-ca" --name uptime-kuma Assuming you've put the CA's root cert in the system trusted certs, that will allow it to work. It doesn't solve the mTLS issue however.

deekerman commented

2026-02-28 01:34:05 -05:00

Author

Owner

@jthigh-mh commented on GitHub (Aug 15, 2022):

@louislam I am also - unfortunately - running into this same mTLS (Mutual TLS Authentication) issue, with applications and services that insist on trying to negotiate a mTLS client cert.

uptime-kuma simply reports "read ECONNRESET", and registers an outage/failure.

Has there been any further thought about an enhancement or workaround that might help us to monitor these successfully going forward? If there was a way to pivot to optionally using curl for the polling step with some parameters that could be passed, that might provide a workaround for some of the more esoteric problems related to polling related to mTLS negotiation?

@jthigh-mh commented on GitHub (Aug 15, 2022): @louislam I am also - unfortunately - running into this same mTLS (Mutual TLS Authentication) issue, with applications and services that insist on trying to negotiate a mTLS client cert. uptime-kuma simply reports "read ECONNRESET", and registers an outage/failure. Has there been any further thought about an enhancement or workaround that might help us to monitor these successfully going forward? If there was a way to pivot to optionally using **curl** for the polling step with some parameters that could be passed, that might provide a workaround for some of the more esoteric problems related to polling related to mTLS negotiation?

deekerman commented

2026-02-28 01:34:05 -05:00

Author

Owner

@Schnuecks commented on GitHub (Dec 10, 2022):

I have a need for this too. I habe several services running with a x.509 client certificate.

@Schnuecks commented on GitHub (Dec 10, 2022): I have a need for this too. I habe several services running with a x.509 client certificate.

deekerman commented

2026-02-28 01:34:06 -05:00

Author

Owner

@GilchristT commented on GitHub (Jan 25, 2023):

+1 for this feature. Thanks for all the work so far as well

@GilchristT commented on GitHub (Jan 25, 2023): +1 for this feature. Thanks for all the work so far as well

deekerman commented

2026-02-28 01:34:06 -05:00

Author

Owner

@wsepam commented on GitHub (Mar 3, 2023):

+1 from me as well.

@wsepam commented on GitHub (Mar 3, 2023): +1 from me as well.

deekerman commented

2026-02-28 01:34:06 -05:00

Author

Owner

@bdsoha commented on GitHub (May 3, 2023):

@abstractvector Did you look at the wiki?

There are 2 env that can be used:

NODE_EXTRA_CA_CERTS: provided you have access to the custom CA.
NODE_TLS_REJECT_UNAUTHORIZED: to ignore all tls errors.

@bdsoha commented on GitHub (May 3, 2023): @abstractvector Did you look at the [wiki](https://github.com/louislam/uptime-kuma/wiki/Environment-Variables#server-environment-variables)? There are 2 `env` that can be used: - `NODE_EXTRA_CA_CERTS`: provided you have access to the custom CA. - `NODE_TLS_REJECT_UNAUTHORIZED`: to ignore all tls errors.

deekerman commented

2026-02-28 01:34:06 -05:00

Author

Owner

@abstractvector commented on GitHub (May 3, 2023):

@bdsoha Yes, these variables will allow you to accept a custom CA and / or ignore TLS related errors, and yes, that does solve the server certificate issue which is great.

However, the remaining (and most significant) part of this issue is referring to client TLS authentication - i.e. allowing the client to authenticate themselves using a certificate. That is not possible with those (or other) environment variables.

@abstractvector commented on GitHub (May 3, 2023): @bdsoha Yes, these variables will allow you to accept a custom CA and / or ignore TLS related errors, and yes, that does solve the server certificate issue which is great. However, the remaining (and most significant) part of this issue is referring to client TLS authentication - i.e. allowing the client to authenticate themselves using a certificate. That is not possible with those (or other) environment variables.

deekerman commented

2026-02-28 01:34:06 -05:00

Author

Owner

@GilchristT commented on GitHub (May 3, 2023):

mTLS wasn't available at the time this thread was created but it has since been added in version 1.21.0

I haven't had a chance to test it myself but it's there :-)

@GilchristT commented on GitHub (May 3, 2023): mTLS wasn't available at the time this thread was created but it has since been added in version 1.21.0 I haven't had a chance to test it myself but it's there :-)

deekerman commented

2026-02-28 01:34:06 -05:00

Author

Owner

@abstractvector commented on GitHub (May 3, 2023):

@GilchristT good to know! I haven't updated our install yet but maybe someone else can test it and close this issue - that would be fantastic!

@abstractvector commented on GitHub (May 3, 2023): @GilchristT good to know! I haven't updated our install yet but maybe someone else can test it and close this issue - that would be fantastic!

deekerman commented

2026-02-28 01:34:06 -05:00

Author

Owner

@ksummersill2 commented on GitHub (Aug 23, 2023):

I've tested the mTLS, however when accessing my sites that require a client certificate, it seems to not find it.

@ksummersill2 commented on GitHub (Aug 23, 2023): I've tested the mTLS, however when accessing my sites that require a client certificate, it seems to not find it.

deekerman commented

2026-02-28 01:34:06 -05:00

Author

Owner

@FrancYescO commented on GitHub (Nov 29, 2023):

Hello, actually mTLS is added but is there a way to consider a monitor online whitout the need of adding the client cert?

so to consider the monitor online with just the HTTPS handshake completed (chrome i.e. shows ERR_BAD_SSL_CLIENT_AUTH_CERT) i've tried the "Ignore TLS/SSL error for HTTPS websites" options but seems to not ignore this case, actually the only workaround i've found is to switch to a TCP-Port monitor but is not really the same

ps. the popup error says
SSL routines:ssl3_read_bytes:sslv3 alert bad certificate:../deps/openssl/openssl/ssl/record/rec_layer_s3.c:1586:SSL alert number 42

@FrancYescO commented on GitHub (Nov 29, 2023): Hello, actually mTLS is added but is there a way to consider a monitor online whitout the need of adding the client cert? so to consider the monitor online with just the HTTPS handshake completed (chrome i.e. shows ERR_BAD_SSL_CLIENT_AUTH_CERT) i've tried the "Ignore TLS/SSL error for HTTPS websites" options but seems to not ignore this case, actually the only workaround i've found is to switch to a TCP-Port monitor but is not really the same ps. the popup error says `SSL routines:ssl3_read_bytes:sslv3 alert bad certificate:../deps/openssl/openssl/ssl/record/rec_layer_s3.c:1586:SSL alert number 42`

deekerman commented

2026-02-28 01:34:06 -05:00

Author

Owner

@GilchristT commented on GitHub (Nov 29, 2023):

so to consider the monitor online with just the HTTPS handshake completed

I can't help with how UptimeKuma handles this but, from an SSL point of view, the client certificate verification is part of the handshake so, if the server is set to require a client certificate, the handshake will fail if an appropriate certificate isn't sent.

The client doesn't get a HTML response, just an error. I suppose if you wanted to treat this as confirmation that the server was up you'd need logic along the lines of "if I get this type of failure to connect, treat it as success", seems like a can of worms that really shouldn't be opened?

Two caveats to the statement above. Firstly servers can be configured with client certificate optional and do the certificate checking logic later in the exchange (but you are unlikely to be seeing the error above if that was the case) .

Secondly, TLS v1.3 has introduced the concept of post-handshake client certificate authentication. However, in my experience this is quite erratically (to be polite) implemented with a lot of browser and server vendors pointing in all directions at each other and accusing everyone else of implementing it incorrectly.

Final caveat, I'm no SSL expert, just lots of bitter experience :-) If any of the above is incorrect I'll happily stand corrected.

@GilchristT commented on GitHub (Nov 29, 2023): > so to consider the monitor online with just the HTTPS handshake completed I can't help with how UptimeKuma handles this but, from an SSL point of view, the client certificate verification is **part** of the handshake so, if the server is set to require a client certificate, the handshake will fail if an appropriate certificate isn't sent. The client doesn't get a HTML response, just an error. I suppose if you wanted to treat this as confirmation that the server was up you'd need logic along the lines of "if I get this type of failure to connect, treat it as success", seems like a can of worms that really shouldn't be opened? Two caveats to the statement above. Firstly servers can be configured with client certificate optional and do the certificate checking logic later in the exchange (but you are unlikely to be seeing the error above if that was the case) . Secondly, TLS v1.3 has introduced the concept of post-handshake client certificate authentication. However, in my experience this is quite erratically (to be polite) implemented with a lot of browser and server vendors pointing in all directions at each other and accusing everyone else of implementing it incorrectly. Final caveat, I'm no SSL expert, just lots of bitter experience :-) If any of the above is incorrect I'll happily stand corrected.

deekerman commented

2026-02-28 01:34:06 -05:00

Author

Owner

@FrancYescO commented on GitHub (Nov 29, 2023):

Yup you are right, maybe i've misused the handshake term, but let me say that in my use case, what chrome browser "detect" as ERR_BAD_SSL_CLIENT_AUTH_CERT (maybe is just due to the fact of that during SSL handshake the server clearly says "hey you need a client cert", and the browser does not find any) is enought for the healthcheck.

i know it's a clear edge case, but maybe is just enought to add this kind of error to the "Ignore TLS/SSL error for HTTPS websites" checkbox

@FrancYescO commented on GitHub (Nov 29, 2023): Yup you are right, maybe i've misused the handshake term, but let me say that in my use case, what chrome browser "detect" as ERR_BAD_SSL_CLIENT_AUTH_CERT (maybe is just due to the fact of that during SSL handshake the server clearly says "hey you need a client cert", and the browser does not find any) is enought for the healthcheck. i know it's a clear edge case, but maybe is just enought to add this kind of error to the "Ignore TLS/SSL error for HTTPS websites" checkbox

deekerman commented

2026-02-28 01:34:06 -05:00

Author

Owner

@Nenodema commented on GitHub (Jan 16, 2024):

Hello, actually mTLS is added but is there a way to consider a monitor online whitout the need of adding the client cert?

so to consider the monitor online with just the HTTPS handshake completed (chrome i.e. shows ERR_BAD_SSL_CLIENT_AUTH_CERT) i've tried the "Ignore TLS/SSL error for HTTPS websites" options but seems to not ignore this case, actually the only workaround i've found is to switch to a TCP-Port monitor but is not really the same

ps. the popup error says SSL routines:ssl3_read_bytes:sslv3 alert bad certificate:../deps/openssl/openssl/ssl/record/rec_layer_s3.c:1586:SSL alert number 42

I encounter almost he same issue. The strange thing is that the error only occurs on some domains, and not all..

Pending: 0088F8F5797F0000:error:0A0003FC:SSL routines:ssl3_read_bytes:sslv3 alert bad record mac:../deps/openssl/openssl/ssl/record/rec_layer_s3.c:1586:SSL alert number 20

@Nenodema commented on GitHub (Jan 16, 2024): > Hello, actually mTLS is added but is there a way to consider a monitor online whitout the need of adding the client cert? > > so to consider the monitor online with just the HTTPS handshake completed (chrome i.e. shows ERR_BAD_SSL_CLIENT_AUTH_CERT) i've tried the "Ignore TLS/SSL error for HTTPS websites" options but seems to not ignore this case, actually the only workaround i've found is to switch to a TCP-Port monitor but is not really the same > > ps. the popup error says `SSL routines:ssl3_read_bytes:sslv3 alert bad certificate:../deps/openssl/openssl/ssl/record/rec_layer_s3.c:1586:SSL alert number 42` I encounter almost he same issue. The strange thing is that the error only occurs on some domains, and not all.. `Pending: 0088F8F5797F0000:error:0A0003FC:SSL routines:ssl3_read_bytes:sslv3 alert bad record mac:../deps/openssl/openssl/ssl/record/rec_layer_s3.c:1586:SSL alert number 20`

deekerman commented

2026-02-28 01:34:06 -05:00

Author

Owner

@CommanderStorm commented on GitHub (Jul 10, 2024):

issue should have been closed when https://github.com/louislam/uptime-kuma/pull/2531 was merged

@CommanderStorm commented on GitHub (Jul 10, 2024): issue should have been closed when https://github.com/louislam/uptime-kuma/pull/2531 was merged

deekerman referenced this issue

2026-02-28 03:01:34 -05:00

Looping Crash After Deleting Monitor #2627