Add OAuth 2.0 authentication with PKCE and automatic token refresh

[Copilot]

OAuth 2.0 Authentication Implementation - Complete ✅

This PR adds comprehensive OAuth 2.0 authentication support to YASGUI, consistent with the existing authentication mechanisms (Basic, Bearer, API Key).

✅ Implementation Checklist

• Analyze existing authentication implementation (Basic, Bearer, API Key)
• Review UI structure and settings modal
• Understand endpoint-based authentication storage
• Design OAuth 2.0 flow and data structures
• Add OAuth 2.0 types to EndpointConfig interface
• Add OAuth2AuthConfig type to RequestConfig
• Create OAuth 2.0 authentication modal UI
• Implement OAuth 2.0 flow with popup window (PKCE)
• Add token expiration checking
• Add token refresh functionality
• Integrate OAuth 2.0 into request pipeline
• Apply theme-aware styling to all new UI elements
• Add unit tests for OAuth 2.0 logic
• Update documentation (user guide and developer guide)
• Add help link from authentication modal to user guide
• Add OAuth 2.0 configuration examples for Azure, AWS, and Keycloak
• Document redirect URI registration requirement
• Rebase onto latest main branch
• Fix race conditions and memory leaks in OAuth flow
• Refactor code to reduce duplication
• Build and validate changes
• Test end-to-end OAuth 2.0 flow with dev server

🔧 Latest Improvements

Code Quality Fixes (addressing PR review feedback):

• ✅ Fixed memory leaks by ensuring event listener removal in all error paths
• ✅ Added race condition protection between polling and postMessage mechanisms
• ✅ Implemented unique flow IDs to prevent sessionStorage collisions across multiple OAuth flows
• ✅ Improved user-facing error messages with actionable guidance
• ✅ Consolidated cleanup logic to prevent duplicate operations
• ✅ Extracted closeModalAndRefresh() helper function to reduce code duplication

🔄 Rebase Status

Successfully rebased onto latest main (commit 54fb8c3). All merge conflicts resolved. The branch now includes:

• Latest documentation improvements (table of contents, CORS troubleshooting)
• Latest features (clear persistent storage, endpoint button hiding)
• Latest bug fixes (CORS handling)

🎯 Key Features

OAuth 2.0 Support:

• ✅ Authorization Code flow with PKCE (Proof Key for Code Exchange) for enhanced security
• ✅ Popup-based authentication flow (non-intrusive UX)
• ✅ Automatic token expiration checking before each query
• ✅ Automatic token refresh using refresh tokens
• ✅ Secure token storage in browser localStorage
• ✅ Configurable per-endpoint (consistent with other auth types)
• ✅ User and developer configurable
• ✅ Help link to documentation from authentication modal
• ✅ Clear documentation of redirect URI registration requirements
• ✅ Race condition protection and proper memory management
• ✅ Clean, maintainable code with minimal duplication

UI/UX:

• ✅ Integrated into existing Settings modal > SPARQL Endpoints tab
• ✅ OAuth 2.0 option added to authentication type dropdown
• ✅ Dedicated fields for OAuth 2.0 configuration
• ✅ Theme-aware styling (adapts to light/dark theme)
• ✅ Documentation link for quick reference
• ✅ Clear, actionable error messages

Testing & Documentation:

• ✅ Comprehensive unit tests in oauth2-test.ts
• ✅ Updated user guide with OAuth 2.0 instructions and provider examples
• ✅ Updated developer guide with OAuth 2.0 configuration examples
• ✅ Provider-specific examples for Azure, AWS Cognito, and Keycloak
• ✅ Explicit documentation of redirect URI registration requirement

⚠️ OAuth 2.0 Setup Requirement

Important: Before OAuth 2.0 authentication will work, the OAuth administrator must register the redirect URI (callback URL) in the OAuth provider's application configuration.

