這是一篇教大家如何把 Azure Storage 從舊時代的金鑰存取，安全升級到託管身分 Managed Identity 的技術指南。

想像一下，你家大門的鑰匙就被你大大方方放在門口的鞋櫃上，任何走過路過的人只要拿到這把鑰匙就能直接進你家搬東西。這就是以前我們使用存取金鑰 Connection String 連線到 Azure Storage 的驚險狀況！

為了不讓駭客當你家是花園，我們強烈建議改用託管身分 Managed Identity。

不過設定上會和 SQL 連線不太一樣。SQL 只要在連線字串加個 useMsi=true 就能解決，但 Blob Storage 必須搭配 Blob SDK 使用 Entra ID Token，並且在 Azure RBAC 權限控管中，給予你的 Container App 相應的權限。

在目前的測試環境中，我們的後端 App 雖然有了系統分配的身分，但只有拿到拉取映像檔的 AcrPull 權限。至於檔案儲存區，依然把金鑰 AZURE_STORAGE_CONNECTION_STRING 硬塞給後端程式碼。

為了達成最高等級的資安防護，以下是推薦的升級改造方向：

1. 打造安全的基礎架構

• 私有化儲存區：Blob Container 絕對不能開啟任何人都能看的公開存取存取權限。
• 後端專屬通道：只有後端 App 可以接觸儲存區，前端完全不拿任何金鑰或 Token。
• 權限最小化原則：給後端 App 的身分授權 Storage Blob Data Contributor 角色，而且範圍只能限定在 demoproject-attachments 這個容器。這樣它就能讀、寫、刪除檔案。（千萬別偷懶給了一般權限，那樣權限太大了！）

2. 後端 Go 程式碼改版

後端改用 DefaultAzureCredential 搭配 Storage Account 的 Blob 端點。這樣做的好處是，你在本機開發時會自動用你電腦 az login 的身分；一旦部署到 Azure Container Apps 時，就會自動無縫切換成 Managed Identity，完全不用改程式碼！

你的專案已經有 azidentity 套件，不需要另外安裝。請把 config.go 中的連線字串改為帳號名稱 AccountName，並修改 internal/storage/blob.go：

// internal/storage/blob.go
import "github.com/Azure/azure-sdk-for-go/sdk/azidentity"

func NewBlobClient(accountName, containerName string) (*BlobClient, error) {
    if accountName == "" {
        return nil, nil // 如果本地環境停用附件功能就跳過
    }
    if containerName == "" {
        return nil, fmt.Errorf("azure storage container name is required")
    }

    credential, err := azidentity.NewDefaultAzureCredential(nil)
    if err != nil {
        return nil, fmt.Errorf("create azure credential: %w", err)
    }

    serviceURL := fmt.Sprintf("https://%s.blob.core.windows.net/", accountName)
    client, err := azblob.NewClient(serviceURL, credential, nil)
    if err != nil {
        return nil, fmt.Errorf("create blob client: %w", err)
    }

    return &BlobClient{client: client, container: containerName}, nil
}

(別忘了主程式 main.go 也要改為呼叫 NewBlobClient(cfg.AzureStorage.AccountName, cfg.AzureStorage.ContainerName) )

3. 自動化部署腳本更新

部署時不再傳送一長串的金鑰，改為傳送儲存區名稱：

$STORAGE_ACCOUNT_NAME = "demostorageaccount"
$AZURE_STORAGE_CONTAINER_NAME = "demoproject-attachments"

在取得後端的服務身分 ID 後，加入 RBAC 授權：

