Azure Entra

Microsoft Azure AD / Entra ID integration for Single Sign-On (SSO). Allows users to authenticate with their Microsoft organizational account instead of email/password.

Architecture

Component	Path
Auth route	backend/src/routes/entra-auth.ts
Service	backend/src/services/entra/
Frontend callback	frontend/src/pages/AuthCallback.tsx

SSO Flow

1. User clicks “Sign in with Microsoft” on login page
2. Frontend redirects to Azure Entra authorization endpoint
3. User authenticates with Microsoft credentials
4. Azure redirects back to /auth/callback with authorization code
5. Backend exchanges code for tokens, extracts user identity
6. Creates or links Users account, issues JWT session
7. Frontend AuthCallback page stores JWT and redirects to app

Redirect URI Management

Each environment needs its redirect URI registered in Azure Entra:

Environment	URI Pattern
Development	http://localhost:<port>/auth/callback
Staging	https://staging.renewa.app/auth/callback
Production	https://app.renewa.app/auth/callback
PR Preview	https://renewa-app-pr-<N>.fly.dev/auth/callback

Managed via: make sso-register which runs scripts/manage-entra-redirect-uri.sh.

See PR Preview Deployments for preview URI registration, Makefile Commands for SSO commands.

Configuration

Secret	Purpose
Azure Tenant ID	Organization directory
Azure Client ID	App registration identifier
Azure Client Secret	App authentication

Stored as GitHub Environment Secrets, synced to Fly.io. See Deployment Pipeline.

User Provisioning

On first SSO login, the system:

1. Checks if a Users account exists with the Microsoft email
2. If exists: links the Azure identity and logs in
3. If not: creates a new user account from the Azure profile

Related

• Authentication — Overall auth architecture (JWT, 2FA, password)
• Users — User account creation and linking
• External Integrations — All third-party integrations
• Makefile Commands — make sso-register command
• PR Preview Deployments — Dynamic redirect URI registration
• Routing — AuthCallback route handling