3.0.0¶

Release Date: December 17, 2025

🎯 Overview¶

Forge 3.0 is a major release that brings significant platform upgrades and architectural improvements. This release focuses on modernizing the platform with .NET 10, enhanced authentication with Entra ID support, and improved developer tooling.

Key Highlights¶

🚀 Platform Upgrade: .NET 10.0 and Aspire 13.1 support
🔐 Dual Authentication: Entra ID (corporate) + Okta (external) authentication
🛠️ CLI Rewrite: Unified services architecture with MCP integration
📦 Terraform Restructuring: Snake_case variables and module version 3.0.0
📚 Documentation Overhaul: Restructured docs with new design system

✨ New Features¶

CLI Tools¶

CLI Rewrite with Unified Services Architecture 🚀¶

Package: SAIF.Platform.CLI

Complete rewrite of the SAIF CLI with a modern unified services architecture and Model Context Protocol (MCP) integration for enhanced developer workflows.

Key Features:

✅ MCP Server Integration - Built-in MCP server for Forge documentation access
✅ Dynamic Command Discovery - ForgeCliTools for automatic CLI command registration
✅ Token Generation - New saif token command for generating access tokens
✅ HTML Content Extraction - ReverseMarkdown integration for documentation processing

New Commands:

saif token - Generate access tokens for API testing
saif update - Update CLI, templates, and development tools (including Aspire CLI)
saif mcp start - Start MCP server for AI assistant integration
saif mcp init - Initialize MCP configuration

Benefits:

🚀 Simplified local development workflow
🔄 Automatic mock configuration updates
🎯 Better integration with VS Code and GitHub Copilot

MCP Server for Forge Documentation 📖¶

Package: SAIF.Platform.CLI

Implement MCP server that provides Forge documentation directly to AI assistants and development tools.

Key Features:

✅ Markdown Download - Automatic download and caching of documentation
✅ Documentation Hooks - Improved content processing and navigation

Benefits:

🚀 AI assistants can access Forge documentation in context
🔄 Always up-to-date documentation access

NuGet Packages¶

.NET 10.0 and Aspire 13.1 Upgrade ⬆️¶

Packages: All SAIF.Platform packages

Upgraded the entire platform to .NET 10.0 LTS and Aspire 13.1 for improved performance and access to new framework features.

Key Changes:

✅ Target Framework - Updated to net10.0
✅ Aspire Integration - Updated to Aspire 13.1 components
✅ Preprocessor Cleanup - Removed legacy .NET compatibility shims

Configuration:

<TargetFramework>net10.0</TargetFramework>

Enhanced Token Caching ⚡¶

Package: SAIF.Platform.Authentication

Improved token caching logic with maximum duration cap for better security and performance.

Benefits:

🚀 Faster token retrieval from cache
🔒 Maximum duration cap prevents stale tokens
🎯 Better handling of on-behalf-of token requests

Terraform Modules¶

Entra ID Authentication Module 🔐¶

Module: security/azure/application

New internal authentication module for Entra ID (Azure AD) supporting corporate authentication scenarios.

Key Features:

✅ Application Registration - Full Entra ID app registration support
✅ Redirect URIs - Web application settings with redirect URI support
✅ Application Identifier URI - Custom identifier URI configuration
✅ Group Membership Claims - Support for groups claims in tokens
✅ Optional Claims - Configurable optional claims for access tokens

Example:

module "application" {
  source  = "app.terraform.io/saif/application/azure"
  version = "~> 3.0.0"

  display_name     = "my-api"
  identifier_uri   = "api://my-api"
  redirect_uris    = ["https://my-api.saif.com/auth/callback"]
}

Application Permissions Module 📋¶

Module: security/azure/application_permissions

Comprehensive module for managing Entra ID application permissions, scopes, and app roles.

Key Features:

✅ Scopes and App Roles - Define OAuth2 scopes and application roles
✅ Pre-Authorized Applications - Automatic API access for trusted apps
✅ Admin Consent - Grant admin consent for delegated permissions
✅ Validation - Prevent overlapping app roles and scopes

Example:

module "permissions" {
  source  = "app.terraform.io/saif/application_permissions/azure"
  version = "~> 3.0.0"

  application_id = module.application.application_id

  scopes = {
    read  = { description = "Read access" }
    write = { description = "Write access" }
  }

  app_roles = {
    admin = { description = "Administrator role" }
  }
}

Entra ID Group Membership Module 👥¶

Module: security/azure/group_membership

New module for managing Entra ID group memberships for non-production role assignments.

Benefits:

🚀 Simplified group membership management
🔒 Role-based access control via Entra groups
🎯 Non-production environment support

