Skip to content

Authentication

Jump to bottom
Daniel Heward-Mills edited this page Sep 27, 2025 · 1 revision

Authentication

SPARQLWorks™ supports multiple authentication methods for accessing protected SPARQL endpoints. This document explains how to configure and use OAuth 2.0 and Bearer token authentication.

🔐 Authentication Methods

OAuth 2.0 (Recommended)

Modern, secure authentication using industry standards:

  • PKCE Flow: Proof Key for Code Exchange for enhanced security
  • Dynamic Registration: Automatic client registration for compatible servers
  • Token Refresh: Automatic token renewal (when supported)
  • Standards Compliant: OAuth 2.0 Authorization Code flow

Bearer Token

Direct token authentication for simple setups:

  • Manual Entry: Direct input of access tokens
  • No Expiry Handling: Manual token renewal required
  • Simple Configuration: Minimal setup required

🔧 OAuth 2.0 Setup

Prerequisites

  • SPARQL Endpoint: Must support OAuth 2.0
  • Client Registration: Endpoint must allow client registration or provide client credentials
  • HTTPS Required: OAuth requires secure connections
  • Redirect URI: Must be configured on the authorization server

Step 1: Configure Endpoint

  1. Open SPARQLWorks in your browser
  2. Enter your OAuth-enabled SPARQL endpoint URL
  3. Example: https://sparql.example.com/sparql

Step 2: Access Account Settings

  1. Click the account icon (👤) in the top-right corner
  2. The account menu will appear
  3. Click "OAuth Settings" to configure OAuth parameters

Step 3: Configure OAuth Settings

  1. Client ID (optional):

    • Enter if provided by your endpoint administrator
    • Leave empty for dynamic registration
    • Example: sparql-client-123

  2. Redirect URI:

    • Usually auto-configured to current page URL
    • Must be HTTPS in production
    • Must be registered with the OAuth server
    • Example: https://sparqlworks.example.com/

Step 4: Initiate Login

  1. Click "Log In" from the account menu
  2. You'll be redirected to your endpoint's login page
  3. Enter your credentials
  4. Grant permission for SPARQLWorks to access the endpoint
  5. You'll be redirected back to SPARQLWorks

Step 5: Verify Authentication

  • Account icon shows "Signed in (OAuth)"
  • Status message confirms successful authentication
  • Queries now include Authorization headers automatically

🏷️ Bearer Token Setup

When to Use Bearer Tokens

  • Simple Endpoints: Endpoints with basic token authentication
  • API Keys: Direct token provision
  • Development: Quick authentication for testing
  • Legacy Systems: Older authentication methods

Step 1: Obtain Token

  1. Contact your endpoint administrator
  2. Request a bearer token or API key
  3. Ensure the token has appropriate permissions

Step 2: Enter Token

  1. Click the account icon (👤)
  2. Select "Provide Bearer token"
  3. Paste your token in the text area
  4. Example token: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

Step 3: Save and Validate

  1. Click "Save & Authenticate"
  2. SPARQLWorks validates the token
  3. Success message appears
  4. Account status updates to "Signed in (Bearer token)"

🔍 Authentication Validation

Automatic Validation

SPARQLWorks validates credentials by:

  1. HEAD/OPTIONS Request: Testing endpoint accessibility
  2. Authorization Header: Including Bearer token
  3. Status Code Check: Verifying 200/401/403 responses
  4. Error Handling: Providing clear feedback

Validation Messages

  • Success: "Credentials stored (OAuth/Bearer). Queries will include Authorization headers."
  • Warning: Token accepted but validation inconclusive
  • Error: Token rejected by endpoint

🌐 Endpoint Compatibility

OAuth 2.0 Compatible Endpoints

  • OpenID Connect: Full OAuth/OIDC support
  • Custom OAuth: Standard OAuth 2.0 implementations
  • Enterprise Systems: Corporate authentication servers
  • Cloud Services: AWS Cognito, Azure AD, etc.

Bearer Token Endpoints

  • API Gateways: Services with token authentication
  • Custom Endpoints: Proprietary authentication schemes
  • Legacy Systems: Older SPARQL implementations

🔄 Token Management

OAuth Token Lifecycle

  1. Authorization Code: Received after user login
  2. Token Exchange: Code exchanged for access token
  3. Storage: Token stored in browser localStorage
  4. Automatic Inclusion: Added to all SPARQL requests
  5. Expiry Handling: Tokens expire based on server configuration

