快速入门:获取令牌并从 Java 守护程序应用中调用 Microsoft Graph API
在本快速入门中,你将下载并运行一个代码示例,该示例演示 Java 应用程序如何使用应用的标识获取访问令牌来调用 Microsoft Graph API 并在目录中显示用户列表。 代码示例演示无人参与的作业或 Windows 服务如何使用应用程序标识而不是用户标识运行。
先决条件
若要运行此示例,需要:
- Java 开发工具包 (JDK) 8 或更高版本
- Maven
注册并下载快速入门应用
提示
本文中的步骤可能因开始使用的门户而略有不同。
步骤 1:注册应用程序
若要手动注册应用程序并将应用的注册信息添加到解决方案,请执行以下步骤:
- 至少以应用程序开发人员的身份登录到 Microsoft Entra 管理中心。
- 如果你有权访问多个租户,请使用顶部菜单中的“设置”图标 , 通过“目录 + 订阅”菜单切换到你希望在其中注册应用程序的租户。
- 浏览到“标识”>“应用程序”>“应用程序注册”。
- 选择“新注册”。
- 输入应用程序的名称(例如
Daemon-console
)。 应用的用户可能会看到此名称,你稍后可对其进行更改。 - 选择“注册” 。
- 在“管理”下,选择“证书和机密”。
- 在“客户端机密”下,选择“新建客户端机密”,输入名称,然后选择“添加” 。 将机密值记录在安全的位置,以供在后面的步骤中使用。
- 在“管理”下,选择“API 权限”>“添加权限” 。 选择“Microsoft Graph”。
- 选择“应用程序权限”。
- 在“用户”节点下选择“User.Read.All”,然后选择“添加权限” 。
步骤 2:下载 Java 项目
步骤 3:配置 Java 项目
- 将 zip 文件解压缩到靠近磁盘根目录的本地文件夹中,例如
C:\Azure-Samples
。 - 导航到
msal-client-credential-secret
子文件夹。 - 编辑
src\main\resources\application.properties
,将字段AUTHORITY
、CLIENT_ID
和SECRET
的值替换为以下代码片段:
AUTHORITY=https://login.partner.microsoftonline.cn/Enter_the_Tenant_Id_Here/
CLIENT_ID=Enter_the_Application_Id_Here
SECRET=Enter_the_Client_Secret_Here
其中:
Enter_the_Application_Id_Here
- 是已注册应用程序的应用程序(客户端)ID。Enter_the_Tenant_Id_Here
- 将此值替换为租户 ID 或租户名称(例如 contoso.microsoft.com) 。Enter_the_Client_Secret_Here
- 将此值替换为在步骤 1 中创建的客户端机密。
提示
若要查找“应用程序(客户端) ID”、“目录(租户) ID”的值,请转到应用的“概览”页。 若要生成新密钥,请转到“证书和机密”页。
步骤 4:管理员同意
如果尝试在此时运行应用程序,则会收到“HTTP 403 - 禁止访问”错误:Insufficient privileges to complete the operation
。 之所以出现这种错误,是因为任何仅限应用的权限都需要管理员同意:目录的全局管理员必须为应用程序授予同意。 根据自己的角色选择下面的一个选项:
全局租户管理员
如果你是全局租户管理员,请转到“应用注册”中的“API 权限”页面,选择“为 {租户名称} 授予管理员许可”(其中,{租户名称} 是目录的名称)。
标准用户
如果你是租户的标准用户,则需要请求全局管理员为你的应用程序授予管理员同意。 为此,请将以下 URL 提供给管理员:
https://login.partner.microsoftonline.cn/Enter_the_Tenant_Id_Here/adminconsent?client_id=Enter_the_Application_Id_Here
其中:
Enter_the_Tenant_Id_Here
- 将此值替换为租户 ID 或租户名称(例如 contoso.microsoft.com)Enter_the_Application_Id_Here
- 是已注册应用程序的应用程序(客户端)ID。
步骤 5:运行应用程序
可通过从 IDE 中运行 ClientCredentialGrant.java 的主方法,直接测试示例。
从 shell 或命令行:
$ mvn clean compile assembly:single
这会在 /targets
目录中生成一个 msal-client-credential-secret-1.0.0.jar
文件。 使用 Java 可执行文件运行此内容,如下所示:
$ java -jar msal-client-credential-secret-1.0.0.jar
运行后,应用程序应显示配置的租户中的用户列表。
重要
本快速入门应用程序使用客户端机密将自己标识为机密客户端。 由于客户端机密是以纯文本形式添加到项目文件的,因此为了安全起见,建议在考虑将应用程序用作生产应用程序之前,使用证书来代替客户端机密。 若要详细了解如何使用证书,请查看有关此示例的这些说明,它们位于同一 GitHub 存储库,但在另一个文件夹(即 MSAL-client-credential-certificate)中。
详细信息
MSAL Java
MSAL Java 是一个用于登录用户和请求令牌的库,此类令牌用于访问受 Microsoft 标识平台保护的 API。 如前所述,本快速入门请求令牌的方法是使用应用程序自身的标识而不是委托的权限。 在此示例中使用的身份验证流称为客户端凭据 oauth 流。 若要详细了解如何搭配使用 MSAL Java 和守护程序应用,请参阅本文。
可以使用 Maven 或 Gradle 将 MSAL4J 添加到应用程序,以通过对应用程序的 pom.xml (Maven) 或 build.gradle (Gradle) 文件进行以下更改来管理依赖项。
在 pom.xml 中:
<dependency>
<groupId>com.microsoft.azure</groupId>
<artifactId>msal4j</artifactId>
<version>1.0.0</version>
</dependency>
在 build.gradle 中:
compile group: 'com.microsoft.azure', name: 'msal4j', version: '1.0.0'
MSAL 初始化
通过将以下代码添加到要在其中使用 MSAL4J 的文件的顶部,来添加对 MSAL for Java 的引用:
import com.microsoft.aad.msal4j.*;
然后,使用以下代码对 MSAL 进行初始化:
IClientCredential credential = ClientCredentialFactory.createFromSecret(CLIENT_SECRET);
ConfidentialClientApplication cca =
ConfidentialClientApplication
.builder(CLIENT_ID, credential)
.authority(AUTHORITY)
.build();
其中: | 说明 |
---|---|
CLIENT_SECRET |
是为应用程序创建的客户端机密。 |
CLIENT_ID |
是所注册应用程序的“应用程序(客户端) ID”。 可以在“概览”页中找到此值。 |
AUTHORITY |
用户要进行身份验证的 STS 终结点。 对于公有云,通常为 https://login.partner.microsoftonline.cn/{tenant} ,其中 {tenant} 是租户名称或租户 ID。 |
请求令牌
若要通过应用的标识来请求令牌,请使用 acquireToken
方法:
IAuthenticationResult result;
try {
SilentParameters silentParameters =
SilentParameters
.builder(SCOPE)
.build();
// try to acquire token silently. This call will fail since the token cache does not
// have a token for the application you are requesting an access token for
result = cca.acquireTokenSilently(silentParameters).join();
} catch (Exception ex) {
if (ex.getCause() instanceof MsalException) {
ClientCredentialParameters parameters =
ClientCredentialParameters
.builder(SCOPE)
.build();
// Try to acquire a token. If successful, you should see
// the token information printed out to console
result = cca.acquireToken(parameters).join();
} else {
// Handle other exceptions accordingly
throw ex;
}
}
return result;
其中: | 说明 |
---|---|
SCOPE |
包含请求的范围。 对于机密客户端,这应该使用与 {Application ID URI}/.default 类似的格式,指示所请求的范围是在应用对象集中静态定义的范围(就 Microsoft Graph 来说,{Application ID URI} 指向 https://microsoftgraph.chinacloudapi.cn )。 对于自定义 Web API,{Application ID URI} 是在“应用注册”的“公开 API”部分中定义的。 |
帮助和支持
如果需要帮助、需要报告问题,或者需要详细了解支持选项,请参阅面向开发人员的帮助和支持。
后续步骤
若要详细了解守护程序应用程序,请参阅方案登陆页面。