Asgardeo iOS SDK

A modern, secure, and easy-to-use iOS SDK for OAuth 2.0 and OpenID Connect authentication with Asgardeo identity provider.

📖 Documentation

• Quick Start Guide - Get up and running in minutes
• Components Guide - Ready-to-use SwiftUI components
• Configuration Guide - Complete setup and configuration
• Architecture Guide - Comprehensive SDK architecture and design patterns
• Sample App - Working example implementation
• Demo Pack - 5-minute demo script and materials

✨ Features

• 🔐 OAuth 2.0 & OpenID Connect - Complete authentication flow support
• 🛡️ PKCE Security - Proof Key for Code Exchange for enhanced security
• 🔑 Secure Storage - Keychain integration for sensitive data
• 📊 Comprehensive Logging - Debug-friendly logging with automatic redaction
• ⚡ Modern Swift - Built with Swift 6.2 and modern iOS APIs
• 🧪 Comprehensive Testing - 100% test coverage with 43 test cases
• 📱 SwiftUI Ready - Perfect for modern iOS app development
• 🚀 Easy Integration - Simple setup with Swift Package Manager
• 📚 Well Documented - Complete API documentation and guides
• 🎨 Ready-to-Use Components - Pre-built SignInButton and OrganizationSwitcher components

🚀 Quick Start

Add the Asgardeo iOS SDK to your project using Swift Package Manager:

Option 1: HTTPS (Recommended for most users)

dependencies: [
    .package(url: "https://github.com/velotio-tech/asgardeo-ios-sdk.git", from: "1.0.0")
]