$storageAccountId = az storage account show `
  --name $STORAGE_ACCOUNT_NAME `
  --resource-group $STORAGE_RG `
  --query id -o tsv
Assert-Success "storage account show"

$storageContainerScope = "$storageAccountId/blobServices/default/containers/$AZURE_STORAGE_CONTAINER_NAME"

az role assignment create `
  --assignee-object-id $backendPrincipalId `
  --assignee-principal-type ServicePrincipal `
  --role "Storage Blob Data Contributor" `
  --scope $storageContainerScope | Out-Null
Assert-Success "Storage Blob Data Contributor role"

最後更新環境變數設定：

@{ name = "AZURE_STORAGE_ACCOUNT_NAME";   value = $STORAGE_ACCOUNT_NAME }
@{ name = "AZURE_STORAGE_CONTAINER_NAME"; value = $AZURE_STORAGE_CONTAINER_NAME }

(小提醒：正式環境的 deploy-production.ps1、.env.example 等檔案也要同步更新，不然正式環境還會傻傻地跟你要金鑰喔！)

4. 警告！附件下載流程會壞掉！

這是大家升級時最容易踩到的超大陷阱！

Managed Identity 的通行證只有「後端 到 儲存區」有效。一旦我們把儲存區設為私有，以前那種直接把網址丟給前端網頁點擊下載的做法就會直接失效，使用者點開只會看到冷酷的 403 Forbidden 拒絕存取畫面！

該怎麼拯救下載功能？

千萬不要因為下載壞掉就把儲存區重新開放給外面的所有人看！

正確的解法是讓後端當「轉接員」，新增一個需要驗證的下載 API 路線：

GET /api/announcements/{id}/attachments/{attachmentId}/download

流程變成：前端跟後端要檔案，後端憑著自己的 Managed Identity 身份去把檔案拿回來，再傳給使用者。這樣既安全又不會斷功能！

改造總結步驟

1. 建立專屬的容器 Container。
2. 設定後端身分的 RBAC 授權。
3. 修改 Go 語言程式碼改走 DefaultAzureCredential。
4. 更新部署時的環境變數。
5. 把下載機制改為後端轉接模式（最重要的一步）。
6. 開始歡樂測試上傳、下載、刪除，確保一切正常！

Demo 資料說明

本文是一篇教學用範例。Example Company、demoproject、Azure 資源名稱、帳號、網域與 tenant 都是虛構資料，不能直接拿來連線或部署。實際使用時，請替換成自己的環境設定。

先說結論

Example Company 的開發團隊想在 Azure Container Apps 裡快速展示 Backend 功能，但暫時不需要使用既有的 Azure SQL Database，也不需要讀取既有的 demoproject-dev 資料。

這種情況可以在同一個 Container Apps Environment 裡，另外部署一個暫時的 Microsoft SQL Server container，提供一個全新的 Demo database。

這個方案的重點是：

• Demo SQL Server 是獨立的新資料庫。
• Backend 不連既有的 demoproject-dev。
• 不匯入正式或 staging 資料。
• 不使用既有 Azure SQL 的 Managed Identity、contained user 或 database roles。
• Backend、MSSQL 和 Frontend 仍然要正確設定網路、secret、storage、health check 和 CI/CD。

換句話說，這不是把原本的 Azure SQL 搬進 container，而是建立一套隔離、短期、只供 Demo 使用的資料庫環境。

為什麼需要這個方案？

假設目前的開發環境是：

cae-example-dev-001

這個 Environment 主要用來執行開發中的 Container App，但沒有連到既有 Azure SQL Private Endpoint 所需的完整 VNet 路徑。

如果 Backend 直接使用 Azure SQL，可能會遇到：

• SQL network connection timeout。
• Private Endpoint 無法連線。
• Azure SQL firewall 拒絕來源 IP。
• Managed Identity 可以取得 token，但 SQL database 沒有對應的 user 或 roles。

可是，這次 Demo 的需求並不是要存取既有資料，而是希望先讓團隊能夠：

1. 啟動 Backend API。
2. 建立一些測試資料。
3. 展示查詢、新增、修改等基本功能。
4. 讓 Frontend 能呼叫 Backend。

因此，可以把資料庫改成和 Backend 位於同一個 Container Apps Environment 的內部 MSSQL App，讓這次 Demo 不依賴既有 Azure SQL 的 Private Endpoint。

目標架構

Demo 環境可以設計成下面這樣：

Frontend 或測試工具
          │
          ▼
ca-example-backend-dev-001
          │ internal connection
          ▼
ca-example-mssql-demo-dev-001
          │ TCP 1433，僅限 internal ingress
          ▼
demoproject-demo

示範資源如下：

MSSQL 應該是獨立的 Container App，不要和 Backend 放在同一個 container。這樣可以分別更新 Backend 和資料庫，也比較容易在 Demo 結束時清理。

需要怎麼做？

第一步：建立獨立的 MSSQL Container App

使用官方 Microsoft SQL Server Linux container image，並固定版本或 digest，不要長期使用會隨時間變動的 latest tag。

MSSQL App 的基本設定應包含：

App name:    ca-example-mssql-demo-dev-001
Environment: cae-example-dev-001
Port:        TCP 1433
Ingress:     internal only
Database:    demoproject-demo

Container 需要設定：

• ACCEPT_EULA=Y
• MSSQL_PID=Developer
• MSSQL_SA_PASSWORD
• 足夠的 CPU 和 memory
• TCP 1433 target port
• readiness/startup health check

SQL Server container 通常至少需要 2 GiB memory；Demo 建議依實際啟動時間與資料量配置更多資源。

MSSQL_PID=Developer 只適合非正式 Demo，不能當成 production license 或正式 staging database。SA password 不可以寫在 Dockerfile、image、repository 或 workflow 明文中。

第二步：只開放內部網路

MSSQL App 只能使用 internal ingress：

Backend App ── internal DNS ──> MSSQL App:1433

不要把 SQL Server 的 TCP 1433 開成 public ingress，也不要讓測試人員直接從 Internet 連入。

Backend 和 MSSQL App 最簡單的做法是放在同一個 cae-example-dev-001。Backend 使用 MSSQL App 的 internal FQDN 連線，不要自行猜測 FQDN 格式，應從 Azure Container Apps 的 App 設定或 DNS 設定取得實際值。

第三步：建立專用 application login

Backend 不應使用 sa 登入。MSSQL container 第一次啟動後，應執行一次初始化流程：

1. 建立 demoproject-demo database。
2. 建立專用的 Backend application login。
3. 只授予 application login 必要的 read/write 權限。
4. 只有需要執行 schema migration 時，才授予有限的 DDL 權限。
5. 確認 Backend 不會取得 SA password。

這個 Demo SQL Server 是獨立的 SQL container，Backend 通常會使用 SQL login/password，而不是既有 Azure SQL 的 Microsoft Entra Managed Identity flow。

因此，application login 的 username 和 password 必須放在 Container App secret 或 Key Vault secret reference 中，不能放在 source code 或公開設定檔。

第四步：修改 Backend 的 connection string

Backend 原本如果使用 Azure SQL Managed Identity，可能會包含這類設定：

fedauth=ActiveDirectoryManagedIdentity
useMsi=true

切換到 Demo MSSQL 後，Backend 必須改成：

• SQL host：ca-example-mssql-demo-dev-001 的 internal FQDN。
• Port：1433。
• Database：demoproject-demo。
• Username：專用 application login。
• Password：由 secret reference 注入。
• Authentication：使用 SQL login/password。

概念上的設定如下：

sqlserver://<mssql-internal-host>:1433
  ?database=demoproject-demo
  &user=<application-user>
  &password=<secret-reference>

實際格式要依 Backend 使用的 SQL driver 調整。不要把完整 connection string 寫進 GitHub Actions log、Dockerfile 或公開的 frontend configuration。

如果 Demo SQL Server 使用 self-signed certificate，請明確決定測試環境的 TLS 設定。即使是 Demo，也不要把關閉加密或無條件信任憑證當成正式環境的解法。

第五步：建立 schema 和測試資料

全新的 demoproject-demo 不會自動有任何 table，因此需要另外準備：

• schema migration。
• 初始化 seed data。
• Demo 使用者和測試帳號。
• API 所需的 reference data。
• migration 失敗時的處理方式。

建議使用一次性的 bootstrap 或 job 初始化 database，不要讓每一個 Backend revision 在啟動時同時執行完整 migration，否則可能發生 migration race condition。

Demo data 應該是新建或去識別化資料，不要將正式資料直接複製到這個 container。

第六步：處理資料持久化

Container App 的 local filesystem 不適合當成可靠的 database storage。如果沒有持久化 volume，以下情況都可能讓資料消失：

• Container restart。
• Revision replacement。
• App 被重新建立。
• Node 或 host 發生故障。

如果 Demo 只做一次性展示，可以接受資料在環境重建後消失；如果需要保留測試結果，至少要：

• 將 SQL Server data/log 目錄掛到持久化 storage，例如 Azure Files。
• 驗證 SQL Server 在該 storage 上的 lock、I/O 和 recovery 行為。
• 設定 backup，並將 backup 放到獨立的儲存位置。
• 訂定資料保存期限。
• 確認刪除 App 或 volume 時，不會誤刪唯一一份資料。

即使使用 Azure Files，這仍然不等同於 Azure SQL Database 的 HA、backup、patching、SLA 和資料庫服務保證，所以必須把它標示為 temporary demo database。

第七步：把資料庫 bootstrap 和一般 CI/CD 分開

MSSQL App 不應該在每次 Backend push 時被刪除或重建。建議把流程分成兩部分。

一次性的 Demo bootstrap：

• 建立或更新 ca-example-mssql-demo-dev-001。
• 設定 image、secret、storage、internal ingress 和 health check。
• 等待 SQL Server ready。
• 建立 demoproject-demo、application login、schema 和 seed data。

一般 Backend CI/CD：

• 編譯 Backend。
• Push Backend image 到 ACR。
• 更新 ca-example-backend-dev-001。
• 保留 MSSQL App 和 volume，不要重新初始化 database。

Backend runtime 仍然需要自己的 ACR AcrPull。GitHub OIDC Service Principal 只負責 CI/CD 所需的 AcrPush 和 App deployment 權限，不需要 SQL database role。

如果 MSSQL image 直接從 MCR pull，必須確認 Environment 可以連到 MCR。如果團隊將 MSSQL image mirror 到 ACR，則 MSSQL App 的 runtime identity 也要另外授予 ACR AcrPull。

第八步：處理啟動順序和健康檢查

SQL Server container 通常比 API container 更久才會 ready，因此 Backend 不能假設 SQL 在啟動第一秒就能連線。

需要加入：

• MSSQL readiness/health check。
• Backend 的 connection retry 和 backoff。
• 將「SQL 尚未 ready」與「帳號密碼錯誤」分開記錄。
• SQL container restart 後，Backend 自動恢復連線。
• 避免在 logs 印出 password、完整 connection string 或 token。

az containerapp update 成功只代表 Azure 接受了 App 設定，不代表 Backend 一定已經能連到 MSSQL。必須等兩個 App 都 healthy 後，再測試 API。

Frontend 要調整什麼？

Frontend 不需要 SQL 權限，也不應取得 Backend 的 SQL credentials。

Frontend 需要確認：

• 使用正確的 Frontend image。
• 使用新的 Backend API URL。
• Nginx 或其他 web server 沒有寫死舊的 Backend hostname。
• 只有必要的 frontend secrets 被注入。

Frontend 只呼叫 Backend API；SQL connection 由 Backend 負責。

安全設定

這個 Demo 方案至少要符合以下原則：

• MSSQL App 只有 internal ingress。
• 不對 Internet 公開 TCP 1433。
• SA password 和 application password 都放在 secret。
• Backend 使用專用 application login，不使用 SA。
• 不把 SQL credentials 寫入 Git repository。
• 不讓 Frontend 取得 SQL credentials。
• 監控 container restart、CPU、memory、storage 和 backup。
• 為 Demo 設定 owner、用途和到期日。
• Demo 結束後移除 App、secret、volume 和 backup。

驗證清單

部署完成後，依照以下順序驗證：

1. MSSQL App revision 是 Healthy / Running。
2. Backend 可以解析 MSSQL App 的 internal FQDN。
3. Backend 可以建立 TCP 1433 connection。
4. demoproject-demo database 存在。
5. Backend application login 可以登入。
6. schema migration 和 seed data 成功。
7. Backend API 可以正常讀寫 Demo database。
8. Backend 重啟後仍然可以重新連線。
9. MSSQL container 重啟後，volume 和 database recovery 正常。
10. Frontend 使用正確的 Backend URL。
11. 沒有任何元件對 Internet 公開 SQL 1433。

這個方案解決什麼、不解決什麼？

Demo 結束後

這個方案應該被明確記錄為：

temporary isolated demo database

Demo 結束時，依序完成：

1. 匯出真正需要保留的 Demo 結果。
2. 停止不再使用的 Backend 和 Frontend revision。
3. 移除 SQL secrets 和 application credentials。
4. 備份或刪除 Demo database volume。
5. 刪除 MSSQL Container App。
6. 清理 ACR 中不再使用的 Demo image。
7. 確認後續部署不會誤連到 demoproject-demo。

總結

在 cae-example-dev-001 自架 MSSQL container，可以讓 Example Company 快速得到一個不依賴既有 Azure SQL 的隔離 Demo database。這個方法適合短期展示和功能驗證，但不是把正式資料庫搬進 Container App，也不是正式 production database 的替代品。

真正需要完成的工作不只是部署一個 MSSQL image，還包括：

• 建立獨立的 MSSQL App。
• 只開放 internal TCP 1433。
• 建立專用 application login。
• 將 Backend connection string 改成新的 Demo database。
• 初始化 schema 和 seed data。
• 決定是否需要持久化 storage 和 backup。
• 將 database bootstrap 與一般 Backend CI/CD 分開。
• 加入 health check、connection retry 和 logs 保護。
• 在 Demo 結束後完整清理資源。

Demo 資料說明

這是一份可以單獨閱讀的教學用範例。所有專案名稱、公司名稱、GitHub repository、Azure 資源名稱、網域、帳號與 tenant 名稱都是虛構資料，不能直接拿來連線或部署。請依照實際環境替換成自己的設定。

這份文件要解決什麼問題

Example Company 的開發團隊希望使用 GitHub Actions 做 Azure CI/CD，流程如下：

1. GitHub Actions 將程式編譯成 container image。
2. 將 image push 到 Azure Container Registry（ACR）。
3. 更新 Azure Container App，讓 App 使用新的 image。
4. Backend 啟動後，透過 Microsoft Entra Managed Identity 連線到 Azure SQL Database。

目前遇到的問題通常會長這樣：

• GitHub Actions 可以登入 Azure，但 Container App 啟動時無法從 ACR 拉 image。
• Container App 的部署指令顯示成功，但新的 revision 變成 ActivationFailed。
• Backend image 可以啟動，卻因為沒有 SQL contained user 或 database role 而無法登入資料庫。
• App 位於沒有 VNet 路徑的 Container Apps Environment，因此連不到 SQL Private Endpoint。
• Frontend 還在使用舊的 Harbor image 或舊的 Backend hostname。
• 舊的部署系統與 Azure GitHub Actions 同時執行，造成兩邊互相覆蓋部署結果。

這些現象看起來都像「權限問題」，但實際上分屬四個不同層次：

1. GitHub Actions 的 CI 身分能不能登入 Azure、push image、更新 App。
2. Container App 執行時的 Managed Identity 能不能從 ACR pull image。
3. Backend 的 Managed Identity 能不能登入 SQL Database。
4. Container Apps Environment 是否有通往 SQL Private Endpoint 的網路路徑。

Demo 情境與資源

以下名稱全部是示意資料：

• 公司：Example Company
• GitHub organization/repository：example-company/demo-backend
• Subscription：Demo-Subscription
• App/ACR Resource Group：rg-demo-stg-001
• 共用 Container Apps Environment：cae-demo-stg-001
• 共用 CAE 所在 Resource Group：rg-cae-demo-stg-001
• ACR：acrdemostg001.azurecr.io
• SQL Server：sql-demo-stg-001.database.windows.net
• SQL Database：demoproject-dev
• SQL Private Endpoint：pe-sql-demo-stg-001
• VNet：vnet-demo-stg-001

預期使用的兩個 Container App 是：

另外，情境中有一組不建議繼續使用的舊 App：

正確的目標架構

完整的部署與連線路徑應該是：

GitHub Actions
    │ OIDC，取得短期 token
    ▼
GitHub CI Service Principal
    │ AcrPush + Container App update
    ▼
Azure Container Registry
    │ image push
    ▼
Container App（共用 cae-demo-stg-001）
    │ App 自己的 system-assigned Managed Identity
    ├─ ACR AcrPull
    ├─ Key Vault secret get/list（如果 App 使用 Key Vault）
    └─ Azure SQL Entra token
          │
          ▼
    VNet + Private DNS + SQL Private Endpoint
          │
          ▼
    demoproject-dev

最重要的觀念是：

GitHub Actions 的 Service Principal 負責部署，不是執行中的 App。
真正需要 pull image 和連 SQL 的，是各個 Container App 自己的 Managed Identity。

CI/CD 的正確流程

1. GitHub Actions 使用 OIDC 登入 Azure

GitHub Actions 不應把長期的 Azure client secret 放在 repository。建議使用 OIDC：

- name: Login to Azure
  uses: azure/login@v2
  with:
    client-id: ${{ vars.AZURE_CLIENT_ID }}
    tenant-id: ${{ vars.AZURE_TENANT_ID }}
    subscription-id: ${{ vars.AZURE_SUBSCRIPTION_ID }}

示範用的 Federated Credential subject 是：

repo:example-company/demo-backend:ref:refs/heads/main

如果 workflow 使用 GitHub Environment，例如 staging，subject 和 variables 的 scope 都要跟 GitHub Environment 的設定一致，不能只改其中一邊。

2. CI 身分將 image push 到 ACR

示範用的 image repository 是：

acrdemostg001.azurecr.io/demo-backend:<github.sha>

GitHub CI Service Principal 需要 AcrPush，但不需要 runtime AcrPull。

AcrPush = GitHub Actions 將 image 推進 ACR
AcrPull = Container App 啟動時從 ACR 拉出 image

demo-backend 在第一次成功 docker push 前可能還不會出現在 ACR repository list 中。ACR 通常會在第一次 push 時建立 repository，這不是權限錯誤。

3. CI 身分更新正確的 Container App

部署 Backend 時，target 應該是位於共用 CAE 的 App：

az containerapp update \
  --resource-group rg-demo-stg-001 \
  --name ca-demo-backend-dev-001 \
  --image acrdemostg001.azurecr.io/demo-backend:${GITHUB_SHA}

這個指令成功只代表 Azure 接受了 App 設定更新，不代表新的 revision 一定能啟動。接下來還要檢查 runtime identity 是否能 pull image。

4. Container App 使用自己的 Managed Identity pull image

Backend 和 Frontend 都要各自完成以下設定：

• 啟用 system-assigned Managed Identity。
• 將該 App 的 identity 在 ACR scope 授予 AcrPull。
• 將 Container App registry authentication 設為 identity: system。

可用以下指令設定 registry identity：

az containerapp registry set \
  --resource-group rg-demo-stg-001 \
  --name ca-demo-backend-dev-001 \
  --server acrdemostg001.azurecr.io \
  --identity system

Frontend App 也要使用相同方式設定，只是 --name 改為 ca-demo-frontend-dev-001。

檢查 App identity、Environment、registry 與 image：

az containerapp show \
  --resource-group rg-demo-stg-001 \
  --name ca-demo-backend-dev-001 \
  --query "{identity:identity,environment:properties.managedEnvironmentId,registries:properties.configuration.registries[].{server:server,identity:identity},images:properties.template.containers[].image}" \
  -o json

檢查 runtime identity 是否有 ACR AcrPull：

az role assignment list \
  --assignee-object-id <BACKEND_APP_PRINCIPAL_ID> \
  --scope "$(az acr show \
    --resource-group rg-demo-stg-001 \
    --name acrdemostg001 \
    --query id -o tsv)" \
  --query "[].{role:roleDefinitionName,scope:scope}" \
  -o table

Frontend 使用自己的 <FRONTEND_APP_PRINCIPAL_ID> 查詢，不要共用 Backend 的 identity。

如果 App 沒有 AcrPull，常見結果是：

• az containerapp update 指令本身成功。
• revision 建立了，但狀態是 ActivationFailed。
• logs 或 revision events 出現 image pull、registry authentication 或 unauthorized 錯誤。

這時應該補在 Container App 的 Managed Identity，不能把 AcrPull 加到 GitHub OIDC Service Principal 代替。

Backend 存取 SQL Database

SQL 身分的分工

Backend 不應把 SQL username/password 寫進 GitHub Secrets 或 container environment。建議使用：

1. Backend App 的 system-assigned Managed Identity 取得 Microsoft Entra token。
2. SQL Entra administrator 在 demoproject-dev 建立對應的 contained user。
3. 只授予 Backend 實際需要的 database roles。

示範用的 database URL 概念如下：

sqlserver://sql-demo-stg-001.database.windows.net:1433
  ?database=demoproject-dev
  &encrypt=true
  &trustservercertificate=false
  &fedauth=ActiveDirectoryManagedIdentity
  &useMsi=true

建立 contained user 與 database roles

以下 SQL 必須由 SQL Microsoft Entra administrator 或有足夠 database 權限的管理者，在 demoproject-dev database 執行：

CREATE USER [ca-demo-backend-dev-001] FROM EXTERNAL PROVIDER;

再依照應用程式需要授予角色：

ALTER ROLE [db_datareader]
ADD MEMBER [ca-demo-backend-dev-001];

ALTER ROLE [db_datawriter]
ADD MEMBER [ca-demo-backend-dev-001];

-- 只有需要由 App 執行 schema migration 時才授予
ALTER ROLE [db_ddladmin]
ADD MEMBER [ca-demo-backend-dev-001];

這些是 SQL Database 裡的 data-plane permissions，不是 Azure Resource Group RBAC。因此 az role assignment list 看不到 db_datareader、db_datawriter 或 db_ddladmin membership。

可以在 SQL 中確認：

SELECT
    dp.name AS database_principal,
    rp.name AS database_role
FROM sys.database_role_members AS drm
JOIN sys.database_principals AS rp
    ON rp.principal_id = drm.role_principal_id
JOIN sys.database_principals AS dp
    ON dp.principal_id = drm.member_principal_id
WHERE dp.name = N'ca-demo-backend-dev-001';

Frontend 不需要 SQL 權限，也不應為 Frontend 建立 SQL contained user。

SQL 網路路徑

即使 SQL user/roles 都正確，網路不通時仍然無法連線。

Demo 情境中的網路設計是：

• pe-sql-demo-stg-001 的狀態為 Approved。
• Private DNS zone privatelink.database.windows.net 連結到 vnet-demo-stg-001。
• 共用 cae-demo-stg-001 有正確的 VNet/infrastructure subnet 路徑。
• App 放在共用 CAE，才能透過 Private Endpoint 解析並連線到 SQL。

舊的 cae-example-dev-001 沒有這條 infrastructure subnet 路徑，因此不適合作為需要存取 Private SQL 的 target。

看到下面的錯誤時，優先檢查 CAE、VNet、Private DNS 和 Private Endpoint：

Client with IP address ... is not allowed to access the server

不要為了繞過問題，直接把 SQL firewall 開成 0.0.0.0。這會把網路問題變成不必要的公開暴露。

看到下面的錯誤時，優先檢查 Managed Identity、contained user 和 database roles：

Login failed

開發者帳號能做什麼

示範開發者帳號是 demo.user@example.com，在 demo tenant 中的 UPN 示意如下：

demo_user_example.com#EXT#@exampletenant.onmicrosoft.com

示範直接授予的 Azure roles：

因此，這個帳號可以：

• 建立或更新 App。
• 將 App 放進共用 cae-demo-stg-001。
• Push image 到 ACR。

但這個帳號不能：

• 建立 Azure RBAC role assignment。
• 替新的 App 授予 ACR AcrPull。
• 修改 SQL Private Endpoint、VNet 或 SQL firewall。
• 在 demoproject-dev 建立 Entra contained user。
• 授予或修改 SQL database roles。

這是刻意的權限邊界：開發者可以部署應用程式，但不能自行擴大 App 的 Azure 權限或資料庫權限。需要新增 AcrPull 或 SQL user/roles 時，應請平台管理者或 SQL Entra administrator 處理。

舊 App 如何切換到共用 CAE

Azure Container Apps 沒有提供用 az containerapp update 直接切換 Environment 的參數。既有 App 不能像更新 image 一樣，直接從：

cae-example-dev-001

搬到：

cae-demo-stg-001

較安全的切換方式是：

1. 在共用 CAE 建立新的 Container App，或使用已準備好的 ca-demo-backend-dev-001 / ca-demo-frontend-dev-001。
2. 逐項複製必要的 environment variables、secrets、ingress、domain、scale 和 traffic 設定。
3. 啟用新 App 的 system-assigned Managed Identity。
4. 由平台管理者授予新 identity ACR AcrPull。
5. 由 SQL Entra administrator 替新的 Backend identity 建立 SQL user/roles。
6. 將 CI/CD 的 target App name 改成新的 App。
7. 驗證 revision、logs、API、Frontend URL、ACR pull 與 SQL 連線。
8. 新 App 穩定後，才考慮移除舊 App。

不要先刪除舊 App 再重建，因為可能遺失 secrets、domain、ingress、traffic 和原本的部署設定。

Frontend 的特別注意事項

Frontend 只需要：

• 從 ACR pull image。
• 連到正確的 Backend URL。
• 必要時讀取自己的 Key Vault secrets。

Frontend 不需要 demoproject-dev 的 SQL roles。

如果 Frontend revision 是 ActivationFailed，但 AcrPull 已經正確，請檢查：

• image 內的 Nginx upstream 設定。
• BACKEND_URL 或其他 Backend endpoint environment variable。
• image 是否仍然包含舊的 backend.legacy.example.invalid hostname。
• 新 image 是否真的已 push 到 ACR，且 App 使用了正確 tag。

這類問題通常是 image/configuration 問題，不是 SQL 權限問題。

建議的執行順序

平台管理者與開發團隊可以依照以下順序處理：

1. 確認 GitHub OIDC Federated Credential 的 repository、branch 和 Environment subject 正確。
2. 確認 CI Service Principal 只有部署所需的 Contributor、AcrPush 等角色。
3. 確認 Backend 和 Frontend 都位於 cae-demo-stg-001。
4. 啟用兩個 App 的 system-assigned identity。
5. 對兩個 App identity 各自授予 ACR AcrPull。
6. 執行 az containerapp registry set --identity system。
7. 由 SQL Entra administrator 建立 Backend contained user 和必要 roles。
8. 確認 CAE、VNet、Private DNS、Private Endpoint 的網路路徑。
9. 只啟用一條正式部署路徑，避免舊 pipeline 和 Azure CI/CD 同時更新同一個 App。
10. 做一次受控部署，逐項檢查 image、revision、logs、API、Frontend 和 SQL。

部署後驗證指令

確認 ACR image tag

az acr repository show-tags \
  --name acrdemostg001 \
  --repository demo-backend \
  --orderby time_desc \
  --top 5 \
  -o table

確認 Backend revision

az containerapp revision list \
  --resource-group rg-demo-stg-001 \
  --name ca-demo-backend-dev-001 \
  --query "[].{name:name,health:properties.healthState,running:properties.runningState,traffic:properties.trafficWeight}" \
  -o table

正常情況應看到 revision 為 Healthy，且 running state 正常。若 revision 建立成功但沒有 running，請查 revision events 和 container logs。

查看 Backend logs

az containerapp logs show \
  --resource-group rg-demo-stg-001 \
  --name ca-demo-backend-dev-001 \
  --type console \
  --tail 100

最後確認的成功條件

• GitHub Actions OIDC login 成功。
• image 成功 push 到 acrdemostg001.azurecr.io。
• Backend 和 Frontend revision 能從 ACR pull image。
• Backend revision 為 Healthy / Running。
• Backend 能以 Managed Identity 取得 SQL token。
• SQL contained user 與必要 roles 存在。
• Backend 能連線到 demoproject-dev。
• Frontend 使用新的 Backend URL。
• 舊的部署系統不會再覆蓋 Azure CI/CD 的結果。

企業或專案引進「新開發團隊」接手部署時，常見的權限混亂、安全風險與網路連線問題。主要包含以下四大核心問題：

• 權限與安全問題：避免為了部署而過度授予高風險權限（例如 Azure Owner 或 SQL 權限），並改用 GitHub Actions OIDC 取代長期保存的明文金鑰（ secrets ）。
• 責任分工不明確：清楚劃分「平台管理者」與「開發團隊」的職責邊界，防止開發團隊誤動基礎架構（如 SQL Firewall、VNet ）。
• 網路連線與架構問題：解決 Container App 因未走正確的 VNet 與 Private Endpoint 導致無法連線至 Azure SQL Database 的問題。
• 新手上手缺乏規範：提供明確的跨團隊開發指南、 CI/CD 自動化流程範本與開通檢查表，縮短團隊上手時間。

demoproject 與 ExampleOrg 只是示範名稱。正式環境使用前，必須由 平台管理者替換所有 <PLACEHOLDER> 與範例資源名稱，並確認權限範圍。

1. 先看結論

新加入的開發團隊平常只需要：

1. 取得 GitHub repository 與必要的 Azure RBAC 權限。
2. 使用平台管理者準備好的共用 Container Apps Environment。
3. 透過 GitHub Actions OIDC 登入 Azure，不使用長期 client secret。
4. Build Docker image、push 到 ACR、更新既有 Container App。
5. 透過 revision 與 logs 查看部署結果。

新加入的開發團隊不需要：

• Azure Owner。
• SQL Resource Group 的 Contributor。
• 直接修改 SQL firewall、Private Endpoint、VNet 或 Private DNS。
• 在 GitHub repository 中存放 SQL 密碼或應用程式 secrets。
• 每次部署都執行完整的基礎資源建立流程。

應用程式連接 SQL 的權限不是由 GitHub Actions Service Principal 提供， 而是由 Backend Container App 自己的 Managed Identity 在資料庫中取得。

2. Azure 服務白話說明

Azure RBAC 與 SQL 權限不是同一件事

• Azure Contributor 可以管理 Azure Resource Manager 資源，不等於可以 查詢 SQL table。
• SQL db_datareader 可以讀資料，不等於可以修改 Azure SQL Server。
• SQL db_datawriter 可以寫資料。
• SQL db_ddladmin 可以執行部分資料庫結構變更，應只授予需要執行 migration 的 Backend identity。
• SQL firewall 與 Private Endpoint 決定「網路能不能到 SQL」；資料庫 roles 只有在網路已連通後才會生效。

3. DemoProject 資源地圖

以下名稱全部是示範值：

3.1 建議的網路路徑

Backend Container App
    |
    |  共用 CAE 的 VNet 網路
    v
vnet-demoproject-stg
    |
    |  Private DNS 將 SQL hostname 解析到私有 IP
    v
SQL Private Endpoint pe-demoproject-sql-stg
    |
    v
sql-demoproject-stg / demoproject-dev

如果 Container App 位於沒有 VNet/private DNS 的獨立 CAE，它可能會透過 公網出口 IP 連線 SQL，並收到：

Client with IP address '...' is not allowed to access the server

遇到這個錯誤時，先確認 App 所在 CAE 與 DNS 路徑，不要立刻把大量公網 IP 加進 SQL firewall。

4. 權限模型

4.1 開發者與 CI 的建議權限

Container Apps Environment Joiner 應只包含：

Microsoft.App/managedEnvironments/join/action

不要為了讓團隊部署而授予共用 CAE Resource Group 的 Contributor。

4.2 平台管理者與開發團隊分工

平台管理者一次性完成：

1. 建立 App Registration 與 Service Principal。
2. 建立指定 repository、branch 或 GitHub Environment 的 Federated Credential。
3. 在 ACR scope 授予 AcrPush。
4. 在既有 Container App scope 授予更新權限。
5. 在共用 CAE scope 授予 Reader 與 Container Apps Environment Joiner。
6. 確認 App runtime Managed Identity 具備 ACR、Key Vault 與 SQL 權限。
7. 確認 App 位於正確的 VNet/private DNS CAE。

開發團隊負責：

1. 維護 GitHub Actions workflow。
2. Build Docker image。
3. Push image 到 ACR。
4. 更新既有 Container App。
5. 查看 revision 與 logs。

開發團隊不應該：

• 建立或刪除 Service Principal。
• 修改 SQL firewall、Private Endpoint、VNet 或 Private DNS。
• 將 App secrets 寫入 repository 或 workflow。
• 執行 SQL CREATE USER。
• 修改共用 CAE 的網路設定。

5. GitHub Actions OIDC

5.1 OIDC 如何運作

GitHub push to main
        |
        | GitHub 發出短期 OIDC token
        v
GitHub Actions
        |
        | azure/login@v2
        v
Microsoft Entra App / Service Principal
        |
        | Federated Credential 比對 repo + branch/environment
        | Azure RBAC 比對允許的 scope
        v
ACR push -> Container App update

OIDC 不等於自動擁有 Azure 權限：

• Federated Credential 決定「哪個 GitHub workflow 可以登入」。
• Azure RBAC 決定「登入後可以做什麼」。

5.2 新團隊專用 Service Principal

建議每個團隊、每個環境使用不同 Service Principal。不要讓所有團隊共用 一個可寫入 Staging 的 identity。

以下是示範值：

SP display name: demoproject-team-a-staging-ci
Client ID:       <APP_CLIENT_ID>
Object ID:       <SERVICE_PRINCIPAL_OBJECT_ID>
Tenant ID:       <TENANT_ID>
Subscription ID: <SUBSCRIPTION_ID>

不需要建立 client secret。

5.3 角色配置範例

以下指令只展示格式，執行前請替換所有 placeholder：

set -euo pipefail

SUB_ID="<SUBSCRIPTION_ID>"
APP_RG="rg-demoproject-stg-app"
CAE_RG="rg-demoproject-stg-cae"
CAE_NAME="cae-demoproject-stg"
ACR_NAME="acr-demoproject-stg"
SP_NAME="demoproject-team-a-staging-ci"

CAE_SCOPE="$(az containerapp env show \
  --subscription "$SUB_ID" \
  --resource-group "$CAE_RG" \
  --name "$CAE_NAME" \
  --query id -o tsv)"

ACR_SCOPE="$(az acr show \
  --subscription "$SUB_ID" \
  --resource-group "$APP_RG" \
  --name "$ACR_NAME" \
  --query id -o tsv)"

APP_ID="$(az ad app create \
  --display-name "$SP_NAME" \
  --query appId -o tsv)"

SP_OBJECT_ID="$(az ad sp create \
  --id "$APP_ID" \
  --query id -o tsv)"

az role assignment create \
  --subscription "$SUB_ID" \
  --assignee-object-id "$SP_OBJECT_ID" \
  --assignee-principal-type ServicePrincipal \
  --role "AcrPush" \
  --scope "$ACR_SCOPE"

az role assignment create \
  --subscription "$SUB_ID" \
  --assignee-object-id "$SP_OBJECT_ID" \
  --assignee-principal-type ServicePrincipal \
  --role "Reader" \
  --scope "$CAE_SCOPE"

az role assignment create \
  --subscription "$SUB_ID" \
  --assignee-object-id "$SP_OBJECT_ID" \
  --assignee-principal-type ServicePrincipal \
  --role "Container Apps Environment Joiner" \
  --scope "$CAE_SCOPE"

若 CI 只更新既有 App，建議把寫入權限限制在 App resource scope：

BACKEND_SCOPE="$(az containerapp show \
  --subscription "$SUB_ID" \
  --resource-group "$APP_RG" \
  --name "ca-demoproject-backend-stg" \
  --query id -o tsv)"

az role assignment create \
  --subscription "$SUB_ID" \
  --assignee-object-id "$SP_OBJECT_ID" \
  --assignee-principal-type ServicePrincipal \
  --role "Contributor" \
  --scope "$BACKEND_SCOPE"

不要把 CI identity 授予：

rg-demoproject-stg-data
rg-demoproject-stg-cae 的 Contributor
demoproject-dev 的 SQL roles

5.4 Federated Credential

方案 A：只允許 main branch

適合單一 staging deploy workflow：

REPO="ExampleOrg/demoproject-backend"
SAFE_NAME="${REPO//\//-}-main"
SUBJECT="repo:${REPO}:ref:refs/heads/main"

PAYLOAD="$(jq -n \
  --arg name "$SAFE_NAME" \
  --arg subject "$SUBJECT" \
  '{
    name: $name,
    issuer: "https://token.actions.githubusercontent.com",
    subject: $subject,
    audiences: ["api://AzureADTokenExchange"]
  }')"

az ad app federated-credential create \
  --id "$APP_ID" \
  --parameters "$PAYLOAD"

方案 B：使用受保護的 GitHub Environment

新團隊建議建立 GitHub Environment staging，設定：

• Required reviewers。
• 只允許 main branch 或指定 tag。
• 將 Azure identifiers 放在 Environment variables。

Federated Credential 的 subject 改為：

repo:ExampleOrg/demoproject-backend:environment:staging

Workflow 的 deploy job 必須包含：

environment: staging

Branch subject 與 Environment subject 不要混用。Azure 會比對完整的 sub claim，字串不完全相同就會登入失敗。

PR 不可取得 write token

以下 subject 不可綁定到具有 Contributor、AcrPush 或 App write 的 identity：

repo:ExampleOrg/demoproject-backend:pull_request

PR 程式碼尚未審核，可能修改 workflow 並呼叫 Azure CLI。PR workflow 應只 執行 lint、test、build；若真的需要查詢 Azure，另建只有 Reader 的 identity。

6. GitHub Actions Workflow 範本

以下範例使用受保護的 staging Environment。若使用 main branch subject， 請移除 environment: staging，或先建立相符的 Environment Federated Credential。

name: Deploy DemoProject Backend

on:
  push:
    branches:
      - main

permissions:
  contents: read
  id-token: write

jobs:
  deploy:
    runs-on: ubuntu-latest
    environment: staging
    steps:
      - name: Checkout
        uses: actions/checkout@v4

      - name: Login to Azure with OIDC
        uses: azure/login@v2
        with:
          client-id: ${{ vars.AZURE_CLIENT_ID }}
          tenant-id: ${{ vars.AZURE_TENANT_ID }}
          subscription-id: ${{ vars.AZURE_SUBSCRIPTION_ID }}

      - name: Login to ACR
        run: az acr login --name acr-demoproject-stg

      - name: Build and push image
        env:
          IMAGE: acr-demoproject-stg.azurecr.io/demoproject-backend:${{ github.sha }}
        run: |
          docker build -t "$IMAGE" .
          docker push "$IMAGE"

      - name: Update existing Container App
        env:
          IMAGE: acr-demoproject-stg.azurecr.io/demoproject-backend:${{ github.sha }}
        run: |
          az containerapp update \
            --resource-group rg-demoproject-stg-app \
            --name ca-demoproject-backend-stg \
            --image "$IMAGE"

Frontend 只需要替換 image repository 與 Container App name。

6.1 PR Workflow

PR workflow 不應取得 Azure write token：

on:
  pull_request:
    branches:
      - main

permissions:
  contents: read

PR 可執行 lint、unit test、build 或不涉及 Staging 的 container build， 但不要：

• id-token: write。
• azure/login。
• Push Staging ACR。
• Update 或 delete Container App。

6.2 不要在 CI 執行完整部署腳本

完整部署腳本通常會包含 secrets、Key Vault policy、Managed Identity、 SQL 授權與首次建立資源的流程，不適合直接放進 GitHub Actions。

CI 建議只做：

OIDC login
  -> docker build
  -> ACR push
  -> containerapp update --image

既有的環境變數與 secrets 由平台管理者預先設定；App runtime 使用自己的 Managed Identity 連接 SQL 與 Key Vault。

7. SQL Database 與 Managed Identity

7.1 App runtime 才需要 SQL role

查詢 Backend App 的 Managed Identity：

az containerapp show \
  --subscription "<SUBSCRIPTION_ID>" \
  --resource-group "rg-demoproject-stg-app" \
  --name "ca-demoproject-backend-stg" \
  --query "{type:identity.type,principalId:identity.principalId}" \
  -o json

如果 Container App 被刪除後重新建立，system-assigned identity 可能改變。 管理者需要重新確認 ACR、Key Vault 與 SQL 權限。

7.2 建立 SQL contained user

以下 SQL 應由 SQL Entra administrator 或等效資料庫管理員，在 demoproject-dev 執行。將 App name 替換成實際值：

IF DATABASE_PRINCIPAL_ID(N'ca-demoproject-backend-stg') IS NULL
BEGIN
    CREATE USER [ca-demoproject-backend-stg] FROM EXTERNAL PROVIDER;
END;

ALTER ROLE [db_datareader]
ADD MEMBER [ca-demoproject-backend-stg];

ALTER ROLE [db_datawriter]
ADD MEMBER [ca-demoproject-backend-stg];

-- 只有 Backend migration 確實需要時才授予
ALTER ROLE [db_ddladmin]
ADD MEMBER [ca-demoproject-backend-stg];

CI Service Principal 不需要執行這段 SQL，也不應被加入這三個 database roles。

7.3 人員需要直接查詢資料庫

不要把 Azure Contributor 當成 SQL data access。若確實需要讓人員直接 查詢：

1. 管理者建立 Microsoft Entra security group。
2. 將需要查詢的人員加入該群組。
3. 在 demoproject-dev 建立該群組的 contained user。
4. 優先只授予 db_datareader。
5. 確認使用者有 VNet、VPN 或其他 Private Endpoint 網路路徑。

8. Private Endpoint 與 SQL Firewall

8.1 為什麼不能只新增一個 IP？

獨立的 Container Apps Environment 可能使用公網出口 IP，而且出口 IP 可能有很多個或因環境變更而改變。錯誤訊息中的 IP 只代表當次連線， 不一定是永久 IP。

使用共用 CAE 時，應該走：

Container App
  -> VNet
  -> Private DNS
  -> SQL Private Endpoint
  -> SQL Database

不要用大量公網 IP firewall 規則取代正確的網路拓撲，也不要未經核准就 建立：

start-ip-address = 0.0.0.0
end-ip-address   = 0.0.0.0

這代表允許大範圍 Azure services 存取，不是只允許本團隊。

8.2 確認 App 使用正確 CAE

$expected = "/subscriptions/<SUBSCRIPTION_ID>/resourceGroups/rg-demoproject-stg-cae/providers/Microsoft.App/managedEnvironments/cae-demoproject-stg"

az containerapp show `
  --name ca-demoproject-backend-stg `
  --resource-group rg-demoproject-stg-app `
  --query properties.managedEnvironmentId `
  -o tsv

$expected

兩個輸出必須相同。如果 App 位於沒有 VNet/private DNS 的 CAE，先請平台 管理者確認網路路徑，不要先修改 SQL firewall。

8.3 常見錯誤

9. 部署後驗證

9.1 查看 App 所在 CAE 與 revision

az containerapp show `
  --name ca-demoproject-backend-stg `
  --resource-group rg-demoproject-stg-app `
  --query "{environment:properties.managedEnvironmentId,latest:properties.latestRevisionName,ready:properties.latestReadyRevisionName}" `
  -o table

az containerapp revision list `
  --name ca-demoproject-backend-stg `
  --resource-group rg-demoproject-stg-app `
  --query "[].{name:name,health:properties.healthState,running:properties.runningState,traffic:properties.trafficWeight}" `
  -o table

9.2 查看 logs

az containerapp logs show `
  --name ca-demoproject-backend-stg `
  --resource-group rg-demoproject-stg-app `
  --type console `
  --tail 100

9.3 驗證 CI 身分

az ad app federated-credential list \
  --id "$APP_ID" \
  --query "[].{name:name,subject:subject,issuer:issuer,audiences:audiences}" \
  -o table

az role assignment list \
  --assignee-object-id "$SP_OBJECT_ID" \
  --all \
  --query "[].{role:roleDefinitionName,scope:scope}" \
  -o table

應確認：

• issuer 是 https://token.actions.githubusercontent.com。
• audience 是 api://AzureADTokenExchange。
• subject 只有指定 repo 與指定 main/environment。
• 沒有 write identity 的 pull_request subject。
• 沒有 SQL Resource Group 或共用 CAE Resource Group 的 Contributor。

10. 首次 bootstrap 與日常部署

10.1 首次 bootstrap

以下工作由平台管理者完成一次：

• 建立 ACR、CAE、Container App 或確認資源已存在。
• 建立 App Registration、Service Principal 與 Federated Credentials。
• 授予 CI 的 ACR/App/CAE 角色。
• 啟用 App system-assigned Managed Identity。
• 授予 App identity AcrPull、Key Vault get/list 與 SQL roles。
• 設定 Private Endpoint、Private DNS、custom domain 與憑證。

如果共用 CAE 暫時不存在，不要讓腳本建立沒有 VNet/private endpoint 的替代 環境；應停止流程並通知平台管理者。

10.2 日常部署

日常 CI 只需：

main push
  -> GitHub OIDC login
  -> build image
  -> push ACR
  -> update existing Container App
  -> check revision and logs

如果 App 被刪除並重新建立，請重新取得 identity，重新處理 ACR、Key Vault 與 SQL 授權。

11. 撤權與團隊交接

11.1 移除某個 repository 的信任

az ad app federated-credential list \
  --id "$APP_ID" \
  --query "[].{id:id,name:name,subject:subject}" \
  -o table

az ad app federated-credential delete \
  --id "$APP_ID" \
  --federated-credential-id "<FEDERATED_CREDENTIAL_ID>"

11.2 移除 Azure role

az role assignment delete \
  --assignee-object-id "$SP_OBJECT_ID" \
  --role "AcrPush" \
  --scope "$ACR_SCOPE"

團隊撤換時同時確認：

1. GitHub Environment/repository variables 已移除。
2. 該 repository 的 Federated Credentials 已刪除。
3. App、ACR、CAE scope 的 role assignments 已移除。
4. Container App runtime Managed Identity 沒有被誤刪。
5. Audit log 與變更紀錄已保存。

12. 新團隊開通檢查表

平台管理者

• [ ] 所有資源名稱、Subscription、tenant 與 repo 已確認。
• [ ] 每個團隊建立獨立 Service Principal。
• [ ] 只建立 main 或受保護 Environment 的 Federated Credential。
• [ ] 沒有建立 write identity 的 pull_request credential。
• [ ] ACR scope 有 AcrPush。
• [ ] 既有 App scope 有更新權限。
• [ ] 共用 CAE scope 有 Reader + Container Apps Environment Joiner。
• [ ] 沒有授予 SQL Resource Group 或共用 CAE Resource Group Contributor。
• [ ] App runtime Managed Identity 有 SQL、Key Vault、ACR 權限。
• [ ] GitHub Environment 的 reviewers 與 branch restriction 已設定。

開發團隊

• [ ] Workflow 有 permissions: id-token: write。
• [ ] environment 或 branch subject 與 Azure FIC 完全一致。
• [ ] 使用 azure/login@v2，沒有 client secret。
• [ ] Docker image 使用不可變的 commit SHA tag。
• [ ] Push 到正確 ACR repository。
• [ ] 只更新指定 Container App。
• [ ] PR workflow 沒有 Azure write token。
• [ ] 部署後確認 revision、logs 與功能。

13. 示範值替換清單

正式使用前，至少替換以下項目：

替換後請再次搜尋以下字串，確認沒有殘留示範 placeholder 或錯誤環境：

<SUBSCRIPTION_ID>
<TENANT_ID>
ExampleOrg
demoproject

14. 安全規則

1. 不要把 client secret、SQL password、JWT secret 或 storage connection string commit 到 Git。
2. 不要把 secrets 貼到 PR、Issue、聊天工具或 deployment log。
3. 不要為了快速測試把 SQL firewall 設成 0.0.0.0 - 0.0.0.0。
4. 不要把 SQL Resource Group 的 Contributor 當成 SQL data access。
5. 不要把 write-capable Azure identity 授予 pull_request。
6. 不要自行刪除共用 CAE、Private Endpoint、Private DNS 或 SQL Server。
7. 遇到錯誤時，先記錄 repository、workflow run、revision 與錯誤時間， 再請平台管理者檢查權限與網路。

15. 官方參考文件

• GitHub OIDC on Azure： https://docs.github.com/en/actions/how-tos/secure-your-work/security-harden-deployments/oidc-in-azure
• GitHub OIDC subject reference： https://docs.github.com/en/actions/reference/security/oidc
• Azure Login with OIDC： https://learn.microsoft.com/en-us/azure/developer/github/connect-from-azure-openid-connect
• Azure Container Apps with GitHub Actions： https://learn.microsoft.com/en-us/azure/container-apps/github-actions

本文件說明未來新的開發團隊如何在沒有 Azure Owner role 的情況下，使用 GitHub Actions 將 Backend 或 Frontend 部署到專案 Staging。

文件目標是讓接手環境管理工作的同仁能快速回答以下問題：

• 為什麼不需要把 Azure client secret 放進 GitHub？
• 哪些工作必須由平台管理者做一次？
• 開發團隊需要哪些最小 Azure 權限？
• GitHub OIDC、Service Principal、Federated Credential、ACR 與 Container Apps 之間如何串接？
• 為什麼 PR 不可以直接取得可寫入 Staging 的 Azure token？
• SQL 權限應該給誰？

適用環境

本文件適用目前的專案 Staging：

• Subscription： DEMO-PoC
• App/ACR Resource Group： rg-demo-stg-jpe-001
• 共用 Container Apps Environment： cae-stg-jpe-001
• ACR： acrdemostgjpe001.azurecr.io
• SQL Server： sql-stg-jpe-001.database.windows.net
• SQL Database： demoproject-dev

重要

目前的 CI 身分由環境管理者建立，開發團隊只負責維護 GitHub Actions。不要要求開發團隊取得 Owner，也不要把 SQL Resource Group 的 Contributor 給開發團隊。

1. 先看整體流程

GitHub push to main
        |
        | GitHub 發出短期 OIDC token
        v
GitHub Actions
        |
        | azure/login@v2
        v
Microsoft Entra App / Service Principal
        |
        | Federated Credential 比對 repo + branch/environment
        | Azure RBAC 比對允許的 scope
        v
Azure Container Registry (AcrPush)
        |
        | push Docker image
        v
Azure Container App
        |
        | 使用 App 自己的 Managed Identity
        v
SQL Private Endpoint -> demoproject-dev

這裡有兩個不同的身分，聲明如下：

• GitHub Actions Service Principal：用途為 Build、push Image、更新 Container App。是否應有 SQL data access：否。
• Backend Container App Managed Identity：用途為執行中的 Backend 連接 SQL、ACR、Key Vault。是否應有 SQL data access：是，僅限該 App。

GitHub Actions 的 OIDC Service Principal 只負責部署。它不應該被加入 demoproject-dev 的 SQL roles，也不應該讀取應用程式 secrets。

2. 為什麼使用 OIDC

傳統做法是把 AZURE_CLIENT_SECRET 存在 GitHub Actions Secret。這會產生長期憑證管理問題：

• secret 可能被誤印到 log。
• secret 可能忘記輪替。
• 離職或團隊更換時，需要追查 secret 被放在哪裡。

OIDC 的做法是：

1. GitHub Actions 向 GitHub OIDC provider 取得短期 token。
2. Azure 驗證 token 的 issuer、subject 與 audience。
3. 只有符合 Federated Credential 條件的 workflow 才能換取 Azure access token。
4. Azure RBAC 再決定這個 Service Principal 可以操作哪些資源。

因此 OIDC 不等於「自動擁有 Azure 權限」：

• Federated Credential：決定「哪個 GitHub workflow 可以登入」。
• Azure RBAC：決定「登入後可以做什麼」。

3. 本次已建立的 CI 身分

本次已建立以下 CI Service Principal：

Display name: demoproject-staging-ci

Client ID: 188a7d0a-30d5-4a0d-9b04-3e118d3d46e7

Object ID: 33ec7c42-e5b5-443c-aae5-e97e1e056d10

Tenant ID: 7ef65350-5b77-4958-aca5-0ccadb6bd0b7

沒有建立 client secret。

3.1 目前已授予的角色

• Scope: rg-demo-stg-jpe-001 | Role: Contributor | 目的: 目前 CI 更新 App/ACR 的過渡權限
• Scope: acrdemostgjpe001 | Role: AcrPush | 目的: 允許 Docker push 到 ACR
• Scope: cae-stg-jpe-001 | Role: Reader | 目的: 讀取共用 CAE 設定
• Scope: cae-stg-jpe-001 | Role: Container Apps Environment Joiner | 目的: 允許使用共用 CAE；只有 Microsoft.App/managedEnvironments/join/action

目前沒有授予：

• rg-cae-stg-jpe-001 的 Contributor。
• rg-data-stg-jpe-001 的任何角色。
• demoproject-dev 的 SQL role。
• Key Vault data-plane secrets 讀取權限。

rg-demo-stg-jpe-001 的 Contributor 是為了讓現有流程先能運作的過渡方案。未來新增團隊時，建議改成各 App resource scope 的 Contributor 或專用 custom role，不要複製成每個團隊都能管理整個 RG。

3.2 目前已信任的 GitHub repositories

目前只建立以下兩個 main branch Federated Credentials：

repo:NYCUITSC/demoproject-backend:ref:refs/heads/main

repo:NYCUITSC/demoproject-frontend:ref:refs/heads/main

刻意沒有建立：

• pull_request credential。
• NYCUITSC/demoproject-api credential。

demoproject-api 目前是 Frontend 用來產生 SDK 的 dependency，不是 Azure deployment repository。除非它未來真的擁有部署 job，否則不要給它 Azure write identity。

4. 新團隊的責任分工

4.1 平台/環境管理者做一次

平台管理者需要：

1. 建立該團隊專用的 App Registration 與 Service Principal。
2. 建立只允許指定 repo、branch 或 GitHub Environment 的 Federated Credentials。
3. 在正確的 ACR scope 授予 AcrPush。
4. 在指定 Container App scope 授予更新權限。
5. 在共用 CAE 授予 Reader 與 Container Apps Environment Joiner。
6. 確認 Container App 的 Managed Identity 已具備 ACR、Key Vault 與 SQL 權限。
7. 確認 App 位於正確的共用 CAE，而不是沒有 VNet/private DNS 的獨立 CAE。
8. 將 Client ID、Tenant ID、Subscription ID 提供給團隊設定 GitHub Variables。

4.2 開發團隊負責

開發團隊只需要：

1. 維護 GitHub Actions workflow。
2. 在 main 或受保護的 staging Environment 執行 deploy。
3. Build Docker image。
4. Push image 到 ACR。
5. 更新既有 Container App 的 image。
6. 查看 revision 與 logs。

開發團隊不應該：

• 建立或刪除 Service Principal。
• 修改 SQL firewall、Private Endpoint 或 Private DNS。
• 將 App secret 寫進 GitHub workflow。
• 執行 SQL CREATE USER。
• 修改共用 CAE 的 VNet 設定。

5. 未來新增團隊的標準開通流程

以下流程由平台管理者執行。每個團隊建議有自己的 Service Principal，不要讓所有團隊共用一個可寫入 Staging 的 identity。

5.1 設定資源變數

以下是目前資源的範例。新增團隊時，App name 與 repo 名稱應換成新團隊實際值。

set -euo pipefail

SUB_ID=”56b72537-d985-4530-88f3-b6ed07e71c67″

APP_RG=”rg-demo-stg-jpe-001″

CAE_RG=”rg-cae-stg-jpe-001″

CAE_NAME=”cae-stg-jpe-001″

ACR_RG=”rg-demo-stg-jpe-001″

ACR_NAME=”acrdemostgjpe001″

每個團隊使用不同名稱，例如：

demoproject-sdc-team-2027-ci

SP_NAME=”demoproject-new-team-ci”

BACKEND_CA_NAME=”ca-demo-backend-dev-jpe-001″

FRONTEND_CA_NAME=”ca-demo-frontend-dev-jpe-001″

不要把 SQL Resource Group 放進 CI role scope：

rg-data-stg-jpe-001

5.2 建立 App Registration 與 Service Principal

執行者必須具備 Entra App 建立權限。建立 Azure role assignment 另外需要 Owner 或 User Access Administrator；新加入的開發團隊不需要具備這些管理權限。

APP_ID=”$(az ad app create

–display-name “$SP_NAME” \ –query appId -o tsv)” SP_OBJECT_ID=”$(az ad sp create

–id “$APP_ID”

–query id -o tsv)”

echo “clientId: $APP_ID”

echo “servicePrincipalObjectId: $SP_OBJECT_ID”

不要用以下方式反查 App ID：

az ad app list –display-name “$SP_NAME”

因為 display name 可能重複，會拿到錯誤的 App。

5.3 授予 CI 最小必要角色

先取得 resource IDs：

APP_SCOPE=”/subscriptions/${SUB_ID}/resourceGroups/${APP_RG}”

CAE_SCOPE=”$(az containerapp env show

–subscription “$SUB_ID”

–resource-group “$CAE_RG”

–name “$CAE_NAME” \ –query id -o tsv)” ACR_SCOPE=”$(az acr show

–subscription “$SUB_ID”

–resource-group “$ACR_RG”

–name “$ACR_NAME” \ –query id -o tsv)” BACKEND_SCOPE=”$(az containerapp show

–subscription “$SUB_ID”

–resource-group “$APP_RG”

–name “$BACKEND_CA_NAME” \ –query id -o tsv)” FRONTEND_SCOPE=”$(az containerapp show

–subscription “$SUB_ID”

–resource-group “$APP_RG”

–name “$FRONTEND_CA_NAME”

–query id -o tsv)”

長期建議只給既有 App scope 的 Contributor：

az role assignment create

–subscription “$SUB_ID”

–assignee-object-id “$SP_OBJECT_ID”

–assignee-principal-type ServicePrincipal

–role “Contributor”

–scope “$BACKEND_SCOPE”

az role assignment create

–subscription “$SUB_ID”

–assignee-object-id “$SP_OBJECT_ID”

–assignee-principal-type ServicePrincipal

–role “Contributor”

–scope “$FRONTEND_SCOPE”

CI push ACR 需要另外的 data-plane role：

az role assignment create

–subscription “$SUB_ID”

–assignee-object-id “$SP_OBJECT_ID”

–assignee-principal-type ServicePrincipal

–role “AcrPush”

–scope “$ACR_SCOPE”

使用共用 CAE 需要：

az role assignment create

–subscription “$SUB_ID”

–assignee-object-id “$SP_OBJECT_ID”

–assignee-principal-type ServicePrincipal

–role “Reader”

–scope “$CAE_SCOPE”

az role assignment create

–subscription “$SUB_ID”

–assignee-object-id “$SP_OBJECT_ID”

–assignee-principal-type ServicePrincipal

–role “Container Apps Environment Joiner”

–scope “$CAE_SCOPE”

若團隊需要由 CI 建立全新的 Container App，而不是更新既有 App，先由平台管理者評估是否真的需要 RG Contributor。可以先由管理者建立 App，再把後續 CI 限制為既有 App scope。

5.4 建立 Federated Credential

方案 A：只允許 main branch

適合簡單的單一 staging deploy workflow：

REPO=”NEW_ORG/NEW_REPO”

SAFE_NAME=”${REPO//\//-}-main” SUBJECT=”repo:${REPO}:ref:refs/heads/main”

PAYLOAD=”$(jq -n

–arg name “$SAFE_NAME”

–arg subject “$SUBJECT”

‘{name: $name, issuer: “https://token.actions.githubusercontent.com

“, subject: $subject, audiences: [“api://AzureADTokenExchange”] }’)”

az ad app federated-credential create

–id “$APP_ID”

–parameters “$PAYLOAD”

方案 B：使用受保護的 GitHub Environment（推薦新團隊）

在 GitHub repository 建立 staging Environment，設定：

• Required reviewers。
• 只允許 main branch 或指定 tag。
• 將 Azure identifiers 放在 Environment variables。

Federated Credential 的 subject 改為：

repo:NEW_ORG/NEW_REPO:environment:staging

Workflow 的 deploy job 必須設定：

environment: staging

Branch subject 與 Environment subject 不要混用。Azure 會比對完整的 sub claim，字串不完全相同就會登入失敗。

絕對不要把 write credential 給 pull_request

以下 subject 不可綁定到具有 Contributor、AcrPush 或 App write 的 identity：

repo:NEW_ORG/NEW_REPO:pull_request

PR 的程式碼尚未審核，任何可以修改 workflow 的 PR 都可能嘗試呼叫 Azure CLI。PR workflow 應只執行 lint/test/build；如果真的需要查詢 Azure，另建只有 Reader 的 CI identity。

5.5 提供 GitHub Variables

提供給團隊的只有識別資訊：

AZURE_CLIENT_ID =

AZURE_TENANT_ID = 7ef65350-5b77-4958-aca5-0ccadb6bd0b7

AZURE_SUBSCRIPTION_ID = 56b72537-d985-4530-88f3-b6ed07e71c67

不需要也不應該提供：

AZURE_CLIENT_SECRET

Client ID、Tenant ID、Subscription ID 本身不是登入密碼；真正的信任條件由 Azure Federated Credential 與 GitHub workflow permission 控制。

6. GitHub Actions Workflow 範本

以下範例使用「受保護 staging Environment」方案。若使用目前既有的 main branch credential，請移除 environment: staging，或先建立相符的 Environment Federated Credential。

name: Deploy Backend to Azure Staging

on:

push:

branches:

– main

permissions:

contents: read

id-token: write

jobs:

deploy:

runs-on: ubuntu-latest

environment: staging

steps:

– name: Checkout

uses: actions/checkout@v4

– name: Login to Azure with OIDC

uses: azure/login@v2

with:

client-id: ${{ vars.AZURE_CLIENT_ID }}

tenant-id: ${{ vars.AZURE_TENANT_ID }}

subscription-id: ${{ vars.AZURE_SUBSCRIPTION_ID }} – name: Login to ACR run: az acr login –name acrdemostgjpe001 – name: Build and push image env: IMAGE: acrdemostgjpe001.azurecr.io/demo-dev-backend:${{ github.sha }}

run: |

docker build -t “$IMAGE” .

docker push “$IMAGE” – name: Update existing Container App env: IMAGE: acrdemostgjpe001.azurecr.io/demo-dev-backend:${{ github.sha }}

run: |

az containerapp update

–resource-group rg-demo-stg-jpe-001

–name ca-demo-backend-dev-jpe-001

–image “$IMAGE”

Frontend 只需要替換 Image repository 與 Container App name。

6.1 不要在 CI 直接執行完整 deploy.dev.ps1

deploy.dev.ps1 適合管理者或本機部署流程，不適合直接放入 GitHub Actions，原因包括：

• 會要求 deploy.secrets.ps1。
• 會將應用程式 secrets 套用到 Container App。
• 會包含 Managed Identity、Key Vault policy、SQL 授權等 bootstrap 工作。
• 可能嘗試建立或修改基礎資源。

CI 的正常流程應是：

OIDC login -> docker build -> ACR push -> containerapp update –image

既有的環境變數與 secrets 由平台管理者預先設定；App runtime 使用自己的 Managed Identity 連接 SQL 與 Key Vault。

6.2 PR Workflow

PR workflow 不應取得 Azure write token：

on:

pull_request:

branches:

– main

permissions:

contents: read

PR 可執行 lint、unit test、build 或不涉及 Staging 的 container build，但不要：

• id-token: write。
• azure/login。
• Push Staging ACR。
• Update 或 delete Container App。

7. 目前既有 Workflow 的注意事項

目前 demoproject-backend/.github/workflows/dev.yaml 與 demoproject-frontend/.github/workflows/dev.yaml 的 Dev 流程原本是：

1. Build/test。
2. Push 到 harbor.sdc.nycu.club。
3. 呼叫 n8n deployment webhook。

建立 Azure OIDC identity 不會自動改變這些 workflow。若要切換到 Azure Container Apps：

1. 由團隊決定是否停止 Harbor+n8n deployment。
2. 將 Azure login、ACR push、Container App update 加入新的 deploy job。
3. 確認新 workflow 的 subject 與 Federated Credential 完全一致。
4. 先在 staging Environment 做一次受審核測試。
5. 確認 revision、logs、API version 與 Frontend URL 後，再移除舊流程。

不要讓 Harbor+n8n 與 Azure CI 同時部署同一個功能環境，否則最後一個完成的 pipeline 可能覆蓋前一個結果。

8. SQL 與網路權限不要放到 CI

8.1 CI identity 不需要 SQL role

CI Service Principal 只更新 Container App image。SQL runtime access 由 Backend Container App 的 system-assigned Managed Identity 處理：

GitHub CI identity -> ACR push -> Container App update

Backend App Managed Identity -> Private Endpoint -> demoproject-dev

如果 App 被刪除後重新建立，system-assigned identity 可能改變。平台/DB 管理者需要重新確認：

• AcrPull。
• Key Vault secret get/list。
• demoproject-dev contained user。
• db_datareader、db_datawriter、必要時 db_ddladmin。

8.2 CI identity 不需要修改 SQL firewall

目前 SQL 使用 Private Endpoint 與 Private DNS。應用程式應部署到有正確 VNet 路徑的共用 cae-stg-jpe-001。

遇到以下錯誤時，不要直接把 GitHub Actions Service Principal 加到 SQL 或把 firewall 設成 0.0.0.0：

Client with IP address ‘…’ is not allowed to access the server

這通常代表 Container App 位於沒有 VNet/private DNS 的 CAE，或 hostname 解析走到公網。請先檢查 App 的 managedEnvironmentId。

9. 驗證清單

9.1 管理者驗證 App 與 Federated Credentials

az ad app federated-credential list
--id "$APP_ID"
--query "[].{name:name,subject:subject,issuer:issuer,audiences:audiences}"
-o table

應確認：

• issuer 是 https://token.actions.githubusercontent.com。
• audience 是 api://AzureADTokenExchange。
• subject 只有指定 repo 與指定 main/environment。
• 沒有 write identity 的 pull_request subject。

9.2 驗證 Azure RBAC

az role assignment list
--assignee-object-id "$SP_OBJECT_ID"
--all
--query "[].{role:roleDefinitionName,scope:scope}"
-o table

不應出現：

• Contributor at rg-cae-stg-jpe-001。
• 任何 role at rg-data-stg-jpe-001。
• 不必要的 SQL 或 Key Vault data-plane role。

9.3 團隊驗證 workflow

部署成功後確認：

az acr repository show-tags
--name acrdemostgjpe001
--repository demo-dev-backend
--orderby time_desc
--top 5
-o table

az containerapp revision list
--resource-group rg-demo-stg-jpe-001
--name ca-demo-backend-dev-jpe-001
--query "[].{name:name,health:properties.healthState,running:properties.runningState,traffic:properties.trafficWeight}"
-o table

az containerapp logs show
--resource-group rg-demo-stg-jpe-001
--name ca-demo-backend-dev-jpe-001
--type console
--tail 100

10. 常見錯誤

• AADSTS70021: No matching federated identity record found | 原因：subject、branch/environment、issuer 或 audience 不一致 | 處理方式：對照 GitHub workflow 的 trigger 與 environment，列出 FIC 逐字比較
• AuthorizationFailed | 原因：CI identity 沒有對應 scope 的 role | 處理方式：由平台管理者補上 App scope、ACR 或 CAE join role
• denied: requested access to the resource is denied | 原因：ACR 沒有 AcrPush | 處理方式：在 ACR scope 加 AcrPush，不是只加 Contributor
• Container App cannot join environment | 原因：缺 Microsoft.App/managedEnvironments/join/action | 處理方式：在共用 CAE scope 加 Container Apps Environment Joiner
• SQL Client with IP … not allowed | 原因：App 走公網，沒有走 Private Endpoint | 處理方式：檢查 App 是否位於共用 CAE，不要先加大量 firewall IP
• SQL Login failed | 原因：App Managed Identity 未建立 contained user 或 SQL role | 處理方式：查 App identity，由 DB 管理者處理，不是修改 CI role
• Image push 後沒有新 revision | 原因：workflow push 到錯誤 ACR/tag，或沒有執行 az containerapp update | 處理方式：檢查 image URI、ACR repository、revision list 與 workflow log
• Workflow 使用 tag 觸發但 Azure login 失敗 | 原因：只有 main branch subject，沒有符合 tag/environment 的 FIC | 處理方式：改成只由 main deploy，或由管理者建立精準的 tag/environment FIC

11. 團隊撤換與緊急撤權

OIDC 不使用長期 client secret，因此撤權主要是刪除 Federated Credential 或 Azure role assignment。

移除某個 repo 的信任

先列出 credential ID：

az ad app federated-credential list
--id "$APP_ID"
--query "[].{id:id,name:name,subject:subject}"
-o table

再刪除指定 credential：

az ad app federated-credential delete
--id "$APP_ID"
--federated-credential-id ""

移除 Azure role

az role assignment delete
--assignee-object-id "$SP_OBJECT_ID"
--role "AcrPush"
--scope "$ACR_SCOPE"

撤換整個團隊時，應同時：

1. 移除 GitHub Environment/repository variables。
2. 刪除該 repo 的 Federated Credentials。
3. 移除 App、ACR、CAE scope 的 role assignments。
4. 確認 Container App runtime Managed Identity 不被誤刪。
5. 保留 audit log 與變更紀錄。
6. 新團隊開通檢查表

平台管理者

• 確認目標 repo 與實際部署的 Backend/Frontend。
• 每個團隊建立獨立 Service Principal。
• 只建立 main 或受保護 Environment 的 FIC。
• 不建立 write identity 的 pull_request FIC。
• ACR scope 有 AcrPush。
• 既有 App scope 有更新權限。
• 共用 CAE scope 有 Reader + Container Apps Environment Joiner。
• 沒有授予 SQL Resource Group 或共用 CAE Resource Group Contributor。
• 確認 App runtime Managed Identity 的 SQL/Key Vault/ACR 權限。
• 將三個 Azure identifiers 提供給 GitHub Environment variables。

開發團隊

• Workflow 有 permissions: id-token: write。
• Deploy job 的 environment 或 branch subject 與 Azure FIC 完全一致。
• 使用 azure/login@v2，沒有 client secret。
• Docker image 使用不可變的 commit SHA tag。
• Push 到正確的 ACR repository。
• 只更新指定 Container App，不修改 CAE/VNet/SQL。
• PR workflow 沒有 Azure write token。
• 部署後確認 revision、logs 與功能。

13. 相關文件

• Staging 新手指南： STAGING-ONBOARDING-ZH-TW.md
• Dev 部署腳本： deploy.dev.ps1
• Backend 權限說明： demoproject-backend\docs\dev-deployment-permissions.md

嗨，各位路過的探險家！今天來聊聊我們網站的超級門神 ── WAF 防火牆。

這個系統就像是一個戒備森嚴的城堡，為了不讓壞人進來搗亂，門神阿福手上有一張點名簿，也就是所謂的白名單。只要你的 IP 位址不在這張點名簿上，阿福就會直接把你塞進小黑屋，連大門口都進不來。

最厲害的是，阿福非常有個性，他只保護特定的城堡。就算隔壁的系統不小心被圍攻，我們 Project Name 這邊依然穩如泰山。

阿福的點名簿現況

目前只有拿到特別通行證的網段才能順利通行：

• 某神秘機房專區： 192.168.1.0/24
• 核心團隊的秘密基地： 192.168.2.0/24
• 測試專用通道： 192.168.3.0/24
• 管理員的個人特權 IP： 203.0.113.89

前置作業：請出管理員鑰匙

在指揮阿福修改點名簿之前，請先確認你已經切換到正確的管理帳號，不然阿福是絕對不會理你的。

指令如下：

az account set –subscription “請輸入你的雲端帳號萬用鑰匙代碼”

新增特權 IP 的四大步驟

假設今天有兩組好朋友，一組是 192.168.99.0/24 的新同學，另一組是 198.51.100.6 的外包夥伴，想要加入點名簿。請跟著以下步驟做：

步驟 1：偷看目前的點名簿

先把阿福現在手上到底登記了誰調查清楚。

az network application-gateway waf-policy custom-rule show –policy-name 門神名稱 –resource-group 城堡名稱 –name 規則名稱 –query “matchConditions[0].matchValues” -o json

步驟 2：大家排排站，準備新名單

請把剛剛查出來的舊名單複製出來，然後把新朋友的名字加進去，排成一列。

步驟 3：大手一揮，整張蓋過去

超級重要： 阿福很健忘，你不能只跟他說我要加兩個人，你要給他一張全新的完整名單，否則舊的人會被他通通忘光光。

我們會用一個腳本把新舊名單綁在一起，然後直接覆蓋：

$allIPs = @(

“192.168.1.0/24”,

“192.168.2.0/24”,

“192.168.3.0/24”,

“203.0.113.89”,

“192.168.99.0/24”, # 這是新朋友一號

“198.51.100.6” # 這是新朋友二號

)

（接下來把這串名單打包成 JSON 格式後，用雲端指令送給阿福更新。因為指令比較長，這裡就不贅述，重點是名單要帶齊。）

步驟 4：檢查阿福有沒有認真工作

更新完之後，再次叫阿福把名單拿出來核對，看看剛才加的新朋友是不是都在上面了。

如果想踢掉某個 IP 呢

方法完全一樣。先去步驟 1 看名單，在步驟 2 的時候拿橡皮擦把不想看到的人擦掉，最後用步驟 3 的覆蓋大法，這個人就被阿福除名了。

實地測試：看看阿福有沒有偷懶

名單改完之後，我們一定要來測試看看阿福是不是真的有在認真抓壞人：

• 叫沒拿通行證的朋友點網址： 如果畫面跳出 403 錯誤，代表被阿福成功攔截，阿福好棒。
• 自己人從白名單點網址： 如果正常顯示網頁，代表通行無阻。

筆記小重點

• 隔壁鄰居很安全： 這個點名簿設定只針對我們 Project Name ，完全不會影響到同一個伺服器底下的其他系統。
• 覆蓋完請稍等： 阿福收到新名單後，大概需要 1 到 2 分鐘的時間來認熟面孔，請給他一點時間。
• 附贈隱形護盾： 除了不讓陌生人進來，阿福同時還開啟了國際防禦標準，一般的網路流氓就算換了白名單 IP 進來，只要手腳不乾淨一樣會被抓走喔。

如果你想使用 Azure Portal 網頁畫面來操作，步驟非常直覺，請跟著以下步驟點選。

第一步、登入與尋找策略

首先打開瀏覽器登入 Azure Portal 網站。在網頁最上方的搜尋欄輸入 Web Application Firewall policies 或是 WAF 策略，然後點選進入。

第二步、選擇特定的策略

在列表中找到並點選你正在使用的 WAF 策略名稱。

第三步、進入自訂規則

進入該策略的頁面後，查看左側的選單，在設定區塊中，點選自訂規則。

第四步、修改名單

在自訂規則的列表中，點選你用來管制 IP 的那一條規則。點開之後，你會看到比對條件，找到比對變數為 RemoteAddr 的那一項，你就可以直接在下方的數值列表中，新增或刪除你要異動的 IP 位址。

第五步、儲存更新

修改完成後，點選畫面最上方的儲存按鈕。系統大約需要 1 到 2 分鐘的時間將新名單同步到防火牆。

在 Azure 的網路安全性群組（NSG）世界裡，有時候我們會遇到一個很像「既要又要」的邊緣狀況：你想要同時把好幾個 Port 關起來，不讓壞人進來，但同時又希望特定幾位好朋友（白名單 IP）可以大搖大擺地走進去。

要同時做到阻擋大家又放行自己人，最乾淨也最聰明的作法，就是利用兩條規則的「優先順序（Priority）」差來玩一場網路版的邏輯遊戲。

因為 Azure NSG 這個門神在檢查規則時，是採取「由上到下」比對的。數字越小的規則越優先執行，而且只要一比對成功，它就會直接定案，懶得再看下面的規則了。

核心邏輯大公開

簡單來說，你只需要左右開弓，建立以下兩條規則：

重要提醒：允許（Allow）規則的 Priority 數字（例如 300）必須小於阻擋（Deny）規則的 Priority 數字（例如 301）。如果把阻擋數字寫得太小，門神就會先把大家都趕走，你的好朋友就再也進不來了。

詳細設定步驟（Azure Portal 傳送門操作）

請直接移駕到你的 NSG （azure vmptstgjpe001-nsg）的「輸入安全性規則（Inbound security rules）」頁面，深呼吸之後點選「新增（Add）」：

步驟 1：建立白名單允許規則

1. Source（來源）：下拉選單請選 IP Addresses。
2. Source IP addresses（來源 IP 位址）：輸入你想放行的白名單 IP。如果好朋友有點多，可以用半形逗號隔開，例如： 1.1.1.1, 2.2.2.0/24。
3. Source port ranges（來源連接埠範圍）：維持預設的 * 號就好。
4. Destination（目的地）：選 Any 或是直接指定那一台 VM 的內網 IP。
5. Destination port ranges（目的連接埠範圍）：輸入你想控制的多個 Port，中間記得用半形逗號隔開，例如： 80, 443, 8080。
6. Protocol（通訊協定）：看你心情與需求，選 TCP、UDP 或是 Any。
7. Action（動作）：大方地選擇 Allow。
8. Priority（優先順序）：給它一個比較小的數字，例如 300。
9. Name（名稱）：取一個好辨識的名字，像是 Allow_Whitelist_MultiPorts。

步驟 2：建立其餘全部阻擋規則

再次點選「新增（Add）」來建立第二道關卡：

1. Source（來源）：這次要選 Any，代表任何路人甲乙丙。
2. Source port ranges：一樣維持 * 號。
3. Destination：選 Any。
4. Destination port ranges：請輸入與步驟 1 完全一模一樣的多個 Port，例如： 80, 443, 8080。
5. Protocol：請與步驟 1 保持同步。
6. Action（動作）：這次要狠下心選擇 Deny。
7. Priority（優先順序）：數字必須比步驟 1 還要大，例如 301。
8. Name（名稱）：給它一個威武的名字，像是 Deny_All_MultiPorts。

進階管理小技巧

如果你的白名單 IP 常常像天氣一樣變來變去，或者你手底下的 VM 越來越多，每次都要手動來改 NSG 規則真的會讓人想砸鍵盤。

這時候建議可以利用「應用程式安全性群組（Application Security Group, ASG）」或者 Azure 的「IP Groups」功能。這就像是把所有好朋友的名字直接打包進一個群組懶人包，以後 NSG 規則的來源直接指定這個群組就可以了，管理起來輕鬆到可以提早下班！

想像一下，你要把家裡一整棟圖書館的書，全部搬到遠在天邊的微軟雲端資料庫。如果你用錯方法，就像是用筷子一粒一粒夾米一樣，天黑了都搬不完。

以下是常見的幾種搬家方法與速度大比拼：

第一名： sqlpackage 工具（ BACPAC 格式）

速度是三顆星！這是官方推薦的最速傳說。它會把你的資料庫打包成一個特製的壓縮檔，然後用高鐵般的速度直接倒進雲端，非常適合追求效率的人。

第二名： Python 腳本

速度只有兩顆星。這就像是你雇用了一個排版工人，他必須一頁一頁看懂你的書，再抄寫到雲端上。因為多了解析文字的時間，所以速度慢了一截。

第三名： 透過網頁（ Azure Portal ）匯入

速度同樣是兩顆星。這個方法的缺點是，你得先自己把大行李箱扛到雲端的置物櫃放好，雲端系統才肯幫你處理，多了一道手續。

第四名： 使用微軟資料庫管理軟體（ SSMS ）直接發佈

速度只有可憐的一顆星。雖然動動滑鼠就能搞定，但它只適合資料量極少、一輩子只想搬一次家的新手。

如果你想用最快的第一名方法，只需要簡單的兩個步驟：

步驟一：在自己的電腦輸入這行指令，把資料庫打包成一個叫做 portal.bacpac 的行李箱。

 sqlpackage /Action:Export `
   /SourceServerName:"10.113.82.1,1733" `
   /SourceDatabaseName:"portal" `
   /SourceUser:"<user>" `
   /SourcePassword:"<pass>" `
   /TargetFile:"portal.bacpac"

