entra-app-registration

概觀

此技能的用途

entra-app-registration 技能提供以開發者為主、逐步操作的說明，用來設定 Microsoft Entra ID（原 Azure Active Directory）的 app registrations。它會帶你完成以下事項：

• 在 Microsoft Entra ID 中建立 app registrations
• 了解重要的身分識別概念（tenant、client ID、redirect URI、service principal）
• 選擇並設定適合的 OAuth 2.0 flows
• 新增與管理 API permissions（delegated vs application）
• 設定 secrets 或 certificates 與 service principals
• 整合多種語言的 MSAL 與 Azure Identity SDKs
• 疑難排解常見的驗證與組態錯誤

內容主要來自 microsoft/azure-skills 儲存庫中的 skills/entra-app-registration 資料夾，包括 references/first-app-registration.md、references/oauth-flows.md、references/api-permissions.md、references/console-app-example.md 等專門指引。

適合使用 entra-app-registration 的對象

如果你符合以下情境，適合使用此技能：

• 後端或 API 開發者，需要使用 Microsoft Entra ID 保護 web API 或服務
• 開發需要登入使用者或呼叫 Microsoft Graph / 自訂 API 的 web、SPA、桌面或主控台應用程式
• DevOps 或平台工程師，需要可重複套用的 app registration 與權限設定模式
• 團隊希望有成文的 Entra ID 驗證與 API 權限最佳實務

在以下情況特別有幫助：

• 建立你的 第一個 Microsoft Entra app registration
• 從舊版 Azure AD 指南遷移到 Microsoft identity platform
• 在 delegated vs application permissions 之間做選擇
• 為你的應用程式類型挑選合適的 OAuth 2.0 flow
• 在主控台或後端應用程式中接上 MSAL

何時不適合使用此技能

entra-app-registration 專注在 身分識別與 app registration，而不是一般的 Azure 安全性或資源管理。

若你的主要需求是以下內容，請不要將此技能當成主要參考：

• Azure 資源的角色型存取控制（RBAC）→ 使用 azure-rbac 技能
• Key Vault secrets 生命週期與到期稽核 → 使用 azure-keyvault-expiration-audit 技能
• 更廣泛的 Azure 資源安全態勢或政策指引 → 使用 azure-security 技能

當你的情境同時涵蓋身分與資源層級授權時，仍可以將 entra-app-registration 與這些技能搭配使用。

主要能力一覽

在此技能中，你會找到如下指引，協助你：

