From f98e8bb2bc9a6bb0ff8d6905b7fe2431ac685a50 Mon Sep 17 00:00:00 2001 From: ivanauth Date: Sat, 18 Oct 2025 00:54:58 -0400 Subject: [PATCH 1/2] Clarify local development security settings for non-localhost scenarios Fixes #350 Updated documentation to address confusion around INSECURE_PLAINTEXT_CREDENTIALS vs INSECURE_LOCALHOST_ALLOWED when using Orbstack, Docker, or other non-localhost setups for local SpiceDB development. Changes: - Added callout explaining when to use INSECURE_PLAINTEXT_CREDENTIALS - Clarified INSECURE_LOCALHOST_ALLOWED limitations with Docker/Orbstack hostnames - Added "Local Development Tips" section with quick reference for all languages - Production examples remain secure and production-ready --- .../getting-started/client-libraries.mdx | 12 ++++++++++++ .../getting-started/protecting-a-blog.mdx | 17 ++++++++++++++++- 2 files changed, 28 insertions(+), 1 deletion(-) diff --git a/pages/spicedb/getting-started/client-libraries.mdx b/pages/spicedb/getting-started/client-libraries.mdx index f233e28..43c1ede 100644 --- a/pages/spicedb/getting-started/client-libraries.mdx +++ b/pages/spicedb/getting-started/client-libraries.mdx @@ -16,6 +16,18 @@ the primary documentation for the gRPC API is in the [buf documentation] for Spi The gRPC client documentation associated with each host language will also be helpful for putting together invocations. Additionally, there are `example` directories in the client libraries that provide example usages. +## Local Development Tips + +When developing locally with SpiceDB running without TLS (localhost, Docker, Orbstack, etc.), you'll need to use insecure credentials in your client configuration: + +- **Node.js**: Use `v1.ClientSecurity.INSECURE_PLAINTEXT_CREDENTIALS` as the third parameter to `v1.NewClient()` +- **Python**: Use `insecure_bearer_token_credentials()` instead of `bearer_token_credentials()` +- **Go**: Use `grpcutil.WithInsecureBearerToken()` and `grpc.WithTransportCredentials(insecure.NewCredentials())` +- **Ruby**: Use `credentials: :this_channel_is_insecure` when creating the client +- **Java**: Use `.usePlaintext()` on your `ManagedChannelBuilder` + +See the [Protecting a Blog Application](./protecting-a-blog#checking-permissions) guide for detailed examples and important security notes about switching to TLS-secured credentials before deploying to production. + ## HTTP Clients SpiceDB exposes an HTTP API when run with the `--http-enabled` flag. diff --git a/pages/spicedb/getting-started/protecting-a-blog.mdx b/pages/spicedb/getting-started/protecting-a-blog.mdx index 9df7d3c..93aa54b 100644 --- a/pages/spicedb/getting-started/protecting-a-blog.mdx +++ b/pages/spicedb/getting-started/protecting-a-blog.mdx @@ -730,6 +730,21 @@ When doing a permission check, in order to get read-after-write consistency, you The following examples demonstrate the transitive property of checks: + +**Local Development Security Settings:** + +When connecting to SpiceDB running locally without TLS, use `INSECURE_PLAINTEXT_CREDENTIALS` (Node.js), `insecure_bearer_token_credentials` (Python), or the equivalent insecure option for your client library. This is the recommended setting for **any** local development scenario, including: +- Localhost connections +- Docker containers (including Docker Desktop) +- Orbstack with `*.orb.local` hostnames +- Remote Kubernetes port-forwards +- Any other non-TLS local setup + +Note: `INSECURE_LOCALHOST_ALLOWED` (if available in your client) works for true localhost connections and port-forwards, but will fail when connecting to Docker containers or Orbstack with non-localhost hostnames like `*.orb.local`. For broader compatibility across all local development scenarios, use `INSECURE_PLAINTEXT_CREDENTIALS` instead. + +**Important:** Always switch back to TLS-secured credentials (e.g., `bearer_token_credentials`) before deploying to production. + + @@ -749,7 +764,7 @@ import { v1 } from '@authzed/authzed-node'; const { promises: client } = v1.NewClient( 't_your_token_here_1234567deadbeef', 'grpc.authzed.com:50051', - // NOTE: Remove if SpiceDB is behind TLS + // For local development without TLS (localhost, Docker, Orbstack, etc.) v1.ClientSecurity.INSECURE_PLAINTEXT_CREDENTIALS ); From 5db994c6042447906fdc7777298b217b5ab5d6a4 Mon Sep 17 00:00:00 2001 From: ivanauth Date: Thu, 23 Oct 2025 11:36:24 -0400 Subject: [PATCH 2/2] Improve local development credential documentation Address issue with INSECURE_PLAINTEXT_CREDENTIALS vs INSECURE_LOCALHOST_ALLOWED confusion for non-localhost scenarios. Improved formatting and conciseness to match existing documentation style. Fixes #350 --- .../getting-started/client-libraries.mdx | 17 +++++++------- .../getting-started/protecting-a-blog.mdx | 23 ++++++++----------- 2 files changed, 19 insertions(+), 21 deletions(-) diff --git a/pages/spicedb/getting-started/client-libraries.mdx b/pages/spicedb/getting-started/client-libraries.mdx index 43c1ede..760b760 100644 --- a/pages/spicedb/getting-started/client-libraries.mdx +++ b/pages/spicedb/getting-started/client-libraries.mdx @@ -16,17 +16,18 @@ the primary documentation for the gRPC API is in the [buf documentation] for Spi The gRPC client documentation associated with each host language will also be helpful for putting together invocations. Additionally, there are `example` directories in the client libraries that provide example usages. -## Local Development Tips +## Local Development -When developing locally with SpiceDB running without TLS (localhost, Docker, Orbstack, etc.), you'll need to use insecure credentials in your client configuration: +When developing locally with SpiceDB running without TLS, you'll need to configure insecure credentials: -- **Node.js**: Use `v1.ClientSecurity.INSECURE_PLAINTEXT_CREDENTIALS` as the third parameter to `v1.NewClient()` -- **Python**: Use `insecure_bearer_token_credentials()` instead of `bearer_token_credentials()` -- **Go**: Use `grpcutil.WithInsecureBearerToken()` and `grpc.WithTransportCredentials(insecure.NewCredentials())` -- **Ruby**: Use `credentials: :this_channel_is_insecure` when creating the client -- **Java**: Use `.usePlaintext()` on your `ManagedChannelBuilder` +- **Node.js**: `v1.ClientSecurity.INSECURE_PLAINTEXT_CREDENTIALS` +- **Python**: `insecure_bearer_token_credentials()` +- **Go**: `grpcutil.WithInsecureBearerToken()` and `grpc.WithTransportCredentials(insecure.NewCredentials())` +- **Ruby**: `credentials: :this_channel_is_insecure` +- **Java**: `.usePlaintext()` +- **Dotnet**: `ChannelCredentials.Insecure` with `UnsafeUseInsecureChannelCallCredentials = true` -See the [Protecting a Blog Application](./protecting-a-blog#checking-permissions) guide for detailed examples and important security notes about switching to TLS-secured credentials before deploying to production. +See the [Protecting a Blog Application](./protecting-a-blog#checking-permissions) guide for examples. ## HTTP Clients diff --git a/pages/spicedb/getting-started/protecting-a-blog.mdx b/pages/spicedb/getting-started/protecting-a-blog.mdx index 93aa54b..d8627ae 100644 --- a/pages/spicedb/getting-started/protecting-a-blog.mdx +++ b/pages/spicedb/getting-started/protecting-a-blog.mdx @@ -731,18 +731,15 @@ When doing a permission check, in order to get read-after-write consistency, you The following examples demonstrate the transitive property of checks: -**Local Development Security Settings:** - -When connecting to SpiceDB running locally without TLS, use `INSECURE_PLAINTEXT_CREDENTIALS` (Node.js), `insecure_bearer_token_credentials` (Python), or the equivalent insecure option for your client library. This is the recommended setting for **any** local development scenario, including: -- Localhost connections -- Docker containers (including Docker Desktop) -- Orbstack with `*.orb.local` hostnames -- Remote Kubernetes port-forwards -- Any other non-TLS local setup - -Note: `INSECURE_LOCALHOST_ALLOWED` (if available in your client) works for true localhost connections and port-forwards, but will fail when connecting to Docker containers or Orbstack with non-localhost hostnames like `*.orb.local`. For broader compatibility across all local development scenarios, use `INSECURE_PLAINTEXT_CREDENTIALS` instead. - -**Important:** Always switch back to TLS-secured credentials (e.g., `bearer_token_credentials`) before deploying to production. +When developing locally with SpiceDB without TLS, use insecure credentials in your client library: +- **Node.js**: `INSECURE_PLAINTEXT_CREDENTIALS` +- **Python**: `insecure_bearer_token_credentials()` +- **Go**: `grpcutil.WithInsecureBearerToken()` and `grpc.WithTransportCredentials(insecure.NewCredentials())` +- **Ruby**: `credentials: :this_channel_is_insecure` +- **Java**: `.usePlaintext()` +- **Dotnet**: `ChannelCredentials.Insecure` with `UnsafeUseInsecureChannelCallCredentials = true` + +This applies to localhost, Docker, Orbstack, and other local environments. Always switch to secure credentials before production deployment. @@ -764,7 +761,7 @@ import { v1 } from '@authzed/authzed-node'; const { promises: client } = v1.NewClient( 't_your_token_here_1234567deadbeef', 'grpc.authzed.com:50051', - // For local development without TLS (localhost, Docker, Orbstack, etc.) + // For local development without TLS v1.ClientSecurity.INSECURE_PLAINTEXT_CREDENTIALS );