Configuration & Setup

This page covers prerequisites, local development setup, the startup pipeline, configuration options, authentication, and troubleshooting.

Prerequisites

• .NET 8 SDK — Download
• Visual Studio 2022 (or later) with the ASP.NET and web development workload
• Azure subscription with access to:
  • Azure Cosmos DB account
  • Azure SQL Server
  • Azure Storage account (Blob + Table)
  • Azure App Configuration service
  • Azure Key Vault
  • Azure SignalR Service
  • Azure Application Insights
  • Microsoft Entra ID (Azure AD) app registration

Local Development Setup

1. Clone the Repository

git clone https://dev.azure.com/cardinalsolutions/Alert%20California/_git/Alert.CA.Frontend.API

2. Configure NuGet Source

The solution depends on private packages from the Alert.CA.Common NuGet feed. The nuget.config file in the repository root should already be configured:

<?xml version="1.0" encoding="utf-8"?>
<configuration>
  <packageSources>
    <clear />
    <add key="Alert.CA.Common" value="https://pkgs.dev.azure.com/cardinalsolutions/4f9f6476-856e-468b-8039-5f1adb64aa9c/_packaging/Alert.CA.Common/nuget/v3/index.json" />
  </packageSources>
</configuration>

If the source isn't showing in Tools → Options → NuGet Package Manager → Package Sources, add it manually.

3. Set Up User Secrets

The API connects to Azure App Configuration at startup to load all other settings. Configure the connection using .NET User Secrets:

cd Alert.CA.Frontend.API
dotnet user-secrets set "ConnectionStrings:AppConfig" "https://{DEV APPCONFIG URL}.azconfig.io"

Or edit secrets.json directly (the User Secrets ID is 69cdc019-4869-4995-9e2d-93c84c04f640):

{
  "ConnectionStrings": {
    "AppConfig": "https://{DEV APPCONFIG URL}.azconfig.io"
  }
}

4. Azure Identity Setup

The application uses DefaultAzureCredential to authenticate with Azure services. For local development, this uses your Visual Studio credential.

1. In Visual Studio, go to Tools → Options → Azure Service Authentication
2. Sign in with your [First].[Last]@wfca.com account
3. Ensure your account is a member of the Insight-AlertCA user group

5. Build and Run

# Restore dependencies (including private NuGet packages)
dotnet restore

# Build the solution
dotnet build

# Run the API
dotnet run --project Alert.CA.Frontend.API

Or press F5 in Visual Studio to launch with debugging.

The API will be available at https://localhost:{port} (check console output for the exact port). Swagger UI is available at /swagger.

---

Startup Pipeline

The Program.cs initializes the application in this order:

AddWebApiServices (ConfigureServices.cs)

Registers:

• Authentication: JWT Bearer via Microsoft.Identity.Web bound to the AzureAd config section
• SignalR: With Azure SignalR Service backing
• Cosmos DB, Storage, SQL Database, Graph, JWT services: From the AlertCAInfrastructure package
• BroadcastService: Scoped service for SignalR server-side pushes
• Response compression: Enabled for HTTPS
• Application Insights: Telemetry collection
• Controllers: With camelCase JSON serialization
• Swagger: OpenAPI documentation with JWT security scheme

AddApplicationServices (Application ConfigureServices.cs)

Registers:

• Configuration options: CameraOperationOptions, EnvironmentOptions, FunctionApiKeyOptions
• CameraControlService: With HttpClient for Image Acquisition API calls
• AlertService, ClipGenerationService, ValidatorService: Scoped services
• MediatR: Assembly scanning for commands, queries, and handlers

---

Configuration Options

All options are loaded from Azure App Configuration and Key Vault at startup. They are bound to strongly-typed options classes via the .NET Options pattern.

Options Class	Source	Purpose
AzureAd	App Config	Azure AD tenant, client ID, audience for JWT Bearer authentication
CameraOperationOptions	App Config	Camera control defaults (lease durations, movement limits)
EnvironmentOptions	App Config	Environment-specific camera visibility rules
FunctionApiKeyOptions	Key Vault	API key for authenticating HTTP calls to the Image Acquisition API (x-api-key header)
ImageAcquisitionOptions	App Config	Image Acquisition API base URL endpoint
BlobStorageOptions	App Config	Storage account name, container name, and base URL for image access
CosmosDbOptions	App Config	Cosmos DB account name, database name, and container names
Azure:SignalR:ConnectionString	Key Vault	Azure SignalR Service connection string

