Register AI Client

Learn how to register and configure AI clients with Authsec for secure authentication and authorization.

Overview

AI clients in Authsec represent applications, services, or AI agents that need to authenticate users or access protected resources. Each client has its own configuration, credentials, and permissions.

Client Types

1. AI Agent Clients

For autonomous AI agents that operate on behalf of users or systems.

Use Cases:

• Conversational AI assistants
• Automated decision-making systems
• Data processing agents
• Task automation bots

2. MCP Server Clients

For Model Context Protocol servers that provide context and capabilities to AI systems.

Use Cases:

• Knowledge base servers
• API gateway services
• Tool integration servers
• Context management systems

3. Web Application Clients

For web-based AI applications with user interfaces.

Use Cases:

• AI-powered dashboards
• Interactive AI tools
• Collaborative AI platforms
• AI model interfaces

4. Mobile Application Clients

For mobile apps that incorporate AI capabilities.

Use Cases:

• AI camera apps
• Voice assistants
• Mobile AI tools
• Augmented reality apps

Registering a Client

Using the Authsec Dashboard

1. Navigate to Applications: Log into your Authsec dashboard and go to the Applications section
2. Create New Application: Click "Create Application"
3. Choose Application Type: Select the appropriate client type for your AI application
4. Configure Basic Settings: Fill in the required information

Basic Configuration Fields

{
  "name": "My AI Assistant",
  "description": "An intelligent conversational AI agent",
  "type": "ai-agent",
  "logo": "https://example.com/logo.png",
  "website": "https://example.com"
}

Using the Management API

For programmatic client registration:

import { AuthsecManagement } from '@authsec/management-sdk';

const management = new AuthsecManagement({
  domain: 'your-domain.authsec.com',
  clientId: 'management-client-id',
  clientSecret: 'management-client-secret'
});

// Register new AI client
const client = await management.clients.create({
  name: 'My AI Assistant',
  description: 'An intelligent conversational AI agent',
  app_type: 'ai_agent',
  grant_types: ['client_credentials', 'authorization_code'],
  token_endpoint_auth_method: 'client_secret_post',
  callbacks: ['https://myapp.com/callback'],
  web_origins: ['https://myapp.com'],
  allowed_scopes: ['openid', 'profile', 'ai:access']
});

console.log('Client ID:', client.client_id);
console.log('Client Secret:', client.client_secret);

Client Configuration

Authentication Settings

Grant Types

Choose appropriate OAuth 2.0 grant types for your client:

• Client Credentials: For service-to-service authentication
• Authorization Code: For applications with user interaction
• Device Code: For devices with limited input capabilities
• Refresh Token: For token refresh capabilities

Token Configuration

const tokenConfig = {
  access_token_lifetime: 3600, // 1 hour
  refresh_token_lifetime: 2592000, // 30 days
  id_token_lifetime: 3600, // 1 hour
  rotate_refresh_token: true
};

AI-Specific Settings

AI Agent Configuration

const aiAgentConfig = {
  agent_type: 'conversational', // conversational, task, analytical
  capabilities: [
    'text_generation',
    'data_analysis', 
    'api_integration'
  ],
  context_retention: '24h',
  max_context_size: 32768,
  rate_limits: {
    requests_per_minute: 60,
    tokens_per_day: 1000000
  }
};

MCP Server Configuration

const mcpConfig = {
  protocol_version: '1.0',
  supported_features: [
    'tools',
    'resources', 
    'prompts'
  ],
  endpoints: {
    tools: 'https://mcp-server.com/tools',
    resources: 'https://mcp-server.com/resources'
  },
  security: {
    require_auth: true,
    allowed_origins: ['https://trusted-client.com']
  }
};

Security Configuration

Allowed URLs

Configure trusted URLs for your client:

const securityConfig = {
  // Callback URLs for authentication redirects
  callbacks: [
    'https://myapp.com/auth/callback',
    'https://myapp.com/silent-auth'
  ],
  
  // Allowed origins for CORS
  web_origins: [
    'https://myapp.com',
    'https://admin.myapp.com'
  ],
  
  // Logout URLs
  logout_urls: [
    'https://myapp.com/logout'
  ]
};

Advanced Security Options

