From fcf6c8d4e1eb26ffc12c8be7ff0b5aced5c517ab Mon Sep 17 00:00:00 2001 From: Mark Phelps <209477+markphelps@users.noreply.github.com> Date: Thu, 26 Feb 2026 15:23:50 +0000 Subject: [PATCH 1/2] Revert "docs: add connecting applications guide + auth sections" This reverts commit 33b9bfca4ea6560783fd13f5590d69157d9f6f6e. --- docs/docs.json | 3 +- .../connecting-applications.mdx | 320 ------------------ docs/v2/integration/client.mdx | 8 - docs/v2/integration/server/rest.mdx | 4 - 4 files changed, 1 insertion(+), 334 deletions(-) delete mode 100644 docs/v2/guides/operations/authentication/connecting-applications.mdx diff --git a/docs/docs.json b/docs/docs.json index 012f746..c33b225 100644 --- a/docs/docs.json +++ b/docs/docs.json @@ -134,8 +134,7 @@ { "group": "Authentication", "pages": [ - "v2/guides/operations/authentication/login-with-github", - "v2/guides/operations/authentication/connecting-applications" + "v2/guides/operations/authentication/login-with-github" ] }, { diff --git a/docs/v2/guides/operations/authentication/connecting-applications.mdx b/docs/v2/guides/operations/authentication/connecting-applications.mdx deleted file mode 100644 index a6c1ea5..0000000 --- a/docs/v2/guides/operations/authentication/connecting-applications.mdx +++ /dev/null @@ -1,320 +0,0 @@ ---- -title: "Connecting Applications to Flipt" -description: "Learn how to authenticate your applications with Flipt using client tokens or JWT authentication" ---- - -This guide explains how to connect your applications to Flipt for production use. You'll learn how to create authentication credentials and use them with Flipt's SDKs, REST API, and gRPC. - -## Overview - -Flipt supports two main authentication methods for applications: - -1. **Static Client Tokens** — generate a secure token and configure it in Flipt -2. **JWT Authentication** — use JWTs from your existing identity provider - -Both methods work with all Flipt SDKs (Python, Node.js, Go, Java, etc.) and the REST/gRPC APIs. - -## Method 1: Static Client Tokens - -Static tokens are the simplest way to authenticate. You generate a secure random token, add it to your Flipt configuration, and then use that token in your applications. - -### Step 1: Generate a Secure Token - -Generate a cryptographically secure random token: - -```bash -# Using openssl (recommended) -openssl rand -hex 32 - -# Using python -python3 -c "import secrets; print(secrets.token_hex(32))" -``` - -This produces a 64-character hex string (e.g., `7f3a8b2c1d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a`). - -### Step 2: Configure Flipt with Your Token - -Add the token to your Flipt configuration: - -```yaml config.yaml -authentication: - required: true - methods: - token: - enabled: true - storage: - tokens: - "my-app-token": - credential: "7f3a8b2c1d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a" - metadata: - app: "production-api" - environment: "production" -``` - - - Use environment variable substitution to avoid committing secrets to config files: - -```yaml -authentication: - methods: - token: - storage: - tokens: - "my-app-token": - credential: "${env:FLIPT_CLIENT_TOKEN}" -``` - -Then set `FLIPT_CLIENT_TOKEN` in your environment or Kubernetes Secret. - - - -### Step 3: Restart Flipt - -Restart your Flipt instance to pick up the new configuration. - -### Step 4: Use the Token in Your Application - -Once configured, use the token in your application code: - - - - -```python -from flipt import FliptClient -from flipt.authentication import ClientTokenAuthentication - -# Create client with token authentication -flipt = FliptClient( - url="http://localhost:8080", - authentication=ClientTokenAuthentication("7f3a8b2c1d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a") -) - -# Evaluate a flag -result = flipt.evaluation.variant( - flag_key="dark-mode", - entity_id="user-123", - context={"theme": "dark"} -) -``` - - - - -```typescript -import { Flipt, ClientTokenAuthentication } from "@flipt-io/flipt-node"; - -const flipt = new Flipt({ - url: "http://localhost:8080", - authentication: new ClientTokenAuthentication( - "7f3a8b2c1d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a" - ), -}); - -const result = await flipt.evaluate("dark-mode", "user-123", { - theme: "dark", -}); -``` - - - - -```go -import ( - flipt "github.com/flipt-io/flipt/sdk/go" - "github.com/flipt-io/flipt/sdk/go/authentication" -) - -opts := []flipt.Option{ - flipt.WithURL("http://localhost:8080"), - flipt.WithAuth(authentication.NewClientTokenAuthentication("7f3a8b2c1d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a")), -} - -client, _ := flipt.New(opts...) -``` - - - - -```java -import io.flipt.api.FliptClient; -import io.flipt.api.authentication.ClientTokenAuthenticationStrategy; - -FliptClient flipt = FliptClient.builder() - .url("http://localhost:8080") - .authenticationStrategy(new ClientTokenAuthenticationStrategy("7f3a8b2c1d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a")) - .build(); -``` - - - - -```bash -curl -X GET http://localhost:8080/v1/flags/dark-mode/evaluations \ - -H "Authorization: Bearer 7f3a8b2c1d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a" \ - -H "Content-Type: application/json" \ - -d '{"flag_key": "dark-mode", "entity_id": "user-123", "context": {"theme": "dark"}}' -``` - - - - -### Using Tokens with Kubernetes Secrets - -For Kubernetes deployments, store the token in a Secret and reference it via environment variables: - -```yaml -# Create secret -apiVersion: v1 -kind: Secret -metadata: - name: flipt-client-token -type: Opaque -stringData: - token: "7f3a8b2c1d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a" - ---- -# In your application deployment -env: - - name: FLIPT_CLIENT_TOKEN - valueFrom: - secretKeyRef: - name: flipt-client-token - key: token -``` - ---- - -## Method 2: JWT Authentication - -If you already have an identity provider (Auth0, Okta, Keycloak, etc.) that issues JWTs, you can use those with Flipt without creating static tokens. - -### Step 1: Configure Flipt for JWT - -Add JWT authentication to your Flipt configuration: - -```yaml config.yaml -authentication: - required: true - methods: - jwt: - enabled: true - # Configure your JWKS endpoint - jwks: - url: "https://your-idp.com/.well-known/jwks.json" -``` - -### Step 2: Use JWTs in Your Application - -Your application obtains a JWT from your identity provider, then passes it to Flipt: - - - - -```python -from flipt import FliptClient -from flipt.authentication import JWTAuthentication - -# Your app gets a JWT from your IdP (Auth0, Okta, etc.) -jwt_token = get_jwt_from_your_idp() - -flipt = FliptClient( - url="http://localhost:8080", - authentication=JWTAuthentication(jwt_token) -) -``` - - - - -```typescript -import { Flipt, JWTAuthentication } from "@flipt-io/flipt-node"; - -// Your app gets a JWT from your IdP -const jwtToken = await getJWTToken(); - -const flipt = new Flipt({ - url: "http://localhost:8080", - authentication: new JWTAuthentication(jwtToken), -}); -``` - - - - -```bash -curl -X GET http://localhost:8080/v1/flags/dark-mode/evaluations \ - -H "Authorization: JWT eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." \ - -H "Content-Type: application/json" \ - -d '{"flag_key": "dark-mode", "entity_id": "user-123", "context": {}}' -``` - - - - -JWT authentication is useful when: - -- You already have SSO set up -- You want to avoid managing static tokens -- You need per-user authentication and audit trails - ---- - -## Method 3: Kubernetes Service Account Tokens - -If you're running Flipt in Kubernetes, you can authenticate using service account tokens — no static tokens required. - -### Step 1: Enable Kubernetes Authentication - -```yaml config.yaml -authentication: - required: true - methods: - kubernetes: - enabled: true - # Path where Kubernetes mounts the service account token - service_account_token_path: /var/run/secrets/kubernetes.io/serviceaccount/token -``` - -### Step 2: Use in Your Applications - -Your Kubernetes pods already have service account tokens mounted. Use them directly: - -```python -import os -from flipt import FliptClient -from flipt.authentication import ClientTokenAuthentication - -# Read the in-cluster service account token -with open("/var/run/secrets/kubernetes.io/serviceaccount/token", "r") as f: - k8s_token = f.read() - -flipt = FliptClient( - url="http://localhost:8080", - authentication=ClientTokenAuthentication(k8s_token) -) -``` - -This approach: - -- Requires no manual token management -- Works seamlessly with pod rotation -- Is the most Kubernetes-native option - ---- - -## Choosing an Authentication Method - -| Method | Best For | Complexity | -| ----------------- | ----------------------------------------------- | ---------- | -| **Static Token** | Simple deployments, CI/CD, single application | Low | -| **JWT** | Teams with existing IdP (Auth0, Okta, Keycloak) | Medium | -| **Kubernetes SA** | Running in Kubernetes with multiple services | Low | - ---- - -## Related - -- [Authentication Configuration](/v2/configuration/authentication) — Full reference for all auth options -- [REST API Reference](/v2/integration/server/rest) — REST API authentication details -- [Server SDKs](/v2/integration/server/rest) — SDK documentation -- [Client SDKs](/v2/integration/client) — Client-side evaluation SDKs diff --git a/docs/v2/integration/client.mdx b/docs/v2/integration/client.mdx index 3ce0ae3..b415d8b 100644 --- a/docs/v2/integration/client.mdx +++ b/docs/v2/integration/client.mdx @@ -19,14 +19,6 @@ Flipt provides a number of client-side SDKs to help you integrate with Flipt in v2. -## Authentication - -Client-side SDKs connect to your Flipt server, which handles authentication. Your application needs a valid client token to communicate with Flipt. - -For detailed instructions on setting up authentication, see the [Connecting Applications to Flipt](/v2/guides/operations/authentication/connecting-applications) guide. - -In brief: create a static token in your Flipt configuration, then pass it to your SDK initialization. - -## Authentication - -Server-side SDKs authenticate with Flipt using client tokens or JWTs. For detailed setup instructions, see the [Connecting Applications to Flipt](/v2/guides/operations/authentication/connecting-applications) guide. - Date: Thu, 26 Feb 2026 15:25:51 +0000 Subject: [PATCH 2/2] docs: add connecting applications guide + auth sections to SDK docs New guide: Connecting Applications to Flipt - Static client token setup with code examples for Python, Node, Go, Java - JWT authentication for teams with existing IdP - Kubernetes service account token auth - Choosing an auth method comparison table Updated: client.mdx - Added authentication section Updated: server/rest.mdx - Added authentication section Updated: docs.json - Added to navigation --- docs/docs.json | 3 +- .../connecting-applications.mdx | 318 ++++++++++++++++++ docs/v2/integration/client.mdx | 8 + docs/v2/integration/server/rest.mdx | 4 + 4 files changed, 332 insertions(+), 1 deletion(-) create mode 100644 docs/v2/guides/operations/authentication/connecting-applications.mdx diff --git a/docs/docs.json b/docs/docs.json index c33b225..012f746 100644 --- a/docs/docs.json +++ b/docs/docs.json @@ -134,7 +134,8 @@ { "group": "Authentication", "pages": [ - "v2/guides/operations/authentication/login-with-github" + "v2/guides/operations/authentication/login-with-github", + "v2/guides/operations/authentication/connecting-applications" ] }, { diff --git a/docs/v2/guides/operations/authentication/connecting-applications.mdx b/docs/v2/guides/operations/authentication/connecting-applications.mdx new file mode 100644 index 0000000..b23e2fc --- /dev/null +++ b/docs/v2/guides/operations/authentication/connecting-applications.mdx @@ -0,0 +1,318 @@ +--- +title: "Connecting Applications to Flipt" +description: "Learn how to authenticate your applications with Flipt using client tokens or JWT authentication" +--- + +This guide explains how to connect your applications to Flipt for production use. You'll learn how to create authentication credentials and use them with Flipt's SDKs, REST API, and gRPC. + +## Overview + +Flipt supports two main authentication methods for applications: + +1. **Static Client Tokens** — generate a secure token and configure it in Flipt +2. **JWT Authentication** — use JWTs from your existing identity provider + +Both methods work with all Flipt SDKs (Python, Node.js, Go, Java, etc.) and the REST/gRPC APIs. + +## Method 1: Static Client Tokens + +Static tokens are the simplest way to authenticate. You generate a secure random token, add it to your Flipt configuration, and then use that token in your applications. + +### Step 1: Generate a Secure Token + +Generate a cryptographically secure random token: + +```bash +# Using openssl (recommended) +openssl rand -hex 32 + +# Using python +python3 -c "import secrets; print(secrets.token_hex(32))" +``` + +This produces a 64-character hex string (e.g., `7f3a8b2c1d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a`). + +### Step 2: Configure Flipt with Your Token + +Add the token to your Flipt configuration: + +```yaml config.yaml +authentication: + required: true + methods: + token: + enabled: true + storage: + tokens: + "my-app-token": + credential: "7f3a8b2c1d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a" + metadata: + app: "production-api" + environment: "production" +``` + + + Use environment variable substitution to avoid committing secrets to config files: + +```yaml +authentication: + methods: + token: + storage: + tokens: + "my-app-token": + credential: "${env:FLIPT_CLIENT_TOKEN}" +``` + +Then set `FLIPT_CLIENT_TOKEN` in your environment or Kubernetes Secret. + + + +### Step 3: Restart Flipt + +Restart your Flipt instance to pick up the new configuration. + +### Step 4: Use the Token in Your Application + +Once configured, use the token in your application code: + + + + +```python +from flipt import FliptClient +from flipt.authentication import ClientTokenAuthentication + +# Create client with token authentication +flipt = FliptClient( + url="http://localhost:8080", + authentication=ClientTokenAuthentication("7f3a8b2c1d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a") +) + +# Evaluate a flag +result = flipt.evaluation.variant( + flag_key="dark-mode", + entity_id="user-123", + context={"theme": "dark"} +) +``` + + + + +```typescript +import { Flipt, ClientTokenAuthentication } from "@flipt-io/flipt-node"; + +const flipt = new Flipt({ + url: "http://localhost:8080", + authentication: new ClientTokenAuthentication( + "7f3a8b2c1d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a" + ), +}); + +const result = await flipt.evaluate("dark-mode", "user-123", { + theme: "dark", +}); +``` + + + + +```go +import ( + flipt "github.com/flipt-io/flipt/sdk/go" + "github.com/flipt-io/flipt/sdk/go/authentication" +) + +opts := []flipt.Option{ + flipt.WithURL("http://localhost:8080"), + flipt.WithAuth(authentication.NewClientTokenAuthentication("7f3a8b2c1d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a")), +} + +client, _ := flipt.New(opts...) +``` + + + + +```java +import io.flipt.api.FliptClient; +import io.flipt.api.authentication.ClientTokenAuthenticationStrategy; + +FliptClient flipt = FliptClient.builder() + .url("http://localhost:8080") + .authenticationStrategy(new ClientTokenAuthenticationStrategy("7f3a8b2c1d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a")) + .build(); +``` + + + + +```bash +curl -X GET http://localhost:8080/v1/flags/dark-mode/evaluations \ + -H "Authorization: Bearer 7f3a8b2c1d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a" \ + -H "Content-Type: application/json" \ + -d '{"flag_key": "dark-mode", "entity_id": "user-123", "context": {"theme": "dark"}}' +``` + + + + +### Using Tokens with Kubernetes Secrets + +For Kubernetes deployments, store the token in a Secret and reference it via environment variables: + +```yaml +# Create secret +apiVersion: v1 +kind: Secret +metadata: + name: flipt-client-token +type: Opaque +stringData: + token: "7f3a8b2c1d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a" + +--- +# In your application deployment +env: + - name: FLIPT_CLIENT_TOKEN + valueFrom: + secretKeyRef: + name: flipt-client-token + key: token +``` + +--- + +## Method 2: JWT Authentication + +If you already have an identity provider (Auth0, Okta, Keycloak, etc.) that issues JWTs, you can use those with Flipt without creating static tokens. + +### Step 1: Configure Flipt for JWT + +Add JWT authentication to your Flipt configuration: + +```yaml config.yaml +authentication: + required: true + methods: + jwt: + enabled: true + jwks: + url: "https://your-idp.com/.well-known/jwks.json" +``` + +### Step 2: Use JWTs in Your Application + +Your application obtains a JWT from your identity provider, then passes it to Flipt: + + + + +```python +from flipt import FliptClient +from flipt.authentication import JWTAuthentication + +# Your app gets a JWT from your IdP (Auth0, Okta, etc.) +jwt_token = get_jwt_from_your_idp() + +flipt = FliptClient( + url="http://localhost:8080", + authentication=JWTAuthentication(jwt_token) +) +``` + + + + +```typescript +import { Flipt, JWTAuthentication } from "@flipt-io/flipt-node"; + +// Your app gets a JWT from your IdP +const jwtToken = await getJWTToken(); + +const flipt = new Flipt({ + url: "http://localhost:8080", + authentication: new JWTAuthentication(jwtToken), +}); +``` + + + + +```bash +curl -X GET http://localhost:8080/v1/flags/dark-mode/evaluations \ + -H "Authorization: JWT eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." \ + -H "Content-Type: application/json" \ + -d '{"flag_key": "dark-mode", "entity_id": "user-123", "context": {}}' +``` + + + + +JWT authentication is useful when: + +- You already have SSO set up +- You want to avoid managing static tokens +- You need per-user authentication and audit trails + +--- + +## Method 3: Kubernetes Service Account Tokens + +If you're running Flipt in Kubernetes, you can authenticate using service account tokens — no static tokens required. + +### Step 1: Enable Kubernetes Authentication + +```yaml config.yaml +authentication: + required: true + methods: + kubernetes: + enabled: true + service_account_token_path: /var/run/secrets/kubernetes.io/serviceaccount/token +``` + +### Step 2: Use in Your Applications + +Your Kubernetes pods already have service account tokens mounted. Use them directly: + +```python +import os +from flipt import FliptClient +from flipt.authentication import ClientTokenAuthentication + +# Read the in-cluster service account token +with open("/var/run/secrets/kubernetes.io/serviceaccount/token", "r") as f: + k8s_token = f.read() + +flipt = FliptClient( + url="http://localhost:8080", + authentication=ClientTokenAuthentication(k8s_token) +) +``` + +This approach: + +- Requires no manual token management +- Works seamlessly with pod rotation +- Is the most Kubernetes-native option + +--- + +## Choosing an Authentication Method + +| Method | Best For | Complexity | +| ----------------- | ----------------------------------------------- | ---------- | +| **Static Token** | Simple deployments, CI/CD, single application | Low | +| **JWT** | Teams with existing IdP (Auth0, Okta, Keycloak) | Medium | +| **Kubernetes SA** | Running in Kubernetes with multiple services | Low | + +--- + +## Related + +- [Authentication Configuration](/v2/configuration/authentication) — Full reference for all auth options +- [REST API Reference](/v2/integration/server/rest) — REST API authentication details +- [Server SDKs](/v2/integration/server/rest) — SDK documentation +- [Client SDKs](/v2/integration/client) — Client-side evaluation SDKs diff --git a/docs/v2/integration/client.mdx b/docs/v2/integration/client.mdx index b415d8b..3ce0ae3 100644 --- a/docs/v2/integration/client.mdx +++ b/docs/v2/integration/client.mdx @@ -19,6 +19,14 @@ Flipt provides a number of client-side SDKs to help you integrate with Flipt in v2. +## Authentication + +Client-side SDKs connect to your Flipt server, which handles authentication. Your application needs a valid client token to communicate with Flipt. + +For detailed instructions on setting up authentication, see the [Connecting Applications to Flipt](/v2/guides/operations/authentication/connecting-applications) guide. + +In brief: create a static token in your Flipt configuration, then pass it to your SDK initialization. + +## Authentication + +Server-side SDKs authenticate with Flipt using client tokens or JWTs. For detailed setup instructions, see the [Connecting Applications to Flipt](/v2/guides/operations/authentication/connecting-applications) guide. +