mTLS Authentication

Mutual TLS (mTLS) adds device-level authentication to nproxy. Only devices with a valid client certificate can access your organization's proxy -- even if an API token is compromised, an unmanaged device cannot use it.

Requires the Enterprise plan.

How it works

Standard TLS (HTTPS) only authenticates the server to the client. With mTLS, the client also authenticates to the server by presenting a certificate signed by your organization's Certificate Authority (CA).

When mTLS is enabled for your organization:

1. The client (developer's machine or CI/CD runner) presents a client certificate during the TLS handshake
2. The certificate chain is verified
3. nproxy checks that the certificate was signed by an allowed CA (via fingerprint matching)
4. If verification passes, the request proceeds. If not, the request is rejected with a 403 error.

Authentication flow

When mtlsRequired is enabled, the proxy evaluates requests in this order:

1. Token with cicd scope -- If a valid token with the cicd scope is present, the request is allowed regardless of certificate status. This is the bypass path for CI/CD pipelines that cannot present client certificates.
2. Valid client certificate — If a certificate is presented, verified, and its fingerprint is in the allowed list, the request is allowed.
3. Neither -- The request is rejected with 403 mTLS required.

This means mTLS and token auth work together: tokens authenticate the user, certificates authenticate the device.

Identity extraction

When a valid certificate is presented, nproxy extracts the user's email address from the certificate's Subject DN. It checks these fields in order:

1. emailAddress= field
2. E= field
3. CN= field (only if the CN value looks like an email address)

The extracted identity is available in audit logs and the MtlsAuthResult.

Setting up mTLS

1. Create your Certificate Authority

If you do not already have an internal CA, create one:

# Generate CA private key
openssl genrsa -out ca-key.pem 4096

# Generate CA certificate (valid for 10 years)
openssl req -new -x509 -key ca-key.pem -out ca-cert.pem -days 3650 \
  -subj "/O=Acme Inc/CN=Acme Internal CA"

2. Generate client certificates

Create a client certificate for each developer or device:

# Generate client private key
openssl genrsa -out client-key.pem 2048

# Generate certificate signing request
openssl req -new -key client-key.pem -out client.csr \
  -subj "/CN=jane@acme.com/O=Acme Inc"

# Sign with your CA
openssl x509 -req -in client.csr -CA ca-cert.pem -CAkey ca-key.pem \
  -CAcreateserial -out client-cert.pem -days 365

3. Get the CA certificate fingerprint

openssl x509 -in ca-cert.pem -noout -fingerprint -sha256

This outputs something like: SHA256 Fingerprint=AB:CD:12:34:...

4. Configure nproxy

In the dashboard, go to Settings and:

1. Add the CA fingerprint (SHA-256) to the Allowed CA Fingerprints list
2. Enable mTLS Required

Or via the API:

curl -X PUT https://nproxy.app/api/v1/orgs/{orgId}/settings \
  -H "Authorization: Bearer <session>" \
  -H "Content-Type: application/json" \
  -d '{
    "mtlsRequired": true,
    "allowedCAFingerprints": ["ABCD1234..."]
  }'

5. Distribute certificates via MDM

Push the client certificate and private key to managed devices using your MDM solution (Jamf, Intune, Kandji, etc.). The certificate should be installed in the system keychain or a location where curl/Node.js can access it.

CI/CD bypass

CI/CD runners typically cannot present client certificates. Instead, create an API token with the cicd scope:

1. In the dashboard, create a new API token with the cicd scope
2. Use this token in your CI/CD pipeline's Authorization header or .npmrc

Tokens with the cicd scope bypass the mTLS requirement entirely. Use them only for CI/CD pipelines, and rotate them regularly.

MDM deployment guide

For a zero-friction deployment, push all three artifacts to managed devices via MDM:

Developers do not need to run any commands or configure anything manually.

Troubleshooting

Audit events

When an mTLS check fails, nproxy logs an mtls.rejected audit event with the error details. This helps security teams identify unauthorized access attempts.