Skip to content

API Reference

This section provides comprehensive documentation for the ZeroTrustKerberosLink API, including the REST API, command-line interface (CLI), and software development kit (SDK).

REST API

ZeroTrustKerberosLink provides a RESTful API that allows you to integrate with your existing systems and automate workflows.

Authentication Endpoints

Endpoint Method Description Security Level
/auth/kerberos POST Authenticate using Kerberos credentials High
/auth/aws POST Obtain AWS temporary credentials High
/auth/refresh POST Refresh existing credentials High
/auth/revoke POST Revoke active credentials High

Configuration Endpoints

Endpoint Method Description Security Level
/config/roles GET List role mappings Medium
/config/roles POST Create role mapping High
/config/roles/{id} PUT Update role mapping High
/config/roles/{id} DELETE Delete role mapping High

Monitoring Endpoints

Endpoint Method Description Security Level
/health GET Check service health Low
/metrics GET Get service metrics Medium
/logs GET Get service logs High

Command-Line Interface (CLI)

ZeroTrustKerberosLink provides a powerful CLI for administration and automation.

Installation

pip install zerotrustkerberos-cli

Authentication Commands

# Authenticate and get AWS credentials
zerotrustkerberos auth aws --profile my-profile

# Refresh credentials
zerotrustkerberos auth refresh --profile my-profile

# Revoke credentials
zerotrustkerberos auth revoke --profile my-profile

Configuration Commands

# List role mappings
zerotrustkerberos config roles list

# Create role mapping
zerotrustkerberos config roles create --principal "user@EXAMPLE.COM" --role "arn:aws:iam::123456789012:role/UserRole"

# Update role mapping
zerotrustkerberos config roles update --id 123 --conditions '{"ip_ranges": ["10.0.0.0/8"]}'

# Delete role mapping
zerotrustkerberos config roles delete --id 123

Security Commands

# Run security tests
zerotrustkerberos security test --comprehensive

# Validate configuration security
zerotrustkerberos security validate-config --config /etc/zerotrustkerberos/config.yaml

# Generate security report
zerotrustkerberos security report --output security-report.pdf

Software Development Kit (SDK)

ZeroTrustKerberosLink provides SDKs for various programming languages to integrate with your applications.

Python SDK

from zerotrustkerberos import ZeroTrustKerberosClient

# Initialize client
client = ZeroTrustKerberosClient()

# Authenticate and get AWS credentials
credentials = client.authenticate()

# Use credentials with boto3
import boto3
session = boto3.Session(
    aws_access_key_id=credentials['AccessKeyId'],
    aws_secret_access_key=credentials['SecretAccessKey'],
    aws_session_token=credentials['SessionToken']
)

# Use the session
s3 = session.client('s3')
response = s3.list_buckets()

JavaScript SDK

import { ZeroTrustKerberosClient } from 'zerotrustkerberos';

// Initialize client
const client = new ZeroTrustKerberosClient();

// Authenticate and get AWS credentials
async function getCredentials() {
  try {
    const credentials = await client.authenticate();

    // Use credentials with AWS SDK
    const AWS = require('aws-sdk');
    AWS.config.credentials = new AWS.Credentials({
      accessKeyId: credentials.AccessKeyId,
      secretAccessKey: credentials.SecretAccessKey,
      sessionToken: credentials.SessionToken
    });

    // Use AWS services
    const s3 = new AWS.S3();
    const response = await s3.listBuckets().promise();
    console.log(response.Buckets);
  } catch (error) {
    console.error('Authentication failed:', error);
  }
}

getCredentials();

Security Considerations

When using the ZeroTrustKerberosLink API, follow these security best practices:

TLS Encryption

Always use HTTPS for all API communications. The API server will reject non-HTTPS connections.

Credential Handling

Never store AWS credentials in code or version control. Use secure credential storage appropriate for your environment.

Principle of Least Privilege

Configure role mappings with the minimum permissions necessary for your application to function.

Input Validation

Although the API performs comprehensive input validation, always validate inputs in your client applications as well.

Rate Limiting

The API implements rate limiting to protect against abuse and denial of service attacks:

  • Authentication endpoints: 30 requests per minute per IP address
  • Configuration endpoints: 60 requests per minute per IP address
  • Monitoring endpoints: 120 requests per minute per IP address

Exceeding these limits will result in HTTP 429 (Too Many Requests) responses.

Error Handling

The API returns standard HTTP status codes and JSON error responses:

{
  "error": {
    "code": "authentication_failed",
    "message": "Kerberos authentication failed",
    "details": "Invalid credentials or expired ticket"
  },
  "request_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}

Always include the request_id when reporting issues to support.