# Resolving SSL Certificate Issues with PDP Behind a Proxy

When running the Permit.io PDP inside a Docker container behind a proxy (such as Zscaler, corporate MITM proxies, or internal firewalls), you may encounter SSL errors like:

```
HTTPSConnectionPool(host='api.permit.io', port=443): Max retries exceeded with url: /v2/pdps/me/config 
(Caused by SSLError(SSLCertVerificationError(1, 
'[SSL: CERTIFICATE_VERIFY_FAILED] certificate verify failed: 
unable to get local issuer certificate (_ssl.c:1007)')))
```

## Summary

This error is due to the PDP container being unable to verify the SSL certificate presented by the `api.permit.io` server, often because:

* A proxy is intercepting traffic and presenting its own certificate.
* The proxy’s root certificate is not trusted by the Python runtime in the container.

This affects Python apps because they typically use the `certifi` package (rather than the OS-level certificate store) to validate SSL certificates.

## Symptoms

* `wget https://api.permit.io` inside the container **succeeds** after adding the proxy root certificate to the system CA store.
* The Python-based PDP continues to **fail** with a certificate verification error.
* Other tools like `curl` may not be available inside the container.

## Debugging the Problem (Inside the Container)

To perform all of the following steps, you need to get a shell into the running container:

### 1. Start a Shell in the Running Container

```bash
docker ps  # Find your running container's ID or name
docker exec -it <container_id_or_name> sh
```

### 2. Check Basic Connectivity

```bash
ping api.permit.io
```

### 3. Check DNS Resolution

```bash
nslookup api.permit.io
```

If `nslookup` is not available, install it or test with `ping`.

### 4. Run OpenSSL Certificate Test

```bash
openssl s_client -connect api.permit.io:443 -showcerts
```

Look for `Verify return code: 0 (ok)` — if not, there is likely a trust issue.

### 5. Run `wget` Test

```bash
wget https://api.permit.io -O /dev/null
```

If this works, the system CA trust is likely fixed. If PDP still fails, Python likely isn't using that store.

## Resolution Steps

### A. Add Your Proxy's Root Certificate to the Container

1. **Copy the proxy root certificate (e.g. `proxy-ca.pem`) into the container.**
   You can do this by mounting it:

   ```bash
   docker run -v $(pwd)/proxy-ca.pem:/etc/ssl/certs/proxy-ca.pem ...
   ```

   Or copying into a running container:

   ```bash
   docker cp proxy-ca.pem <container_id>:/etc/ssl/certs/proxy-ca.pem
   ```

2. **Install it to the system CA store:**

   ```bash
   cp /etc/ssl/certs/proxy-ca.pem /usr/local/share/ca-certificates/proxy-ca.crt
   update-ca-certificates
   ```

### B. Tell Python to Use the System CA Store

Set the following environment variables so Python uses the updated system CA bundle:

```bash
export SSL_CERT_FILE=/etc/ssl/certs/ca-certificates.crt
export REQUESTS_CA_BUNDLE=/etc/ssl/certs/ca-certificates.crt
```

Add these to your `docker run` command:

```bash
docker run -it \
  -p 7766:7000 \
  --env PDP_API_KEY=your_api_key \
  --env PDP_DEBUG=True \
  --env SSL_CERT_FILE=/etc/ssl/certs/ca-certificates.crt \
  --env REQUESTS_CA_BUNDLE=/etc/ssl/certs/ca-certificates.crt \
  permitio/pdp-v2:latest
```

### C. (Alternative) Patch Python's Certifi CA Bundle

If the app ignores the above env vars, patch the certifi bundle manually:

```bash
python -m certifi  # Get the path to the certifi bundle
cat /etc/ssl/certs/proxy-ca.crt >> /path/to/certifi/cacert.pem
```

> Note: This method will be overwritten on package updates and is less maintainable.

## Final Verification

* Restart the PDP container and confirm the SSL error no longer occurs.
* You should see successful syncing with `api.permit.io` in logs.
* You can also test from within the container:

  ```bash
  python -c "import requests; print(requests.get('https://api.permit.io').status_code)"
  ```

## Troubleshooting Tips

* Ensure your certificate file is valid PEM format.
* If `wget` works but `pdp` fails, Python is likely not trusting the proxy certificate.
* If you're using Apple Silicon, check for ARM vs x86 image compatibility.
* If using a proxy, verify whether MITM interception is active.
* Use debugging tools like `openssl`, `wget`, and Python scripts inside the container to test step-by-step.

## Summary

PDP will fail behind a proxy unless the proxy’s root certificate is explicitly trusted. Fixing the issue requires either telling Python to trust the system CA store, or manually updating Python's certifi bundle inside the container. This doc provides a generic approach that applies to most proxy-related SSL issues in Docker-based Python apps.
