entra-app-registration

概述

Microsoft Entra ID（原 Azure Active Directory）是 Microsoft 基于云的身份和访问管理服务。应用注册允许应用对用户进行身份验证，并安全地访问 Azure 资源。

核心概念

概念	描述
应用注册	允许应用使用 Microsoft 身份平台的配置
应用程序（客户端）ID	应用程序的唯一标识符
租户 ID	Azure AD 租户／目录的唯一标识符
客户端密钥	应用程序的密码（仅适用于机密客户端）
重定向 URI	接收身份验证响应的 URL
API 权限	应用请求的访问范围
服务主体	注册应用时在租户中创建的身份

应用程序类型

类型	用例
Web 应用程序	服务端应用、API
单页应用（SPA）	JavaScript／React／Angular 应用
移动／原生应用	桌面、移动应用
守护程序／服务	后台服务、API

核心工作流

步骤 1：注册应用程序

在 Azure 门户中或使用 Azure CLI 创建应用注册。

门户方式：

1. 转到 Azure 门户 → Microsoft Entra ID → 应用注册
2. 点击“新注册”
3. 提供名称、支持的帐户类型和重定向 URI
4. 点击“注册”

**CLI 方式：**请参阅 references/cli-commands.md **IaC 方式：**请参阅 references/BICEP-EXAMPLE.bicep

如果项目已使用 IaC、需要可扩展的方案来管理大量应用注册，或需要对配置变更进行精细的审计记录，强烈建议使用 IaC 管理 Entra 应用注册。

步骤 2：配置身份验证

根据应用程序类型设置身份验证选项。

• Web 应用：添加重定向 URI；如有需要，启用 ID 令牌
• SPA：添加重定向 URI；如有必要，启用隐式授权流
• 移动／桌面应用：使用 http://localhost 或自定义 URI 方案
• 服务：客户端凭据流无需重定向 URI

步骤 3：配置 API 权限

授予应用访问 Microsoft API 或自有 API 的权限。

常见的 Microsoft Graph 权限：

• User.Read - 读取用户配置文件
• User.ReadWrite.All - 读取和写入所有用户
• Directory.Read.All - 读取目录数据
• Mail.Send - 以用户身份发送邮件

**详情：**请参阅 references/api-permissions.md

步骤 4：创建客户端凭据（如有需要）

对于机密客户端应用程序（Web 应用、服务），创建客户端密钥、证书或联合身份凭据。

客户端密钥：

• 转到“证书和机密”
• 创建新的客户端密钥
• 立即复制其值（仅显示一次）
• 安全存储（建议使用 Key Vault）

**证书：**在生产环境中，使用证书代替密钥以增强安全性。通过“证书和机密”部分上传证书。

**联合身份凭据：**用于动态向 Entra 平台验证机密客户端的身份。

步骤 5：实现 OAuth 流程

将 OAuth 流程集成到应用程序代码中。

请参阅：

• references/oauth-flows.md - OAuth 2.0 流程详情
• references/console-app-example.md - 控制台应用实现

常见模式

模式 1：首次注册应用

逐步引导用户完成首次应用注册。

所需信息：

• 应用程序名称
• 应用程序类型（Web、SPA、移动应用、服务）
• 重定向 URI（如适用）
• 所需权限

**脚本：**请参阅 references/first-app-registration.md

模式 2：带用户身份验证的控制台应用

创建一个用于验证用户身份的 .NET/Python/Node.js 控制台应用。

所需信息：

• 编程语言（C#、Python、JavaScript 等）
• 身份验证库（推荐使用 MSAL）
• 所需权限

**示例：**参见 references/console-app-example.md

模式 3：服务到服务身份验证

设置无需用户交互的守护程序/服务身份验证。

所需信息：

• 服务/应用名称
• 目标 API/资源
• 使用客户端密钥还是证书

**实现：**使用客户端凭据流（参见 references/oauth-flows.md#client-credentials-flow）

MCP 工具和 CLI

Azure CLI 命令

命令	用途
az ad app create	创建新的应用注册
az ad app list	列出应用注册
az ad app show	显示应用详细信息
az ad app permission add	添加 API 权限
az ad app credential reset	生成新的客户端密钥
az ad sp create	创建服务主体

**完整参考：**参见 references/cli-commands.md

Microsoft Authentication Library (MSAL)

MSAL 是集成 Microsoft identity platform 的推荐库。

支持的语言：

• .NET/C# - Microsoft.Identity.Client
• JavaScript/TypeScript - @azure/msal-browser、@azure/msal-node
• Python - msal

**示例：**参见 references/console-app-example.md

安全最佳实践

实践	建议
切勿将密钥硬编码	使用环境变量、Azure Key Vault 或托管标识
定期轮换密钥	设置过期时间，并自动执行轮换
优先使用证书而非密钥	在生产环境中更安全
遵循最小权限原则	仅请求所需的 API 权限
启用 MFA	要求用户使用多重身份验证
使用托管标识	对于托管在 Azure 上的应用，可完全避免使用密钥
验证令牌	始终验证颁发者、受众和过期时间
仅使用 HTTPS	所有重定向 URI 都必须使用 HTTPS（localhost 除外）
监控登录活动	使用 Entra ID 登录日志检测异常

SDK 快速参考

• Azure Identity：Python | .NET | TypeScript | Java | Rust
• Key Vault（密钥）：Python | TypeScript
• 身份验证事件：.NET

参考资料

• OAuth 流程 - OAuth 2.0 流程详细说明
• CLI 命令 - 应用注册的 Azure CLI 参考
• 控制台应用示例 - 完整的可运行示例
• 首个应用注册 - 面向初学者的分步指南
• API 权限 - 了解和配置权限
• 故障排除 - 常见问题及解决方案

外部资源

• Microsoft Identity Platform 文档
• OAuth 2.0 和 OpenID Connect 协议
• MSAL 文档
• Microsoft Graph API