步驟二：在雲端的虛擬機器上輸入這行指令，把行李箱拆開並倒進雲端資料庫。

 sqlpackage /Action:Import \
   /TargetServerName:"itsc-sqlsvr.database.windows.net" \
   /TargetDatabaseName:"portal-stg" \
   /TargetUser:"" \
   /SourceFile:"portal.bacpac" \
   /p:DatabaseEdition=GeneralPurpose \
   /AccessToken:"$(az account get-access-token --resource https://database.windows.net --query accessToken -o tsv)"

最棒的是，第二步在雲端執行時，使用特別的通行證就可以直接開門，連帳號密碼都不用輸入，安全又省事。

身為一個每天跟資料庫談戀愛的後端工程師，追求「快，還要更快」是我們的天性。當我們用 Python 的 pyodbc 連線到 SQL Server / Azure MSSQL 時，通常會興奮地開啟這個加速外掛：

Python

cursor.fast_executemany = True

「哇！批次寫入速度直線上傳，簡直起飛！」

正當你準備提早下班、開心地去買杯珍奶時，資料庫突然對你吐了一口血：

pyodbc.Error: ('HY000', '[HY000] [Microsoft][ODBC Driver... String data, right truncation ...')

原本以為是完美的資料寫入，結果直接死在半路。這到底是怎麼回事？

