Configuration

BinoAuth requires configuration at multiple levels: environment variables, tenant settings, and application-specific configuration. This guide covers all configuration options.

Environment Variables

Required Variables

These environment variables must be set for BinoAuth to function:


# Database Configuration
DATABASE_URL=postgresql://username:password@localhost:5432/binoauth
REDIS_URL=redis://localhost:6379/0
 
# Security
SECRET_KEY=your-256-bit-secret-key-here
JWT_ALGORITHM=HS256
JWT_ACCESS_TOKEN_EXPIRE_MINUTES=15
JWT_REFRESH_TOKEN_EXPIRE_DAYS=30
 
# Server Configuration
API_HOST=0.0.0.0
API_PORT=8000
ADMIN_FRONTEND_URL=http://localhost:3000
AUTH_FRONTEND_URL=http://localhost:3100

Email Configuration

Configure SMTP for sending verification emails and magic links:


# SMTP Settings
SMTP_HOST=smtp.gmail.com
SMTP_PORT=587
SMTP_USERNAME=your-email@gmail.com
SMTP_PASSWORD=your-app-password
SMTP_FROM_EMAIL=noreply@yourdomain.com
SMTP_FROM_NAME="BinoAuth"
SMTP_USE_TLS=true

External OAuth Providers

Configure external authentication providers:


# Google OAuth
GOOGLE_CLIENT_ID=your-google-client-id.googleusercontent.com
GOOGLE_CLIENT_SECRET=your-google-client-secret
 
# GitHub OAuth
GITHUB_CLIENT_ID=your-github-client-id
GITHUB_CLIENT_SECRET=your-github-client-secret
 
# Custom Provider Example
CUSTOM_PROVIDER_CLIENT_ID=your-custom-provider-client-id
CUSTOM_PROVIDER_CLIENT_SECRET=your-custom-provider-client-secret
CUSTOM_PROVIDER_AUTHORIZE_URL=https://provider.com/oauth/authorize
CUSTOM_PROVIDER_TOKEN_URL=https://provider.com/oauth/token
CUSTOM_PROVIDER_USERINFO_URL=https://provider.com/api/user

Optional Configuration


# Rate Limiting
RATE_LIMIT_ENABLED=true
RATE_LIMIT_PER_MINUTE=60
 
# Session Configuration
SESSION_COOKIE_NAME=binoauth_session
SESSION_COOKIE_DOMAIN=.yourdomain.com
SESSION_COOKIE_SECURE=true
SESSION_COOKIE_HTTPONLY=true
SESSION_COOKIE_SAMESITE=lax
 
# Logging
LOG_LEVEL=INFO
LOG_FORMAT=json
 
# CORS
CORS_ALLOWED_ORIGINS=http://localhost:3000,http://localhost:3100
CORS_ALLOW_CREDENTIALS=true
 
# Phone Authentication (optional)
TWILIO_ACCOUNT_SID=your-twilio-account-sid
TWILIO_AUTH_TOKEN=your-twilio-auth-token
TWILIO_PHONE_NUMBER=+1234567890

Tenant Configuration

Each tenant in BinoAuth can be configured independently through the admin dashboard or API.

Creating a Tenant

Using the CLI:


python -m cli tenants create \
  --name "My Company" \
  --domain "mycompany.com" \
  --subdomain "mycompany" \
  --admin-email "admin@mycompany.com"

Using the API:


curl -X POST "http://localhost:8000/api/v1/tenants" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your-api-key" \
  -d '{
    "name": "My Company",
    "domain": "mycompany.com",
    "subdomain": "mycompany",
    "settings": {
      "allow_registration": true,
      "require_email_verification": true,
      "enable_magic_links": true,
      "enable_phone_auth": false
    }
  }'

Tenant Settings

Each tenant supports the following settings:


interface TenantSettings {
  // Registration
  allow_registration: boolean;
  require_email_verification: boolean;
  require_phone_verification: boolean;
  
  // Authentication Methods
  enable_magic_links: boolean;
  enable_phone_auth: boolean;
  enable_external_providers: boolean;
  
  // Security
  enable_mfa: boolean;
  require_mfa: boolean;
  password_min_length: number;
  password_require_special_chars: boolean;
  
  // Branding
  logo_url?: string;
  primary_color?: string;
  secondary_color?: string;
  custom_css?: string;
  
  // External Providers
  external_providers: ExternalProvider[];
}

Application Configuration

Creating an OAuth Application

