Support client certificate authentication (mTLS) for mobile clients
Describe the feature you'd like
Description
I am running a self-hosted Karakeep instance behind a reverse proxy with mutual TLS (mTLS) enabled.
The web UI works correctly on Android Firefox because Firefox can request and use the configured client certificate. However, the native Android app and the Firefox Android extension cannot connect to the same server because they do not appear to use or request the client certificate.
I would like to request support for client certificate authentication (mTLS) in the Karakeep mobile clients and, if technically possible, the browser extension.
Current behavior
I tested the following three scenarios on the same Android device and against the same self-hosted Karakeep server:
1. Karakeep Web UI in Firefox Android — works
Opening the Karakeep web UI directly in Firefox Android triggers the Android/Firefox client certificate selection dialog.
After selecting the client certificate, the TLS connection succeeds and I can use Karakeep normally.
This confirms that the reverse proxy and mTLS configuration are working correctly.
2. Karakeep Android app — does not work
The native Android app does not trigger a client certificate selection dialog.
The server responds with:
400 No required SSL certificate was sent
The app also provides an option to configure custom HTTP headers for API requests, but HTTP headers cannot replace TLS client certificate authentication because the client certificate is exchanged during the TLS handshake, before HTTP requests and headers are sent.
3. Karakeep Firefox Android extension — cannot connect
The Karakeep Firefox Android extension also cannot connect to my self-hosted Karakeep server behind mTLS.
Unlike opening the Karakeep web UI directly in Firefox, the extension does not trigger the browser's client certificate selection dialog.
The extension simply cannot establish a connection to the server. There is no specific error message such as 400 No required SSL certificate was sent displayed by the extension, so I cannot determine exactly where the connection fails.
Expected behavior
It would be useful if Karakeep mobile clients could support mTLS/client certificate authentication when connecting to self-hosted instances.
For example:
- Android client certificate authentication using the Android system certificate store / KeyStore
- Ability to select or configure a client certificate for a Karakeep server
- Native TLS client-certificate authentication
- Equivalent support on iOS using the appropriate system certificate/keychain mechanisms
- If technically feasible, support for client certificates in the mobile browser extension as well
The exact implementation can of course be determined by the developers.
Reproduction steps
- Deploy a self-hosted Karakeep instance behind an HTTPS reverse proxy.
- Configure the reverse proxy to require a client certificate (mTLS).
- Access the Karakeep URL directly using Firefox Android.
- Firefox prompts for a client certificate and the Karakeep web UI works.
- Install and configure the Karakeep Android app with the same server URL.
- The Android app does not request the client certificate and receives:
400 No required SSL certificate was sent - Install the Karakeep Firefox Android extension and configure it to use the same self-hosted server.
- The extension does not trigger client certificate selection and cannot connect to the server.
Environment
- Karakeep: self-hosted
- Platform: Android
- Browser: Firefox for Android
- Reverse proxy: nginx
- Authentication at reverse proxy: mutual TLS (client certificate required)
- Firefox Android Web UI: works
- Karakeep Android app: fails with
400 No required SSL certificate was sent - Karakeep Firefox Android extension: cannot connect, with no specific error message shown
Describe the benefits this would bring to existing Karakeep users
Why this would be useful
mTLS is a useful authentication mechanism for self-hosted services because it allows users to keep the service protected without exposing a separate unauthenticated or non-mTLS endpoint to the Internet.
Currently, users who want to use mTLS with Karakeep on Android appear to have to choose between:
- using the web UI/PWA in a browser that supports client certificates,
- exposing a separate endpoint without mTLS,
- or using a VPN/network-level solution.
Native client certificate support would make the Android app much more practical for securely self-hosted Karakeep deployments.
Thank you for considering this feature.
Can the goal of this request already be achieved via other means?
Partially.
The Karakeep web UI can be accessed through Firefox for Android, where Firefox can use the client certificate and complete the mTLS handshake successfully.
However, using the web UI is not equivalent to having native Android share-target support.
One important use case for the native Android app is receiving content through Android's system share mechanism from other apps. For example, I would like to share a link, article, or media item from another Android application directly to Karakeep for quick saving.
If I have to first open Firefox and then use the web UI, this workflow becomes considerably less convenient and defeats one of the main advantages of having a native mobile app.
The current alternatives are therefore:
- use the Karakeep web UI/PWA through Firefox;
- expose a separate endpoint without mTLS;
- or use a VPN/network-level solution.
The first option works technically, but does not provide the same native Android sharing workflow. The other two options require compromising the current security or network architecture.
Therefore, there is currently no equivalent workaround that provides native Android app functionality while retaining mTLS.
Have you searched for an existing open/closed issue?
- I have searched for existing issues and none cover my fundamental request
Additional context
No response
Source: karakeep-app/karakeep