azure_setup_guide - mamoorkhan/glasslewis GitHub Wiki

Complete Azure Setup Guide

This guide provides a detailed walkthrough for setting up Azure Entra External ID, app registrations, and service principals for the GlassLewis Platform.

📋 Prerequisites

  • Azure subscription with Global Administrator or Application Administrator privileges
  • Azure CLI installed locally
  • Basic understanding of Azure Portal navigation

🎯 Overview

You'll create 3 app registrations:

  1. API App Registration - Protects the .NET Web API
  2. Client App Registration - Enables Angular SPA authentication
  3. Service Principal - Allows GitHub Actions to deploy resources

🔧 Step 1: Create Azure Entra External ID Tenant (If Needed)

If you don't have an existing Entra External ID tenant:

  1. Navigate to Azure Portal

  2. Create New Tenant

    Tenant Type: External ID
Organization Name: GlassLewis Platform
Domain Name: glasslewis-platform (or your preferred name)
Country/Region: Your region

  3. Switch to Your New Tenant

    • Click your profile icon → Switch directory
    • Select your new Entra External ID tenant

🔑 Step 2: Create API App Registration

2.1 Basic Registration

  1. Navigate to App Registrations

    • Azure Portal → Microsoft Entra ID → App registrations
    • Click New registration

  2. Configure Basic Settings

    Name: glasslewis-api-dev
Supported account types: Accounts in this organizational directory only (Single tenant)
Redirect URI: Leave blank

  3. Click Register

2.2 Configure API Scopes

  1. Expose an API

    • Go to Expose an API in the left menu
    • Click Add a scope

  2. Set Application ID URI

    Application ID URI: api://[your-client-id]
(Accept the suggested value or customize)

  3. Add Company.Read Scope

    Scope name: Company.Read
Who can consent: Admins and users
Admin consent display name: Read company data
Admin consent description: Allows the application to read company information on behalf of the user
User consent display name: Read your company data
User consent description: Allows the app to read company information that you have access to
State: Enabled

  4. Add Company.ReadWrite Scope

    Scope name: Company.ReadWrite
Who can consent: Admins and users
Admin consent display name: Read and write company data
Admin consent description: Allows the application to read and write company information on behalf of the user
User consent display name: Read and write your company data
User consent description: Allows the app to read and write company information that you have access to
State: Enabled

2.3 Configure Authentication

  1. Go to Authentication

    • No redirect URIs needed for API-only registration

  2. Configure Token Configuration (Optional)

    • Go to Token configuration
    • Add optional claim → Access tokens
    • Select: email, family_name, given_name

2.4 Record Important Values

📝 Save these values securely:

API Application (client) ID: [copy from Overview page]
API Object ID: [copy from Overview page]
Directory (tenant) ID: [copy from Overview page]
Application ID URI: api://[your-client-id]

🌐 Step 3: Create Client App Registration

3.1 Basic Registration

  1. Create New Registration 
    Name: glasslewis-client-dev
Supported account types: Accounts in this organizational directory only (Single tenant)
Redirect URI: 
  - Platform: Single-page application (SPA)
  - URI: http://localhost:4200

3.2 Configure Authentication

  1. Add Additional Redirect URIs

    • Go to Authentication
    • Add URI → Single-page application
    Development: http://localhost:4200
Development Alt: http://localhost:4200/auth/callback
Production: https://your-production-domain.com
Production Alt: https://your-production-domain.com/auth/callback

  2. Configure Advanced Settings

    ✅ Access tokens (used for implicit flows)
✅ ID tokens (used for implicit and hybrid flows)
❌ Allow public client flows: No

  3. Configure Logout URL (Optional)

    Front-channel logout URL: http://localhost:4200/auth/logout

3.3 Configure API Permissions

  1. Add API Permissions

    • Go to API permissions
    • Add a permission → My APIs
    • Select your API app registration (glasslewis-api-dev)

  2. Select Delegated Permissions

    ✅ Company.Read
✅ Company.ReadWrite

  3. Grant Admin Consent

    • Click Grant admin consent for [Your Organization]
    • Confirm by clicking Yes
    • Verify status shows green checkmarks

3.4 Configure Token Configuration

  1. Add Optional Claims
    • Go to Token configuration
    • Add optional claim → ID tokens
    • Select: email, family_name, given_name, preferred_username

3.5 Record Important Values

📝 Save these values securely:

Client Application (client) ID: [copy from Overview page]
Client Object ID: [copy from Overview page]
Directory (tenant) ID: [same as API]

🤖 Step 4: Create Service Principal for GitHub Actions

4.1 Create App Registration

  1. Create New Registration 
    Name: glasslewis-github-actions
