Authentication & Authorization ‐ Oauth 2 and API tokens - fctr-id/okta-ai-agent GitHub Wiki

Authentication Setup Guide

Tako v1.25 and above supports two types of token mechanisms for secure authentication with Okta.

Table of Contents

Overview

Authentication Methods:

  1. 🔐 OAuth 2.0 Tokens - Modern OAuth 2.0 flow with enhanced security (Recommended)
  2. 🔑 API Tokens - Simple token-based authentication

💡 Recommendation: Use OAuth 2.0 for production environments as it provides better security, audit trails, and granular permissions.

OAuth 2.0 Setup (Recommended)

OAuth 2.0 provides enhanced security with private key authentication and granular scope-based permissions.

Creating OAuth 2.0 Application

Step 1: Create API Services Application

  1. Navigate to Admin Console → Applications → Create App Integration
  2. Select API Services

Step 2: Configure Application Name

  1. Give it a descriptive name like "Tako API OAuth2"
  2. Click Save to create the application

Private Key Configuration

Step 3: Configure Client Credentials

  1. On the General Tab, click EDIT button in the Client Credentials section
  2. Select Public key / Private Key
  3. Select Save keys in Okta
  4. Click on Add Key button

Step 4: Generate Private Key

  1. Click on Generate new key
  2. In the bottom section, select PEM format
  3. Copy the generated private key to clipboard

⚠️ Important: This private key value goes into the OKTA_OAUTH2_PRIVATE_KEY_PEM variable in your .env file

API Scopes Configuration

Step 5: Grant API Scopes

  1. Click on the Okta API Scopes tab
  2. Click Grant on all scopes ending with ".read"
  3. For enhanced security, grant only specific scopes you need

📋 Best Practice: By default, select all scopes that end with ".read" for comprehensive read-only access

Admin Roles Assignment

Step 6: Assign Administrative Role

  1. Click on Admin Roles tab
  2. Assign the Read-only Administrator role to start
  3. Add additional custom roles as needed

Rate Limits Configuration

Step 7: Configure Application Rate Limits

  1. Click on Application Rate Limits tab
  2. Set appropriate rate limits based on your usage requirements

⚠️ Critical: Rate limits determine the OKTA_CONCURRENT_VALUE in your configuration. Refer to the optimal API settings guide for concurrent limit values.

API Token Setup

Creating API Tokens

Step 1: Access Okta Admin Console

  1. Login to the Okta admin console with a read-only administrator account
  2. Navigate to Security → API → Tokens
  3. Click Create Token

Step 2: Configure Token Security

  1. Give the token a descriptive name
  2. ⚠️ HIGHLY RECOMMENDED: Restrict the token to a specific IP address or network zone for enhanced security

Security Recommendations

  • ✅ Always use IP restrictions when possible
  • ✅ Use network zones to limit token access
  • ✅ Follow the principle of least privilege
  • ✅ Regularly rotate API tokens
  • ❌ Never embed tokens in client-side code

Custom Roles Configuration

For scenarios requiring additional permissions beyond the read-only administrator role (e.g., listing Okta administrators), you can create custom roles.

Step 1: Create Custom Role

  1. Navigate to Admin Console → Security → Administrators → Roles
  2. Click Create New Role

Step 2: Configure Role Permissions

  1. Select the necessary permissions based on your requirements
  2. Click Save Role to finalize the configuration

Step 3: Create Resource Set

  1. Create a resource set for Identity and Access Management resources
  2. Define the scope of resources this role can access

Step 4: Assign Role and Resource Set

Finally, assign both the custom role and resource set to the user or service account that will be used to create the API token.

API Token rate Limits:

Set the appropriate rate limits. This is IMPORTANT because this decides the OKTA_CONCURRENT_VALUE limit in the configuration Refer to this table to see how the AP rate limit affects the CONCURRENT_LIMIT value: https://github.com/fctr-id/okta-ai-agent?tab=readme-ov-file#-optimal-api-settings-for-maximum-sync-speed-

Best Practices

Security Guidelines

  • 🔐 Use OAuth 2.0 when possible, for enhanced security
  • 🛡️ Implement IP restrictions for all API tokens
  • 🔄 Rotate tokens regularly (recommended: every 90 days)
  • 📊 Monitor token usage through audit logs
  • 🚫 Revoke unused tokens immediately

Administrative Considerations

  • 👥 Use service accounts for automated processes
  • 📋 Maintain an inventory of all active tokens
  • 🔍 Regular access reviews for custom roles
  • 📝 Document all custom role configurations

Troubleshooting

  • ❓ Token not working? Check IP restrictions and network zones
  • ❓ Permission denied? Verify custom role assignments
  • ❓ Audit failures? Confirm resource set configurations

Related Documentation

Last updated: August 31, 2025