对 Microsoft Graph PowerShell SDK 使用仅限应用的身份验证Use app-only authentication with the Microsoft Graph PowerShell SDK

PowerShell SDK 支持两种类型的身份验证: 委派访问权限和 仅限应用访问The PowerShell SDK supports two types of authentication: delegated access, and app-only access. 本指南将重点介绍启用仅限应用访问权限所需的配置。This guide will focus on the configuration needed to enable app-only access.

重要

仅限应用访问权限向应用程序直接授予权限,并要求管理员同意所需的权限范围。App-only access grants permissions directly to an application, and requires an administrator to consent to the required permission scopes. 有关仅限应用访问权限的详细信息,请参阅 Microsoft identity platform 和 OAuth 2.0 客户端凭据流For more details on app-only access, see Microsoft identity platform and the OAuth 2.0 client credentials flow.

我们来演练如何为简单脚本配置仅应用程序访问权限,以列出 Microsoft 365 租户中的用户和组。Let's walk through configuring app-only access for a simple script to list users and groups in your Microsoft 365 tenant.

配置Configuration

在使用仅限应用访问的 SDK 之前,您需要具备以下各项。Before you can use app-only access with the SDK, you need the following.

  • 证书用作应用程序的凭据。A certificate to use as a credential for the application. 这可以是自签名证书或来自颁发机构的证书。This can be a self-signed certificate or a certificate from an authority.
  • 您必须在 Azure AD 中 注册应用程序 ,并使用您的方案所需的权限范围进行配置,并共享证书的公钥。You must register an application in Azure AD, configure it with the permission scopes your scenario requires, and share the public key for your certificate.

证书Certificate

您将需要在将运行脚本的计算机上安装在用户的受信任存储区中的 x.509 证书。You will need an X.509 certificate installed in your user's trusted store on the machine where you will run the script. 您还需要以 .cer、pem 或 .crt 格式导出的证书公钥。You'll also need the certificate's public key exported in .cer, .pem, or .crt format. 你将需要证书主题的值。You'll need the value of the certificate subject.

注册应用程序Register the application

你可以在 Azure Active Directory 门户中或使用 PowerShell 注册应用程序。You can register the application either in the Azure Active Directory portal, or using PowerShell.

  1. 打开浏览器并导航到 Azure Active Directory 管理中心 ,并使用 Microsoft 365 租户组织管理员登录。Open a browser and navigate to the Azure Active Directory admin center and login using an Microsoft 365 tenant organization admin.

  2. 选择左侧导航栏中的“ Azure Active Directory ”,再选择“ 管理 ”下的“ 应用注册 ”。Select Azure Active Directory in the left-hand navigation, then select App registrations under Manage .

    应用注册的屏幕截图A screenshot of the App registrations

  3. 选择“新注册” 。Select New registration . 在“注册应用” 页上,按如下方式设置值。On the Register an application page, set the values as follows.

    • 将“名称” 设置为“Graph PowerShell Script”。Set Name to Graph PowerShell Script.
    • 仅将 受支持的帐户类型 设置为 此组织目录中的帐户Set Supported account types to Accounts in this organizational directory only .
    • 重定向 URI 保留为空。Leave Redirect URI blank.

    "注册应用程序" 页的屏幕截图

  4. 选择“ 注册 ”。Select Register . 在 " 图形 PowerShell 脚本 " 页面上,将应用程序的值复制 (客户端) id目录 (租户) id 并保存它们。On the Graph PowerShell Script page, copy the values of the Application (client) ID and Directory (tenant) ID and save them.

    新应用注册的应用程序 ID 的屏幕截图

  5. 选择 " 管理 " 下的 " API 权限 "。Select API Permissions under Manage . 选择 " 添加权限 "。Choose Add a permission .

  6. 依次选择 " Microsoft Graph " 和 " 应用程序权限 "。Select Microsoft Graph , then Application Permissions . 添加 用户。 read. allGroup. all ,然后选择 " 添加权限 "。Add User.Read.All and Group.Read.All , then select Add permissions .

  7. 配置的权限 中,删除委派的 用户。Microsoft Graph 下,选择权限右侧的 " ... ",然后选择 " 删除权限 " 来读取权限。In the Configured permissions , remove the delegated User.Read permission under Microsoft Graph by selecting the ... to the right of the permission and selecting Remove permission . 选择 "是,删除 以确认"。Select Yes, remove to confirm.

  8. 选择 " 授予管理员同意 ... " 按钮,然后选择 "是" 授予管理员同意配置的应用程序权限。Select the Grant admin consent for... button, then select Yes to grant admin consent for the configured application permissions. " 已配置权限 " 表中的 " 状态 " 列更改为 "已 授予"。The Status column in the Configured permissions table changes to Granted for ... .

    授予了管理员同意的 webhook 的已配置权限的屏幕截图

  9. 选择“管理” 下的“证书和密码” 。Select Certificates & secrets under Manage . 选择 " 上传证书 " 按钮。Select the Upload certificate button. 浏览到证书的公钥文件,然后选择 " 添加 "。Browse to your certificate's public key file and select Add .