Supported account types: Accounts in this organizational directory only (Single tenant)
Redirect URI: None

4.2 Create Client Secret

  1. Go to Certificates & secrets

    • Click New client secret
    Description: GitHub Actions Deployment Secret
Expires: 24 months

  2. ⚠️ CRITICAL: Copy Secret Value

    • Immediately copy the secret value
    • Store it securely - you won't see it again!

4.3 Assign Azure RBAC Permissions

  1. Navigate to Subscription

    • Azure Portal → Subscriptions → Select your subscription

  2. Add Role Assignment

    • Access control (IAM) → Add → Add role assignment
    Role: Contributor
Assign access to: User, group, or service principal
Members: Search for "glasslewis-github-actions"

  3. Verify Assignment

    • Go to Role assignments tab
    • Confirm the service principal has Contributor role

4.4 Record Important Values

📝 Save these values securely:

Service Principal Application ID: [copy from Overview]
Service Principal Object ID: [copy from Overview]
Service Principal Secret: [copy from Certificates & secrets]
Directory (tenant) ID: [same as above]
Subscription ID: [copy from subscription overview]

🔐 Step 5: Configure GitHub Secrets

5.1 Navigate to GitHub Repository

  1. Go to Repository Settings
    • Your GitHub repo → Settings → Secrets and variables → Actions

5.2 Add Repository Secrets

Click "New repository secret" for each:

  1. AZURE_CREDENTIALS

    {
  "clientId": "your-service-principal-application-id",
  "clientSecret": "your-service-principal-secret",
  "subscriptionId": "your-azure-subscription-id",
  "tenantId": "your-tenant-id"
}

  2. API_CLIENT_ID

    your-api-app-registration-client-id

  3. CLIENT_APP_ID

    your-client-app-registration-client-id

  4. TENANT_ID

    your-tenant-id

  5. AZURE_SUBSCRIPTION_ID

    your-azure-subscription-id

✅ Step 6: Verification Checklist

6.1 API App Registration Verification

  • App registration created successfully
  • Application ID URI configured (api://your-client-id)
  • Company.Read scope created and enabled
  • Company.ReadWrite scope created and enabled
  • Optional claims configured for access tokens

6.2 Client App Registration Verification

  • SPA app registration created
  • Redirect URIs configured for all environments
  • API permissions granted (Company.Read, Company.ReadWrite)
  • Admin consent granted (green checkmarks visible)
  • Optional claims configured for ID tokens

6.3 Service Principal Verification

  • GitHub Actions app registration created
  • Client secret created and saved securely
  • Contributor role assigned to subscription
  • All values recorded for GitHub secrets

6.4 GitHub Secrets Verification

  • AZURE_CREDENTIALS secret created with valid JSON
  • API_CLIENT_ID secret created
  • CLIENT_APP_ID secret created
  • TENANT_ID secret created
  • AZURE_SUBSCRIPTION_ID secret created

🔧 Step 7: Test Your Configuration

7.1 Test API App Registration

Run this PowerShell/Bash command to verify your API app:

# Using Azure CLI
az ad app show --id "your-api-client-id" --query "{displayName:displayName, appId:appId, identifierUris:identifierUris}"

7.2 Test Client App Registration

# Using Azure CLI
az ad app show --id "your-client-app-id" --query "{displayName:displayName, appId:appId, spa:spa.redirectUris}"

7.3 Test Service Principal

# Test Azure authentication
az login --service-principal \
  --username "your-service-principal-app-id" \
  --password "your-service-principal-secret" \
  --tenant "your-tenant-id"

# Test permissions
az account show

🚨 Common Issues & Solutions

Issue: "AADSTS50011: The reply URL specified in the request does not match"

Solution:

  • Verify redirect URIs in Client App Registration
  • Ensure URL exactly matches (including trailing slashes)
  • Check for HTTP vs HTTPS mismatch

Issue: "AADSTS65001: The user or administrator has not consented"

Solution:

  • Grant admin consent in API permissions
  • Verify scopes are properly exposed in API app registration
  • Check that scopes match between API and client apps

Issue: "AADSTS700016: Application not found in directory"

Solution:

  • Verify you're in the correct Azure tenant
  • Check that app registration exists and is not deleted
  • Ensure client ID is copied correctly

Issue: Service Principal permission denied

Solution:

  • Verify Contributor role assignment
  • Check that you're assigning at the correct scope (subscription level)
  • Ensure service principal is not disabled

📚 Next Steps

After completing this setup:

  1. Configure Local Development Environment
  2. Test Authentication Flow
  3. Deploy to Azure

📞 Need Help?