From f62a5ae84e8c5cdbecd378b1f276beeab1d695f2 Mon Sep 17 00:00:00 2001 From: JunghwanNA <70629228+shaun0927@users.noreply.github.com> Date: Fri, 17 Apr 2026 00:30:19 +0900 Subject: [PATCH] Document how custom auth post-checks are enabled The current proxy docs mention custom_auth_run_common_checks, but not the outer enable_post_custom_auth_checks gate that actually activates the post-custom-auth validation flow. This leaves operators without a clear explanation of the default behavior or the interaction between the two flags. This update adds the missing config entry and explains how to opt into the built-in post-custom-auth checks while preserving the current performance-oriented default. Constraint: Current runtime behavior is intentional and should not be changed in this PR Rejected: Change the default to true | would alter production behavior instead of documenting it Confidence: high Scope-risk: narrow Reversibility: clean Directive: Keep the docs aligned with the custom-auth fast-path behavior when auth semantics change again Tested: Local diff review and source verification against current auth flow Not-tested: Full docs build / repo test suite in local environment Related: #25862 --- docs/my-website/docs/proxy/config_settings.md | 1 + docs/my-website/docs/proxy/custom_auth.md | 22 +++++++++++++++++++ 2 files changed, 23 insertions(+) diff --git a/docs/my-website/docs/proxy/config_settings.md b/docs/my-website/docs/proxy/config_settings.md index 544ace9063a..89c1febe24a 100644 --- a/docs/my-website/docs/proxy/config_settings.md +++ b/docs/my-website/docs/proxy/config_settings.md @@ -285,6 +285,7 @@ router_settings: | always_include_stream_usage | boolean | If true, includes usage metrics in every streaming response chunk | | auto_redirect_ui_login_to_sso | boolean | If true, automatically redirects UI login page to SSO provider | | control_plane_url | string | URL of the control plane for cross-instance state sharing | +| enable_post_custom_auth_checks | boolean | If true, runs LiteLLM post-custom-auth checks (for example expiry, end-user budget, and model budget checks) on `UserAPIKeyAuth` objects returned by custom auth handlers. Default is false for performance. | | custom_auth_run_common_checks | boolean | If true, runs standard auth validation checks alongside custom auth handlers | | custom_ui_sso_sign_in_handler | string | Custom handler for SSO sign-in logic in the UI | | database_connection_pool_timeout | integer | Database connection pool timeout in seconds | diff --git a/docs/my-website/docs/proxy/custom_auth.md b/docs/my-website/docs/proxy/custom_auth.md index 3d46e1074cc..4832af9eb32 100644 --- a/docs/my-website/docs/proxy/custom_auth.md +++ b/docs/my-website/docs/proxy/custom_auth.md @@ -230,6 +230,28 @@ general_settings: [**Implementation Code**](https://github.com/BerriAI/litellm/blob/caf2a6b279ddbe89ebd1d8f4499f65715d684851/litellm/proxy/utils.py#L122) +### Optional: run LiteLLM's post-custom-auth checks + +If your custom auth function returns a `UserAPIKeyAuth` object and you want LiteLLM to run the built-in checks on that object, enable the following flags in `general_settings`: + +```yaml +general_settings: + custom_auth: custom_auth.user_api_key_auth + enable_post_custom_auth_checks: true # opt in to LiteLLM post-auth checks + custom_auth_run_common_checks: true # optional: also run standard model access checks +``` + +What each flag does: + +- `enable_post_custom_auth_checks: true` + - Runs LiteLLM's post-custom-auth validation on the returned `UserAPIKeyAuth` + - This includes checks such as key expiry, end-user budget enforcement, and per-model budget enforcement +- `custom_auth_run_common_checks: true` + - Runs the common model-access / fallback checks inside the post-custom-auth flow + - This flag only has an effect when `enable_post_custom_auth_checks` is also enabled + +By default, `enable_post_custom_auth_checks` is `false`. This keeps trusted custom-auth deployments on the fast path and avoids extra DB-backed checks unless you explicitly opt in. + #### 3. Start the proxy ```shell $ litellm --config /path/to/config.yaml