Documentation for the legacy version (0.6.1‐beta) - fctr-id/okta-ai-agent GitHub Wiki

Meet Tako, the first AI agent of its kind that offers dual capabilities - both powerful database queries and real-time API operations through natural language. Built specifically for administrators, IAM managers, IT GRC teams and auditors, Tako leverages enterprise AI models to translate plain English questions into accurate data insights from synced databases or direct Okta API interactions. Our vision is to evolve Tako into a fully autonomous agent capable of performing nearly all Okta administrative functions while maintaining enterprise-grade security and compliance.

Installation and Demo Video

Watch our step-by-step installation guide and Tako feature demonstration:

• 📋 Table of Contents
• ⚠️ BREAKING CHANGES ALERT
• 🆕 New in This Version (0.6.1-beta)
• ✨ What's Special?
• 🚀 Quick Start (The No-Frills Docker Way)
  • Prerequisites
  • Docker Compose
    • Linux/macOS Instructions
    • Windows Instructions
  • 🚨 Optimal API settings for maximum sync speed 🚨
  • ⚠️ Important: Monitor for Errors
  • 🆘 Need Help?
  • Launching the Application
  • Tailing docker logs
  • Access the Web Interface
  • Dual Operation Modes
  • When to Use Each Mode
  • Realtime Agent Capabilities
  • Additional Improvements
  • Available Tools for Realtime Mode
  • LLM Requirements for Realtime Mode
• 🛡️ Security & Privacy
  • Common Security Features
    • Access Management
    • AI Provider Options
  • Data Privacy by Mode
    • Database Mode
    • Realtime Mode
  • Database Mode Data Model
• ⚠️ Good to Know
  • Beta Release 🧪
  • Security First 🛡️
  • Current Limitations 🔍
• 🗺️ Roadmap
  • Phase 1: Data Access & Insights
  • Phase 2: Infrastructure & Interface Enhancements
  • Phase 3: Real-time Operations
  • Phase 4: Autonomous Operations
  • Phase 5: Full Automation
• 🆘 Need Help?
• 💡 Feature Requests & Ideas
• 👥 Contributors
• 💌 Thank You
• ⚖️ Legal Stuff

IMPORTANT: Version 0.6.1-beta contains breaking changes. If you are using previous versions or installed before 06/13/2025, you will need to completely redo your setup to ensure compatibility with the new realtime capabilities.

