diff --git a/docs/how-to/images/ipfs-webui-config-connected.png b/docs/how-to/images/ipfs-webui-config-connected.png new file mode 100644 index 000000000..22a978c63 Binary files /dev/null and b/docs/how-to/images/ipfs-webui-config-connected.png differ diff --git a/docs/how-to/images/ipfs-webui-config-domain.png b/docs/how-to/images/ipfs-webui-config-domain.png new file mode 100644 index 000000000..b3b0485d1 Binary files /dev/null and b/docs/how-to/images/ipfs-webui-config-domain.png differ diff --git a/docs/how-to/images/ipfs-webui-config.png b/docs/how-to/images/ipfs-webui-config.png new file mode 100644 index 000000000..d41ef98d2 Binary files /dev/null and b/docs/how-to/images/ipfs-webui-config.png differ diff --git a/docs/how-to/kubo-rpc-tls-auth.md b/docs/how-to/kubo-rpc-tls-auth.md index 55f29dad7..7b649750b 100644 --- a/docs/how-to/kubo-rpc-tls-auth.md +++ b/docs/how-to/kubo-rpc-tls-auth.md @@ -1,14 +1,15 @@ --- title: Secure Kubo RPC with TLS and HTTP Auth -description: Learn how to set up TLS for Kubo with Caddy reverse proxy for secure RPC API access over public networks. +description: Set up TLS for Kubo with Caddy reverse proxy for secure RPC API access over public networks, and use the IPFS Web UI with the configured RPC API endpoint. --- # Secure Kubo RPC with TLS and HTTP Auth -This guide will help you set up two things: +This guide will help you set up several things: - **Transport Encryption:** Caddy as a reverse proxy with automatic TLS certificate management for your Kubo node using a domain you control. - **Authentication:** Basic HTTP authentication for the [Kubo RPC API](../reference/kubo/rpc.md). +- **CORS (Cross-origin resource sharing):** Allow web requests from additional domains to the Kubo RPC API. This is highly recommended if you run your own Kubo node and want to use the Kubo RPC API over public networks, for example, to pin CIDs from CI, or other services. Since the Kubo RPC API is exposed over plain HTTP, TLS is used to ensure the connection to the API is encrypted. @@ -21,7 +22,7 @@ Before starting, ensure you have: - Port 443 open on your server's firewall - [Caddy web server](https://caddyserver.com/) installed on the server -The guide assumes the Caddy process is managed by systemd. If you are using a different process manager or Docker, you will need to adjust the configuration accordingly. +The guide assumes the Caddy and Kubo are managed by systemd. If you are using a different process manager or Docker, you will need to adjust the configuration accordingly. ## Configure Kubo @@ -51,6 +52,16 @@ This configuration: > **Note:** You should set the `AuthSecret` to a stronger username and password combination. +## Restart Kubo + +After updating the Kubo config file, restart Kubo: + +```bash +sudo systemctl restart kubo +``` + +> **Note:** the name of the service may be different depending on how you installed Kubo. + ## Configure Caddy Create or edit your Caddyfile (typically at `/etc/caddy/Caddyfile`) with the following configuration, making sure to replace `YOUR_DOMAIN` with your actual domain name: @@ -90,6 +101,95 @@ ipfs id --api /dns/YOUR_DOMAIN/tcp/443/https --api-auth basic:hello:world123 If successful, you should see your node's identify displayed. The command connects to your Kubo node through the secure HTTPS endpoint using basic authentication. +## Configuring CORS for use with IPFS Web UI + +In this step, we will configure [CORS](https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS) to allow the [webui.ipfs.io](https://webui.ipfs.io/) to access the Kubo RPC API. + +For this, you will need to update both the Kubo config file to allow requests from `webui.ipfs.io` and the Caddyfile to correctly handle preflight `OPTIONS` requests from `webui.ipfs.io`. + +### Kubo Config + +Add `webui.ipfs.io` to the `API.HTTPHeaders.Access-Control-Allow-Origin` section in the Kubo config file (in addition to `YOUR_DOMAIN`): + +```diff +"API": { + "HTTPHeaders": { +- "Access-Control-Allow-Origin": ["https://YOUR_DOMAIN"], ++ "Access-Control-Allow-Origin": ["https://YOUR_DOMAIN", "https://webui.ipfs.io"], + "Access-Control-Allow-Credentials": ["true"] + }, +} +``` + +After updating the Kubo config file, restart the Kubo service: + +```bash +sudo systemctl restart kubo +``` + +### Caddyfile + +Update the Caddyfile to handle preflight `OPTIONS` requests from `webui.ipfs.io`: + +```diff +YOUR_DOMAIN { ++ # Handle CORS preflight requests ++ @options { ++ method OPTIONS ++ } ++ handle @options { ++ header { ++ Access-Control-Allow-Origin "https://webui.ipfs.io" ++ Access-Control-Allow-Methods "GET, POST, PUT, DELETE, OPTIONS" ++ Access-Control-Allow-Headers "*" ++ Access-Control-Allow-Credentials "true" ++ } ++ respond 204 ++ } + + # Handle all other requests + handle { + reverse_proxy localhost:5001 + } + + log { + output stdout + format json + level INFO + } +} +``` + +After updating the Caddyfile, restart Caddy: + +```bash +sudo systemctl restart caddy +``` + +## Using the IPFS Web UI with the Kubo RPC API endpoint you configured + +To use the [IPFS Web UI](https://webui.ipfs.io/) with the Kubo RPC API, you can pass the + +Start by opening [webui.ipfs.io/#/welcome](https://webui.ipfs.io/#/welcome): + +![WebUI Config](./images/ipfs-webui-config.png) + +Enter the Kubo RPC API endpoint as follows, including the basic auth credentials: + +``` +https://hello:world123@YOUR_DOMAIN +``` + +> **Note:** Make sure to replace `hello:world123` with the credentials you configured in the Kubo config file, and `YOUR_DOMAIN` with your actual domain name. + +![WebUI Config](./images/ipfs-webui-config-domain.png) + +Click on the "Submit" button, and you should see the IPFS Web UI connected to your Kubo node. + +![WebUI Connected](./images/ipfs-webui-config-connected.png) + +🎉 Congratulations! You can now use the IPFS Web UI to interact with your Kubo node. + ## Security Considerations - Change the `AuthSecret` to a strong username and password combination