​

Authentication Overview

​

Why Authentication?

• Security - Protect your agents from unauthorized access
• Audit Trail - Track which service or user performed which action
• Access Control - Fine-grained permissions for different operations
• Multi-tenancy - Isolate different clients or organizations
• Compliance - Meet security and regulatory requirements

​

Supported Authentication Methods

​

Auth0 (Current)

• ✅ Machine-to-Machine (M2M) - Service-to-service authentication
• ✅ JWT Validation - Signature verification using JWKS
• ✅ Permission-Based Access - Fine-grained operation control
• ✅ Token Caching - Automatic refresh and caching
• ✅ Public Endpoints - Agent discovery remains accessible

​

Coming Soon

• 🔜 GitHub OAuth - Authenticate with GitHub accounts
• 🔜 AWS Cognito - Enterprise identity management
• 🔜 Google OAuth - Sign in with Google
• 🔜 Azure AD (Microsoft Entra) - Enterprise SSO

​

How It Works

​

Authentication Process

1. Client requests token from Auth0 with credentials
2. Auth0 issues JWT with permissions and metadata
3. Client includes token in Authorization header
4. Agent validates token using Auth0’s public keys
5. Agent checks permissions against required scopes
6. Request processed if authorized

​

Configuration

​

Enable Authentication

{
  "author": "[email protected]",
  "name": "Secure Agent",
  "auth": {
    "enabled": true,
    "domain": "your-tenant.auth0.com",
    "audience": "https://api.bindu.ai"
  }
}

​

Configuration Options

​

Public vs Protected Endpoints

​

Public Endpoints (No Authentication)

• /.well-known/agent.json - Agent card (discovery)
• /did/resolve - DID resolution
• /agent/info - Agent information
• /health - Health check

​

Protected Endpoints (Authentication Required)

• POST / - All JSON-RPC methods:
  • message/send - Send messages to agent
  • tasks/get - Get task details
  • tasks/cancel - Cancel running tasks
  • tasks/list - List all tasks
  • contexts/list - List conversation contexts
  • tasks/feedback - Provide task feedback

​

Permission-Based Access Control

​

Enable Permissions

{
  "auth": {
    "enabled": true,
    "require_permissions": true,
    "permissions": {
      "message/send": ["agent:write"],
      "tasks/get": ["agent:read"],
      "tasks/cancel": ["agent:admin"],
      "tasks/list": ["agent:read"],
      "contexts/list": ["agent:read"],
      "tasks/feedback": ["agent:write"]
    }
  }
}

​

Permission Scopes

• agent:read - Read tasks, contexts, agent info
• agent:write - Send messages, create tasks, provide feedback
• agent:admin - Cancel tasks, clear contexts, admin operations

​

How It Works

1. Define permissions in Auth0 API settings
2. Grant permissions to M2M applications
3. Auth0 includes permissions in JWT token
4. Agent validates token has required permissions
5. Request allowed/denied based on permissions

​

Error Codes

​

Error Response Example

{
  "jsonrpc": "2.0",
  "error": {
    "code": -32001,
    "message": "Authentication required",
    "data": {
      "details": "No Authorization header provided"
    }
  },
  "id": "1"
}

​

Security Best Practices

​

Recommended Practices

1. ✅ Store credentials securely - Use environment variables
2. ✅ Use HTTPS in production - Encrypt all traffic
3. ✅ Rotate secrets regularly - Update client secrets periodically
4. ✅ Grant minimum permissions - Principle of least privilege
5. ✅ Monitor Auth0 logs - Track suspicious activity
6. ✅ Cache tokens - Reduce Auth0 API calls
7. ✅ Separate environments - Use different tenants for dev/staging/prod
8. ✅ Validate audience - Ensure tokens are for your API
9. ✅ Check token expiration - Implement automatic refresh
10. ✅ Use short-lived tokens - Reduce exposure window

​

Quick Start

​

Client Examples

​

Python

from bindu.client import BinduM2MClient

client = BinduM2MClient(
    auth0_domain="your-tenant.auth0.com",
    client_id="your_client_id",
    client_secret="your_client_secret",
    audience="https://api.bindu.ai",
    agent_url="http://localhost:3773"
)

# Automatically handles token management
result = client.send_message("Hello, secure agent!")

​

JavaScript/TypeScript

import { BinduM2MClient } from '@bindu/client';

const client = new BinduM2MClient({
  auth0Domain: 'your-tenant.auth0.com',
  clientId: process.env.AUTH0_CLIENT_ID,
  clientSecret: process.env.AUTH0_CLIENT_SECRET,
  audience: 'https://api.bindu.ai',
  agentUrl: 'http://localhost:3773'
});

// Automatically handles token management
const result = await client.sendMessage('Hello, secure agent!');

​

Troubleshooting

​

Next Steps

​

Resources

• Auth0 Documentation - Official Auth0 guides
• JWT.io - Debug and decode JWT tokens
• OAuth 2.0 Spec - OAuth 2.0 specification
• GitHub Examples - Client implementation examples