# 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:**

```xml
<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:**

```hcl
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:**

```hcl
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:**

```bash
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:**

- [API Integration Testing Guide](../guides/development/testing/api-integration-testing.md)
- [Web Integration Testing Guide](../guides/development/testing/web-integration-testing.md)

---

#### 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](../guides/migration/forge-v2-to-v3.md) - Comprehensive migration guide for upgrading
- 📖 [API Integration Testing Guide](../guides/development/testing/api-integration-testing.md) - Testing APIs with Playwright
- 📖 [Web Integration Testing Guide](../guides/development/testing/web-integration-testing.md) - Browser testing with Aspire
- 📖 [Design System Guidelines](../about/contributing/design-system.md) - UI/UX patterns and components
- 📖 [JWT Creation Guide (Updated)](../guides/security/testing/create-jwt-for-testing-apis.md) - Corporate and external user JWT creation

### Updated Documentation

- 📝 [Version Compatibility Matrix](../reference/version-compatibility.md) - Updated for .NET 10, Aspire 13.1
- 📝 [TypeSpec Guide](../guides/development/typespec.md) - Updated OpenAPI output path configuration
- 📝 [CLI Installation Guide](../guides/development/install-saif-cli.md) - Updated prerequisites and setup
- 📝 [WireMock CLI Hosting Guide](../foundry/aspire-wiremockcli.md) - 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:**

```hcl
# 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:**

1. Update Terraform configurations to use Entra ID modules for corporate auth
2. Update application code to handle Entra ID tokens
3. See [Migration Guide](../guides/migration/forge-v2-to-v3.md) 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:**

```hcl
# 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:**

1. Run the provided migration script or manually update variable names
2. 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:**

```xml
<!-- 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:**

1. Install .NET 10.0 SDK
2. Update target framework in project files
3. 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:**

1. Use `saif-feature-api` or `saif-aspire` templates for new projects
2. See [CLI Installation Guide](../guides/development/install-saif-cli.md) 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

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

### Support

- 📧 Teams Support Channel: [Support](https://teams.microsoft.com/l/channel/19%3Acb611810fb0b42b080cfff5590bdd51c%40thread.tacv2/Support?groupId=514d2dac-2d62-48ce-bf99-0fa0ce39469c&tenantId=a86cb8ed-369b-4df5-ace5-43811f6e08cf)
- 📖 [Migration Guide](../guides/migration/forge-v2-to-v3.md)

---