案發現場：為什麼「快」反而出事？

這一切的罪魁禍首，居然是因為 fast_executemany 的「第一印象偏見」。

為了追求極致的效能，fast_executemany 在處理一大批資料時，只會偷偷看第一列（First Row）的資料長度，然後心裡就默默下了決定：

「嗯，第一列的這個字串長度是 10，那我就幫接下來的所有資料都準備 10 個字元的緩衝區（Buffer Size）吧！」

這時候，如果你的第 2 列、第 100 列、或是第 999 列資料裡，藏了一個長度是 25 的超級長字串……

蹦！ 緩衝區塞不下了。

SQL Server 的 ODBC 驅動程式就會立刻翻臉，丟出 HY000 截斷錯誤（Truncation Error），然後整批資料就直接報銷。

這就像是搬家公司看了一眼你家門口的第一個小紙箱，就決定開一台發財車來，結果後面搬出來的其實是雙門大冰箱一樣荒謬。

絕妙解法：打不過就加入？不，我們可以「彈性裝死」！

既然這外掛這麼任性，我們該怎麼辦？難道要為了那幾顆老鼠屎，放棄整片 fast_executemany 的效能森林嗎？

在這次 Commit 中，展現了一個非常優雅又帶點「渣男哲學」的解法——自動倒退嚕（Fallback）機制。

