Skip to content

fix: separate HTTP bind host from gRPC gateway target host #2824

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
omer-topal merged 1 commit into from
Mar 10, 2026
Merged

fix: separate HTTP bind host from gRPC gateway target host #2824

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
8 changes: 8 additions & 0 deletions docs/setting-up/configuration.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -23,10 +23,12 @@ docker run -p 3476:3476 -p 3478:3478 ghcr.io/permify/permify --help
# including whether or not TLS is enabled and the certificate and
# key file locations.
server:
host: ""
rate_limit: 100
http:
enabled: true
port: 3476
grpc_target_host: 127.0.0.1
tls:
enabled: true
cert: /etc/letsencrypt/live/yourdomain.com/fullchain.pem
Expand Down Expand Up @@ -137,10 +139,12 @@ Server options to run Permify. (`grpc` and `http` available for now.)

```
├── server
├── host
├── rate_limit
├── (`grpc` or `http`)
│ ├── enabled
│ ├── port
│ ├── grpc_target_host
│ └── tls
│ ├── enabled
│ ├── cert
Expand All @@ -151,10 +155,12 @@ Server options to run Permify. (`grpc` and `http` available for now.)

| Required | Argument | Default | Description |
|----------|---------------------------|---------|---------------------------------------------------------------------|
| [ ] | host | "" | host/interface to bind the HTTP server. |
| [ ] | rate_limit | 100 | the maximum number of requests the server should handle per second. |
| [x] | [ server_type ] | - | server option type can either be `grpc` or `http`. |
| [ ] | enabled (for server type) | true | switch option for server. |
| [x] | port | - | port that server run on. |
| [ ] | grpc_target_host (HTTP) |127.0.0.1| host the HTTP gateway uses to connect to the local gRPC server. |
| [x] | tls | - | transport layer security options. |
| [ ] | enabled (for tls) | false | switch option for tls |
| [ ] | cert | - | tls certificate path. |
Expand All @@ -164,13 +170,15 @@ Server options to run Permify. (`grpc` and `http` available for now.)

| Argument | ENV | Type |
|---------------------------|-----------------------------------|--------------|
| server-host | PERMIFY_SERVER_HOST | string |
| rate_limit | PERMIFY_RATE_LIMIT | int |
| grpc-port | PERMIFY_GRPC_PORT | string |
| grpc-tls-enabled | PERMIFY_GRPC_TLS_ENABLED | boolean |
| grpc-tls-key-path | PERMIFY_GRPC_TLS_KEY_PATH | string |
| grpc-tls-cert-path | PERMIFY_GRPC_TLS_CERT_PATH | string |
| http-enabled | PERMIFY_HTTP_ENABLED | boolean |
| http-port | PERMIFY_HTTP_PORT | string |
| http-grpc-target-host | PERMIFY_HTTP_GRPC_TARGET_HOST | string |
| http-tls-key-path | PERMIFY_HTTP_TLS_KEY_PATH | string |
| http-tls-cert-path | PERMIFY_HTTP_TLS_CERT_PATH | string |
| http-cors-allowed-origins | PERMIFY_HTTP_CORS_ALLOWED_ORIGINS | string array |
Expand Down
2 changes: 2 additions & 0 deletions example.config.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,10 +4,12 @@ account_id: ""
# including whether or not TLS is enabled and the certificate and
# key file locations.
server:
host: ""
rate_limit: 100
http:
enabled: true
port: 3476
grpc_target_host: 127.0.0.1
tls:
enabled: false
cert: /etc/letsencrypt/live/yourdomain.com/fullchain.pem
Expand Down
8 changes: 5 additions & 3 deletions internal/config/config.go
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -38,6 +38,7 @@ type (
HTTP struct {
Enabled bool `mapstructure:"enabled"` // Whether the HTTP server is enabled
Port string `mapstructure:"port"` // Port for the HTTP server
GRPCTargetHost string `mapstructure:"grpc_target_host"` // Host the HTTP gateway uses to reach the local gRPC server
TLSConfig TLSConfig `mapstructure:"tls"` // TLS configuration for the HTTP server
CORSAllowedOrigins []string `mapstructure:"cors_allowed_origins"` // List of allowed origins for CORS
CORSAllowedHeaders []string `mapstructure:"cors_allowed_headers"` // List of allowed headers for CORS
Expand Down Expand Up @@ -284,10 +285,11 @@ func DefaultConfig() *Config {
AccountID: "",
Server: Server{
NameOverride: "",
Host: "127.0.0.1",
Host: "",
HTTP: HTTP{
Enabled: true,
Port: "3476",
Enabled: true,
Port: "3476",
GRPCTargetHost: "127.0.0.1",
Comment on lines +288 to +292
Copy link
Copy Markdown

@coderabbitai coderabbitai Bot Mar 10, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟠 Major

Keep server.host loopback-only by default.

Setting Host to "" makes the HTTP server bind :3476, i.e. all interfaces. That broadens network exposure on upgrade even though this change only needs to decouple the gateway dial target from the bind address. Please keep the bind default on loopback and use server.http.grpc_target_host only for the internal gRPC dial path.

Suggested fix 
 		Server: Server{
 			NameOverride: "",
-			Host:         "",
+			Host:         "127.0.0.1",
 			HTTP: HTTP{
 				Enabled:        true,
 				Port:           "3476",
 				GRPCTargetHost: "127.0.0.1",
📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change
Host: "",
HTTP: HTTP{
Enabled: true,
Port: "3476",
Enabled: true,
Port: "3476",
GRPCTargetHost: "127.0.0.1",
Host: "127.0.0.1",
HTTP: HTTP{
Enabled: true,
Port: "3476",
GRPCTargetHost: "127.0.0.1",
🤖 Prompt for AI Agents 
Verify each finding against the current code and only fix it if needed.

In `@internal/config/config.go` around lines 288 - 292, The server default
currently sets Host = "" which binds to all interfaces; change the default to
loopback-only by setting Host to "127.0.0.1" (or "::1" if IPv6 desired) while
leaving HTTP.GRPCTargetHost (server.http.grpc_target_host) unchanged for
internal gRPC dialing; update the default in the config struct where Host and
HTTP (Enabled, Port, GRPCTargetHost) are initialized so the HTTP server binds to
loopback by default but continues to use GRPCTargetHost for the internal dial
path.

TLSConfig: TLSConfig{
Enabled: false,
},
Expand Down
6 changes: 6 additions & 0 deletions internal/config/config_test.go
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -18,7 +18,9 @@ func TestNewConfig_FileNotFound(t *testing.T) {
assert.NotNil(t, cfg)

// Check if default values are applied correctly
assert.Equal(t, "", cfg.Server.Host)
assert.Equal(t, "3476", cfg.Server.HTTP.Port)
assert.Equal(t, "127.0.0.1", cfg.Server.HTTP.GRPCTargetHost)
assert.Equal(t, "3478", cfg.Server.GRPC.Port)
assert.Equal(t, "info", cfg.Log.Level)
}
Expand Down Expand Up @@ -59,6 +61,8 @@ logger:
assert.Equal(t, "debug", cfg.Log.Level)

// Check if default values are applied correctly
assert.Equal(t, "", cfg.Server.Host)
assert.Equal(t, "127.0.0.1", cfg.Server.HTTP.GRPCTargetHost)
assert.False(t, cfg.Server.HTTP.TLSConfig.Enabled)
assert.False(t, cfg.Server.GRPC.TLSConfig.Enabled)
assert.False(t, cfg.Profiler.Enabled)
Expand Down Expand Up @@ -131,6 +135,8 @@ database:
assert.Equal(t, "postgres://user:password@localhost/dbname", cfg.Database.URI)

// Check if default values are applied correctly
assert.Equal(t, "", cfg.Server.Host)
assert.Equal(t, "127.0.0.1", cfg.Server.HTTP.GRPCTargetHost)
assert.Equal(t, "3478", cfg.Server.GRPC.Port)
assert.False(t, cfg.Server.HTTP.TLSConfig.Enabled)
assert.False(t, cfg.Server.GRPC.TLSConfig.Enabled)
Expand Down
4 changes: 2 additions & 2 deletions internal/servers/server.go
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -269,8 +269,8 @@ func (s *Container) Run(
options = append(options, grpc.WithTransportCredentials(insecure.NewCredentials()))
}

targetAddr := net.JoinHostPort(srv.Host, srv.GRPC.Port) // gRPC server address
conn, err := grpc.NewClient(targetAddr, options...) // Create gRPC client connection
targetAddr := net.JoinHostPort(srv.HTTP.GRPCTargetHost, srv.GRPC.Port)
conn, err := grpc.NewClient(targetAddr, options...) // Create gRPC client connection
if err != nil {
return err
}
Expand Down
4 changes: 4 additions & 0 deletions pkg/cmd/config.go
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -30,12 +30,14 @@ func NewConfigCommand() *cobra.Command {
f.Bool("http-enabled", conf.Server.HTTP.Enabled, "switch option for HTTP server")
f.String("account-id", conf.AccountID, "account id")
f.Int64("server-rate-limit", conf.Server.RateLimit, "the maximum number of requests the server should handle per second")
f.String("server-host", conf.Server.Host, "host/interface to bind the HTTP server")
f.String("server-name-override", conf.Server.NameOverride, "server name override")
f.String("grpc-port", conf.Server.GRPC.Port, "port that GRPC server run on")
f.Bool("grpc-tls-enabled", conf.Server.GRPC.TLSConfig.Enabled, "switch option for GRPC tls server")
f.String("grpc-tls-key-path", conf.Server.GRPC.TLSConfig.KeyPath, "GRPC tls key path")
f.String("grpc-tls-cert-path", conf.Server.GRPC.TLSConfig.CertPath, "GRPC tls certificate path")
f.String("http-port", conf.Server.HTTP.Port, "HTTP port address")
f.String("http-grpc-target-host", conf.Server.HTTP.GRPCTargetHost, "host the HTTP gateway uses to connect to the local gRPC server")
f.Bool("http-tls-enabled", conf.Server.HTTP.TLSConfig.Enabled, "switch option for HTTP tls server")
f.String("http-tls-key-path", conf.Server.HTTP.TLSConfig.KeyPath, "HTTP tls key path")
f.String("http-tls-cert-path", conf.Server.HTTP.TLSConfig.CertPath, "HTTP tls certificate path")
Expand Down Expand Up @@ -154,12 +156,14 @@ func conf() func(cmd *cobra.Command, args []string) error { // Return config han
data = append(data,
[]string{"account_id", cfg.AccountID, getKeyOrigin(cmd, "account-id", "PERMIFY_ACCOUNT_ID")},
// SERVER
[]string{"server.host", cfg.Server.Host, getKeyOrigin(cmd, "server-host", "PERMIFY_SERVER_HOST")},
[]string{"server.name_override", fmt.Sprintf("%v", cfg.Server.NameOverride), getKeyOrigin(cmd, "server-name-override", "PERMIFY_NAME_OVERRIDE")},
[]string{"server.rate_limit", fmt.Sprintf("%v", cfg.Server.RateLimit), getKeyOrigin(cmd, "server-rate-limit", "PERMIFY_RATE_LIMIT")},
[]string{"server.grpc.port", cfg.Server.GRPC.Port, getKeyOrigin(cmd, "grpc-port", "PERMIFY_GRPC_PORT")},
[]string{"server.grpc.tls.enabled", fmt.Sprintf("%v", cfg.Server.GRPC.TLSConfig.Enabled), getKeyOrigin(cmd, "grpc-tls-enabled", "PERMIFY_GRPC_TLS_ENABLED")},
[]string{"server.grpc.tls.cert", cfg.Server.GRPC.TLSConfig.CertPath, getKeyOrigin(cmd, "grpc-tls-cert-path", "PERMIFY_GRPC_TLS_CERT_PATH")},
[]string{"server.http.enabled", fmt.Sprintf("%v", cfg.Server.HTTP.Enabled), getKeyOrigin(cmd, "http-enabled", "PERMIFY_HTTP_ENABLED")},
[]string{"server.http.grpc_target_host", cfg.Server.HTTP.GRPCTargetHost, getKeyOrigin(cmd, "http-grpc-target-host", "PERMIFY_HTTP_GRPC_TARGET_HOST")},
[]string{"server.http.tls.enabled", fmt.Sprintf("%v", cfg.Server.HTTP.TLSConfig.Enabled), getKeyOrigin(cmd, "http-tls-enabled", "PERMIFY_HTTP_TLS_ENABLED")},
[]string{"server.http.tls.key", HideSecret(cfg.Server.HTTP.TLSConfig.KeyPath), getKeyOrigin(cmd, "http-tls-key-path", "PERMIFY_HTTP_TLS_KEY_PATH")},
[]string{"server.http.tls.cert", HideSecret(cfg.Server.HTTP.TLSConfig.CertPath), getKeyOrigin(cmd, "http-tls-cert-path", "PERMIFY_HTTP_TLS_CERT_PATH")},
Expand Down
14 changes: 14 additions & 0 deletions pkg/cmd/flags/serve.go
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -29,6 +29,13 @@ func RegisterServeFlags(flags *pflag.FlagSet) {
panic(err)
}

if err = viper.BindPFlag("server.host", flags.Lookup("server-host")); err != nil {
panic(err)
}
if err = viper.BindEnv("server.host", "PERMIFY_SERVER_HOST"); err != nil {
panic(err)
}

if err = viper.BindPFlag("server.name_override", flags.Lookup("server-name-override")); err != nil {
panic(err)
}
Expand Down Expand Up @@ -80,6 +87,13 @@ func RegisterServeFlags(flags *pflag.FlagSet) {
panic(err)
}

if err = viper.BindPFlag("server.http.grpc_target_host", flags.Lookup("http-grpc-target-host")); err != nil {
panic(err)
}
if err = viper.BindEnv("server.http.grpc_target_host", "PERMIFY_HTTP_GRPC_TARGET_HOST"); err != nil {
panic(err)
}

if err = viper.BindPFlag("server.http.tls.enabled", flags.Lookup("http-tls-enabled")); err != nil {
panic(err)
}
Expand Down
2 changes: 2 additions & 0 deletions pkg/cmd/serve.go
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -60,12 +60,14 @@ func NewServeCommand() *cobra.Command {
f.Bool("http-enabled", conf.Server.HTTP.Enabled, "switch option for HTTP server")
f.String("account-id", conf.AccountID, "account id")
f.Int64("server-rate-limit", conf.Server.RateLimit, "the maximum number of requests the server should handle per second")
f.String("server-host", conf.Server.Host, "host/interface to bind the HTTP server")
f.String("server-name-override", conf.Server.NameOverride, "server name override")
f.String("grpc-port", conf.Server.GRPC.Port, "port that GRPC server run on")
f.Bool("grpc-tls-enabled", conf.Server.GRPC.TLSConfig.Enabled, "switch option for GRPC tls server")
f.String("grpc-tls-key-path", conf.Server.GRPC.TLSConfig.KeyPath, "GRPC tls key path")
f.String("grpc-tls-cert-path", conf.Server.GRPC.TLSConfig.CertPath, "GRPC tls certificate path")
f.String("http-port", conf.Server.HTTP.Port, "HTTP port address")
f.String("http-grpc-target-host", conf.Server.HTTP.GRPCTargetHost, "host the HTTP gateway uses to connect to the local gRPC server")
f.Bool("http-tls-enabled", conf.Server.HTTP.TLSConfig.Enabled, "switch option for HTTP tls server")
f.String("http-tls-key-path", conf.Server.HTTP.TLSConfig.KeyPath, "HTTP tls key path")
f.String("http-tls-cert-path", conf.Server.HTTP.TLSConfig.CertPath, "HTTP tls certificate path")
Expand Down