refactor: rename pre_authenticate option to use_eager_auth

Signed-off-by: Patrick Chin <8509935+thepatrickchin@users.noreply.github.com>

Author: thepatrickchin

docs/source/components/auth/api-authentication.md

@@ -114,8 +114,8 @@ authentication:
 | `token_endpoint_auth_method` | Some token provider endpoints require specific types of authentication. For example `client_secret_post`. |
 | `redirect_uri` | The redirect URI for OAuth 2.0 authentication. Must match the registered redirect URI with the OAuth provider.|
 | `scopes` | List of permissions to the API provider (e.g., `read`, `write`). |
-| `pre_authenticate` | Whether to trigger authentication at WebSocket connection time before the user submits their first prompt, defaults to `False`. Only applies in `nat serve` mode. When enabled, tokens are cached for the session to avoid re-authentication on reconnect. |
 | `use_pkce` | Whether to use PKCE (Proof Key for Code Exchange) in the OAuth 2.0 flow, defaults to `False` |
+| `use_eager_auth` | Whether to trigger authentication at WebSocket connection time before the workflow requires credentials, defaults to `False`. When enabled, tokens are cached for the session to avoid re-authentication on reconnect. |
 | `use_redirect_auth` | Whether to use a redirect-based flow or open the OAuth consent page in a popup window, defaults to `False` (popup) |
 | `authorization_kwargs` | Additional keyword arguments to include in the authorization request. |
 

examples/front_ends/simple_auth/src/nat_simple_auth/configs/config.yml

@@ -56,8 +56,8 @@ authentication:
       - email
     client_id: ${NAT_OAUTH_CLIENT_ID}
     client_secret: ${NAT_OAUTH_CLIENT_SECRET}
-    pre_authenticate: false
     use_pkce: false
+    use_eager_auth: false
     use_redirect_auth: false
 
 workflow:

packages/nvidia_nat_core/src/nat/authentication/oauth2/oauth2_auth_code_flow_provider_config.py

@@ -41,11 +41,10 @@ class OAuth2AuthCodeFlowProviderConfig(AuthProviderBaseConfig, name="oauth2_auth
                      "remains open. When True, the browser navigates to the OAuth login page directly and is "
                      "redirected back after authentication completes."))
 