直接來看這段神奇的程式碼精髓：

Python

try:
    # 依然保持樂觀，先用快快的 fast_executemany 塞塞看
    cur.executemany(sql_insert, rows)
except pyodbc.Error as e:
    # 哎呀，被抓到有長字串、被嫌太長（HY000 截斷錯誤）了！
    if "HY000" in str(e) or "truncat" in str(e).lower():
        
        # 【精髓在此】秒關外掛，裝作什麼事都沒發生，用慢速但安全的模式重試這批資料
        cur.fast_executemany = False
        cur.executemany(sql_insert, rows)
        
        # 幫這批長字串擦完屁股後，下批資料我們繼續「開掛」
        cur.fast_executemany = True
    else:
        # 如果是別的錯誤（例如語法錯），那就真的沒救，直接噴錯誤
        raise

運作邏輯簡單說：

1. 先開掛衝一波： 預設繼續用 fast_executemany = True，畢竟 90% 的情況大家都很安全。
2. 遇到挫折就認輸： 一旦遇到 HY000（字串太長裝不下），立刻把外掛關掉（fast_executemany = False）。這時候 pyodbc 就會乖乖地為每一列資料重新計算正確的長度，確保安全寫入。
3. 安全過關後再開掛： 幫這批比較特別的資料擦完屁股後，下一批資料進來時，再把外掛重新打開。