APIM Policy Split for Entra/Okta 🔄¶

Module: compute/azure/apim

Split API Management policies between Entra ID and Okta authentication providers for cleaner configuration.

Key Features:

✅ Separate Policies - Distinct policies for corporate (Entra) and external (Okta)
✅ JWT Validation - Proper openid-config URLs for each provider
✅ Centralized Auth URLs - Corp discovery keys and auth URLs in App Configuration

Project Templates¶

Template Updates for .NET 10 and Aspire 13.1 📦¶

Templates: All SAIF templates

Updated all project templates to target .NET 10.0 with Aspire 13.1 integration.

Key Changes:

✅ Scalar Integration - Replaced Swagger with Scalar for API documentation
✅ JavaScriptAppResource - Updated web front-end resource type
✅ Event Subscription Setup - Azure packages for event subscription
✅ Pipeline Templates - Updated to reference releases/v3 branch
✅ Terraform Modules - Updated to version ~> 3.0.0

Usage:

dotnet new saif-feature-api -n MyApi

Foundry Examples¶

Aspire Playwright Integration Testing 🧪¶

Example: foundry/dotnet/aspire-playwright

New comprehensive example for integration testing with Playwright in Aspire applications.

Key Features:

✅ API Integration Tests - Test API endpoints with generated clients
✅ Web Integration Tests - End-to-end browser testing
✅ Kiota Client Generation - Generated API clients for Weather API

Documentation:

DevTunnels Webhook Receiver 🔗¶

Example: foundry/dotnet/devtunnels-simple-webhook

Sample application demonstrating webhook receiver with DevTunnels and real-time dashboard.

Key Features:

✅ DevTunnels Integration - Receive webhooks via Azure DevTunnels
✅ Real-Time Dashboard - Live webhook monitoring UI
✅ Multi-Service Orchestration - Aspire-based service coordination

WireMock CLI Aspire Hosting Extension 🧪¶

Package: SAIF.Platform.Aspire.Hosting

New Aspire hosting extension for WireMock CLI with full orchestration, cloud sync, and service discovery support.

Key Features:

✅ AddWiremockCli Extension - Aspire resource builder for WireMock CLI orchestration
✅ AddMock Method - Add mock services with port allocation and service discovery
✅ WireMock Cloud Sync - Automatic pull from WireMock Cloud projects with autoUpdate option
✅ Health Checks - Built-in health monitoring via /__admin/health endpoint
✅ Dashboard Integration - Mock resources visible in Aspire dashboard with state management
✅ Service Discovery - Seamless WithReference() integration for consuming services

🔧 Enhancements¶

CLI Tools¶

✅ SAIF.Platform.CLI - Enhanced application search functionality in token generation
✅ SAIF.Platform.CLI - Updated HttpClient configuration for token service
✅ SAIF.Platform.CLI - Improved command descriptions for clarity and consistency

NuGet Packages¶

✅ SAIF.Platform.Authentication - Simplified OpenID Connect service scope configuration
✅ SAIF.Platform.Authentication - Removed unnecessary email and User.Read scopes
✅ SAIF.Platform.Kiota - Consolidated ApiDescription.Client into HttpClientLibrary package

Terraform Modules¶

✅ All Modules - Standardized variable naming to snake_case
✅ All Modules - Updated provider version constraints (AzureRM >= 4.0, AzureAD >= 3.0)
✅ security/azure - Updated UUID generation for scopes and roles
✅ security/azure - Improved token timeout configuration logic
✅ security/okta - Standardized variable names and YAML keys to snake_case

Project Templates¶

✅ saif-feature-api - Added auth terraform templates and sample configs
✅ All Templates - Improved formatting and structure of resource builder
✅ All Templates - Added descriptions to project templates for clarity

Documentation¶

✅ MkDocs - Updated table of contents depth for better navigation
✅ Design System - New design system documentation and guidelines
✅ Navigation - Reordered navigation items for improved structure

🐛 Bug Fixes¶

NuGet Packages¶

🐛 SAIF.Platform.Authentication - Fixed on-behalf-of token request parameters handling
🐛 SAIF.Platform.Authentication - Corrected casing for Microsoft Graph permission name
🐛 SAIF.Platform.Authentication - Fixed support for missing projectId and null authTenant when building scopes
🐛 SAIF.Platform.Authentication - Normalized environment name in scope generation
🐛 SAIF.Platform.Authentication - Include roles claim when adding custom token claims
🐛 SAIF.Platform.Aspire - Corrected scalar path in ApiResourceBuilder
🐛 SAIF.Platform.Kiota - Updated scope assertions for tenant-specific configurations

Terraform Modules¶