身份验证Authenticate

完成上述配置步骤后,您应具有三条信息。You should have three pieces of information after completing the configuration steps above.

  • 上载到 Azure AD 应用注册的证书的证书主题。Certificate subject of the certificate uploaded to your Azure AD app registration.
  • 应用注册的应用程序 ID。Application ID for your app registration.
  • 你的租户 ID。Your tenant ID.

让我们使用它们来测试身份验证。Let's use those to test authentication. 打开 PowerShell 并运行以下命令,将占位符替换为您的信息。Open PowerShell and run the following command, replacing the placeholders with your information.

Connect-MgGraph -ClientID YOUR_APP_ID -TenantId YOUR_TENANT_ID -CertificateName YOUR_CERT_SUBJECT

如果成功,你将看到 "" Welcome To Microsoft Graph!If this succeeds, you will see Welcome To Microsoft Graph!. 运行 Get-MgContext 以验证您是否已通过仅限应用进行身份验证。Run Get-MgContext to verify that you've authenticated with app-only. 输出的外观应如下所示。The output should look like the following.

ClientId              : YOUR_APP_ID
TenantId              : YOUR_TENANT_ID
CertificateThumbprint :
Scopes                : {Group.Read.All, User.Read.All}
AuthType              : AppOnly
CertificateName       : YOUR_CERT_SUBJECT
Account               :
AppName               : Graph PowerShell Script
ContextScope          : Process

创建脚本Create the script

创建一个名为 GraphAppOnly.ps1 的新文件,并添加以下代码。Create a new file named GraphAppOnly.ps1 and add the following code.

# Authenticate
Connect-MgGraph -ClientID YOUR_APP_ID -TenantId YOUR_TENANT_ID -CertificateName YOUR_CERT_SUBJECT

Write-Host "USERS:"
Write-Host "======================================================"
# List first 50 users
Get-MgUser -Property "id,displayName" -PageSize 50 | Format-Table DisplayName, Id

Write-Host "GROUPS:"
Write-Host "======================================================"
# List first 50 groups
Get-MgGroup -Property "id,displayName" -PageSize 50 | Format-Table DisplayName, Id

# Disconnect
Disconnect-MgGraph

将命令中的占位符替换 Connect-MgGraph 为您的信息。Replace the placeholders in the Connect-MgGraph command with your information. 保存该文件,然后在创建该文件的目录中打开 PowerShell。Save the file, then open PowerShell in the directory where you created the file. 使用以下命令运行脚本。Run the script with the following command.

.\GraphAppOnly.ps1

该脚本输出用户和组的列表,该列表类似于 (截断以简化) 的以下输出。The script outputs a list of users and groups similar to the output below (truncated for brevity).

Welcome To Microsoft Graph!
USERS:
======================================================

DisplayName              Id
-----------              --
Conf Room Adams          88d1ba68-8ff5-4de2-90ed-768c00abcfae
Adele Vance              3103c7b9-cfe6-4cd3-a696-f88909b9a609
MOD Administrator        da3a885e-2d97-41de-9347-5271ef321b58
...

GROUPS:
======================================================

DisplayName                         Id
-----------                         --
App Development                     06dce3e5-d310-4add-ab2c-be728fb9076e
All Employees                       1a1cd42d-9801-4e9d-9b77-5215886174ef
Mark 8 Project Team                 2bf1b0d0-81f6-4e80-b971-d1db69f8d651
...