總結

這個解法厲害的地方在於，你完全不用在寫入前花費 CPU 效能去檢查每一列字串到底有多長（這通常很慢），而是採取「做錯再修正」的樂觀策略。

既保住了大部份時間的極致高速，又完美的解決了偶發性的字串截斷地雷。

下次用 Python 倒資料到 MSSQL 遇到 HY000 嗎？不妨也試試看這種「彈性裝死」的 Fallback 機制吧！

適用情境：React / Vite 前端 + 任意後端 + Azure Container Apps + nginx 反向代理

一、什麼是 CSP？

Content Security Policy（CSP）是一組 HTTP 回應標頭，讓瀏覽器知道「這個頁面可以載入哪些來源的資源」。它是防禦 Cross-Site Scripting（XSS）與資料注入攻擊的第二道防線。

一旦瀏覽器收到 CSP，即使攻擊者成功注入惡意 <script>，瀏覽器也會拒絕執行——因為注入的腳本不符合 CSP 白名單。

CSP 補足了什麼？

[沒有 CSP]
攻擊者注入 <script src="https://evil.com/steal.js"> → 瀏覽器直接執行 ✗

[有 CSP: script-src 'self']
攻擊者注入 <script src="https://evil.com/steal.js"> → 瀏覽器拒絕執行 ✓

