# 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
```javascript
// In browser console
localStorage.removeItem('oauthAccessToken');
localStorage.removeItem('sparqlworks.auth.source');
location.reload();
```

#### Reset OAuth Session
```javascript
// 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
```javascript
// 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](Examples.md) | [Next: Controls and Settings →](Controls-and-Settings.md)