feat: add conditional authentication provider configuration (#5002)

Adds support for conditionally enabling/disabling authentication via
environment variables, following the same pattern as inference
providers.

Key features:
- Auth provider can be enabled/disabled using
${env.AUTH_PROVIDER:+oauth2_token} syntax in config.yaml
- When AUTH_PROVIDER env var is set, auth is enabled; when unset, auth
is completely disabled (no middleware initialized)
- Allows same config.yaml to work across dev/staging/prod environments
- Added to ci-tests distribution as example and for testing

Implementation:
- Special handling in replace_env_vars() intercepts auth config before
Pydantic validation
- When type field resolves to None/empty, entire provider_config is set
to None to avoid discriminated union validation errors
- remove auth provider_config during list-deps, it isn't used and as
config hasn't passed through replace_env_vars fails syntax checks

Changes:
- src/llama_stack/core/stack.py: Add conditional auth handling
- src/llama_stack/distributions/template.py: Add auth_config field to
RunConfigSettings
- src/llama_stack/distributions/ci-tests/: Add conditional auth config
- docs/docs/distributions/configuration.mdx: Document conditional auth
- tests/unit/server/test_replace_env_vars.py: Add tests
- src/llama_stack/cli/stack/_list_deps.py: remove auth provider_config

Related to #4365

Signed-off-by: Derek Higgins <derekh@redhat.com>

Author: derekhiggins

docs/docs/distributions/configuration.mdx

@@ -288,6 +288,36 @@ The `auth` section configures authentication for the server. When configured, al
 Authorization: Bearer <token>
 ```
 
+#### Conditional Authentication
+
+Authentication can be conditionally enabled or disabled using environment variables with the conditional syntax (`:+`). This is useful for deploying the same configuration to different environments where auth may or may not be required.
+
+Example:
+```yaml
+server:
+  auth:
+    provider_config:
+      type: ${env.AUTH_PROVIDER:+oauth2_token}
+      audience: "llama-stack"
+      jwks:
+        uri: ${env.KEYCLOAK_URL}/realms/llamastack/protocol/openid-connect/certs
+      issuer: ${env.KEYCLOAK_URL}/realms/llamastack
+```
+
+**Behavior:**
+- **If `AUTH_PROVIDER` is set** (to any value): Authentication is enabled with OAuth2
+- **If `AUTH_PROVIDER` is NOT set**: Authentication is completely disabled (no middleware added)
+
+This allows you to:
+- Run without authentication in local development (unset the env var)
+- Enable authentication in staging/production (set the env var)
+- Use the same config.yaml across all environments
+
+**Important Notes:**
+- The `type` field uses the conditional syntax to control whether the entire auth provider is enabled
+- When the env var is not set, the entire `provider_config` is set to `None` and no authentication middleware is initialized
+- Other auth config fields (like `route_policy`) can still be used independently when `provider_config` is disabled
+
 The server supports multiple authentication providers:
 
 #### OAuth 2.0/OpenID Connect Provider with Kubernetes

src/llama_stack/cli/stack/_list_deps.py

@@ -81,6 +81,14 @@ def run_stack_list_deps_command(args: argparse.Namespace) -> None:
             with open(config_file) as f:
                 try:
                     contents = yaml.safe_load(f)
+                    # Remove auth provider_config to avoid validation errors with env var syntax.
+                    # We only need provider dependencies, not auth config (auth has no pip_packages).
+                    # This is simpler than modifying the schema to accept type="" which would require
+                    # removing discriminated union and adding custom validation logic and modifying
+                    # all 4 auth provider config classes (a very invasive change)
+                    if "server" in contents and "auth" in contents["server"]:
+                        if "provider_config" in contents["server"]["auth"]:
+                            contents["server"]["auth"]["provider_config"] = None
                     config = StackConfig(**contents)
                 except Exception as e:
                     cprint(

src/llama_stack/core/stack.py

@@ -386,6 +386,35 @@ def __init__(self, var_name: str, path: str = ""):
 
 def replace_env_vars(config: Any, path: str = "") -> Any:
     if isinstance(config, dict):
+        # Special handling for auth provider_config with conditional type field
+        # This allows auth to be enabled/disabled via environment variables
+        # Example: type: ${env.AUTH_PROVIDER:+oauth2_token}
+        if "provider_config" in config and path == "server.auth":
+            provider_cfg = config.get("provider_config")
+            if isinstance(provider_cfg, dict) and "type" in provider_cfg:
+                try:
+                    # Resolve the type field first to check if auth should be enabled
+                    resolved_type = replace_env_vars(provider_cfg["type"], f"{path}.provider_config.type")
+
+                    # If type is empty/None, disable auth by setting provider_config to None
+                    # This prevents validation errors on the discriminated union
+                    if resolved_type is None or resolved_type == "":
+                        # Process rest of config normally but exclude provider_config from expansion
+                        # to avoid EnvVarError from bare env vars (e.g., ${env.KEYCLOAK_URL})
+                        result = {
+                            k: replace_env_vars(v, f"{path}.{k}" if path else k)
+                            for k, v in config.items()
+                            if k != "provider_config"
+                        }
+                        result["provider_config"] = None
+                        return result
+                except EnvVarError as e:
+                    # If we can't resolve type, continue with normal processing
+                    # and let validation catch the error
+                    logger.debug(
+                        f"Could not resolve auth provider type field: {e.var_name} - continuing with normal processing"
+                    )
+
         result = {}
         for k, v in config.items():
             try:

src/llama_stack/distributions/ci-tests/ci_tests.py

@@ -34,6 +34,25 @@ def get_distribution_template() -> DistributionTemplate:
         url="http://localhost:5199/sse",
     )
 
+    # Add conditional authentication config (disabled by default for CI tests)
+    # This tests the conditional auth provider feature and provides a template for users
+    # To enable: export AUTH_PROVIDER=enabled and configure the auth env vars
+    auth_config = {
+        # Authentication is disabled by default (AUTH_PROVIDER not set)
+        # To enable: export AUTH_PROVIDER=enabled
+        # Then configure the required auth provider settings below
+        "provider_config": {
+            "type": "${env.AUTH_PROVIDER:+oauth2_token}",
+            "audience": "${env.AUTH_AUDIENCE:=llama-stack}",
+            "issuer": "${env.AUTH_ISSUER:=}",
+            "jwks": {
+                "uri": "${env.AUTH_JWKS_URI:=}",
+                "key_recheck_period": "${env.AUTH_JWKS_RECHECK_PERIOD:=3600}",
+            },
+            "verify_tls": "${env.AUTH_VERIFY_TLS:=true}",
+        }
+    }
+
     for run_config in template.run_configs.values():
         if run_config.default_models is None:
             run_config.default_models = []
@@ -43,4 +62,7 @@ def get_distribution_template() -> DistributionTemplate:
             run_config.default_connectors = []
         run_config.default_connectors.append(test_mcp_connector)
 
+        # Add conditional auth config
+        run_config.auth_config = auth_config
+
     return template

src/llama_stack/distributions/ci-tests/config.yaml

@@ -300,6 +300,15 @@ registered_resources:
     provider_id: rag-runtime
 server:
   port: 8321
+  auth:
+    provider_config:
+      type: ${env.AUTH_PROVIDER:+oauth2_token}
+      audience: ${env.AUTH_AUDIENCE:=llama-stack}
+      issuer: ${env.AUTH_ISSUER:=}
+      jwks:
+        uri: ${env.AUTH_JWKS_URI:=}
+        key_recheck_period: ${env.AUTH_JWKS_RECHECK_PERIOD:=3600}
+      verify_tls: ${env.AUTH_VERIFY_TLS:=true}
 vector_stores:
   default_provider_id: faiss
   default_embedding_model:

src/llama_stack/distributions/ci-tests/run-with-postgres-store.yaml

@@ -309,6 +309,15 @@ registered_resources:
     provider_id: rag-runtime
 server:
   port: 8321
+  auth:
+    provider_config:
+      type: ${env.AUTH_PROVIDER:+oauth2_token}
+      audience: ${env.AUTH_AUDIENCE:=llama-stack}
+      issuer: ${env.AUTH_ISSUER:=}
+      jwks:
+        uri: ${env.AUTH_JWKS_URI:=}
+        key_recheck_period: ${env.AUTH_JWKS_RECHECK_PERIOD:=3600}
+      verify_tls: ${env.AUTH_VERIFY_TLS:=true}
 vector_stores:
   default_provider_id: faiss
   default_embedding_model:

src/llama_stack/distributions/template.py

@@ -184,6 +184,7 @@ class RunConfigSettings(BaseModel):
     default_connectors: list[ConnectorInput] | None = None
     vector_stores_config: VectorStoresConfig | None = None
     safety_config: SafetyConfig | None = None
+    auth_config: dict[str, Any] | None = None
     storage_backends: dict[str, Any] | None = None
     storage_stores: dict[str, Any] | None = None
 
@@ -289,6 +290,9 @@ def run_config(
             },
         }
 
+        if self.auth_config:
+            config["server"]["auth"] = self.auth_config
+
         if self.vector_stores_config:
             config["vector_stores"] = self.vector_stores_config.model_dump(exclude_none=True)
 

tests/unit/server/test_replace_env_vars.py

@@ -185,3 +185,119 @@ def test_multiple_resources_with_conditional_ids(setup_env_vars):
         assert len(result["models"]) == 0
     finally:
         del os.environ["INCLUDE_BENCHMARK"]
+
+
+def test_auth_provider_disabled_when_type_not_set(setup_env_vars):
+    """Test that auth provider_config is set to None when type field is conditional and env var not set."""
+    data = {
+        "server": {
+            "auth": {
+                "provider_config": {
+                    "type": "${env.AUTH_PROVIDER:+oauth2_token}",
+                    "audience": "llama-stack",
+                    "issuer": "https://auth.example.com",
+                },
+                "route_policy": [],
+            }
+        }
+    }
+    # AUTH_PROVIDER is not set, so provider_config should become None
+    result = replace_env_vars(data, "")
+    assert result["server"]["auth"]["provider_config"] is None
+    # route_policy should still be present
+    assert result["server"]["auth"]["route_policy"] == []
+
+
+def test_auth_provider_enabled_when_type_is_set(setup_env_vars):
+    """Test that auth provider_config is preserved when type field is set via env var."""
+    os.environ["AUTH_PROVIDER"] = "yes"
+    try:
+        data = {
+            "server": {
+                "auth": {
+                    "provider_config": {
+                        "type": "${env.AUTH_PROVIDER:+oauth2_token}",
+                        "audience": "llama-stack",
+                        "issuer": "https://auth.example.com",
+                    },
+                    "route_policy": [],
+                }
+            }
+        }
+        result = replace_env_vars(data, "")
+        # AUTH_PROVIDER is set, so provider_config should be preserved with resolved type
+        assert result["server"]["auth"]["provider_config"] is not None
+        assert result["server"]["auth"]["provider_config"]["type"] == "oauth2_token"
+        assert result["server"]["auth"]["provider_config"]["audience"] == "llama-stack"
+        assert result["server"]["auth"]["provider_config"]["issuer"] == "https://auth.example.com"
+    finally:
+        del os.environ["AUTH_PROVIDER"]
+
+
+def test_auth_provider_disabled_when_type_is_empty(setup_env_vars):
+    """Test that auth provider_config is set to None when type field resolves to empty string."""
+    data = {
+        "server": {
+            "auth": {
+                "provider_config": {
+                    "type": "${env.NOT_SET:=}",
+                    "audience": "llama-stack",
+                },
+                "route_policy": [],
+            }
+        }
+    }
+    # NOT_SET env var is not set, and default is empty, so provider_config should become None
+    result = replace_env_vars(data, "")
+    assert result["server"]["auth"]["provider_config"] is None
+
+
+def test_auth_provider_with_hardcoded_type(setup_env_vars):
+    """Test that auth provider_config with hardcoded type is preserved."""
+    data = {
+        "server": {
+            "auth": {
+                "provider_config": {
+                    "type": "oauth2_token",
+                    "audience": "llama-stack",
+                    "issuer": "https://auth.example.com",
+                },
+                "route_policy": [],
+            }
+        }
+    }
+    result = replace_env_vars(data, "")
+    # Hardcoded type should be preserved as-is
+    assert result["server"]["auth"]["provider_config"] is not None
+    assert result["server"]["auth"]["provider_config"]["type"] == "oauth2_token"
+    assert result["server"]["auth"]["provider_config"]["audience"] == "llama-stack"
+
+
+def test_auth_provider_with_complex_config(setup_env_vars):
+    """Test conditional auth with complex nested config."""
+    os.environ["ENABLE_AUTH"] = "true"
+    os.environ["KEYCLOAK_URL"] = "http://keycloak:8080"
+    try:
+        data = {
+            "server": {
+                "auth": {
+                    "provider_config": {
+                        "type": "${env.ENABLE_AUTH:+oauth2_token}",
+                        "audience": "account",
+                        "issuer": "${env.KEYCLOAK_URL}/realms/llamastack",
+                        "jwks": {"uri": "${env.KEYCLOAK_URL}/realms/llamastack/protocol/openid-connect/certs"},
+                    }
+                }
+            }
+        }
+        result = replace_env_vars(data, "")
+        assert result["server"]["auth"]["provider_config"] is not None
+        assert result["server"]["auth"]["provider_config"]["type"] == "oauth2_token"
+        assert result["server"]["auth"]["provider_config"]["issuer"] == "http://keycloak:8080/realms/llamastack"
+        assert (
+            result["server"]["auth"]["provider_config"]["jwks"]["uri"]
+            == "http://keycloak:8080/realms/llamastack/protocol/openid-connect/certs"
+        )
+    finally:
+        del os.environ["ENABLE_AUTH"]
+        del os.environ["KEYCLOAK_URL"]