Skip to content

Commit 55dba79

Browse files
authored
Add CORS and IPFS WebUI usage with remote Kubo RPC to Kubo Auth guide. (#2000)
* add cors and webui with auth rpc endpoint guide * address feedback --------- Co-authored-by: Daniel N <[email protected]>
1 parent 9bee736 commit 55dba79

File tree

4 files changed

+103
-3
lines changed

4 files changed

+103
-3
lines changed
Loading
27.9 KB
Loading
134 KB
Loading

docs/how-to/kubo-rpc-tls-auth.md

Lines changed: 103 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,14 +1,15 @@
11
---
22
title: Secure Kubo RPC with TLS and HTTP Auth
3-
description: Learn how to set up TLS for Kubo with Caddy reverse proxy for secure RPC API access over public networks.
3+
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.
44
---
55

66
# Secure Kubo RPC with TLS and HTTP Auth
77

8-
This guide will help you set up two things:
8+
This guide will help you set up several things:
99

1010
- **Transport Encryption:** Caddy as a reverse proxy with automatic TLS certificate management for your Kubo node using a domain you control.
1111
- **Authentication:** Basic HTTP authentication for the [Kubo RPC API](../reference/kubo/rpc.md).
12+
- **CORS (Cross-origin resource sharing):** Allow web requests from additional domains to the Kubo RPC API.
1213

1314
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.
1415

@@ -21,7 +22,7 @@ Before starting, ensure you have:
2122
- Port 443 open on your server's firewall
2223
- [Caddy web server](https://caddyserver.com/) installed on the server
2324

24-
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.
25+
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.
2526

2627
## Configure Kubo
2728

@@ -51,6 +52,16 @@ This configuration:
5152

5253
> **Note:** You should set the `AuthSecret` to a stronger username and password combination.
5354
55+
## Restart Kubo
56+
57+
After updating the Kubo config file, restart Kubo:
58+
59+
```bash
60+
sudo systemctl restart kubo
61+
```
62+
63+
> **Note:** the name of the service may be different depending on how you installed Kubo.
64+
5465
## Configure Caddy
5566

5667
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
90101

91102
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.
92103

104+
## Configuring CORS for use with IPFS Web UI
105+
106+
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.
107+
108+
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`.
109+
110+
### Kubo Config
111+
112+
Add `webui.ipfs.io` to the `API.HTTPHeaders.Access-Control-Allow-Origin` section in the Kubo config file (in addition to `YOUR_DOMAIN`):
113+
114+
```diff
115+
"API": {
116+
"HTTPHeaders": {
117+
- "Access-Control-Allow-Origin": ["https://YOUR_DOMAIN"],
118+
+ "Access-Control-Allow-Origin": ["https://YOUR_DOMAIN", "https://webui.ipfs.io"],
119+
"Access-Control-Allow-Credentials": ["true"]
120+
},
121+
}
122+
```
123+
124+
After updating the Kubo config file, restart the Kubo service:
125+
126+
```bash
127+
sudo systemctl restart kubo
128+
```
129+
130+
### Caddyfile
131+
132+
Update the Caddyfile to handle preflight `OPTIONS` requests from `webui.ipfs.io`:
133+
134+
```diff
135+
YOUR_DOMAIN {
136+
+ # Handle CORS preflight requests
137+
+ @options {
138+
+ method OPTIONS
139+
+ }
140+
+ handle @options {
141+
+ header {
142+
+ Access-Control-Allow-Origin "https://webui.ipfs.io"
143+
+ Access-Control-Allow-Methods "GET, POST, PUT, DELETE, OPTIONS"
144+
+ Access-Control-Allow-Headers "*"
145+
+ Access-Control-Allow-Credentials "true"
146+
+ }
147+
+ respond 204
148+
+ }
149+
150+
# Handle all other requests
151+
handle {
152+
reverse_proxy localhost:5001
153+
}
154+
155+
log {
156+
output stdout
157+
format json
158+
level INFO
159+
}
160+
}
161+
```
162+
163+
After updating the Caddyfile, restart Caddy:
164+
165+
```bash
166+
sudo systemctl restart caddy
167+
```
168+
169+
## Using the IPFS Web UI with the Kubo RPC API endpoint you configured
170+
171+
To use the [IPFS Web UI](https://webui.ipfs.io/) with the Kubo RPC API, you can pass the
172+
173+
Start by opening [webui.ipfs.io/#/welcome](https://webui.ipfs.io/#/welcome):
174+
175+
![WebUI Config](./images/ipfs-webui-config.png)
176+
177+
Enter the Kubo RPC API endpoint as follows, including the basic auth credentials:
178+
179+
```
180+
https://hello:world123@YOUR_DOMAIN
181+
```
182+
183+
> **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.
184+
185+
![WebUI Config](./images/ipfs-webui-config-domain.png)
186+
187+
Click on the "Submit" button, and you should see the IPFS Web UI connected to your Kubo node.
188+
189+
![WebUI Connected](./images/ipfs-webui-config-connected.png)
190+
191+
🎉 Congratulations! You can now use the IPFS Web UI to interact with your Kubo node.
192+
93193
## Security Considerations
94194

95195
- Change the `AuthSecret` to a strong username and password combination

0 commit comments

Comments
 (0)