Each tenant can have multiple OAuth applications (clients):


curl -X POST "http://localhost:8000/api/v1/applications" \
  -H "Content-Type: application/json" \
  -H "X-Tenant-ID: your-tenant-id" \
  -H "X-API-Key: your-api-key" \
  -d '{
    "name": "My Web App",
    "client_type": "confidential",
    "redirect_uris": [
      "http://localhost:3000/auth/callback",
      "https://myapp.com/auth/callback"
    ],
    "scopes": ["openid", "profile", "email"],
    "grant_types": ["authorization_code", "refresh_token"]
  }'

Application Types

Confidential Clients: For server-side applications that can securely store credentials

Web applications with server-side rendering
Backend APIs
Microservices

Public Clients: For applications that cannot securely store credentials

Single-page applications (SPAs)
Mobile applications
Desktop applications

Scopes Configuration

BinoAuth supports standard OpenID Connect scopes:

openid: Required for OpenID Connect
profile: Access to user profile information
email: Access to user email address
phone: Access to user phone number
offline_access: Request refresh tokens

SDK Configuration

React Configuration


// app/providers.tsx
import { AuthProvider } from '@binoauth/react';
 
export function Providers({ children }: { children: React.ReactNode }) {
  return (
    <AuthProvider
      clientId="your-client-id"
      issuer="http://localhost:8000"
      redirectUri="http://localhost:3000/auth/callback"
      scope="openid profile email"
    >
      {children}
    </AuthProvider>
  );
}

Next.js Configuration


// auth.config.ts
export const authConfig = {
  clientId: process.env.BINOAUTH_CLIENT_ID!,
  clientSecret: process.env.BINOAUTH_CLIENT_SECRET!,
  issuer: process.env.BINOAUTH_ISSUER!,
  redirectUri: process.env.BINOAUTH_REDIRECT_URI!,
  authSecret: process.env.AUTH_SECRET!,
  scope: 'openid profile email',
};

Node.js Configuration


// config/auth.ts
import { BinoAuthOAuth } from 'binoauth';
 
export const authClient = new BinoAuthOAuth({
  clientId: process.env.BINOAUTH_CLIENT_ID!,
  clientSecret: process.env.BINOAUTH_CLIENT_SECRET!,
  issuer: process.env.BINOAUTH_ISSUER!,
  redirectUri: process.env.BINOAUTH_REDIRECT_URI!,
});

Development vs Production

Development Configuration


# Development settings
DEBUG=true
LOG_LEVEL=DEBUG
CORS_ALLOWED_ORIGINS=*
SECURE_COOKIES=false
SESSION_COOKIE_SECURE=false

Production Configuration


# Production settings
DEBUG=false
LOG_LEVEL=INFO
CORS_ALLOWED_ORIGINS=https://myapp.com,https://admin.myapp.com
SECURE_COOKIES=true
SESSION_COOKIE_SECURE=true
SESSION_COOKIE_DOMAIN=.myapp.com
 
# Enhanced security
RATE_LIMIT_ENABLED=true
CSRF_PROTECTION=true
HSTS_ENABLED=true

Configuration Validation

BinoAuth validates configuration on startup. Common validation errors:

Missing Required Variables


ConfigError: DATABASE_URL is required

Invalid URLs


ConfigError: Invalid REDIS_URL format

Security Warnings


SecurityWarning: Using default SECRET_KEY in production

Environment-Specific Files

Development (.env.development)


DATABASE_URL=postgresql://binoauth:dev@localhost:5432/binoauth_dev
DEBUG=true
LOG_LEVEL=DEBUG

Testing (.env.test)


DATABASE_URL=postgresql://binoauth:test@localhost:5432/binoauth_test
REDIS_URL=redis://localhost:6379/1
EMAIL_BACKEND=console

Production (.env.production)


DATABASE_URL=postgresql://binoauth:prod@db.mycompany.com:5432/binoauth
REDIS_URL=redis://cache.mycompany.com:6379/0
DEBUG=false

Configuration Best Practices

Use environment-specific files: Keep separate configurations for development, testing, and production
Secure secrets: Never commit secrets to version control
Validate early: Check configuration on application startup
Document dependencies: Clearly document required environment variables
Use secure defaults: Configure secure defaults for production environments

What’s Next?

With BinoAuth configured, you’re ready to:

Quick Start - Build your first integration
Core Concepts - Understand BinoAuth fundamentals
Authentication Methods - Explore authentication options