# Mutual TLS for Apps

Psono apps can authenticate HTTPS connections with a client certificate provisioned separately from the app configuration. Administrators distribute the identity (a certificate and its matching private key) through their device management solution, then reference it in the managed ConfigJson.

The configuration contains references only. Do not put private keys or certificate bundles into ConfigJson.

# Prerequisites

  • A reverse proxy configured to validate client certificates against your client certificate authority.
  • A client certificate with a matching private key accessible to Psono. Prefer a unique identity per device or user and automated enrollment/renewal.
  • A Psono app version with managed client certificate support.
  • Managed configuration delivered before the first connection. See Mobile App and Desktop App for the delivery mechanisms.

Client certificates authenticate the HTTPS connection. Users still sign in to their Psono accounts normally.

# Configure nginx

nginx can terminate mutual TLS and forward accepted requests to Psono over your existing internal connection. Start with the reverse proxy installation guide and add client certificate verification to the HTTPS server block.

# Certificates

Place the following files on the reverse proxy:

File Contents
/etc/ssl/fullchain.pem The HTTPS server certificate for passwords.example.com and its intermediate certificates.
/etc/ssl/privkey.pem The matching HTTPS server private key.
/etc/nginx/mtls/client-ca-chain.pem PEM certificates for the CA hierarchy trusted to issue your client certificates. Include the root and relevant intermediate CA certificates.

The client CA bundle contains public CA certificates, not individual device certificates or CA private keys. It can use a different CA from the one that issued the HTTPS server certificate. The client identities distributed by your MDM must chain to a CA trusted by this bundle and be suitable for TLS client authentication.

# Require a client certificate

For a deployment where the Psono container is available at 127.0.0.1:10200, the relevant nginx configuration looks like this:

server {
    listen 443 ssl;
    server_name passwords.example.com;

    # The certificate presented by nginx to the app or browser.
    ssl_certificate /etc/ssl/fullchain.pem;
    ssl_certificate_key /etc/ssl/privkey.pem;
    ssl_protocols TLSv1.2 TLSv1.3;

    # Verify certificates presented by connecting clients.
    ssl_client_certificate /etc/nginx/mtls/client-ca-chain.pem;
    ssl_verify_client on;
    ssl_verify_depth 2;

    # Revalidate client certificates on new connections rather than resuming
    # previously authenticated TLS sessions.
    ssl_session_cache off;
    ssl_session_tickets off;

    client_max_body_size 256m;

    location / {
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;

        # No trailing URI: preserve paths such as /server/info/.
        proxy_pass http://127.0.0.1:10200;
        proxy_read_timeout 90s;
    }
}

Replace the hostname, paths, and upstream address with your deployment's values. Keep the security headers and other deployment-specific settings from your existing reverse proxy configuration. Adjust ssl_verify_depth to accommodate your client CA hierarchy.

ssl_verify_client on requires a valid client certificate for the entire HTTPS virtual host, including the webclient, admin portal, /config.json, and /server/info/. Browsers accessing those URLs need an appropriate identity as well. Client certificate negotiation happens during TLS setup, so nginx's ssl_verify_client directive belongs in the server block, not in an individual location block.

Keep the backend upstream accessible only through the reverse proxy, for example by binding the container's published port to 127.0.0.1, so clients cannot bypass nginx's certificate checks.

If a separate file server or webclient hostname also requires mTLS, apply client certificate verification to its HTTPS virtual host and include its origin in the app's allowed_origins. Configure the final HTTPS URLs directly; managed app connections do not follow redirects.

# Certificate revocation

To reject revoked client certificates before they expire, nginx can use PEM certificate revocation lists (CRLs) issued by your client CAs. Add this directive to the same HTTPS server block:

ssl_crl /etc/nginx/mtls/client-ca-crls.pem;

Provide the CRLs needed for your client certificate chain, including intermediate CA CRLs when applicable. Automate refreshing the file before the CRLs expire, and reload nginx after updates. Expired or incomplete CRLs can cause otherwise valid client certificates to be rejected. Updating a CA bundle or CRL affects new TLS connections; it does not terminate requests already in progress.

# Apply and verify

Validate and reload the configuration:

sudo nginx -t && sudo systemctl reload nginx

A request without a client certificate must be rejected rather than returning Psono's server information:

curl --fail --show-error https://passwords.example.com/server/info/

Depending on the TLS version and client, rejection may appear as a TLS alert or an nginx HTTP error response.

Repeat with a valid test identity issued by your client CA:

curl --fail --show-error \
    --cert /path/to/test-client-chain.pem \
    --key /path/to/test-client-key.pem \
    https://passwords.example.com/server/info/

This request should return Psono's server information JSON. The test client's chain file contains its certificate and any required intermediate certificates. If your HTTPS server uses a private CA, add --cacert /path/to/server-ca.pem to both checks. Use a separate test identity for these checks; device-bound private keys do not need to be exported from managed devices.

See the nginx HTTP SSL module documentation (opens new window) for the certificate verification and CRL directives.

# Configuration

Add client_tls to the JSON distributed through your existing managed configuration mechanism:

{
  "backend_servers": [
    {
      "title": "Company Psono",
      "url": "https://passwords.example.com/server"
    }
  ],
  "allow_custom_server": false,
  "client_tls": {
    "allowed_origins": [
      "https://passwords.example.com",
      "https://files.example.com"
    ],
    "android_key_alias": "psono-client",
    "apple_identity_identifier": "psono-client",
    "macos_identity_label": "Psono Client Identity",
    "windows_certificate_thumbprint": "0123456789ABCDEF0123456789ABCDEF01234567",
    "windows_certificate_store": "current_user",
    "linux_certificate_path": "/etc/opt/psono/client-chain.pem",
    "linux_private_key_path": "/etc/opt/psono/client-key.pem"
  }
}

