From 0c28ffba1492f27a2c74c7827a5882407f5f746d Mon Sep 17 00:00:00 2001
From: pballai <46489780+pballai@users.noreply.github.com>
Date: Tue, 9 Dec 2025 10:20:47 -0500
Subject: [PATCH] oauth pkce revision 2
---
.../security_oauth_pkce_secure_integration.md | 530 ++++++++++++++----
1 file changed, 417 insertions(+), 113 deletions(-)
diff --git a/site/sigmaguides/src/security_oauth_pkce_secure_integration/security_oauth_pkce_secure_integration.md b/site/sigmaguides/src/security_oauth_pkce_secure_integration/security_oauth_pkce_secure_integration.md
index 85b1e639..213523d0 100644
--- a/site/sigmaguides/src/security_oauth_pkce_secure_integration/security_oauth_pkce_secure_integration.md
+++ b/site/sigmaguides/src/security_oauth_pkce_secure_integration/security_oauth_pkce_secure_integration.md
@@ -65,21 +65,25 @@ The person who owns the data and grants access to it. In Sigma deployments, this
The application requesting access to protected resources on behalf of the user. When using Sigma Embedding, this is your custom application hosting embedded Sigma content (dashboards, workbooks, or visualizations).
**Authorization Server:**
+NOTE:
KEY BENEFIT:
+GOOD NEWS:
+
+**Authorization Server Must Support:**
+- OAuth 2.0 authorization code flow
+- PKCE extension (code challenge/verifier)
- Token refresh capability
-- Configurable token expiration
-- Scope management
-- Token revocation endpoint
+- Configurable token expiration times
+- Scope-based permission management
+- Token revocation endpoints
+
+**Your Application Must Support:**
+- HTTPS/TLS for all OAuth communications
+- Secure token storage (never in localStorage)
+- Automatic token refresh before expiration
+- Error handling for expired/invalid tokens
+- OAuth redirect URI handling
+- State parameter for CSRF protection
+
+
+
+
+## Common Implementation Challenges
+Duration: 10
+
+Let's walk through the four most common challenges teams face when implementing OAuth with Sigma, with practical solutions you can apply.
+
+### Challenge 1: Token Refresh Timing
+
+**The Problem:**
-**Application Requirements:**
-- HTTPS/TLS support
-- Secure token storage
-- Token refresh logic
-- Error handling for expired tokens
-- Redirect URI handling
-- State parameter management (CSRF protection)
+Your embedded Sigma dashboard is working perfectly. A user is exploring data, building visualizations, when suddenly: "Authentication Error - Token Expired." The access token expired mid-session, breaking their workflow.
-### Common Implementation Challenges
+**Why This Happens:**
-**Challenge 1: Token Refresh Timing**
+Access tokens typically expire after 60 minutes. If you wait for the token to expire before refreshing, users will see errors when Sigma tries to query data.
-**Problem:** Access tokens expire mid-session, interrupting user workflows
+**The Solution:**
-**Solution:**
-- Implement proactive token refresh (refresh before expiration)
-- Set up background refresh process
-- Queue API requests during refresh
-- Add retry logic with exponential backoff
+Implement proactive token refresh that runs before expiration.
-**Challenge 2: Redirect URI Management**
+**Practical Example:**
-**Problem:** OAuth requires exact redirect URI matching, complex with multiple environments
+```code
+// Check token expiration every 5 minutes
+setInterval(async () => {
+ const tokenExpiry = getTokenExpiration();
+ const now = Date.now();
+ const timeUntilExpiry = tokenExpiry - now;
-**Solution:**
-- Register separate OAuth apps per environment
-- Use environment variables for redirect URIs
-- Implement wildcard subdomain support if available
-- Document all registered URIs
+ // Refresh if less than 10 minutes remaining
+ if (timeUntilExpiry < 10 * 60 * 1000) {
+ await refreshAccessToken();
+ }
+}, 5 * 60 * 1000);
+```
-**Challenge 3: Mobile Deep Linking**
+**Best Practices:**
+- Refresh tokens when 5-10 minutes remain on the access token
+- Queue Sigma API requests during the refresh process
+- Implement retry logic with exponential backoff for failed refreshes
+- Monitor refresh token success rates to catch issues early
-**Problem:** OAuth redirects to browser, must return to app
+
+SIGMA TIP:
+
+### Challenge 2: Redirect URI Management
+
+**The Problem:**
+
+OAuth requires exact redirect URI matching. You register `https://app.example.com/callback` with your data warehouse, but your staging environment uses `https://staging.example.com/callback`. Result? OAuth fails in staging with "redirect_uri_mismatch" error.
+
+**Why This Happens:**
+
+For security, authorization servers require exact matches between registered redirect URIs and the URI in your OAuth request. Different environments (dev/staging/prod) need different URIs.
+
+**The Solution:**
+
+Register separate OAuth applications for each environment and use environment variables.
+
+**Practical Example:**
+
+```code
+// config/oauth.js
+const oauthConfig = {
+ development: {
+ clientId: process.env.DEV_OAUTH_CLIENT_ID,
+ redirectUri: 'http://localhost:3000/oauth/callback'
+ },
+ staging: {
+ clientId: process.env.STAGING_OAUTH_CLIENT_ID,
+ redirectUri: 'https://staging.example.com/oauth/callback'
+ },
+ production: {
+ clientId: process.env.PROD_OAUTH_CLIENT_ID,
+ redirectUri: 'https://app.example.com/oauth/callback'
+ }
+};
+
+const config = oauthConfig[process.env.NODE_ENV];
+```
-**Solution:**
-- Implement custom URL schemes
-- Use universal links (iOS) or app links (Android)
-- Handle app resumption gracefully
-- Preserve application state across redirect
+**Best Practices:**
+- Create separate OAuth apps in your data warehouse for each environment
+- Store client IDs and redirect URIs in environment variables
+- Document all registered redirect URIs in your team wiki
+- Use wildcard subdomains if your authorization server supports them
+- Test OAuth flow in each environment before deploying
-**Challenge 4: Token Storage on Web**
+### Challenge 3: Secure Token Storage
-**Problem:** XSS vulnerabilities in browser-based apps
+**The Problem:**
-**Solution:**
-- Use httpOnly, secure cookies
-- Implement Content Security Policy
-- Use SameSite cookie attribute
-- Consider backend-for-frontend pattern
+A developer stores OAuth tokens in browser localStorage for convenience. Later, a security audit flags this as a critical XSS vulnerability - any malicious script can steal tokens and access your data warehouse.
-### Testing OAuth Flows
+**Why This Happens:**
+
+localStorage is accessible to any JavaScript running on your page. If an attacker injects malicious code (XSS attack), they can steal tokens and impersonate users in Sigma.
+
+**The Solution:**
+
+Use httpOnly, secure cookies that JavaScript cannot access.
+
+**Practical Example:**
+
+```code
+// Backend: Set token as httpOnly cookie (Node.js/Express)
+app.post('/oauth/callback', async (req, res) => {
+ const tokens = await exchangeCodeForTokens(req.query.code);
+
+ // Store access token in httpOnly cookie
+ res.cookie('sigma_access_token', tokens.access_token, {
+ httpOnly: true, // JavaScript cannot access
+ secure: true, // HTTPS only
+ sameSite: 'strict', // CSRF protection
+ maxAge: 3600000 // 1 hour
+ });
+
+ // Store refresh token separately with longer expiry
+ res.cookie('sigma_refresh_token', tokens.refresh_token, {
+ httpOnly: true,
+ secure: true,
+ sameSite: 'strict',
+ maxAge: 90 * 24 * 3600000 // 90 days
+ });
+
+ res.redirect('/dashboard');
+});
+```
+
+**Best Practices:**
+- Always use httpOnly, secure cookies for tokens
+- Implement Content Security Policy headers
+- Use SameSite cookie attribute to prevent CSRF attacks
+- For mobile apps, use platform-native secure storage (Keychain/KeyStore)
+- Consider backend-for-frontend pattern for maximum security
+- Never store tokens in localStorage, sessionStorage, or URL parameters
+
+
+SECURITY CRITICAL:
+
+### Challenge 4: Mobile Deep Linking
+
+**The Problem:**
+
+A user clicks your embedded Sigma dashboard in your mobile app. OAuth redirects them to Safari/Chrome for data warehouse login. After authenticating, they're stuck in the browser - the app doesn't resume, and the user is confused.
+
+**Why This Happens:**
+
+OAuth redirects users to the authorization server's web login. Mobile apps need special URL schemes to redirect users back from the browser to the app.
+
+**The Solution:**
+
+Implement universal links (iOS) or app links (Android) to seamlessly return users to your app.
+
+**Practical Example:**
+
+```code
+// iOS Universal Link Configuration (apple-app-site-association)
+{
+ "applinks": {
+ "apps": [],
+ "details": [
+ {
+ "appID": "TEAMID.com.example.app",
+ "paths": ["/oauth/callback"]
+ }
+ ]
+ }
+}
+
+// Handle OAuth callback in your app
+func application(_ app: UIApplication,
+ continue userActivity: NSUserActivity,
+ restorationHandler: @escaping ([UIUserActivityRestoring]?) -> Void) -> Bool {
+
+ guard userActivity.activityType == NSUserActivityTypeBrowsingWeb,
+ let url = userActivity.webpageURL,
+ url.path == "/oauth/callback" else {
+ return false
+ }
+
+ // Extract authorization code from URL
+ let code = extractAuthCode(from: url)
+
+ // Exchange for tokens and load Sigma embed
+ exchangeCodeForTokens(code) { tokens in
+ loadSigmaEmbed(with: tokens.accessToken)
+ }
+
+ return true
+}
+```
+
+**Best Practices:**
+- Configure universal links (iOS) or app links (Android)
+- Test deep linking across different iOS/Android versions
+- Preserve user's place in the app during OAuth redirect
+- Implement custom URL schemes as fallback
+- Handle cases where universal links aren't configured
+- Provide clear visual feedback during OAuth redirect flow
+
+
+
+
+## Testing and Monitoring
+Duration: 5
+
+### Testing Your OAuth Implementation
**Local Development:**
-- Use localhost redirect URIs
-- Mock authorization server for unit tests
-- Implement token generation utilities
-- Test token expiration scenarios
+
+Start by testing OAuth flows on your development machine:
+
+```code
+// Use localhost for development
+const devRedirectUri = 'http://localhost:3000/oauth/callback';
+
+// Mock authorization server for unit tests
+const mockAuthServer = {
+ generateTokens: () => ({
+ access_token: 'mock_access_token',
+ refresh_token: 'mock_refresh_token',
+ expires_in: 3600
+ })
+};
+```
+
+**Key Tests to Run:**
+- Successful OAuth authorization flow end-to-end
+- Token expiration and automatic refresh
+- Error handling when tokens are invalid
+- PKCE code challenge/verifier validation
+- Redirect URI mismatch scenarios
**Staging Environment:**
-- Register separate OAuth application
-- Test with production-like data
-- Verify all redirect flows
-- Test error conditions
+
+Register a separate OAuth application for staging and test with production-like data:
+
+- Verify all redirect flows work correctly
+- Test token refresh before expiration
+- Simulate token expiration mid-session
+- Test error conditions (network failures, invalid tokens)
+- Verify Sigma embeds load with staging OAuth tokens
**Production Monitoring:**
-- Log OAuth errors (without logging tokens!)
-- Monitor token refresh success rates
-- Track authorization success/failure
-- Alert on unusual patterns
+
+Once deployed, monitor your OAuth implementation continuously:
+
+```code
+// Log OAuth events (but never log tokens!)
+logger.info('OAuth authorization started', {
+ userId: user.id,
+ timestamp: Date.now()
+});
+
+logger.info('Token refresh succeeded', {
+ userId: user.id,
+ expiresIn: 3600,
+ scopes: ['sql', 'offline_access']
+});
+
+logger.error('Token refresh failed', {
+ userId: user.id,
+ errorType: 'invalid_grant',
+ // DO NOT log the actual token or refresh token
+});
+```
+
+**Metrics to Monitor:**
+- Token refresh success rate (target: >99%)
+- Authorization flow success rate
+- Average time for OAuth redirect flow
+- Token expiration errors
+- Unusual token usage patterns
-SECURITY WARNING: SECURITY WARNING:
-### Compliance and Governance
-
-**Audit Requirements:**
-- Log all token issuance events
-- Track which users accessed what data
-- Retain audit logs per compliance requirements
-- Implement log analysis for anomaly detection
-
-**Data Privacy:**
-- Document what data each scope accesses
-- Implement data access agreements
-- Allow users to review granted permissions
-- Provide permission revocation capability
-
-**Security Policies:**
-- Define token lifetime policies
-- Establish refresh token rotation
-- Implement rate limiting
-- Regular security audits
+
+
+
+## Compliance and Governance
+Duration: 5
+
+OAuth implementations must meet audit, privacy, and security requirements.
+
+### Audit Requirements
+
+**What to Log:**
+- Token issuance events (who, when, which scopes)
+- Data access through Sigma (which user queried what data)
+- Token refresh and revocation events
+- Failed authorization attempts
+- Scope changes or permission grants
+
+**Practical Example:**
+
+```code
+// Audit log entry for Sigma query
+{
+ "timestamp": "2025-12-08T14:30:00Z",
+ "event_type": "sigma_query_executed",
+ "user_id": "john.doe@example.com",
+ "data_platform": "snowflake",
+ "query_type": "dashboard_load",
+ "dashboard_id": "sales_metrics_q4",
+ "scopes_used": ["session:role-any", "refresh_token"],
+ "rows_returned": 1523
+}
+```
+
+**Retention:** Retain audit logs according to your compliance requirements (typically 1-7 years).
+
+### Data Privacy
+
+**User Consent:**
+
+Users must understand what access they're granting when they authorize Sigma:
+
+- Clearly document what data each OAuth scope accesses
+- Show users which permissions Sigma is requesting
+- Allow users to review granted permissions in account settings
+- Provide easy permission revocation capability
+
+**Privacy Controls:**
+- Implement data access agreements for sensitive data
+- Log data access for GDPR/CCPA compliance
+- Allow users to export their access history
+- Provide user data deletion capability
+
+### Security Policies
+
+**Token Lifetime Policies:**
+- Access tokens: 60 minutes (standard for most platforms)
+- Refresh tokens: 90 days maximum
+- Implement token rotation on each refresh
+- Revoke tokens immediately on user logout
+
+**Rate Limiting:**
+
+Prevent abuse by limiting OAuth requests:
+
+```code
+// Example rate limit: 10 token refresh requests per hour per user
+const rateLimiter = {
+ maxRequests: 10,
+ windowMs: 3600000, // 1 hour
+ message: 'Too many token refresh requests'
+};
+```
+
+**Regular Security Audits:**
+- Review OAuth logs quarterly for suspicious patterns
+- Test token revocation workflows
+- Verify token encryption at rest
+- Scan for exposed tokens in logs or error messages
+- Update OAuth libraries to patch security vulnerabilities
+
+
+COMPLIANCE TIP:
