Core Concepts

Understanding BinoAuth’s core concepts will help you make the most of its features and integrate it effectively into your applications.

Multi-Tenancy

BinoAuth is built as a multi-tenant platform, meaning it can serve multiple organizations (tenants) from a single deployment.

What is a Tenant?

A tenant represents an organization or company using BinoAuth. Each tenant has:

Isolated user base: Users belong to specific tenants
Separate configuration: Each tenant can have different settings
Custom branding: Logos, colors, and styling per tenant
Independent applications: OAuth clients scoped to tenants

Tenant Isolation

BinoAuth ensures complete data isolation between tenants:


Tenant A                    Tenant B
├── Users                   ├── Users
├── Applications            ├── Applications
├── Sessions                ├── Sessions
└── Configuration           └── Configuration

Use Cases

SaaS Platforms: Each customer gets their own tenant
Enterprise: Different departments or subsidiaries
Agencies: Separate clients with isolated authentication

Authentication vs Authorization

BinoAuth focuses on authentication (who you are) rather than authorization (what you can do).

Authentication

Identity verification: Confirming user identity
Session management: Maintaining login state
Token issuance: Providing access tokens

Authorization

Permission checking: What resources users can access
Role-based access: Different user roles and permissions
Resource protection: Securing specific endpoints or features

BinoAuth provides the foundation for authorization through:

User information: Profile data and custom claims
Token scopes: Limiting access to specific resources
Custom claims: Adding role/permission information to tokens

OAuth 2.0 and OpenID Connect

BinoAuth implements industry-standard protocols for secure authentication.

OAuth 2.0

OAuth 2.0 is an authorization framework that allows applications to obtain limited access to user accounts.

Key Components:

Client: Your application
Authorization Server: BinoAuth
Resource Server: Your API or BinoAuth’s user info endpoint
Resource Owner: The user

Flow Example:


1. User clicks "Login" in your app
2. App redirects to BinoAuth
3. User authenticates with BinoAuth
4. BinoAuth redirects back with authorization code
5. App exchanges code for access token
6. App uses token to access user information

OpenID Connect

OpenID Connect extends OAuth 2.0 to provide authentication on top of authorization.

Additional Features:

ID Token: JWT containing user identity information
UserInfo Endpoint: Standardized way to get user profile
Standard Claims: Predefined user attributes (name, email, etc.)

Grant Types

BinoAuth supports multiple OAuth 2.0 grant types:

Authorization Code Flow

Best for: Web applications, mobile apps
Security: Highest security with PKCE
Use case: Interactive user login

Client Credentials Flow

Best for: Server-to-server communication
Security: Confidential clients only
Use case: API access without user interaction

Device Authorization Flow

Best for: IoT devices, TV apps, CLI tools
Security: Secure for devices without browsers
Use case: Limited input device authentication

Client Types

BinoAuth supports two types of OAuth clients:

Confidential Clients

Can securely store credentials (client secret):

Web applications with server-side rendering
Backend APIs and microservices
Server-side applications


// Example: Server-side Next.js app
const client = {
  client_id: "web-app-123",
  client_secret: "secret-key-456", // Stored securely on server
  client_type: "confidential"
};

Public Clients

Cannot securely store credentials:

Single-page applications (SPAs)
Mobile applications
Desktop applications


// Example: React SPA
const client = {
  client_id: "spa-app-789",
  client_secret: null, // No secret for public clients
  client_type: "public"
};

Token Types

BinoAuth issues different types of tokens for different purposes:

Access Tokens

Purpose: Access protected resources
Format: JWT or opaque tokens
Lifetime: Short-lived (15 minutes by default)
Contains: User ID, scopes, expiration

Refresh Tokens

Purpose: Obtain new access tokens
Format: Opaque tokens
Lifetime: Long-lived (30 days by default)
Security: Stored securely, can be revoked

ID Tokens

Purpose: User identity information
Format: JWT
Lifetime: Short-lived
Contains: User profile, authentication time

Token Lifecycle


1. User logs in
2. BinoAuth issues access + refresh + ID tokens
3. App uses access token for API calls
4. Access token expires
5. App uses refresh token to get new access token
6. Process repeats until refresh token expires

Scopes and Claims

Scopes