Option 2: SSH (Use if HTTPS doesn't work)

dependencies: [
    .package(url: "[email protected]:velotio-tech/asgardeo-ios-sdk.git", from: "1.0.0")
]

Note: If you encounter authentication issues with HTTPS, try using the SSH URL instead. This is common in corporate environments or when GitHub authentication is restricted.

Ready to get started? Check out our Quick Start Guide for step-by-step instructions on using ready-to-use components and programmatic authentication.

🏗️ Architecture

The SDK is built with a clean, layered architecture using modern Swift patterns and design principles. For a comprehensive overview, see the Architecture Guide.

High-Level Overview

flowchart LR
  classDef box fill:#F7FBFF,stroke:#1565C0,stroke-width:2,color:#0B1F2A,rx:10,ry:10
  classDef support fill:#E8F5E8,stroke:#2E7D32,stroke-width:1.5,color:#0B1F2A,rx:10,ry:10

  A["📱 iOS Application<br/>• Integrates SDK APIs<br/>• Drives sign-in/out<br/>• Observes session"]:::box
  S["🚀 Asgardeo iOS SDK<br/>• OIDC + PKCE<br/>• Token & session mgmt<br/>• Organization switching"]:::box
  C["☁️ Asgardeo Identity Platform<br/>• OAuth/OIDC endpoints<br/>• Org & user APIs"]:::box
  P["🍎 iOS Services<br/>ASWebAuthenticationSession<br/>Keychain / Secure Enclave<br/>URLSession (HTTPS)"]:::support

  A -- "Calls public SDK APIs" --> S
  S -- "OAuth/OIDC flows (Authorize, Token, UserInfo, Orgs)" --> C
  S -. "Uses system auth, secure storage,<br/>network transport" .-> P

Loading

Directory Structure

AsgardeoAuth
├── AsgardeoClient     # Main authentication client (singleton)
├── AsgardeoConfig     # Configuration management
├── AsgardeoSession    # Session management
├── Services/          # Core business logic
│   ├── AuthenticationService  # OAuth 2.0/OIDC flows
│   ├── OrganizationService    # Organization management
│   └── SessionService         # Session persistence
├── Network/           # Network layer
│   ├── HTTPClient     # HTTP communication
│   └── Endpoints/     # Type-safe API endpoints
├── Utilities/         # Helper utilities
│   └── OIDCUtilities  # OIDC discovery and token exchange
├── SecureStore/       # Secure storage abstraction
├── Logging/           # Centralized logging system
└── Errors/            # Centralized error handling

Key Design Patterns

• Singleton Pattern: AsgardeoClient uses singleton pattern for consistent state management
• Service Layer: Business logic separated into focused service classes
• Endpoint Protocol: Type-safe, protocol-oriented approach to API endpoints
• Dependency Injection: Services receive dependencies through constructor injection
• Async/Await: Modern Swift concurrency throughout the codebase
• Sendable Compliance: All public types are thread-safe and Sendable

Architecture Layers

1. Public API Layer: Single entry point (AsgardeoClient)
2. Service Layer: Business logic (AuthenticationService, OrganizationService, SessionService)
3. Infrastructure Layer: Network, storage, logging, and utilities
4. Data Layer: Models and configurations
5. External Systems: Asgardeo APIs and iOS platform services

For detailed architecture diagrams, component relationships, and data flow patterns, see the Architecture Guide.

🔧 Requirements

• iOS: 13.0+
• Xcode: 16.0+
• Swift: 6.2+
• macOS: 10.15+ (for development)

📦 What's Included

Core Components

• Authentication Flow - Complete OAuth 2.0/OpenID Connect implementation
• Organization Management - Multi-organization support with switching
• Session Management - Secure token storage and validation
• PKCE Security - Enhanced security with Proof Key for Code Exchange
• Keychain Integration - Secure storage for sensitive data
• Token Refresh - Automatic token refresh with retry logic
• Comprehensive Logging - Debug-friendly logging with automatic redaction

Ready-to-Use SwiftUI Components

• SignInButton - Pre-built sign-in button with multiple styles and customization options
• OrganizationSwitcher - Dropdown component for organization switching
• Multiple Initialization Patterns - Minimal, callback-based, and configuration-based setup
• Built-in Error Handling - Automatic error display and management
• Customizable Styling - Colors, sizes, and visual appearance
• Loading States - Visual feedback during operations

Sample App

A complete SwiftUI sample app demonstrating:

• Ready-to-use components in action
• Multiple SignInButton and OrganizationSwitcher variations
• Modern authentication UI with MVVM architecture
• Organization switching functionality
• Session management and persistence
• Comprehensive error handling
• Best practices and patterns

Testing

• 43 Test Cases - Comprehensive test coverage
• Unit Tests - All components thoroughly tested
• Integration Tests - End-to-end functionality validation
• CI/CD - Automated testing with GitHub Actions

🛠️ Development

Building from Source

# Clone the repository
git clone https://github.com/velotio-tech/asgardeo-ios-sdk.git
cd asgardeo-ios-sdk

# Build the package
swift build

# Run tests
swift test

# Build and run sample app
cd Examples/SampleApp
xcodebuild -project SampleApp.xcodeproj -scheme SampleApp -destination 'platform=iOS Simulator,name=iPhone 17'

Running the Sample App

1. Open Examples/SampleApp/SampleApp.xcodeproj
2. Build and run the project
3. Explore the authentication features and organization switching

🔒 Security

The SDK implements industry-standard security practices:

• PKCE (RFC 7636) - Enhanced security for public clients
• Secure Storage - Keychain integration for sensitive data
• Token Validation - Automatic expiry checking and refresh
• HTTPS Only - All network communication over secure channels
• No Hardcoded Secrets - All sensitive data properly managed
• Automatic Redaction - Sensitive data automatically redacted from logs

📊 Project Status

✅ Production Ready - Fully Functional

• ✅ Core SDK - Complete and functional
• ✅ Authentication Flow - Full OAuth 2.0/OpenID Connect support
• ✅ Organization Management - Multi-organization support with switching
• ✅ Token Refresh - Automatic token refresh with retry logic
• ✅ Security Features - PKCE, secure storage, token management
• ✅ Testing - Comprehensive test suite with 43 test cases
• ✅ Documentation - Complete guides and API documentation
• ✅ Sample App - Working SwiftUI example with MVVM architecture
• ✅ CI/CD - Automated testing and deployment
• ✅ Modern Swift - Built with Swift 6.2 and async/await