appsettings.json

The appsettings.json file contains only logging configuration. All other settings come from Azure App Configuration:

{
  "Logging": {
    "LogLevel": {
      "Default": "Information",
      "Microsoft.AspNetCore": "Warning",
      "Microsoft.AspNetCore.Authentication.JwtBearer": "Debug"
    }
  },
  "AllowedHosts": "*"
}

tip

JwtBearer logging is set to Debug to help diagnose authentication issues during development. Consider setting this to Warning in production.

---

Authentication

The API uses Microsoft Entra ID (Azure AD) with JWT Bearer tokens.

How It Works

1. The client navigates to GET /authorization/login, which redirects to Microsoft's Entra ID login page
2. After authentication, Microsoft redirects to GET /authorization/callback with an authorization code
3. The callback exchanges the code for access and refresh tokens via the IJWTService
4. The access token is used as a Bearer token in subsequent API requests
5. The API validates the token using the AzureAd configuration section (tenant, client ID, audience)

Security Roles

Roles are defined as Azure AD app roles and checked via [Authorize(Roles = "...")] attributes:

Role	Description
Camera.Operate	PTZ control, focus, brightness, guard tour, activity logs, lease management
Notification.Alert	Creating and sending alert messages
Notification.Subscribe	Managing notification subscriptions
AI.Access	Access to AI-specific operational metadata

Claim Extraction

The ApiControllerBase extracts these claims from the JWT:

Property	Claim	Description
EntraUserId	oid	User's Object ID in Entra ID
EntraDisplayName	name	User's display name
EntraEmail	preferred_username	User's email address
CompanyName	companyname	User's company (optional)

---

Swagger

Swagger UI is available at /swagger when the API is running. It provides interactive documentation for all endpoints.

To authenticate in Swagger:

1. Click the link in the Swagger description to go to /authorization/login
2. Complete the Microsoft login flow
3. Copy the access token from the callback response
4. Click the Authorize button in Swagger and paste the token

---

Development Guidelines

• Branching: Follows GitFlow. Feature branches from develop, named with your initials (e.g., feature/jd-camera-filters)
• Commits: Use descriptive commit messages
• Pull Requests: All changes require PR review before merging
• Testing: Add or update unit tests in Alert.CA.Frontend.API.Test for all changes
• Documentation: Update docs in the docs/ folder for any API or architecture changes. Documentation auto-syncs to the centralized documentation site via CI pipeline.

---

Troubleshooting

Authentication Errors

"AADSTS700016: Application not found"

• Ensure the AzureAd section in App Configuration has the correct TenantId and ClientId

"401 Unauthorized" on all requests

• Verify your token hasn't expired
• Check that you're using the correct Azure AD app registration
• Ensure the JWT audience matches the configured audience

DefaultAzureCredential fails at startup

• Confirm you're signed into the correct account in Tools → Options → Azure Service Authentication
• Ensure your @wfca.com account is a member of the Insight-AlertCA group
• Try running az login in a terminal as a fallback credential

NuGet Restore Failures

"Unable to find package AlertCAInfrastructure"

• Verify the Alert.CA.Common NuGet source is configured (check nuget.config)
• Ensure your Azure DevOps PAT has Packaging (Read) scope
• Try authenticating the feed: Tools → Options → NuGet Package Manager → Package Sources → add credentials

App Configuration Connection Errors

"Failed to connect to App Configuration"

• Verify the ConnectionStrings:AppConfig value in User Secrets
• Ensure the URL format is https://{name}.azconfig.io (no trailing slash)
• Check that your Azure identity has the App Configuration Data Reader role on the resource

SignalR Connection Issues

Clients cannot connect to /cameraHub

• Verify the Azure SignalR Service connection string is set in Key Vault
• Check that AddAzureSignalR() is configured in ConfigureServices.cs
• Ensure the SignalR Service is running and accessible from your network

General

API starts but returns 500 errors

• Check Application Insights or console logs for detailed error messages
• Common causes: missing App Configuration keys, expired Key Vault secrets, or Cosmos DB connection issues
• Run with ASPNETCORE_ENVIRONMENT=Development for detailed error pages