Skip to content

Security

Configure authentication and authorization for your Forge applications.

📋 Overview

Security in Forge applications consists of two main components:

Component Description Guide
User Permissions Control which users can access your application via Business Roles Configure User Permissions
App Permissions Grant your API access from upstream applications Configure App Permissions

🏛️ Dual-Identity Architecture

Forge 3.0 uses a dual-identity architecture with two identity providers:

Aspect Corporate (Entra ID) External (Okta)
Users Internal employees Policyholders, injured workers, employers, providers
Identity Provider Microsoft Entra ID Okta
Configuration Location infra/auth/corp/ infra/auth/ext/
Business Role Storage Entra ID security groups Okta groups
User-delegation Scope user_impersonation user-groups

Keep Configurations Synchronized

Both identity providers should define the same app roles, scopes, and business role mappings—with only platform-specific differences.

📁 Auth Folder Structure

infra/
├── api/
│   └── config.yml              # App roles & scopes definition (Entra)
└── auth/
    ├── corp/                   # Corporate authentication (Entra ID)
    │   └── config.yml          # Business roles & authorized apps
    └── ext/                    # External authentication (Okta)
        ├── app/
        │   └── authorized-apps.yml
        ├── okta-client/
        │   ├── scopes.yml
        │   └── user_groups.yml
        └── user/
            └── business-role-app-role.yml

📚 Security Guides

Configuration Guides

Guide Description
Deployment Workflow Step-by-step guide for deploying auth configuration
Configure User Permissions Set up Business Roles and map them to app permissions
Configure App Permissions Allow other applications to call your API
Subscription Key Auth APIM subscription key auth with crypto registration for legacy apps
Understanding Business Roles Learn how Business Roles work and best practices
Aspire Security Configuration Define security configuration in C# with Aspire extensions

Testing & Development

Security testing workflows for development and non-production environments:

Guide Description
Create JWT for Testing APIs Generate JWT tokens for local API testing
Manage External Test Users Create and manage Okta test users
Non-Production Role Assignment Assign roles in non-production environments

Reference

Document Description
Authorization Concepts Scopes vs. Roles, JWT structure, how auth works

🚀 Quick Start

First Time Setup

Follow the Deployment Workflow guide for step-by-step instructions covering:

  1. ✅ Create Business Roles (if needed)
  2. ✅ Deploy your API
  3. ✅ Run auth pipeline
  4. ✅ Assign yourself test roles
  5. ✅ Generate a test token

Common Tasks

I want to... Go to...
Understand scopes vs. roles Authorization Concepts
See deployment order Deployment Workflow
Get a token for testing Create JWT for Testing
Grant users access to my app User Permissions
Allow other apps to call my API App Permissions
Legacy access with subscription keys Subscription Key Auth
Assign myself test roles Non-Production Roles
Understand Business Roles Business Roles
Configure security in C# code Aspire Security Configuration

⚙️ Authentication Pipelines

Pipeline Purpose When to Use
azure-pipelines-auth.yml Production auth deployment Deploy auth changes independently
azure-pipelines-auth-pr.yml PR validation (plan only) Validate auth changes before merge

Conditional Execution

The auth pipeline runs conditionally based on which configuration files changed. If you only modified corporate auth, the external auth steps are skipped.

📖 Configuration File Reference

Corporate Authentication (Entra ID)

File Purpose Key Configuration
infra/api/config.yml Define app roles and scopes app_roles, scopes
infra/auth/corp/config.yml Business roles and authorized apps business_roles, authorized_apps

External Authentication (Okta)

File Purpose Key Configuration
infra/auth/ext/okta-client/user_groups.yml Define app permissions app_permissions
infra/auth/ext/okta-client/scopes.yml Define API scopes scopes
infra/auth/ext/user/business-role-app-role.yml Map Business Roles to app roles authorized_business_roles
infra/auth/ext/app/authorized-apps.yml Authorize upstream apps authorized_apps