sarman/tftsr-devops_investigation
1
0
Fork 0
Code Issues 1 Pull Requests Actions 34 Packages Projects 3 Releases 9 Wiki Activity
1de50f1c87
tftsr-devops_investigation/INTEGRATION_AUTH_GUIDE.md
Shaun Arman 9e8db9dc81 feat(ai): add tool-calling and integration search as AI data source 
This commit implements two major features:

1. Integration Search as Primary AI Data Source
   - Confluence, ServiceNow, and Azure DevOps searches execute before AI queries
   - Search results injected as system context for AI providers
   - Parallel search execution for performance
   - Webview-based fetch for HttpOnly cookie support
   - Persistent browser windows maintain authenticated sessions

2. AI Tool-Calling (Function Calling)
   - Allows AI to automatically execute functions during conversation
   - Implemented for OpenAI-compatible providers and Custom REST provider
   - Created add_ado_comment tool for updating Azure DevOps tickets
   - Iterative tool-calling loop supports multi-step workflows
   - Extensible architecture for adding new tools

Key Files:
- src-tauri/src/ai/tools.rs (NEW) - Tool definitions
- src-tauri/src/integrations/*_search.rs (NEW) - Integration search modules
- src-tauri/src/integrations/webview_fetch.rs (NEW) - HttpOnly cookie workaround
- src-tauri/src/commands/ai.rs - Tool execution and integration search
- src-tauri/src/ai/openai.rs - Tool-calling for OpenAI and Custom REST provider
- All providers updated with tools parameter support

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
2026-04-07 09:35:34 -05:00

5.1 KiB
Raw Blame History

Integration Authentication Guide

Overview

The TRCAA application supports three integration authentication methods, with automatic fallback between them:

  1. API Tokens (Manual) - Recommended ✅
  2. OAuth 2.0 - Fully automated (when configured)
  3. Browser Cookies - Partially working ⚠️

Authentication Priority

When you ask an AI question, the system attempts authentication in this order:

1. Extract cookies from persistent browser window
   ↓ (if fails)
2. Use stored API token from database
   ↓ (if fails)
3. Skip that integration and log guidance

HttpOnly Cookie Limitation

Problem: Confluence, ServiceNow, and Azure DevOps use HttpOnly cookies for security. These cookies:

  • ✅ Exist in the persistent browser window
  • ✅ Are sent automatically by the browser
  • ❌ Cannot be extracted by JavaScript (security feature)
  • ❌ Cannot be used in separate HTTP requests

Impact: Cookie extraction via the persistent browser window fails for HttpOnly cookies, even though you're logged in.

Recommended Solution: Use API Tokens

Confluence Personal Access Token

  1. Log into Confluence
  2. Go to Profile → Settings → Personal Access Tokens
  3. Click Create token
  4. Copy the generated token
  5. In TRCAA app:
    • Go to Settings → Integrations
    • Find your Confluence integration
    • Click "Save Manual Token"
    • Paste the token
    • Token Type: Bearer

ServiceNow API Key

  1. Log into ServiceNow
  2. Go to System Security → Application Registry
  3. Click New → OAuth API endpoint for external clients
  4. Configure and generate API key
  5. In TRCAA app:
    • Go to Settings → Integrations
    • Find your ServiceNow integration
    • Click "Save Manual Token"
    • Paste the API key

Azure DevOps Personal Access Token (PAT)

  1. Log into Azure DevOps
  2. Click User Settings (top right) → Personal Access Tokens
  3. Click New Token
  4. Scopes: Select Read for:
    • Code (for wiki)
    • Work Items (for work item search)
  5. Click Create and copy the token
  6. In TRCAA app:
    • Go to Settings → Integrations
    • Find your Azure DevOps integration
    • Click "Save Manual Token"
    • Paste the token
    • Token Type: Bearer

Verification

After adding API tokens, test the integration:

  1. Open or create an issue
  2. Go to Triage page
  3. Ask a question like: "How do I upgrade Vesta NXT to 1.0.12"
  4. Check the logs for: 
    INFO Using stored cookies for confluence (count: 1)
INFO Found X integration sources for AI context

If successful, the AI response should include:

  • Content from internal documentation
  • Source citations with URLs
  • Links to Confluence/ServiceNow/Azure DevOps pages

Troubleshooting

No search results found

Symptom: AI gives generic answers instead of internal documentation

Check logs for:

WARN Unable to search confluence - no authentication available

Solution: Add an API token (see above)

Cookie extraction timeout

Symptom: Logs show:

WARN Failed to extract cookies from confluence: Timeout extracting cookies

Why: HttpOnly cookies cannot be extracted via JavaScript

Solution: Use API tokens instead

Integration not configured

Symptom: No integration searches at all

Check: Settings → Integrations - ensure integration is added with:

  • Base URL configured
  • Either browser window open OR API token saved

Future Enhancements

Native Cookie Extraction (Planned)

We plan to implement platform-specific native cookie extraction that can access HttpOnly cookies directly from the webview's cookie store:

  • macOS: Use WKWebView's HTTPCookieStore (requires cocoa/objc crates)
  • Windows: Use WebView2's cookie manager (requires windows crate)
  • Linux: Use WebKitGTK cookie manager (requires webkit2gtk binding)

This will make the persistent browser approach fully automatic, even with HttpOnly cookies.

Webview-Based Search (Experimental)

Another approach is to make search requests FROM within the authenticated webview using JavaScript fetch, which automatically includes HttpOnly cookies. This requires reliable IPC communication between JavaScript and Rust.

Security Notes

Token Storage

API tokens are:

  • ✅ Encrypted using AES-256-GCM before storage
  • ✅ Hashed (SHA-256) for audit logging
  • ✅ Stored in encrypted SQLite database
  • ✅ Never exposed to frontend JavaScript

Cookie Storage (when working)

Extracted cookies are:

  • ✅ Encrypted before database storage
  • ✅ Only retrieved when making API requests
  • ✅ Transmitted only over HTTPS

Audit Trail

All integration authentication attempts are logged:

  • Cookie extraction attempts
  • Token usage
  • Search requests
  • Authentication failures

Check Settings → Security → Audit Log to review activity.

Summary

For reliable integration search NOW: Use API tokens (Option 1)

For automatic integration search LATER: Native cookie extraction will be implemented in a future update

Current workaround: API tokens provide full functionality without browser dependency