entra-app-registration

概览

这个技能的功能

entra-app-registration 技能为配置 Microsoft Entra ID（原 Azure Active Directory）应用注册提供面向开发者的分步指导。它会引导你完成：

• 在 Microsoft Entra ID 中创建应用注册
• 理解关键身份概念（租户 tenant、client ID、redirect URI、service principal 等）
• 选择并配置 OAuth 2.0 流程
• 添加和管理 API 权限（delegated vs application）
• 配置机密（secret）或证书以及 service principal
• 集成多种语言的 MSAL 和 Azure Identity SDK
• 排查常见的身份验证与配置错误

内容来源于 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、桌面或控制台应用
• 需要可重复 app registration 和权限配置模式的 DevOps 或平台工程师
• 希望整合 Entra ID 身份验证与 API 权限最佳实践的团队

在这些场景下尤其有用：

• 正在创建你的第一个 Microsoft Entra 应用注册
• 从旧版 Azure AD 指南迁移到 Microsoft identity platform
• 在 delegated 与 application 权限之间做选择
• 为你的应用类型选择合适的 OAuth 2.0 流程
• 在控制台或后端应用中集成 MSAL

什么时候不适合使用此技能

entra-app-registration 专注于身份和应用注册，而不是通用 Azure 安全或资源管理。

如果你主要需要的是以下内容，请不要把该技能作为首选参考：

• Azure 资源的基于角色的访问控制（RBAC） → 使用 azure-rbac 技能
• Key Vault 机密生命周期与过期审计 → 使用 azure-keyvault-expiration-audit 技能
• 更广义的 Azure 资源安全态势或策略指南 → 使用 azure-security 技能

当你的场景同时涉及身份和资源级授权时，可以将 entra-app-registration 与上述技能组合使用。

关键能力速览

在该技能中，你可以找到以下类型的指南：

