# 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](configuration/user-permissions.md) |
| **App Permissions**  | Grant your API access from upstream applications                   | [Configure App Permissions](configuration/app-permissions.md)   |

---

## 🏛️ 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`                                        |

!!! warning "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](configuration/deployment-workflow.md)                     | Step-by-step guide for deploying auth configuration        |
| [Configure User Permissions](configuration/user-permissions.md)                 | Set up Business Roles and map them to app permissions      |
| [Configure App Permissions](configuration/app-permissions.md)                   | Allow other applications to call your API                  |
| [Subscription Key Auth](configuration/subscription-key-auth.md)                | APIM subscription key auth with crypto registration for legacy apps |
| [Understanding Business Roles](configuration/business-roles.md)                 | Learn how Business Roles work and best practices           |
| [Aspire Security Configuration](configuration/aspire-security-configuration.md) | 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](testing/create-jwt-for-testing-apis.md)       | Generate JWT tokens for local API testing   |
| [Manage External Test Users](testing/manage-external-test-users.md)         | Create and manage Okta test users           |
| [Non-Production Role Assignment](testing/non-production-role-assignment.md) | Assign roles in non-production environments |

### Reference

| Document                                                   | Description                                     |
| ---------------------------------------------------------- | ----------------------------------------------- |
| [Authorization Concepts](../../reference/authorization.md) | Scopes vs. Roles, JWT structure, how auth works |

---

## 🚀 Quick Start

### First Time Setup

Follow the [Deployment Workflow](configuration/deployment-workflow.md) 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](../../reference/authorization.md)                      |
| **See deployment order**            | [Deployment Workflow](configuration/deployment-workflow.md)                     |
| **Get a token for testing**         | [Create JWT for Testing](testing/create-jwt-for-testing-apis.md)                |
| **Grant users access to my app**    | [User Permissions](configuration/user-permissions.md)                           |
| **Allow other apps to call my API** | [App Permissions](configuration/app-permissions.md)                             |
| **Legacy access with subscription keys**    | [Subscription Key Auth](configuration/subscription-key-auth.md)       |
| **Assign myself test roles**        | [Non-Production Roles](testing/non-production-role-assignment.md)               |
| **Understand Business Roles**       | [Business Roles](configuration/business-roles.md)                               |
| **Configure security in C# code**   | [Aspire Security Configuration](configuration/aspire-security-configuration.md) |

---

## ⚙️ 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 |

!!! tip "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`           |

---

## 🔗 Related Documentation

- [Aspire Publish](../development/aspire-publish.md) - Generate pipeline YAML and auth config from your AppHost
- [Authorization Concepts](../../reference/authorization.md) - How authorization works in Forge
- [Calling Downstream APIs](../development/calling-apis.md) - Configure Kiota clients with scopes
- [Settings and Secrets](../development/settings-and-secrets.md) - Manage application configuration