🐛 security/azure - Fixed group_membership_claims format to array
🐛 security/azure - Fixed claim value formatting in JWT validation
🐛 security/azure - Corrected openid-config URL in JWT validation policies
🐛 security/azure - Use oauth2_permission_scopes when resolving scope ids
🐛 security/azure - Use login.microsoftonline.com OIDC URLs for corporate auth
🐛 security/okta - Updated audience to use correct value from OktaApp output
🐛 security/okta - Updated Okta user and app auth prefix values
🐛 compute/azure - Fixed for_each errors with unknown conditionals
🐛 compute/azure - Enable public network access for function app
🐛 Key Vault - Updated secret references to use versionless ID

Project Templates¶

🐛 Templates - Added fallback port values for project templates
🐛 Templates - Updated OpenAPI file paths in configuration and scripts

CI/CD¶

🐛 Azure DevOps - Corrected branch reference in versioning configuration
🐛 Azure DevOps - Updated vars template paths in multiple YAML files

📚 Documentation¶

New Documentation¶

📖 Forge 2.x to 3.0 Migration Guide - Comprehensive migration guide for upgrading
📖 API Integration Testing Guide - Testing APIs with Playwright
📖 Web Integration Testing Guide - Browser testing with Aspire
📖 Design System Guidelines - UI/UX patterns and components
📖 JWT Creation Guide (Updated) - Corporate and external user JWT creation

Updated Documentation¶

📝 Version Compatibility Matrix - Updated for .NET 10, Aspire 13.1
📝 TypeSpec Guide - Updated OpenAPI output path configuration
📝 CLI Installation Guide - Updated prerequisites and setup
📝 WireMock CLI Hosting Guide - New sections and examples

⚠️ Breaking Changes¶

1. Okta Workspaces Limited to External Tenant¶

Change Description:

Okta authentication workspaces are now restricted to the External tenant only. Corporate authentication must use Entra ID.

Migration Guide:

# Before (Forge 2.x) - Okta for corporate
module "okta_auth" {
  source = "app.terraform.io/saif/okta-app-auth/okta"
  tenant = "Corporate"  # No longer supported
}

# After (Forge 3.0) - Entra ID for corporate
module "entra_auth" {
  source  = "app.terraform.io/saif/application/azure"
  version = "~> 3.0.0"
}

Impact:

Applications using Okta for corporate authentication must migrate to Entra ID
External tenant applications continue to use Okta

Action Required:

Update Terraform configurations to use Entra ID modules for corporate auth
Update application code to handle Entra ID tokens
See Migration Guide for detailed steps

2. Terraform Variable Naming (snake_case)¶

Change Description:

All Terraform variable names have been standardized to snake_case for consistency.

Migration Guide:

# Before (Forge 2.x)
module "app" {
  projectId     = "my-project"
  displayName   = "My App"
  authTenant    = "Corporate"
}

# After (Forge 3.0)
module "app" {
  project_id    = "my-project"
  display_name  = "My App"
  auth_tenant   = "Corporate"
}

Impact:

All Terraform configurations must update variable names

Action Required:

Run the provided migration script or manually update variable names
Validate Terraform plans before applying

3. .NET 10.0 Target Framework¶

Change Description:

All packages now target .NET 10.0 only. .NET 8.0 and 9.0 are no longer supported.

Migration Guide:

<!-- Before (Forge 2.x) -->
<TargetFramework>net8.0</TargetFramework>

<!-- After (Forge 3.0) -->
<TargetFramework>net10.0</TargetFramework>

Impact:

Applications must upgrade to .NET 10.0 SDK
CI/CD pipelines must use .NET 10.0 runtime

Action Required:

Install .NET 10.0 SDK
Update target framework in project files
Update pipeline templates to use dotnet-10.0 images

4. Removed Templates¶

Change Description:

Legacy templates have been removed: saif-azure-web-onprem, saif-console, saif-web-api, saif-web-mvc.

Impact:

New projects cannot use these templates
Existing projects are unaffected

Action Required:

Use saif-feature-api or saif-aspire templates for new projects
See CLI Installation Guide for available templates

📋 Additional Notes¶

Total commits: 240
Files changed: 1,200+
Contributors: Emmitt Johnson, Brian Sheridan, Jason Coria Corona Yue, Platform Build Service

Upgrade Path¶

Review Breaking Changes - Understand impact on your applications
Update .NET SDK - Install .NET 10.0 SDK
Update Terraform - Run migration scripts for variable naming
Update Authentication - Migrate corporate auth from Okta to Entra ID
Test Thoroughly - Validate all integrations before deploying

Support¶

📧 Teams Support Channel: Support
📖 Migration Guide