Scopes define what information or actions a token grants access to:

openid: Required for OpenID Connect
profile: Basic profile information (name, picture)
email: User’s email address
phone: User’s phone number
offline_access: Request refresh tokens

Custom Scopes:


{
  "scopes": [
    "admin",      // Administrative access
    "billing",    // Billing information
    "analytics"   // Analytics data
  ]
}

Claims

Claims are pieces of information about the user included in tokens:

Standard Claims:

sub: User ID (subject)
name: Full name
email: Email address
email_verified: Email verification status
picture: Profile picture URL

Custom Claims:


{
  "sub": "user-123",
  "name": "John Doe",
  "email": "john@example.com",
  "role": "admin",
  "tenant_id": "tenant-456",
  "permissions": ["read", "write", "delete"]
}

Sessions and State Management

Session Types

BinoAuth supports multiple session strategies:

Storage: HTTP cookies
Security: HttpOnly, Secure, SameSite
Use case: Traditional web applications

Token-based Sessions

Storage: Local storage, session storage
Security: JWT tokens with expiration
Use case: SPAs, mobile apps

Server-side Sessions

Storage: Redis, database
Security: Session IDs in cookies
Use case: High-security applications

State Management

BinoAuth manages authentication state across your application:


interface AuthState {
  user: User | null;
  tokens: Tokens | null;
  loading: boolean;
  error: Error | null;
}

Security Features

PKCE (Proof Key for Code Exchange)

Purpose: Prevents code interception attacks
Required for: Public clients
How it works: Client generates code verifier/challenge pair

Rate Limiting

Purpose: Prevent brute force attacks
Scope: Per IP, per user, per endpoint
Configuration: Customizable limits and windows

Multi-Factor Authentication (MFA)

TOTP: Time-based one-time passwords
SMS: Phone-based verification
Email: Email-based verification

Cross-Site Request Forgery (CSRF) Protection

State Parameter: Prevents CSRF attacks
SameSite Cookies: Additional protection
Origin Validation: Validates request origins

Architecture Patterns

Frontend Architecture


Frontend App → BinoAuth SDK → BinoAuth API
     ↓
User Interface

Backend Architecture


Client App → API Gateway → Your API → BinoAuth
                               ↓
                         Token Validation

Full-Stack Architecture


Frontend → Your Backend → BinoAuth API
    ↓           ↓
  User UI   Token Validation

Data Models

User Model


interface User {
  id: string;
  email: string;
  email_verified: boolean;
  name?: string;
  picture?: string;
  phone?: string;
  phone_verified: boolean;
  created_at: Date;
  updated_at: Date;
  last_login?: Date;
  mfa_enabled: boolean;
}

Application Model


interface Application {
  id: string;
  name: string;
  client_id: string;
  client_secret?: string;
  client_type: 'confidential' | 'public';
  redirect_uris: string[];
  scopes: string[];
  grant_types: string[];
  tenant_id: string;
}

Token Model


interface Tokens {
  access_token: string;
  refresh_token?: string;
  id_token?: string;
  token_type: 'Bearer';
  expires_in: number;
  scope: string;
}

Best Practices

Security

Use HTTPS in production
Validate tokens on every request
Store secrets securely (environment variables)
Implement proper CORS policies
Use short-lived tokens with refresh

Performance

Cache tokens appropriately
Implement token refresh logic
Use efficient storage strategies
Minimize API calls with batching

User Experience

Handle loading states gracefully
Provide clear error messages
Implement auto-refresh for seamless experience
Support multiple auth methods

Common Patterns

Single-Page Applications (SPAs)

Use public clients with PKCE
Store tokens in memory or secure storage
Implement token refresh automatically

Server-Side Rendered (SSR) Apps

Use confidential clients
Store tokens in secure cookies
Validate tokens on server-side

Mobile Applications

Use public clients with PKCE
Store tokens in secure device storage
Implement biometric authentication

APIs and Microservices

Validate tokens on each request
Use client credentials for service-to-service
Implement proper error handling

What’s Next?

Now that you understand BinoAuth’s core concepts:

Explore Authentication Methods - Learn about different ways users can authenticate
SDK Documentation - Dive deep into SDK features
API Reference - Understand the underlying APIs
Security Guide - Implement security best practices