Docker users: Stop containers, delete SQLite files (rm sqlite_db/*.db), then restart.

Repository Clone users: Delete database files (rm *.db sqlite_db/*.db), update dependencies (pip install -r requirements.txt), then restart.

• 📋 Custom User Attributes - You can define custom user attributes that will be synced and available for querying.
• 📱 Devices Sync - Full devices sync with user relationships, security context, and analytics (Optional - set to false by default)
• 🔍 Enhanced Queries - Query users by custom attributes and devices by platform, security status, etc.
• 🔒 SSL Certificate Support - Self-signed certificates and organizational CAs are now supported for the openai_compatible provider

Note: Device sync controlled by SYNC_OKTA_DEVICES environment variable in .env file.

📋 View complete change log →

• 🚀 Easy Okta Sync - Quick and parallel okta sync to local SQLite DB
• 💡 Natural Language Queries - Talk to your Okta data with Tako using simple English
• 🔄 Real-time Operation Mode - Direct API interaction for up-to-the-second data access
• ⚡ Multiple AI Providers - Tako leverages the power of leading AI providers:
  • Google Vertex AI (Gemini 1.5 Pro, 2.5 Pro)
  • OpenAI (GPT-4, o4-mini)
  • Azure OpenAI (GPT-4)
  • Anthropic (Claude 3.7 Sonnet)
  • Ollama (Local, Self-hosted, use 32B+ models)
  • OpenAI Compatible APIs (Fireworks, Together AI, OpenRouter ...etc)
• 🖥️ Web Interface - Modern UI for easier interaction with Tako and your Okta data

✅ Docker installed on your machine
✅ Okta tenant with superadmin access
✅ Access to any of the supported AI providers

The easiest way to get started is with Docker Compose:

# 1. Create a project directory and navigate to it
mkdir okta-ai-agent 
cd okta-ai-agent

# 2. Create required directories for data persistence
### Upload your own key and cert pem files to certs directory if you need them
mkdir -p sqlite_db logs certs

# 3. Download the docker-compose.yml file
curl -O https://raw.githubusercontent.com/fctr-id/okta-ai-agent/main/docker-compose.yml

# 4. Download and modify the .env file with your configuration
curl -O https://raw.githubusercontent.com/fctr-id/okta-ai-agent/main/.env.sample
mv .env.sample .env

# ⚠️ IMPORTANT: Edit the .env file with your settings! ⚠️
# The app will not work without properly configured environment variables
# nano .env (or use your favorite editor)

# 1. Create a project directory and navigate to it
New-Item -ItemType Directory -Path okta-ai-agent
Set-Location okta-ai-agent

# 2. Create required directories for data persistence
### Upload your own key and cert pem files to certs directory if you need them
New-Item -ItemType Directory -Path sqlite_db, logs, certs -Force

# 3. Download the docker-compose.yml file
Invoke-WebRequest -Uri "https://raw.githubusercontent.com/fctr-id/okta-ai-agent/main/docker-compose.yml" -OutFile "docker-compose.yml"

# 4. Download and modify the .env file with your configuration
Invoke-WebRequest -Uri "https://raw.githubusercontent.com/fctr-id/okta-ai-agent/main/.env.sample" -OutFile ".env.sample"
Rename-Item -Path ".env.sample" -NewName ".env"

# ⚠️ IMPORTANT: Edit the .env file with your settings! ⚠️
# The app will not work without properly configured environment variables
# notepad .env (or use your favorite editor)

For fastest sync times, set your API rate limit to 100% as shown above.

If you cannot use 100%, use this table to set the optimal OKTA_CONCURRENT_LIMIT in your .env file:

Check your sync logs for this warning: WARNING - Concurrent limit rate exceeded

If you see this error frequently:

• Reduce your OKTA_CONCURRENT_LIMIT by 10-20 % and re-try
• Cancel the sync, then try a lower value
• Contact [email protected] if issues persist

If you experience frequent API rate limit errors, contact [email protected]

After configuring your .env file with your specific settings, launch the application:

docker compose up -d

docker compose logs -f

• 🌐 Open your browser and go to: https://localhost:8001 to start using Tako 🌐

Tako now offers two powerful ways to interact with your Okta tenant:

• Database Mode - The original query engine for fast insights from synced data
• Realtime Mode - Direct API operations for up-to-the-second data access and complex workflows

• Direct API Integration - Tako now connects directly to Okta's API for real-time data access
• Intelligent Code Generation - Safely generates and executes Python code based on your natural language queries
• Multi-step Processing - Complex queries are broken down into manageable steps with intelligent results processing
• Command Line Interface - New CLI script allows advanced queries without context limitations

• Anthropic Support - Added Claude models as another AI provider option
• Custom HTTP Headers - Support for LLM proxies and security solutions
• Enhanced Sync Process - Better API-DB synchronization with cleaner logging
• Performance Optimizations - Faster response times and improved stability

IMPORTANT NOTICE: Realtime agent functionality requires modern reasoning LLMs released after December 2024 to work effectively. Older models may not properly reason through complex API calls and data relationships.

Tested and Compatible Models:

• OpenAI - o4-mini
• Google Vertex AI - Gemini Pro 2.5
• Anthropic - Claude 3.7 Sonnet (with thinking)
• DeepSeek v3

Using older or less capable models may result in degraded performance or incorrect API calls when in realtime mode.

• Your Token, Your Rules: You create and control the Okta API token, including restricting its network access and role permissions
• Least-Privilege Design: Operates with read-only permissions by default for safe exploration

• LLM Flexibility:
  • Use your enterprise-approved AI providers
  • Deploy Ollama locally for a completely air-gapped environment
  • Full control over model selection and data boundaries

• Local Storage: All Okta data is stored in SQLite DB - a file-based database that lives entirely on your PC/VM
• Zero Cloud Dependencies: Your organizational data never leaves your infrastructure
• No Okta Data to LLMs: Only user queries and system prompts are sent to AI providers

• Direct API Access: Queries Okta API directly with no local storage
• Limited Data Sampling: Small samples of query results are sent to AI providers for processing
• Sandboxed Execution: All code runs in a secure, isolated environment
• Data Minimization: Only data necessary to fulfill specific queries is processed

The following data model applies only when using Database Mode with a synced SQLite database:

Note: You can view the data saved to your SQLite DB using tools like DB Browser for SQLite.

• Tako is still in testing grounds - keep it out of production!
• Currently focusing on core user fields
• Large orgs might need a coffee break during sync

• Data lives safely in your local SQLite
• AI/LLM sees only what it needs to
• Proper token hygiene required

• The responses are stateless, i.e., every query is answered as is asked without any relevance to the previous queries / responses.
• Tested on Identity engine only
• AI responses vary by provider
• Complex questions might need simplifying
• One tenant at a time

• Tako's natural language queries for Okta data
• Multi-provider AI support
• Save details for users, apps, groups, factors, policies and their relationships

• Modern Web Interface
  • Intuitive dashboard experience
  • Responsive design for all devices
  • Accessibility compliance
• High-Performance API Backend
  • FastAPI implementation for enhanced throughput
  • Asynchronous request handling
  • Optimized database interactions
• Enterprise Security Implementation
  • HTTPS with proper certificate management
  • Secure authentication mechanisms
  • Data protection in transit
• Advanced Synchronization Interface
  • Visual synchronization monitoring
  • Progress tracking and analytics

• Live user summary
  • Profile, factors & activity snapshots
  • Risk indicators
  • Session management
• Event Log Analytics
  • Natural language log queries
  • Anomaly detection
  • Custom report generation

• Automated Changes with Approval Workflow
  • Group memberships
  • Policy modifications
  • App assignments
• Self-service Integration
  • Chatbot interface
  • Teams/Slack integration
  • Email notifications

• AI-driven Policy Management
• Automated User Lifecycle
• Intelligent Access Reviews
• Risk-based Authentication
• Complete Admin Automation

Before raising an issue with Tako, check:

1. 📝 .env configuration
2. 🔑 Okta API permissions
3. 🤖 AI provider setup
4. 📊 logs directory

Still having problems? Open an issue on GitHub, email [email protected], or contact Dan directly:

• Email: [email protected]
• Slack: [email protected]

Have an idea or suggestion? Open a feature request on GitHub!

Interested in contributing? We'd love to have you! Reach out to [email protected]

Thank you for all the interest shown by users who have reached out to us for support and feature requests. We greatly appreciate your feedback and enthusiasm for Tako. Your suggestions help us make the product better!

Check out License.md for the fine print.

🌟 © 2025 Fctr. All rights reserved. Meet Tako, made with ❤️ for the Okta community.