二、Azure 環境的架構選擇

在 Azure 上，安全標頭可以加在三個層次：

Internet
   │
   ▼
Azure Application Gateway (WAF)
   │  ← 可在此加 HTTP Response Header Rewrite Rules
   ▼
Azure Container Apps (nginx)
   │  ← 可在此加 add_header
   ▼
Go 後端 (middleware)
   │  ← 可在此加 w.Header().Set(...)

各層優缺比較

建議

對 SPA 網站來說，nginx 是最合適的地方，原因：

1. SPA 的安全標頭只需要加在 HTML 頁面回應，不需要加在 API 回應
2. nginx 已作為 SPA 的靜態資源伺服器，天然邊界清晰
3. 設定檔進版控，可 review、可追蹤

如果日後 Application Gateway 有設定 Header Rewrite，要記得移除 nginx 這邊的設定，避免同一個 header 重複出現（瀏覽器會套用第一個，但會造成混淆）。

三、為 React + Vite SPA 設計 CSP

分析資源來源

在設計 CSP 之前，先盤點頁面實際載入的所有資源：

Mantine UI 的特殊考量

Mantine（React UI library）會透過 MantineProvider 在 DOM 注入一個 <style> 標籤，內容是 CSS 自訂屬性（design token）：

<style>
  :root {
    --mantine-color-blue-9: #1971c2;
    --mantine-font-size-md: 1rem;
    /* ... */
  }