const advancedSecurity = {
  // Require PKCE for authorization code flow
  require_proof_key_for_code_exchange: true,
  
  // JWT configuration for private_key_jwt auth
  jwks_uri: 'https://myapp.com/.well-known/jwks.json',
  
  // Token endpoint authentication method
  token_endpoint_auth_method: 'client_secret_post',
  
  // Require pushed authorization requests
  require_pushed_authorization_requests: false
};

Client Credentials

Storing Credentials Securely

Environment Variables (Recommended):

# .env file
AUTHSEC_DOMAIN=your-domain.authsec.com
AUTHSEC_CLIENT_ID=abc123def456
AUTHSEC_CLIENT_SECRET=super-secret-key-xyz789

Configuration File:

// config/authsec.js
module.exports = {
  domain: process.env.AUTHSEC_DOMAIN,
  clientId: process.env.AUTHSEC_CLIENT_ID,
  clientSecret: process.env.AUTHSEC_CLIENT_SECRET,
  audience: 'https://api.myapp.com',
  scope: 'openid profile ai:access'
};

Credential Rotation

Regular credential rotation enhances security:

// Rotate client credentials
const newCredentials = await management.clients.rotateSecret({
  client_id: 'your-client-id'
});

// Update your application configuration
await updateApplicationConfig({
  clientSecret: newCredentials.client_secret
});

Permissions and Scopes

Defining Client Scopes

Scopes control what your AI client can access:

const scopes = [
  'openid',           // Basic authentication
  'profile',          // User profile access  
  'ai:generate',      // AI generation capabilities
  'ai:analyze',       // AI analysis capabilities
  'mcp:tools',        // MCP tool access
  'mcp:resources',    // MCP resource access
  'admin:users',      // User management (if needed)
  'logs:read'         // Audit log access
];

Custom Scopes for AI Applications

Create application-specific scopes:

// Define custom AI scopes
const customScopes = {
  'ai:conversations': 'Access to conversation history',
  'ai:models:gpt4': 'Access to GPT-4 model',
  'ai:data:training': 'Access to training data',
  'mcp:context:read': 'Read MCP context information',
  'mcp:context:write': 'Modify MCP context information'
};

// Register custom scopes
await management.scopes.create(customScopes);

Testing Your Client

Basic Authentication Test

import { AuthsecClient } from '@authsec/sdk';

// Initialize client
const authsec = new AuthsecClient({
  domain: 'your-domain.authsec.com',
  clientId: 'your-client-id',
  clientSecret: 'your-client-secret'
});

// Test client credentials flow
try {
  const token = await authsec.getClientCredentialsToken({
    audience: 'https://api.myapp.com',
    scope: 'ai:access'
  });
  
  console.log('Authentication successful!');
  console.log('Access Token:', token.access_token);
} catch (error) {
  console.error('Authentication failed:', error.message);
}

Authorization Code Flow Test

// Redirect user to authorization URL
const authUrl = authsec.buildAuthorizeUrl({
  response_type: 'code',
  scope: 'openid profile ai:access',
  redirect_uri: 'https://myapp.com/callback'
});

// Handle callback and exchange code for tokens
app.get('/callback', async (req, res) => {
  try {
    const tokens = await authsec.exchangeCodeForTokens({
      code: req.query.code,
      redirect_uri: 'https://myapp.com/callback'
    });
    
    // Store tokens and redirect user
    res.redirect('/dashboard');
  } catch (error) {
    res.status(400).send('Authentication failed');
  }
});

Best Practices

Security Best Practices

1. Secure Credential Storage: Never hardcode secrets in your source code
2. Principle of Least Privilege: Only request necessary scopes and permissions
3. Regular Rotation: Rotate client credentials regularly
4. Environment Separation: Use different clients for development, staging, and production
5. Monitor Usage: Track client usage and watch for anomalies

Development Best Practices

1. Descriptive Naming: Use clear, descriptive names for clients
2. Documentation: Document each client's purpose and configuration
3. Version Control: Track client configuration changes
4. Testing: Thoroughly test authentication flows in all environments
5. Error Handling: Implement robust error handling for authentication failures

AI-Specific Best Practices

1. Rate Limiting: Configure appropriate rate limits for AI operations
2. Context Management: Properly manage conversation context and history
3. Model Access: Control access to specific AI models and capabilities
4. Data Privacy: Ensure AI clients comply with data privacy requirements
5. Audit Logging: Enable comprehensive logging for AI client activities