• 理解应用注册的基础构件（来自 SKILL.md 和 references/first-app-registration.md）
• 配置 OAuth 2.0 流程，包括 authorization code 与 client credentials（references/oauth-flows.md）
• 规划并分配 Microsoft Graph 及自定义 API 的 API 权限（references/api-permissions.md）
• 遵循 Azure 身份验证最佳实践，包括使用 managed identities 和推荐凭据类型（references/auth-best-practices.md）
• 使用 Azure CLI 自动创建和更新应用注册（references/cli-commands.md）
• 在 C#、Python、Node.js 中实现基于 MSAL 的控制台应用（references/console-app-example.md）
• 集成 .NET、Java、Python、Rust、TypeScript 的 Azure Identity SDK（references/sdk/*.md）
• 诊断 redirect URI、token 与 consent 相关问题（references/troubleshooting.md）

这使得 entra-app-registration 非常适合依赖 Microsoft Entra ID 的访问控制、API 开发和后端开发工作。

使用方式

安装 entra-app-registration 技能

要在兼容的 agent 环境中，从 microsoft/azure-skills 仓库添加 entra-app-registration 技能，运行：

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

这样，该技能的文档（包括 SKILL.md 和 references/ 目录）就会对你的 agent 可用，从而可以回答关于 Microsoft Entra 应用注册、OAuth 流程和权限的详细问题。

如果你的平台提供技能的 UI，你也可以：

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 应用注册的详细步骤教程。
3. references/oauth-flows.md – Microsoft Entra ID 支持的 OAuth 2.0 流程说明与示意图，并附实现要点。
4. references/api-permissions.md – 如何选择与配置 delegated 和 application 权限、scope 格式以及常见 Graph 权限。
5. references/auth-best-practices.md – 如何针对不同环境选择合适的凭据类型（managed identity、证书、本地使用 DefaultAzureCredential 等）。
6. references/cli-commands.md – 用于在脚本或 CI/CD 中创建和管理应用注册的 Azure CLI 命令。
7. references/console-app-example.md – 使用 Microsoft Entra ID 和 MSAL 进行身份验证的完整控制台应用示例。
8. references/sdk/*.md – 使用 Azure Identity 及相关 SDK 的不同语言集成指南。
9. references/troubleshooting.md – 当出现 AADSTS 错误、consent 问题或 redirect URI 不匹配时可参考。

按此顺序，你可以从概念理解逐步过渡到基于 portal 的配置，再进一步到自动化流程与代码级集成。

该技能支持的典型工作流

1. 注册你的首个 Microsoft Entra 应用

在初次接触 Entra ID 或创建新应用时使用：

• 按 references/first-app-registration.md 中的步骤进行：
  • 打开 Azure portal 并导航到 Microsoft Entra ID → App registrations
  • 创建新的应用注册，并选择正确的 supported account types
  • 根据是 Web app、SPA 还是本机客户端，配置相应的 redirect URI
  • 设置身份验证选项和平台配置
  • 添加所需 API 权限（例如 Microsoft Graph 的 User.Read）
  • 视情况创建客户端凭据（secret 或证书）
  • 在应用中测试身份验证流程

技能中按步骤组织的内容能有效减少 redirect URI、租户选择和账号类型选择等常见错误。

2. 选择合适的 OAuth 2.0 流程

当你不确定为新应用选择哪种身份验证流程时使用：

• 打开 references/oauth-flows.md，对比不同流程，例如：
  • 面向具有服务端机密的 Web 应用和服务的 authorization code flow
  • 面向 daemon 应用和后台服务的 client credentials flow
  • 指南中展示的其他支持流程
• 每种流程章节都会说明：
  • 用户、应用、Microsoft Entra ID 与 API 之间的交互步骤（编号顺序）
  • client_id、tenant、redirect_uri、scope 等关键参数
  • 该流程的推荐使用场景

通过参考该指南，你可以将应用类型（Web、SPA、daemon、console）与合适的 OAuth 流程相匹配并安全实现。

3. 配置 delegated 与 application 权限

当你的应用需要调用 Microsoft Graph 或自定义 API 时使用：

• 打开 references/api-permissions.md，以便：
  • 理解 delegated permissions（以用户为上下文）与 application permissions（仅应用上下文）的区别
  • 判断何时适合用户同意（user consent），何时必须管理员同意（admin consent）
  • 学习 scope 格式，包括 Graph scope（如 https://graph.microsoft.com/User.Read）以及自定义 API scope（如 api://myapi-id/access_as_user）
  • 了解 .default scope 在 client credentials 和迁移场景中的用法
• 基于这些指导，你可以：
  • 在应用注册中正确配置 API permissions
  • 在应用代码中请求合适的 scopes
  • 避免过度授权及不必要的管理员同意请求

4. 使用 Azure CLI 自动化应用注册

当你希望通过脚本而不是 portal 完成应用注册时使用：

• 打开 references/cli-commands.md，了解：
  • CLI 前置条件（az 安装与 az login）
  • 创建以下类型应用注册的示例命令：
    • 带 redirect URI 的 Web 应用
    • 具有 SPA redirect URI 的 Single Page Application (SPA)
    • 公共客户端应用（桌面/移动端）
    • 使用不同 sign-in audience 设置的多租户应用
  • 更新 redirect URI 和其他配置的命令片段

你可以将这些示例改造为 shell 脚本或 CI/CD pipeline，以在不同环境中保持一致的应用注册配置。

5. 在控制台或后端应用中实现 MSAL

当你需要可直接运行的身份验证和获取 token 的代码时使用：

• 打开 references/console-app-example.md，按照其中步骤：
  • 创建新的控制台项目（例如 dotnet new console）
  • 安装 MSAL 包（例如 .NET 的 Microsoft.Identity.Client）
  • 使用完整示例程序：
    • 配置 ClientId、TenantId 和 Scopes
    • 构建 public client application 实例
    • 以交互或静默（缓存）方式获取 token
    • 处理错误并输出 token 结果

你可以直接复制这些示例到自己的项目中，并将占位符替换为你的应用注册配置。

6. 在多种语言中使用 Azure Identity SDK

当你希望使用 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
  • 在合适场景下配置基于环境的凭据

这有助于你将应用注册与现代 Azure SDK 的身份验证模式结合起来。

7. 排查常见身份验证问题

当你遇到典型的 Microsoft Entra ID 错误时使用：

• 打开 references/troubleshooting.md，诊断类似问题：
  • Redirect URI 不匹配（如 AADSTS50011）
  • 客户端机密无效或已过期
  • 调用 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 中、用于客户端凭据的 secrets 时，配合 azure-keyvault-expiration-audit
• 当需要更广义的安全态势、策略与合规性建议时，配合 azure-security

常见问题 FAQ

entra-app-registration 主要解决哪些问题？

entra-app-registration 解决的是首次使用 Microsoft Entra ID 应用注册时常见的实际配置与落地问题。它提供结构化指导，帮助你：

• 在 portal 或 CLI 中正确创建应用注册
• 为你的应用选择合适的账户类型和 OAuth 流程
• 配置 redirect URI、机密、证书以及 service principal
• 添加适用于 Microsoft Graph 或自定义 API 的正确 API 权限与 scopes
• 在真实应用中集成 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/ 目录）将对 agent 可用，从而能回答关于 Microsoft Entra 应用注册与身份验证方面的问题。

安装后应该先看哪些文件？

建议从以下文件开始：

• SKILL.md – 了解整体范围与使用指导
• references/first-app-registration.md – 基于 portal 的分步配置指南
• references/oauth-flows.md – 了解适用于你场景的 OAuth 2.0 流程
• references/api-permissions.md – 选择并配置 API 权限

随后可根据需求查看 references/cli-commands.md（用于自动化）、references/console-app-example.md（查看示例代码）以及 references/troubleshooting.md（解决错误）。

这个技能能帮我配置 Azure RBAC 或资源角色吗？

只能算是间接帮助。entra-app-registration 聚焦于应用身份、OAuth 流程和 API 权限，并不深入讲解 Azure 资源角色分配或 RBAC 配置。针对这类内容，应结合 azure-rbac 技能使用。

entra-app-registration 能用于非微软云平台吗？

该技能专门针对 Microsoft Entra ID 与 Microsoft identity platform。虽然 OAuth 2.0 的概念具有通用性，但其中的配置步骤、命令与示例都是面向 Azure 与 Microsoft Entra ID 租户的。

是否提供多种语言的代码示例？

是。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 机密生命周期的全部内容。如果需要审计过期时间或深度管理 Key Vault secrets，应同时使用 azure-keyvault-expiration-audit 技能。

如果我已经有应用注册但配置不当怎么办？

你可以使用 references/troubleshooting.md 诊断错误，然后：

• 将当前应用注册设置与 references/first-app-registration.md 和 references/oauth-flows.md 中的推荐模式进行对比
• 按指南修正 redirect URI、权限与机密配置
• 根据 references/console-app-example.md 和 SDK 文档中的示例检查并调整你的代码

该技能既适用于全新搭建（greenfield），也适用于对现有配置进行纠正。

在哪里可以看到这个技能包含的所有文档？

在你的环境中打开 entra-app-registration 技能的 Files 或 Sources 视图，你可以浏览：

• SKILL.md
• references/ 目录下的专题指南（API permissions、OAuth flows、CLI commands、console 示例、troubleshooting 等）
• references/sdk/ 子目录下各语言的 Azure Identity 示例

查看整个目录结构，可以全面了解该技能打包提供的所有指导内容。