Add option to enable redirect-based OAuth flow

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

@@ -115,6 +115,7 @@ authentication:
 | `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`). |
 | `use_pkce` | Whether to use PKCE (Proof Key for Code Exchange) in the OAuth 2.0 flow, defaults to `False` |
+| `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/Dockerfile

@@ -24,8 +24,16 @@ RUN apt-get update && apt-get install -y \
     git \
     && rm -rf /var/lib/apt/lists/*
 
-# Clone the OAuth2 server example
-RUN git clone https://github.com/authlib/example-oauth2-server.git oauth2-server
+# Clone the OAuth2 server example and pin to a specific commit for
+# reproducibility before applying the local patch.
+RUN git clone https://github.com/authlib/example-oauth2-server.git oauth2-server \
+    && git -C oauth2-server checkout d1f35586067c3990122b3b2b0c191385f2a9fed8
+
+# Apply patches: add an explicit Cancel button to the authorize route and
+# template so that declining the OAuth2 consent redirects back with
+# error=access_denied instead of leaving the client app waiting indefinitely.
+COPY patches/oauth2-server.patch /tmp/oauth2-server.patch
+RUN patch -p1 -d /app/oauth2-server < /tmp/oauth2-server.patch
 
 # Change to the OAuth2 server directory
 WORKDIR /app/oauth2-server

examples/front_ends/simple_auth/patches/oauth2-server.patch

@@ -0,0 +1,30 @@
+--- a/website/routes.py
++++ b/website/routes.py
+@@ -105,7 +105,7 @@
+     if not user and "username" in request.form:
+         username = request.form.get("username")
+         user = User.query.filter_by(username=username).first()
+-    if request.form["confirm"]:
++    if request.form.get("confirm") == "yes":
+         grant_user = user
+     else:
+         grant_user = None
+--- a/website/templates/authorize.html
++++ b/website/templates/authorize.html
+@@ -9,14 +9,11 @@
+ <form action="" method="post">
+-  <label>
+-    <input type="checkbox" name="confirm">
+-    <span>Consent?</span>
+-  </label>
+   {% if not user %}
+   <p>You haven't logged in. Log in with:</p>
+   <div>
+     <input type="text" name="username">
+   </div>
+   {% endif %}
+   <br>
+-  <button>Submit</button>
++  <button type="submit" name="confirm" value="yes">Authorize</button>
++  <button type="submit" name="confirm" value="no">Cancel</button>
+ </form>

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

@@ -57,6 +57,7 @@ authentication:
     client_id: ${NAT_OAUTH_CLIENT_ID}
     client_secret: ${NAT_OAUTH_CLIENT_SECRET}
     use_pkce: false
+    use_redirect_auth: false
 
 workflow:
   _type: react_agent

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

@@ -35,6 +35,12 @@ class OAuth2AuthCodeFlowProviderConfig(AuthProviderBaseConfig, name="oauth2_auth
     use_pkce: bool = Field(default=False,
                            description="Whether to use PKCE (Proof Key for Code Exchange) in the OAuth 2.0 flow.")
 
+    use_redirect_auth: bool = Field(
+        default=False,
+        description=("When False (default), the OAuth login page opens in a popup window and the originating page "
+                     "remains open. When True, the browser navigates to the OAuth login page directly and is "
+                     "redirected back after authentication completes."))
+
     authorization_kwargs: dict[str, str] | None = Field(description=("Additional keyword arguments for the "
                                                                      "authorization request."),
                                                         default=None)

packages/nvidia_nat_core/src/nat/data_models/interactive.py

@@ -161,6 +161,9 @@ class _HumanPromptOAuthConsent(HumanPromptBase):
     the consent flow.
     """
     input_type: typing.Literal[HumanPromptModelType.OAUTH_CONSENT] = HumanPromptModelType.OAUTH_CONSENT
+    use_redirect: bool = Field(default=False,
+                               description="When False the UI should open the OAuth URL in a popup window. "
+                               "When True the UI should navigate the current tab to the OAuth URL.")
 
 
 class HumanPromptBinary(HumanPromptBase):

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

@@ -42,6 +42,7 @@ class FlowState:
     verifier: str | None = None
     client: AsyncOAuth2Client | None = None
     config: OAuth2AuthCodeFlowProviderConfig | None = None
+    return_url: str | None = None
 
 
 class WebSocketAuthenticationFlowHandler(FlowHandlerBase):
@@ -50,12 +51,14 @@ def __init__(self,
                  add_flow_cb: Callable[[str, FlowState], Awaitable[None]],
                  remove_flow_cb: Callable[[str], Awaitable[None]],
                  web_socket_message_handler: WebSocketMessageHandler,
-                 auth_timeout_seconds: float = 300.0):
+                 auth_timeout_seconds: float = 300.0,
+                 return_url: str | None = None):
 
         self._add_flow_cb: Callable[[str, FlowState], Awaitable[None]] = add_flow_cb
         self._remove_flow_cb: Callable[[str], Awaitable[None]] = remove_flow_cb
         self._web_socket_message_handler: WebSocketMessageHandler = web_socket_message_handler
         self._auth_timeout_seconds: float = auth_timeout_seconds
+        self._return_url: str | None = return_url
 
     async def authenticate(
             self,
@@ -113,8 +116,13 @@ def _create_authorization_url(self,
 
     async def _handle_oauth2_auth_code_flow(self, config: OAuth2AuthCodeFlowProviderConfig) -> AuthenticatedContext:
 
+        if config.use_redirect_auth and self._return_url is None:
+            raise ValueError("Redirect-based authentication (use_redirect_auth=True) requires a return URL, "
+                             "but none was configured. Pass return_url when constructing the flow handler.")
+
         state = secrets.token_urlsafe(16)
-        flow_state = FlowState(config=config)
+        return_url = self._return_url if config.use_redirect_auth else None
+        flow_state = FlowState(config=config, return_url=return_url)
 
         flow_state.client = self.create_oauth_client(config)
 
@@ -130,8 +138,8 @@ async def _handle_oauth2_auth_code_flow(self, config: OAuth2AuthCodeFlowProvider
                                                            challenge=flow_state.challenge)
 
         await self._add_flow_cb(state, flow_state)
-        await self._web_socket_message_handler.create_websocket_message(_HumanPromptOAuthConsent(text=authorization_url)
-                                                                        )
+        await self._web_socket_message_handler.create_websocket_message(
+            _HumanPromptOAuthConsent(text=authorization_url, use_redirect=config.use_redirect_auth))
         try:
             token = await asyncio.wait_for(flow_state.future, timeout=self._auth_timeout_seconds)
         except TimeoutError as exc:

packages/nvidia_nat_core/src/nat/front_ends/fastapi/html_snippets/auth_code_grant_cancelled.py

@@ -0,0 +1,76 @@
+# SPDX-FileCopyrightText: Copyright (c) 2025-2026, NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+import json
+
+AUTH_REDIRECT_CANCELLED_POPUP_HTML = """
+<!DOCTYPE html>
+<html>
+<head>
+    <title>Authorization Cancelled</title>
+    <script>
+        (function () {
+            window.history.replaceState(null, "", window.location.pathname);
+
+            window.opener?.postMessage({ type: 'AUTH_CANCELLED' }, '*');
+
+            window.close();
+        })();
+    </script>
+</head>
+<body>
+    <p>Authorization cancelled. You may now close this window.</p>
+</body>
+</html>
+"""
+
+_AUTH_REDIRECT_CANCELLED_HTML_TEMPLATE = """\
+<!DOCTYPE html>
+<html>
+<head>
+    <title>Authorization Cancelled</title>
+    <script>
+        (function () {
+            var returnTo = RETURN_URL_PLACEHOLDER;
+            if (returnTo) {
+                window.location.replace(returnTo);
+            } else {
+                window.history.back();
+            }
+        })();
+    </script>
+</head>
+<body>
+    <p>Authorization cancelled. Redirecting&hellip;</p>
+</body>
+</html>
+"""
+
+
+def build_auth_redirect_cancelled_html(return_url: str | None = None) -> str:
+    """Build the authorization-cancelled HTML page.
+
+    Redirects back to the UI without the ``oauth_auth_completed`` query
+    parameter so the UI's cancellation-message branch handles it.
+
+    Args:
+        return_url: The UI origin to navigate back to. Falls back to
+            ``window.history.back()`` when not provided.
+
+    Returns:
+        An HTML string for the post-cancellation redirect page.
+    """
+    safe_json = json.dumps(return_url).replace('<', '\\u003c').replace('>', '\\u003e').replace('/', '\\u002f')
+    return _AUTH_REDIRECT_CANCELLED_HTML_TEMPLATE.replace("RETURN_URL_PLACEHOLDER", safe_json)

packages/nvidia_nat_core/src/nat/front_ends/fastapi/html_snippets/auth_code_grant_error.py

@@ -0,0 +1,76 @@
+# SPDX-FileCopyrightText: Copyright (c) 2025-2026, NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+import json
+
+AUTH_REDIRECT_ERROR_HTML = """
+<!DOCTYPE html>
+<html>
+<head>
+    <title>Authentication Error</title>
+    <script>
+        (function () {
+            window.history.replaceState(null, "", window.location.pathname);
+
+            window.opener?.postMessage({ type: 'AUTH_ERROR' }, '*');
+
+            window.close();
+        })();
+    </script>
+</head>
+<body>
+    <p>Authentication failed. You may now close this window.</p>
+</body>
+</html>
+"""
+
+_AUTH_REDIRECT_ERROR_HTML_TEMPLATE = """\
+<!DOCTYPE html>
+<html>
+<head>
+    <title>Authentication Error</title>
+    <script>
+        (function () {
+            var returnTo = RETURN_URL_PLACEHOLDER;
+            if (returnTo) {
+                window.location.replace(returnTo);
+            } else {
+                window.history.back();
+            }
+        })();
+    </script>
+</head>
+<body>
+    <p>Authentication failed. Redirecting&hellip;</p>
+</body>
+</html>
+"""
+
+
+def build_auth_redirect_error_html(return_url: str | None = None) -> str:
+    """Build the redirect-based authentication error HTML page.
+
+    Navigates back to the UI without the ``oauth_auth_completed`` query
+    parameter so the UI's error-message branch handles it.
+
+    Args:
+        return_url: The UI origin to navigate back to. Falls back to
+            ``window.history.back()`` when not provided.
+
+    Returns:
+        An HTML string for the post-error redirect page.
+    """
+    safe_json = json.dumps(return_url).replace('<', '\\u003c').replace('>', '\\u003e').replace('/', '\\u002f')
+    return _AUTH_REDIRECT_ERROR_HTML_TEMPLATE.replace("RETURN_URL_PLACEHOLDER", safe_json)

packages/nvidia_nat_core/src/nat/front_ends/fastapi/html_snippets/auth_code_grant_success.py

@@ -13,6 +13,8 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
+import json
+
 AUTH_REDIRECT_SUCCESS_HTML = """
 <!DOCTYPE html>
 <html>
@@ -33,3 +35,43 @@
 </body>
 </html>
 """
+
+_AUTH_REDIRECT_SUCCESS_HTML_REDIRECT_TEMPLATE = """\
+<!DOCTYPE html>
+<html>
+<head>
+    <title>Authentication Complete</title>
+    <script>
+        (function () {
+            var returnTo = RETURN_URL_PLACEHOLDER;
+            if (returnTo) {
+                var url = new URL(returnTo);
+                url.searchParams.set('oauth_auth_completed', 'true');
+                window.location.replace(url.toString());
+            } else {
+                window.history.back();
+            }
+        })();
+    </script>
+</head>
+<body>
+    <p>Authentication complete. Redirecting&hellip;</p>
+</body>
+</html>
+"""
+
+
+def build_auth_redirect_success_html(return_url: str | None = None) -> str:
+    """Build the redirect-based authentication success HTML page.
+
+    Args:
+        return_url: The URL to redirect to after successful authentication. When
+            provided the page navigates there immediately with an ``oauth_auth_completed``
+            query parameter so the UI can distinguish a successful return from the user
+            pressing back; otherwise it falls back to ``window.history.back()``.
+
+    Returns:
+        An HTML string for the post-authentication redirect page.
+    """
+    safe_json = json.dumps(return_url).replace('<', '\\u003c').replace('>', '\\u003e').replace('/', '\\u002f')
+    return _AUTH_REDIRECT_SUCCESS_HTML_REDIRECT_TEMPLATE.replace("RETURN_URL_PLACEHOLDER", safe_json)