</style>

這個 inline <style> 是 Mantine 的執行時行為，無法預先計算 hash（除非用 CSP nonce）。因此 style-src 需要加上 'unsafe-inline'。

這樣安全嗎？ 相對安全。

• style-src 'unsafe-inline' 的攻擊面遠小於 script-src 'unsafe-inline'
• CSS 注入最多能做到 UI 欺騙或 timing attack，無法直接竊取 cookie 或執行任意程式碼
• 重點是 script-src 'self' 嚴格設定，不允許 inline script 或外部 script

完整 CSP 設計

Content-Security-Policy:
  default-src 'self';
  script-src 'self';
  style-src 'self' 'unsafe-inline';
  img-src 'self' data:;
  font-src 'self';
  connect-src 'self';
  frame-src 'none';
  frame-ancestors 'none';
  form-action 'self';
  base-uri 'self';
  object-src 'none'

其他安全標頭

除了 CSP，建議同時加上這些標頭：

四、nginx.conf.template 實作

在 nginx server block 層級（非個別 location 內）加上 add_header ... always：

server {
    listen 80;
    server_name _;

    root /usr/share/nginx/html;
    index index.html;

    # Security headers
    add_header Content-Security-Policy "default-src 'self'; script-src 'self'; style-src 'self' 'unsafe-inline'; img-src 'self' data:; font-src 'self'; connect-src 'self'; frame-src 'none'; frame-ancestors 'none'; form-action 'self'; base-uri 'self'; object-src 'none'" always;
    add_header X-Content-Type-Options "nosniff" always;
    add_header X-Frame-Options "DENY" always;
    add_header Referrer-Policy "strict-origin-when-cross-origin" always;
    add_header Permissions-Policy "camera=(), microphone=(), geolocation=()" always;

    # ... 其他設定
}

always 參數：確保即使後端回傳 4xx/5xx，nginx 也會加上這些 headers。沒有 always 的話，錯誤頁面會沒有安全標頭。

要注意的地方

1. 不要加在 /api/ proxy location 裡：API 回應不需要 CSP，加了反而讓前端 XHR 請求帶著多餘 header。
2. 避免重複設定：如果 Application Gateway 已設定 Header Rewrite，nginx 這邊要移除，否則 header 會出現兩次（部分瀏覽器行為不一致）。
3. HTTPS only 部署才需要 HSTS：Strict-Transport-Security 只有在全站 HTTPS 時才加；如果有任何 HTTP 存取路徑，HSTS 會造成無法回頭。

五、上線前驗證

本地驗證

部署後使用 curl 確認標頭存在：

curl -I https://your-app.example.com/ | grep -i "content-security\|x-frame\|x-content\|referrer\|permissions"

瀏覽器 DevTools

1. 開 DevTools → Network → 選 index.html 請求
2. 查看 Response Headers，確認五個安全標頭都在
3. 開 Console，確認沒有 CSP violation 錯誤（Refused to load ...）

線上掃描工具

• Mozilla Observatory — 綜合安全標頭評分
• SecurityHeaders.com — 詳細標頭分析
• CSP Evaluator（Google） — 評估 CSP 強度

六、常見陷阱與排查

問題：Mantine 樣式全部消失

原因：style-src 缺少 'unsafe-inline'，Mantine 注入的 <style> block 被拒絕。
解法：加上 'unsafe-inline'。

問題：Console 出現 Refused to connect to 'http://...'

原因：connect-src 'self' 嚴格限制，可能有程式碼直接連外部 API（非透過 nginx proxy）。
解法：找出來源並調整，或暫時在 connect-src 白名單加入該 origin。

問題：OAuth redirect 失敗

原因：OAuth 流程是瀏覽器 window.location.href 跳轉（navigation），不是 form submit 也不是 XHR，CSP 的 form-action 和 connect-src 都不管這個。
結論：OAuth redirect 不受 CSP 影響，不需要特別處理。

問題：第三方 SSO（POST 到 /auth/sso/callback）失敗

原因：第三方 SSO 是由外部伺服器 redirect 瀏覽器 POST 到我們的 callback（form submit 跨站）。
確認：這是第三方 SSO 頁面的 form-action，不是我們這邊的 CSP 設定問題。CSP 加在我們頁面的回應，不影響來自其他頁面的 form submit。

七、結論

對於 Azure 上的 React SPA：

1. 現在就可以加：資源全 self-hosted + 無 inline script，加 CSP 的風險很低
2. 加在 nginx：比 Application Gateway 更容易維護，可版控，redeploy 即生效
3. 接受 style-src 'unsafe-inline'：這是 Mantine 的現實限制，不影響最重要的 script XSS 防護
4. 配套加其他標頭：X-Content-Type-Options、X-Frame-Options、Referrer-Policy、Permissions-Policy 是低成本高效益的防護
5. 上線後立刻掃描：用 Mozilla Observatory 驗證，確認等級達到 B 或以上

場景：Azure Container Apps 上的 React SPA 安全加固