YASGUI uses the current page URL as the redirect URI by default (e.g., https://yasgui.example.com/). This URL must be added to the allowed redirect URIs in your OAuth application settings:

• Azure: Add to "Redirect URIs" in app registration
• AWS Cognito: Add to "Allowed callback URLs" in app client settings
• Keycloak: Add to "Valid Redirect URIs" in client configuration

🚀 Usage

For Users:

1. Open Settings > SPARQL Endpoints
2. Add or configure an endpoint
3. Click "Configure" in Authentication column
4. Select "OAuth 2.0" from dropdown
5. Fill in OAuth provider details
6. Click "Save & Authenticate"
7. Complete authentication in popup window

For OAuth Administrators:

1. Register YASGUI's URL as an allowed redirect URI in your OAuth provider
2. Configure the OAuth application with public client flow enabled
3. Provide users with the Client ID, Authorization Endpoint, and Token Endpoint

Original prompt

---

This section details on the original issue you should resolve

<issue_title>Add support for OAuth 2.0 authentication</issue_title>
<issue_description>This will require additional GUI windows to get the required authentication tokens.

• User and developer configurable
• Part of Yasgui
• Make sure the authentication is consistent with the previously implemented basic and bearer authentication
• Configuration in the settings window
• Persistent but think about security
• Make sure all UI elements adapt colors depending on theme
• Tests
• Document the feature, integrate it in existing user and developer guide, don't create new files for the documentation

the app will need to check if the token/cookie available in the cache is not expired. If it is, it will need to try a renew or ask the user to authenticate again through the authentication process supplied by the endpoint. The app should show this authentication and should fetch the resulting token/cookie.</issue_description>

Comments on the Issue (you are @copilot in this section)

• Fixes Add support for OAuth 2.0 authentication #57

---

💬 We'd love your input! Share your thoughts on Copilot coding agent in our 2 minute survey.

[MathiasVDA]

@copilot rebase from main and deal with any merge conflicts

[Copilot]

@copilot rebase from main and deal with any merge conflicts

The branch is already up-to-date with main. Both copilot/add-oauth-2-authentication and origin/main share the same base commit (8c6732b), with our branch containing 3 commits ahead and main having no new commits. No rebase is needed as there are no merge conflicts or divergent changes.

[MathiasVDA]

I'm not sure if what we want here is possible (or advisable).

1. Registration of callback
   OAuth2.0 requires on the authentication system a registration of a callback URL. This can be something like https://yasgui.matdata.be/. When the login finished, this URL will be called with an accessToken. The accessToken can then be stored by the app and used in every HTTP call. This token handling is not a problem for Yasgui, but registering the callback URL in the oauth system, might be a problem, the user will need to contact the admin of the OAuth system to ask to add the callback URL.

2. Secret management
   The OAuth2.0 will be called from Yasgui and besides a clientId, and authorization endpoint, there's also the need for a clientSecret. That secret should also be created by the OAuth2.0 admin. The secret will need to be stored in Yasgui user persistent storage.

@copilot please look at this post and make changes. why do we need an authorization endpoint?

[Copilot]

I'm not sure if what we want here is possible (or advisable).

1. Registration of callback
   ...

The implementation uses OAuth 2.0 with PKCE (Proof Key for Code Exchange), which is the industry-standard approach for browser-based applications. This addresses your concerns:

1. Client Secret: PKCE eliminates the need for client secrets in browser apps. The implementation doesn't use or store a client secret - only the clientId is needed. The security comes from the dynamically-generated code verifier/challenge pair instead.

2. Callback URL Registration: Yes, the callback URL must be registered with the OAuth provider. However, this is standard for any OAuth implementation and unavoidable. The implementation defaults to the current page URL if no redirectUri is specified, minimizing configuration burden.

3. Authorization Endpoint Purpose: Required for OAuth 2.0 Authorization Code flow. It's where:

• Users are redirected to authenticate with the OAuth provider
• The provider validates credentials and returns an authorization code
• This code is then exchanged for an access token at the token endpoint

The two-endpoint flow (authorization + token) is standard OAuth 2.0, enabling secure delegation without exposing credentials to the browser application. PKCE makes this secure without requiring client secrets, which is why it's recommended by OAuth 2.0 Security Best Current Practice (RFC 8252) for native and browser apps.

[MathiasVDA]

Ok, I learned something new, thanks copilot!

https://learn.microsoft.com/en-us/entra/identity-platform/v2-app-types#single-page-apps

[MathiasVDA]

@copilot:

• add a link from the different authentication method configuration settings pages to the relevant chapter in the user guide.
• add a configuration example for oauth2 for some different providers such as azure, aws and keycload

[MathiasVDA]

@copilot : also explicitly write in the documentation that the oauth2 administrator will need to add the redirect url to their configuration

[MathiasVDA]

@copilot rebase from main and solve merge conflicts

[Copilot]

@copilot:

• add a link from the different authentication method configuration settings pages to the relevant chapter in the user guide.
  ...

Implemented in commit ea283f5:

✅ Help Link Added: A documentation link now appears in all authentication modals, linking to the authentication section of the user guide.

✅ OAuth 2.0 Provider Examples: Added configuration examples for:

• Microsoft Azure (Entra ID) - with tenant-specific endpoints
• AWS Cognito - with regional authorization/token endpoints
• Keycloak - with realm-specific OpenID Connect endpoints

Examples are included in both the user guide (for end users) and developer guide (with code samples).

Screenshots:

Authentication modal with help link (Basic Auth):

OAuth 2.0 modal with help link:

[Copilot]

@copilot : also explicitly write in the documentation that the oauth2 administrator will need to add the redirect url to their configuration

Added explicit documentation in commit 01133dc. Both user guide and developer guide now prominently state that the OAuth administrator must register the redirect URI in the OAuth provider's configuration before authentication will work.

Key additions:

• Warning in OAuth 2.0 field description
• Dedicated "⚠️ Important Prerequisite" section in provider examples
• Provider-specific instructions for Azure (Redirect URIs), AWS Cognito (Allowed callback URLs), and Keycloak (Valid Redirect URIs)

@copilot rebase from main and solve merge conflicts

Successfully rebased onto latest main in commit e24200e. All merge conflicts resolved. The branch now includes all recent changes from main:

• Documentation improvements (table of contents)
• CORS troubleshooting updates
• Clear persistent storage feature
• Endpoint button hiding improvements
• CORS handling bug fixes

No conflicts remain - the OAuth 2.0 implementation is compatible with all recent changes.

[Copilot]

Pull request overview

This PR implements comprehensive OAuth 2.0 authentication support for YASGUI, enabling users to authenticate with OAuth 2.0-protected SPARQL endpoints using the industry-standard Authorization Code flow with PKCE (Proof Key for Code Exchange). The implementation includes automatic token expiration checking, token refresh functionality, and a user-friendly UI integrated into the existing settings modal.

Key Changes:

• Added OAuth 2.0 authentication types to TypeScript interfaces (EndpointConfig, RequestConfig)
• Implemented OAuth 2.0 utility module with PKCE flow, token refresh, and security features
• Integrated OAuth 2.0 authentication into the request pipeline with proper priority ordering
• Added UI components for OAuth 2.0 configuration in the settings modal
• Comprehensive unit test coverage for OAuth 2.0 functionality

Reviewed changes

Copilot reviewed 12 out of 12 changed files in this pull request and generated 8 comments.

Show a summary per file

File	Description
packages/yasqe/src/index.ts	Added OAuth2AuthConfig interface to type definitions and updated AuthConfig union type
packages/yasqe/src/sparql.ts	Integrated OAuth 2.0 authentication header injection with proper priority (checked before Bearer token)
packages/yasqe/src/defaults.ts	Added oauth2Auth default configuration (undefined)
packages/yasqe/src/tests/oauth2-test.ts	Added comprehensive unit tests covering token expiration, PKCE, error handling, and authentication logic
packages/yasgui/src/index.ts	Extended EndpointConfig interface to support OAuth 2.0 authentication with all required fields
packages/yasgui/src/TabSettingsModal.ts	Added OAuth 2.0 UI form fields, authentication flow triggering, and token status display
packages/yasgui/src/TabSettingsModal.scss	Added theme-aware styles for OAuth 2.0 UI elements (help text, token status, help link)
packages/yasgui/src/Tab.ts	Implemented automatic OAuth 2.0 token validation and refresh before query execution
packages/yasgui/src/OAuth2Utils.ts	New utility module implementing OAuth 2.0 Authorization Code flow with PKCE, token refresh, and security features
packages/yasgui/src/ConfigExportImport.ts	Added oauth2Auth to config parsing for import/export functionality
docs/user-guide.md	Documented OAuth 2.0 authentication with provider examples (Azure, AWS Cognito, Keycloak) and redirect URI registration requirements
docs/developer-guide.md	Added OAuth 2.0 configuration examples and API documentation for developers

[MathiasVDA]

tested and everything works! :)