Bearer Token Management

  1. Manual Entry: User provides token directly
  2. Storage: Token stored securely in localStorage
  3. No Expiry: No automatic renewal
  4. Manual Refresh: User must update expired tokens

Security Considerations

  • HTTPS Only: All authentication requires secure connections
  • Local Storage: Credentials stored client-side only
  • No Server Transmission: SPARQLWorks never sends credentials to its own servers
  • Session Isolation: Credentials isolated per browser session

🐛 Troubleshooting Authentication

OAuth Issues

"Endpoint does not support OAuth"

  • Verify endpoint supports OAuth 2.0
  • Check discovery document availability
  • Confirm CORS configuration

"Dynamic client registration failed"

  • Server may require manual client registration
  • Contact administrator for client credentials
  • Use manual client ID configuration

"Redirect URI mismatch"

  • Ensure redirect URI matches OAuth server configuration
  • Check for HTTPS requirement
  • Verify exact URI matching

"PKCE verification failed"

  • Browser security restrictions
  • Clear browser cache and retry
  • Check for browser extensions interfering

Bearer Token Issues

"Token rejected"

  • Verify token format and validity
  • Check token permissions
  • Confirm token hasn't expired

"CORS blocked"

  • Endpoint doesn't allow browser requests
  • May need proxy or server-side implementation
  • Check endpoint CORS policy

"Invalid token format"

  • Ensure token is properly formatted
  • Check for extra whitespace
  • Verify base64 encoding if applicable

Common Solutions

Clear Stored Credentials

// In browser console
localStorage.removeItem('oauthAccessToken');
localStorage.removeItem('sparqlworks.auth.source');
location.reload();

Reset OAuth Session

// Clear all OAuth data
localStorage.removeItem('pkce_verifier');
localStorage.removeItem('oauth_state_nonce');
localStorage.removeItem('oauth_client_id');
localStorage.removeItem('oauth_origin');

Test Endpoint Accessibility

// Test basic connectivity
fetch('https://your-endpoint.com/sparql', {
  method: 'HEAD',
  headers: { 'Authorization': 'Bearer YOUR_TOKEN' }
}).then(r => console.log('Status:', r.status));

🔒 Security Best Practices

OAuth 2.0 Security

  • PKCE Always: Proof Key for Code Exchange prevents code interception
  • State Parameter: Prevents CSRF attacks
  • HTTPS Required: Prevents token interception
  • Short Token Lifetime: Reduces exposure window

Bearer Token Security

  • Secure Storage: Browser localStorage with same-origin policy
  • No Logging: Tokens never logged or displayed
  • Manual Handling: User responsible for token security
  • Regular Rotation: Update tokens periodically

General Security

  • No Credential Transmission: SPARQLWorks never sends credentials to external servers
  • Client-Side Only: All authentication handled in browser
  • Session Isolation: Credentials isolated per origin
  • Automatic Cleanup: Failed authentication clears stored tokens

📚 Advanced Configuration

Custom OAuth Endpoints

For endpoints with non-standard OAuth configuration:

  1. Manual Discovery: Configure custom endpoints if auto-discovery fails
  2. Client Credentials: Use pre-registered client IDs
  3. Custom Scopes: Specify required OAuth scopes
  4. Token Refresh: Configure refresh token handling

Proxy Authentication

For endpoints behind authentication proxies:

  1. Proxy Configuration: Configure proxy settings if needed
  2. Header Forwarding: Ensure Authorization headers pass through
  3. CORS Handling: Configure CORS for proxy scenarios

Enterprise Integration

For corporate environments:

  1. SSO Integration: Configure with corporate identity providers
  2. Multi-Factor Authentication: Support MFA when available
  3. Compliance: Meet enterprise security requirements
  4. Audit Logging: Enable authentication auditing

📞 Support

Getting Help

  • Documentation: Check endpoint-specific authentication docs
  • Administrator: Contact your SPARQL endpoint administrator
  • Community: Check SPARQLWorks issue tracker
  • Logs: Use browser developer tools for detailed error information

Diagnostic Information

When reporting authentication issues, include:

  • Endpoint URL
  • Authentication method (OAuth/Bearer)
  • Browser and version
  • Error messages
  • Network request details

← Examples | Next: Controls and Settings →

Clone this wiki locally