Recon Ranger (FastAPI)

Local development instructions for running the API on your machine.

Prerequisites

• Python 3.13+
• Optional: uv (recommended because uv.lock is included)

Azure Entra ID Setup

The dashboard at / requires login via Azure Entra ID. Assuming you have a tenant ID, follow these steps:

1. Create an App Registration

1. Go to Azure Portal → Microsoft Entra ID → App registrations
2. Click + New registration
3. Fill in:
   • Name: Recon Ranger
   • Supported account types: Accounts in this organizational directory only
4. Click Register

2. Configure Redirect URI

1. In your app registration, go to Authentication (left sidebar)
2. Click + Add a platform
3. Select Web
4. Under Redirect URIs, add: http://127.0.0.1:8000/auth/callback
5. Check Access tokens and ID tokens under Implicit grant and hybrid flows
6. Click Configure

3. Create a Client Secret

1. Go to Certificates & secrets (left sidebar)
2. Click + New client secret
3. Set Expires to 24 months
4. Click Add
5. Copy the Value (you won't see it again!) — this is your AZURE_CLIENT_SECRET

4. Collect Your Credentials

From your app registration Overview page, copy:

• Directory (tenant) ID → AZURE_TENANT_ID
• Application (client) ID → AZURE_CLIENT_ID
• Client secret value from step 3 → AZURE_CLIENT_SECRET

5. Generate SESSION_SECRET_KEY

Generate a random 32-byte secret for session encryption:

python -c "import secrets; print(secrets.token_urlsafe(32))"

Copy the output — this is your SESSION_SECRET_KEY.

6. Configure Local .env File

1. Create a local .env file from the template:

cp .env.example .env

2. Fill in your credentials:

SESSION_SECRET_KEY="<output-from-python-command>"
AZURE_TENANT_ID="<your-tenant-id>"
AZURE_CLIENT_ID="<your-client-id>"
AZURE_CLIENT_SECRET="<your-client-secret>"
AZURE_OAUTH_VERIFY_SSL="true"

The app automatically loads .env on startup.

Corporate Firewall / SSL Interception

If /login fails with SSL:CERTIFICATE_VERIFY_FAILED behind a corporate proxy/firewall, prefer trusting your corporate CA:

AZURE_OAUTH_CA_BUNDLE="/path/to/corporate-root-ca.pem"

For local dev only, you can temporarily disable verification:

AZURE_OAUTH_VERIFY_SSL="false"

Run Locally (Using uv)

1. Create a virtual environment:

uv venv

2. Activate the virtual environment:

source .venv/bin/activate

3. Install dependencies from lockfile:

uv sync

4. Start the FastAPI app with reload:

uv run uvicorn app.main:app --reload

Endpoints

• API docs: http://127.0.0.1:8000/api/docs
• OpenAPI schema: http://127.0.0.1:8000/openapi.json