From ef07dcb702c4dea114bbc1179d493c2ad618e129 Mon Sep 17 00:00:00 2001 From: Mark Phelps <209477+markphelps@users.noreply.github.com> Date: Thu, 26 Feb 2026 12:43:17 -0500 Subject: [PATCH 1/2] docs: fix auth guide examples and k8s troubleshooting values --- .../connecting-applications.mdx | 193 +++++------------- .../deployment/kubernetes-troubleshooting.mdx | 36 ++-- 2 files changed, 72 insertions(+), 157 deletions(-) diff --git a/docs/v2/guides/operations/authentication/connecting-applications.mdx b/docs/v2/guides/operations/authentication/connecting-applications.mdx index f2421b6..f0eef07 100644 --- a/docs/v2/guides/operations/authentication/connecting-applications.mdx +++ b/docs/v2/guides/operations/authentication/connecting-applications.mdx @@ -7,12 +7,13 @@ This guide explains how to connect your applications to Flipt for production use ## Overview -Flipt supports two main authentication methods for applications: +Flipt supports these application authentication patterns: 1. **Static Client Tokens** — generate a secure token and configure it in Flipt 2. **JWT Authentication** — use JWTs from your existing identity provider +3. **Kubernetes Service Account Exchange** — exchange a pod service account token for a Flipt client token -Both methods work with all Flipt SDKs (Python, Node.js, Go, Java, etc.) and the REST/gRPC APIs. +Static client tokens and JWTs work with Flipt's SDKs and HTTP APIs. Kubernetes service account authentication is a token exchange flow that returns a Flipt client token (or is handled automatically by supported SDKs). ## Method 1: Static Client Tokens @@ -74,90 +75,32 @@ 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: +Once configured, pass the client token to your SDK or send it in the HTTP `Authorization` header. - - + + SDK authentication class names and initialization options vary by language and + SDK version. Use the auth strategy/client token option documented in the SDK + README for your language from the [Server SDKs](/v2/integration/server/rest) + and [Client SDKs](/v2/integration/client) pages. + -```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(); -``` - - - +Example HTTP request using a client token: ```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"}}' +curl --request POST http://localhost:8080/evaluate/v1/variant \ + --header 'Content-Type: application/json' \ + --header 'Accept: application/json' \ + --header 'Authorization: Bearer ' \ + --data '{ + "flagKey": "dark-mode", + "entityId": "user-123", + "namespaceKey": "default", + "context": { + "theme": "dark" + } + }' ``` - - - ### Using Tokens with Kubernetes Secrets For Kubernetes deployments, store the token in a Secret and reference it via environment variables: @@ -198,57 +141,27 @@ authentication: methods: jwt: enabled: true - jwks: - url: "https://your-idp.com/.well-known/jwks.json" + 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), -}); -``` - - - +Your application obtains a JWT from your identity provider, then passes it to Flipt using the JWT authorization header format: ```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": {}}' +curl --request POST http://localhost:8080/evaluate/v1/variant \ + --header 'Content-Type: application/json' \ + --header 'Accept: application/json' \ + --header 'Authorization: JWT ' \ + --data '{ + "flagKey": "dark-mode", + "entityId": "user-123", + "namespaceKey": "default", + "context": {} + }' ``` - - +For SDK usage, configure the SDK's JWT authentication strategy/option for your language and pass the token returned by your identity provider. JWT authentication is useful when: @@ -260,7 +173,7 @@ JWT authentication is useful when: ## Method 3: Kubernetes Service Account Tokens -If you're running Flipt in Kubernetes, you can authenticate using service account tokens — no static tokens required. +If you're running Flipt in Kubernetes, you can use the Kubernetes authentication method to exchange a pod service account token for a Flipt client token. ### Step 1: Enable Kubernetes Authentication @@ -274,30 +187,28 @@ authentication: service_account_token_path: /var/run/secrets/kubernetes.io/serviceaccount/token ``` -### Step 2: Use in Your Applications +### Step 2: Exchange the Service Account Token for a Flipt Client Token -Your Kubernetes pods already have service account tokens mounted. Use them directly: +Kubernetes service account tokens are not used directly as Flipt client tokens. Instead, send the pod token to Flipt's Kubernetes auth endpoint to obtain a Flipt client token: -```python -import os -from flipt import FliptClient -from flipt.authentication import ClientTokenAuthentication +```bash +# assumes curl (and optionally jq) is installed in the pod +curl -s -X POST http://flipt:8080/auth/v1/method/kubernetes/serviceaccount \ + --data "{\"service_account_token\":\"$(cat /var/run/secrets/kubernetes.io/serviceaccount/token)\"}" +``` -# Read the in-cluster service account token -with open("/var/run/secrets/kubernetes.io/serviceaccount/token", "r") as f: - k8s_token = f.read() +Use the returned `clientToken` value as a normal Flipt client token (`Authorization: Bearer `). -flipt = FliptClient( - url="http://localhost:8080", - authentication=ClientTokenAuthentication(k8s_token) -) -``` + + Some SDKs can perform this Kubernetes token exchange and refresh flow + automatically. See the SDK documentation for your language. + This approach: -- Requires no manual token management -- Works seamlessly with pod rotation -- Is the most Kubernetes-native option +- Avoids provisioning static tokens per workload +- Aligns Flipt credentials to Kubernetes service account token expiration +- Works well for in-cluster service-to-service authentication --- diff --git a/docs/v2/guides/operations/deployment/kubernetes-troubleshooting.mdx b/docs/v2/guides/operations/deployment/kubernetes-troubleshooting.mdx index 3bb978f..bc37d12 100644 --- a/docs/v2/guides/operations/deployment/kubernetes-troubleshooting.mdx +++ b/docs/v2/guides/operations/deployment/kubernetes-troubleshooting.mdx @@ -79,6 +79,12 @@ extraVolumes: This mounts the host node's machine ID into the container, allowing the license system to identify the machine. + + This workaround depends on `hostPath` volumes and a node filesystem. It won't + work in environments that don't allow `hostPath` (for example, many managed + serverless node offerings such as EKS Fargate). + + If your cluster's security policy restricts `hostPath` volumes, you may need to request an exception for this read-only mount, or wait for the @@ -157,10 +163,9 @@ Or use [External Secrets Operator](https://external-secrets.io/) to sync from yo **Step 2:** Reference the Secret in your `values.yaml`: ```yaml -flipt: - envFrom: - - secretRef: - name: flipt-secrets +envFrom: + - secretRef: + name: flipt-secrets ``` **Step 3:** Use environment variable references in your Flipt configuration: @@ -197,16 +202,15 @@ This pattern works with any tool that creates Kubernetes Secrets: If you prefer to inject secrets as individual environment variables rather than from a Secret reference, use `extraEnvVars`: ```yaml -flipt: - extraEnvVars: - - name: FLIPT_LICENSE_KEY - valueFrom: - secretKeyRef: - name: flipt-license - key: license-key - - name: FLIPT_GIT_ACCESS_TOKEN - valueFrom: - secretKeyRef: - name: flipt-git-creds - key: access-token +extraEnvVars: + - name: FLIPT_LICENSE_KEY + valueFrom: + secretKeyRef: + name: flipt-license + key: license-key + - name: FLIPT_GIT_ACCESS_TOKEN + valueFrom: + secretKeyRef: + name: flipt-git-creds + key: access-token ``` From fb754b0f1e325d7aa936d7a2141fc314198671a9 Mon Sep 17 00:00:00 2001 From: Mark Phelps <209477+markphelps@users.noreply.github.com> Date: Thu, 26 Feb 2026 13:13:44 -0500 Subject: [PATCH 2/2] docs: address PR review feedback on auth and k8s guides --- .../operations/authentication/connecting-applications.mdx | 5 +++-- .../operations/deployment/kubernetes-troubleshooting.mdx | 1 - 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/v2/guides/operations/authentication/connecting-applications.mdx b/docs/v2/guides/operations/authentication/connecting-applications.mdx index f0eef07..51330ac 100644 --- a/docs/v2/guides/operations/authentication/connecting-applications.mdx +++ b/docs/v2/guides/operations/authentication/connecting-applications.mdx @@ -1,6 +1,6 @@ --- title: "Connecting Applications to Flipt" -description: "Learn how to authenticate your applications with Flipt using client tokens or JWT authentication" +description: "Learn how to authenticate your applications with Flipt using client tokens, JWT, or Kubernetes service account tokens" --- 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. @@ -193,7 +193,8 @@ Kubernetes service account tokens are not used directly as Flipt client tokens. ```bash # assumes curl (and optionally jq) is installed in the pod -curl -s -X POST http://flipt:8080/auth/v1/method/kubernetes/serviceaccount \ +curl --request POST http://flipt:8080/auth/v1/method/kubernetes/serviceaccount \ + --header 'Content-Type: application/json' \ --data "{\"service_account_token\":\"$(cat /var/run/secrets/kubernetes.io/serviceaccount/token)\"}" ``` diff --git a/docs/v2/guides/operations/deployment/kubernetes-troubleshooting.mdx b/docs/v2/guides/operations/deployment/kubernetes-troubleshooting.mdx index bc37d12..e9106f0 100644 --- a/docs/v2/guides/operations/deployment/kubernetes-troubleshooting.mdx +++ b/docs/v2/guides/operations/deployment/kubernetes-troubleshooting.mdx @@ -98,7 +98,6 @@ This mounts the host node's machine ID into the container, allowing the license - Amazon EKS with containerd runtime - Any Kubernetes cluster using containerd instead of Docker - Rootless container environments -- Amazon EKS with AWS Fargate node groups ## Persistent Volume Configuration