• 了解 app registration 的基礎組成（來自 SKILL.md 與 references/first-app-registration.md）
• 設定 OAuth 2.0 flows，包括 authorization code 與 client credentials（references/oauth-flows.md）
• 規劃並指派 Microsoft Graph 與自訂 API 的 API permissions（references/api-permissions.md）
• 遵循 Azure 驗證最佳實務，包括使用 managed identities 與建議的憑證型式（references/auth-best-practices.md）
• 使用 Azure CLI 自動化建立與更新 app registrations（references/cli-commands.md）
• 在 C#、Python、Node.js 中實作以 MSAL 為基礎的 console applications（references/console-app-example.md）
• 整合 .NET、Java、Python、Rust、TypeScript 的 Azure Identity SDKs（references/sdk/*.md）
• 診斷 redirect URI、token 與 consent 相關問題（references/troubleshooting.md）

這些內容讓 entra-app-registration 對於依賴 Microsoft Entra ID 的存取控制、API 開發與後端開發工作，成為實用的配套技能。

使用方式

安裝 entra-app-registration 技能

若要從 microsoft/azure-skills 儲存庫將 entra-app-registration 技能新增到相容的代理環境，請執行：

npx skills add https://github.com/microsoft/azure-skills --skill entra-app-registration

這會讓技能的說明文件（包含 SKILL.md 與 references/ 資料夾）對你的代理可用，代理即可回答關於 Microsoft Entra app registration、OAuth flows 與權限設定的詳細問題。

如果你的平台提供 skills 的圖形介面，你也可以：

1. 在技能目錄中搜尋「entra-app-registration」。
2. 確認 GitHub 來源為 microsoft/azure-skills。
3. 按下 Add 或 Enable，將其加入你的工作區或專案。

建議閱讀順序

安裝完成後，到此技能的 Files 或 Sources 檢視中，依照以下順序探索：

1. SKILL.md – 高階概觀、技能涵蓋範圍，以及建議／不建議的使用情境。
2. references/first-app-registration.md – 在 Azure portal 建立第一個 Microsoft Entra app registration 的具體逐步教學。
3. references/oauth-flows.md – 說明及圖解 Microsoft Entra ID 支援的 OAuth 2.0 flows，並附上實作重點。
4. references/api-permissions.md – 教你如何選擇與設定 delegated vs application permissions、scope 格式與常見的 Graph 權限。
5. references/auth-best-practices.md – 依環境選擇正確的 credential 類型（managed identity、certificates、本機使用 DefaultAzureCredential 等）。
6. references/cli-commands.md – 使用 Azure CLI 透過指令碼或 CI/CD 建立與管理 app registrations。
7. references/console-app-example.md – 可直接執行的主控台應用程式範例，示範如何透過 MSAL 與 Microsoft Entra ID 驗證。
8. references/sdk/*.md – 各語言使用 Azure Identity 等 SDK 的整合指南。
9. references/troubleshooting.md – 當你遇到 AADSTS 錯誤、consent 問題或 redirect URI 不相符時，從這裡著手。

此閱讀順序可幫助你從概念理解、portal 操作，一路到自動化流程與程式碼層級整合。

此技能支援的典型工作流程

1. 註冊你的第一個 Microsoft Entra app

當你剛開始使用 Entra ID，或要建立新應用程式時可以這樣做：

• 依照 references/first-app-registration.md：
  • 開啟 Azure portal，前往 Microsoft Entra ID → App registrations
  • 建立新的 registration 並選擇正確的 supported account types
  • 依照你是 web app、SPA 或 native client，設定適當的 redirect URIs
  • 設定 authentication options 與 platform configurations
  • 新增必要的 API permissions（例如 Microsoft Graph 的 User.Read）
  • 視需求建立 client credentials（secrets 或 certificates）
  • 在你的應用程式中測試驗證流程

此技能的逐步結構能減少 redirect URIs、tenant 選擇與 account type 選錯等常見失誤。

2. 選擇正確的 OAuth 2.0 flow

當你不確定新應用程式該用哪種驗證流程時：

• 開啟 references/oauth-flows.md 比較不同 flows，例如：
  • 適用於有 server-side secrets 的 web apps 與服務的 authorization code flow
  • 適用於 daemon apps 與背景服務的 client credentials flow
  • 指南中說明的其他支援 flows
• 每一種 flow 的章節會說明：
  • 使用者、應用程式、Microsoft Entra ID 與 APIs 之間的互動步驟（編號流程）
  • 重要參數，例如 client_id、tenant、redirect_uri、scope
  • 該 flow 的建議使用情境

參考此指南，你可以將應用程式類型（web、SPA、daemon、console）對應到適當的 OAuth flow，並安全地實作。

3. 設定 delegated vs application permissions

當你的應用程式需要呼叫 Microsoft Graph 或自訂 API 時：

• 開啟 references/api-permissions.md：
  • 了解 delegated permissions（使用者脈絡）與 application permissions（僅應用程式脈絡）的差異
  • 判斷哪些情況適合使用者同意，哪些情況需要系統管理員同意
  • 學習 scope 格式，包括 Graph scopes（如 https://graph.microsoft.com/User.Read）與自訂 API scopes（如 api://myapi-id/access_as_user）
  • 了解 .default scopes 在 client credentials 與遷移情境中的運作方式
• 運用這些指引來：
  • 在 app registration 中正確設定 API permissions
  • 從應用程式程式碼中要求正確的 scopes
  • 避免過度授權與不必要的系統管理員同意要求

4. 使用 Azure CLI 自動化 app registration

當你希望透過指令碼自動化 app registration，而不是手動操作 portal 時：

• 開啟 references/cli-commands.md，內容包含：
  • CLI 先決條件（az 安裝與 az login）
  • 建立下列類型 app registrations 的範例指令：
    • 具有 redirect URIs 的 web applications
    • 具有 SPA redirect URIs 的 Single Page Applications (SPA)
    • 公用 client apps（桌面／行動）
    • 具有不同 sign-in audience 設定的 multi-tenant apps
  • 更新 redirect URIs 與其他組態的指令片段

你可以將這些範例改寫為 shell scripts 或 CI/CD pipeline，以在不同環境間維持一致的 app registration 設定。

5. 在主控台或後端應用程式中實作 MSAL

當你需要可用的程式碼來進行驗證並取得 tokens 時：

• 開啟 references/console-app-example.md：
  • 建立新的 console 專案（例如 dotnet new console）
  • 安裝 MSAL 套件（例如 .NET 的 Microsoft.Identity.Client）
  • 使用完整範例程式：
    • 設定 ClientId、TenantId 與 Scopes
    • 建立 public client application 實例
    • 以互動式或從快取靜默方式取得 tokens
    • 處理錯誤並輸出 token 結果

你可以直接將這些範例複製到自己的專案中，再將 placeholder 值替換為你的 app registration 資訊。

6. 在多種語言中使用 Azure Identity SDKs

當你想使用 Azure Identity 函式庫，而不是直接呼叫 MSAL 時：

• 開啟 references/sdk/ 中對應語言的檔案，例如：
  • azure-identity-dotnet.md
  • azure-identity-java.md
  • azure-identity-py.md
  • azure-identity-rust.md
  • azure-identity-ts.md
• 這些指南與 references/auth-best-practices.md 一致，說明如何：
  • 在本機開發時使用 DefaultAzureCredential
  • 在正式環境偏好使用 ManagedIdentityCredential 或 workload identity
  • 視情況設定以環境為基礎的 credentials

這能協助你將 app registrations 與現代 Azure SDK 的驗證模式整合。

7. 疑難排解常見驗證問題

當你遇到 Microsoft Entra ID 常見錯誤時：

• 開啟 references/troubleshooting.md 來診斷問題，例如：
  • Redirect URI 不相符（如 AADSTS50011）
  • 無效或已過期的 client secrets
  • 呼叫 API 時的權限與 consent 錯誤
  • Token 驗證與組態問題
• 指南內容包括：
  • 錯誤訊息範例
  • 問題根本原因說明
  • 具體修正步驟，包括 Azure portal 操作與 Azure CLI 指令

這可以在開發或正式環境中，替你節省排除驗證與授權錯誤的時間。

最佳實務與與其他技能的搭配

在 references/auth-best-practices.md 中，此技能強調：

• 在 Azure 上執行的正式環境工作負載，使用 managed identities 搭配 Azure RBAC
• DefaultAzureCredential 主要用於本機開發，而非正式環境
• 依環境選擇有針對性的憑證型別（例如 ManagedIdentityCredential、ClientCertificateCredential 或 workload identity），以兼顧可預期性與效能

你可以將 entra-app-registration 與以下技能搭配：

• 當身分已設定後，需要授權存取 Azure 資源時，使用 azure-rbac
• 需要管理與稽核儲存在 Key Vault 中用於 client credentials 的 secrets 到期狀態時，使用 azure-keyvault-expiration-audit
• 若需要更全面的安全態勢、政策與合規性指引，使用 azure-security

常見問題 (FAQ)

entra-app-registration 能解決哪些問題？

entra-app-registration 主要解決你首次處理 Microsoft Entra ID app registrations 時，實際遇到的設定與組態難題。它提供結構化的指引，協助你：

• 在 portal 或透過 CLI 正確建立 app registration
• 為你的應用程式選擇合適的 account types 與 OAuth flows
• 設定 redirect URIs、secrets、certificates 與 service principals
• 新增適當的 API permissions 與 scopes 給 Microsoft Graph 或自訂 API
• 在實際應用程式中整合 MSAL 與 Azure Identity
• 疑難排解常見錯誤碼與錯誤組態

要如何安裝 entra-app-registration 技能？

你可以從 microsoft/azure-skills 儲存庫安裝此技能。在相容的環境中執行：

npx skills add https://github.com/microsoft/azure-skills --skill entra-app-registration

安裝完成後，技能的檔案（包含 SKILL.md 與 references/ 資料夾）會在你的代理中可用，讓代理可以回答關於 Microsoft Entra app registration 與驗證的問題。

安裝後應該先看哪些檔案？

建議先從以下檔案開始：

• SKILL.md – 瞭解整體範圍與使用指引
• references/first-app-registration.md – 以 portal 為主的逐步設定流程
• references/oauth-flows.md – 釐清你情境中適合的 OAuth 2.0 flow
• references/api-permissions.md – 選擇與設定 API permissions

接著依需求，參考 references/cli-commands.md 進行自動化、references/console-app-example.md 查看程式碼範例，以及 references/troubleshooting.md 用於錯誤排除。

這個技能會協助處理 Azure RBAC 或資源角色嗎？

只能算間接協助。entra-app-registration 專注在應用程式身分、OAuth flows 與 API permissions，不深入涵蓋 Azure 資源角色指派或 RBAC 設定。若要處理這些議題，建議搭配 azure-rbac 技能。

可以在非 Microsoft 雲環境使用 entra-app-registration 嗎？

此技能專門針對 Microsoft Entra ID 與 Microsoft identity platform。雖然 OAuth 2.0 概念是通用的，但其中的組態步驟、指令與範例，都以 Azure 與 Microsoft Entra ID tenants 為目標環境。

是否提供多種語言的程式碼？

有。references/console-app-example.md 提供使用 MSAL 的 C#、Python、Node.js 主控台應用程式範例。此外，references/sdk/ 資料夾也包含 .NET、Java、Python、Rust、TypeScript 的 Azure Identity 函式庫語言別文件。

此技能與 Azure Key Vault 的關係是什麼？

entra-app-registration 會提到驗證最佳實務，並可能建議安全儲存 secrets，但不會完整涵蓋 Key Vault secrets 的生命週期管理。若需要深入的到期稽核與 Key Vault secrets 管理，請搭配使用 azure-keyvault-expiration-audit 技能。

如果我已經有 app registrations，但設定似乎有問題怎麼辦？

你可以使用 references/troubleshooting.md 來診斷錯誤，然後：

• 將現有 app registration 設定與 references/first-app-registration.md、references/oauth-flows.md 中的模式做比較
• 依照指引修正 redirect URIs、permissions 與 secrets
• 將你的程式碼對照 references/console-app-example.md 與 SDK 文件中的範例進行調整

此技能不僅適用於全新環境，也適合用來修補與調整既有組態。

要去哪裡查看此技能包含的所有文件？

在你的環境中開啟 entra-app-registration 技能的 Files 或 Sources 分頁，你可以瀏覽：

• SKILL.md
• references/ 資料夾中的主題式指南（API permissions、OAuth flows、CLI commands、console 範例、troubleshooting 等）
• references/sdk/ 子資料夾中的各語言 Azure Identity 範例

瀏覽這個檔案樹，可以完整掌握此技能所包含的所有指引內容。