-    pre_authenticate: bool = Field(
+    use_eager_auth: bool = Field(
         default=False,
-        description=("When True, authentication is triggered at WebSocket connection time before the user submits "
-                     "their first prompt. When False (default), authentication is deferred until the workflow first "
-                     "requires credentials. Only applies in nat serve mode."))
+        description=("When False (default), authentication is deferred until the workflow first requires "
+                     "credentials. When True, authentication is triggered at WebSocket connection time."))
 
     authorization_kwargs: dict[str, str] | None = Field(description=("Additional keyword arguments for the "
                                                                      "authorization request."),

packages/nvidia_nat_core/src/nat/front_ends/fastapi/auth_flow_handlers/websocket_flow_handler.py

@@ -75,15 +75,15 @@ async def authenticate(
 
         raise NotImplementedError(f"Authentication method '{method}' is not supported by the websocket frontend.")
 
-    async def pre_authenticate(self, auth_providers: dict[str, AuthProviderBaseConfig]) -> None:
+    async def run_eager_auth(self, auth_providers: dict[str, AuthProviderBaseConfig]) -> None:
         """Run auth for every configured OAuth2 provider before the first user message.
 
-        Only providers with pre_authenticate option set in their config are processed.
+        Only providers with use_eager_auth option set in their config are processed.
         Returns immediately if tokens are already cached. Otherwise triggers the OAuth
         redirect so the user authenticates at page load rather than mid-workflow.
         """
         for provider_config in auth_providers.values():
-            if isinstance(provider_config, OAuth2AuthCodeFlowProviderConfig) and provider_config.pre_authenticate:
+            if isinstance(provider_config, OAuth2AuthCodeFlowProviderConfig) and provider_config.use_eager_auth:
                 await self.authenticate(provider_config, AuthFlowType.OAUTH2_AUTHORIZATION_CODE)
 
     def create_oauth_client(self, config: OAuth2AuthCodeFlowProviderConfig) -> AsyncOAuth2Client:

packages/nvidia_nat_core/src/nat/front_ends/fastapi/routes/websocket.py

@@ -107,7 +107,7 @@ async def _websocket_endpoint(websocket: WebSocket):
             skip_pre_auth = websocket.query_params.get("skip_pre_auth") == "true"
             if not skip_pre_auth:
                 try:
-                    await flow_handler.pre_authenticate(worker._config.authentication)
+                    await flow_handler.run_eager_auth(worker._config.authentication)
                 except Exception as e:
                     logger.info("Pre-authentication did not complete: %s", e)
             await handler.run()

packages/nvidia_nat_core/tests/nat/front_ends/auth_flow_handlers/test_websocket_flow_handler.py

@@ -500,22 +500,22 @@ async def create_websocket_message(self, msg):
 
 
 # --------------------------------------------------------------------------- #
-# pre_authenticate tests                                                      #
+# run_eager_auth tests                                                        #
 # --------------------------------------------------------------------------- #
-async def test_pre_authenticate_skips_non_oauth2_providers(noop_handler):
-    """pre_authenticate is a no-op for non-OAuth2 providers such as APIKeyAuthProviderConfig."""
+async def test_run_eager_auth_skips_non_oauth2_providers(noop_handler):
+    """run_eager_auth is a no-op for non-OAuth2 providers such as APIKeyAuthProviderConfig."""
     api_key_config = APIKeyAuthProviderConfig(raw_key="my-api-key-value")
-    await noop_handler.pre_authenticate({"my_api_key": api_key_config})
+    await noop_handler.run_eager_auth({"my_api_key": api_key_config})
 
 
-async def test_pre_authenticate_skips_oauth2_provider_flag_false(noop_handler, minimal_oauth_config):
-    """pre_authenticate does not trigger auth for OAuth2 providers with pre_authenticate=False (the default)."""
-    # minimal_oauth_config has pre_authenticate=False (the default); if the guard were absent this would hang
-    await noop_handler.pre_authenticate({"my_provider": minimal_oauth_config})
+async def test_run_eager_auth_skips_oauth2_provider_flag_false(noop_handler, minimal_oauth_config):
+    """run_eager_auth does not trigger auth for OAuth2 providers with use_eager_auth=False (the default)."""
+    # minimal_oauth_config has use_eager_auth=False (the default); if the guard were absent this would hang
+    await noop_handler.run_eager_auth({"my_provider": minimal_oauth_config})
 
 
-async def test_pre_authenticate_uses_cached_token(minimal_oauth_config):
-    """pre_authenticate returns immediately without calling create_websocket_message on a cache hit."""
+async def test_run_eager_auth_uses_cached_token(minimal_oauth_config):
+    """run_eager_auth returns immediately without calling create_websocket_message on a cache hit."""
 
     async def _noop_add(state, flow_state):
         pass
@@ -532,8 +532,8 @@ async def create_websocket_message(self, msg):
 
     ctx = AuthenticatedContext(headers={"Authorization": "Bearer cached-tok"}, metadata={"expires_at": None})
     store: dict = {}
-    # Enable pre_authenticate so the cache lookup is actually reached
-    active_config = minimal_oauth_config.model_copy(update={"pre_authenticate": True})
+    # Enable use_eager_auth so the cache lookup is actually reached
+    active_config = minimal_oauth_config.model_copy(update={"use_eager_auth": True})
     handler = WebSocketAuthenticationFlowHandler(
         add_flow_cb=_noop_add,
         remove_flow_cb=_noop_remove,
@@ -544,5 +544,5 @@ async def create_websocket_message(self, msg):
     key = handler._token_cache_key(active_config)
     store[key] = (ctx, time.time() + 3600)
 
-    await handler.pre_authenticate({"my_provider": active_config})
-    assert message_count[0] == 0, "pre_authenticate must not trigger OAuth when token is cached"
+    await handler.run_eager_auth({"my_provider": active_config})
+    assert message_count[0] == 0, "run_eager_auth must not trigger OAuth when token is cached"