Include the reference for each platform you deploy. The other platform references can be omitted. If your MDM expects a string under the ConfigJson key, encode this JSON as that string as you would for the other settings.

Setting Meaning
allowed_origins Required nonempty list of exact HTTPS origins where Psono may use the identity. Include an explicit port when it is not 443. Paths, wildcards, credentials, query strings, and fragments are not allowed.
android_key_alias Alias of the identity installed in Android KeyChain, with private-key access granted to Psono.
apple_identity_identifier Identifier of an app-specific identity provisioned through Apple's ManagedApp framework. Requires iOS/iPadOS 18.4 or later.
macos_identity_label Exact Keychain identity label. It must identify one accessible identity.
windows_certificate_thumbprint SHA-1 thumbprint of the certificate in the selected Personal (MY) certificate store. Spaces and colon separators are accepted.
windows_certificate_store current_user (default) or local_machine.
linux_certificate_path Absolute path to the PEM client certificate chain.
linux_private_key_path Absolute path to the matching unencrypted PEM private key, protected by filesystem permissions.

These settings take effect only when delivered through managed configuration, including the Windows registry policy and Linux configuration file. Downloaded Remote Config and QR configuration do not activate certificate access.

# Android

  1. Enroll or install the identity into Android KeyChain using your MDM.
  2. Grant the Psono package, com.psono.psono, access to its private key. Installing the certificate alone does not grant that access. Depending on the MDM, this is exposed as an application access setting or a device-policy-controller key-pair grant.
  3. Set android_key_alias to the installed identity's alias.
  4. Install Psono and the identity in the same Android user/work profile.

Psono uses the configured identity without displaying a certificate picker. An incorrect alias or a missing grant produces a client certificate error. Private-key operations use Android's native TLS stack; the key is not exported into Dart.

For non-exportable keys, ensure the certificate enrollment and device support the key protection you require.

# iOS and iPadOS

Requires iOS/iPadOS 18.4 or later and an MDM that supports provisioning app-specific identities through ManagedApp.

  1. Provision the identity specifically for the managed Psono app using the MDM's supported ManagedApp identity workflow.
  2. Set apple_identity_identifier to the identifier of that identity.
  3. If users use the iOS AutoFill extension, provision an identity for that extension as well, using the same identifier. The main app and extension have separate ManagedApp identity scopes; provision each executable that needs to contact the server.

A conventional device certificate profile used by Safari is not sufficient: third-party apps cannot generally access those private keys. The identity identifier is the ManagedApp identifier, not a certificate subject, profile UUID, or Keychain label.

Psono resolves the identity using ManagedAppIdentitiesProvider and answers client certificate challenges using URLSession. Builds made with an Apple SDK without ManagedApp support report that managed client certificates are unsupported; they do not fall back to an ordinary connection.

See Apple's managed identity and client certificate authentication documentation (opens new window).

# macOS

  1. Provision the identity into a Keychain accessible to the Psono app.
  2. Grant Psono permission to use the private key, including any Keychain access-control settings applied by your provisioning mechanism.
  3. Set macos_identity_label to its exact identity label.

The label must resolve to exactly one identity. Provisioning into a Keychain does not itself override private-key access controls or app sandbox restrictions. Use the same label when replacing an identity and remove the old duplicate so selection remains unambiguous.

# Windows

  1. Provision the certificate and matching private key into the user's Personal certificate store (CurrentUser\My), or the machine's Personal store (LocalMachine\My).
  2. Set windows_certificate_store accordingly and set windows_certificate_thumbprint to the certificate's thumbprint.
  3. For machine-store identities, grant the interactive user running Psono access to the private key. Psono does not run as the MDM service or as an administrator.

Psono uses WinHTTP and the Windows certificate store. Private keys can remain non-exportable. Update the configured thumbprint when replacing the certificate during renewal.

For example, inspect the user's installed certificates with PowerShell:

Get-ChildItem Cert:\CurrentUser\My |
    Select-Object Subject, Thumbprint, HasPrivateKey, NotAfter

# Linux

Distribute the certificate chain and matching private key as separate PEM files, then reference their absolute paths. The app user must be able to read them. Restrict access to the private key to the intended user or dedicated group. The private key must not require an interactive password prompt.

For sandboxed packages, such as Flatpak, the files also need to be accessible within the application sandbox.

Psono reloads these files for new requests. Renew them using atomic file replacement and keep each certificate paired with its matching key. This file-based mechanism does not support PKCS#11 tokens or non-exportable hardware keys.

# Connections and renewal

  • Certificate settings apply to backend API requests, Remote Config downloads, protected file uploads/downloads, and iOS AutoFill API requests, when their origin is listed.
  • List each protected origin explicitly. A backend origin does not implicitly include a separate webclient or file server origin.
  • Managed connections do not follow HTTP redirects. Configure the final HTTPS endpoint directly, including the server path. This prevents forwarding credentials or request bodies to another destination.
  • Other origins use ordinary HTTPS without the configured identity.
  • Server certificate and hostname verification remain enabled. Client certificate configuration does not add a server CA or permit self-signed server certificates.
  • New managed requests use fresh identity lookups/connections so replacement or removal takes effect without reusing a previously authenticated TLS connection. An in-flight request may finish with its original identity.
  • Removing client_tls from managed configuration removes certificate use for subsequent requests. Removing an identity while its reference remains configured causes matching requests to fail.
  • Browser-based SAML/OIDC authentication uses the system authentication browser. Provision any certificate required by that browser separately; the app's identity reference does not configure it.

The proxy should enforce mTLS on the protected endpoints. App configuration selects the identity; the proxy's certificate validation determines which clients may connect.