快速入门:从 iOS 或 macOS 应用将用户登录并调用 Microsoft Graph API
欢迎使用! 这可能不是你期望看到的页面。 在修复时,此链接应会将你转至正确的文章:
对此造成你的不便,我们深表歉意;感谢你的耐心等待,我们正在努力解决此问题。
在本快速入门中,你将下载并运行一个代码示例,该示例演示本机 iOS 或 macOS 应用程序如何让用户登录并获取访问令牌来调用 Microsoft Graph API。
本快速入门适用于 iOS 和 macOS 应用。 某些步骤仅为 iOS 应用所需,并将如下所示进行说明。
先决条件
- 具有活动订阅的 Azure 帐户。 创建帐户。
- XCode 10+
- iOS 10+
- macOS 10.12+
示例工作原理
步骤 1:配置应用程序
为使此快速入门的代码示例正常运行,请添加与身份验证代理兼容的重定向 URI。
应用程序已使用这些属性进行配置
步骤 2:下载示例项目
步骤 3:安装依赖项
- 解压缩 zip 文件。
- 在终端窗口中导航到已下载代码示例所在的文件夹,然后运行
pod install
以安装最新的 MSAL 库。
步骤 4:应用已配置并可以运行
我们已经为项目配置了应用属性的值,并且该项目已准备好运行。
注意
Enter_the_Supported_Account_Info_Here
如果为 Microsoft Entra 国家云生成应用,请将以“let kGraphEndpoint”和“let kAuthority”开头的行替换为正确的终结点。 若要进行全局访问,请使用默认值:
let kGraphEndpoint = "https://microsoftgraph.chinacloudapi.cn/" let kAuthority = "https://login.partner.microsoftonline.cn/common"
此处阐述了其他终结点。 例如,若要在 Microsoft Entra 德国运行本快速入门,请使用以下命令:
let kGraphEndpoint = "https://graph.microsoft.de/" let kAuthority = "https://login.microsoftonline.de/common"
打开项目设置。 在“标识”部分,输入以前在门户中输入的捆绑标识符。
右键单击“Info.plist”,然后选择“打开为”>“源代码”。
在 dict 根节点下,将
Enter_the_bundle_Id_Here
替换为你在门户中使用的捆绑 ID。 请注意字符串中的msauth.
前缀。<key>CFBundleURLTypes</key> <array> <dict> <key>CFBundleURLSchemes</key> <array> <string>msauth.Enter_the_Bundle_Id_Here</string> </array> </dict> </array>
构建并运行应用!
更多信息
阅读以下各部分来详细了解本快速入门。
获取 MSAL
MSAL (MSAL.framework) 是一个库,用于用户登录和请求令牌,此类令牌用于访问受 Microsoft 标识平台保护的 API。 可以使用以下过程将 MSAL 添加到应用程序中:
$ vi Podfile
将以下内容添加到此 podfile(包含项目的目标):
use_frameworks!
target 'MSALiOS' do
pod 'MSAL'
end
运行 CocoaPods 安装命令:
pod install
初始化 MSAL
可以通过添加以下代码,为 MSAL 添加引用:
import MSAL
然后,使用以下代码对 MSAL 进行初始化:
let authority = try MSALAADAuthority(url: URL(string: kAuthority)!)
let msalConfiguration = MSALPublicClientApplicationConfig(clientId: kClientID, redirectUri: nil, authority: authority)
self.applicationContext = try MSALPublicClientApplication(configuration: msalConfiguration)
其中: 说明 clientId
在 portal.azure.cn 中注册的应用程序的应用程序 ID authority
Microsoft 标识平台。 在大多数情况下,这是 https://login.partner.microsoftonline.cn/common
>redirectUri
应用程序的重定向 URI。 可以传递“nil”以使用默认值,也可以使用自定义重定向 URI。
(仅适用于 iOS)其他应用要求
应用还必须在 AppDelegate
中有以下内容。 这样就可以在你进行身份验证时让 MSAL SDK 处理来自身份验证代理应用的令牌响应。
func application(_ app: UIApplication, open url: URL, options: [UIApplication.OpenURLOptionsKey : Any] = [:]) -> Bool {
return MSALPublicClientApplication.handleMSALResponse(url, sourceApplication: options[UIApplication.OpenURLOptionsKey.sourceApplication] as? String)
}
注意
在 iOS 13+ 上,如果采用 UISceneDelegate
而不是 UIApplicationDelegate
,请改将此代码置于 scene:openURLContexts:
回调中(请参阅 Apple 的文档)。
如果支持兼容旧版 iOS 的 UISceneDelegate 和 UIApplicationDelegate,则需将 MSAL 回调置于两个位置。
func scene(_ scene: UIScene, openURLContexts URLContexts: Set<UIOpenURLContext>) {
guard let urlContext = URLContexts.first else {
return
}
let url = urlContext.url
let sourceApp = urlContext.options.sourceApplication
MSALPublicClientApplication.handleMSALResponse(url, sourceApplication: sourceApp)
}
最后,应用必须在 Info.plist 中有一个与 CFBundleURLTypes
一起的 LSApplicationQueriesSchemes
条目。 示例包含此条目。
<key>LSApplicationQueriesSchemes</key>
<array>
<string>msauthv2</string>
<string>msauthv3</string>
</array>
登录用户与请求令牌
MSAL 有两种用来获取令牌的方法:acquireToken
和 acquireTokenSilent
。
acquireToken:以交互方式获取令牌
有些情况下,需要用户与 Microsoft 标识平台交互。 在这些情况下,最终用户可能需要选择其帐户、输入其凭据,或者同意应用的权限。 例如,
- 用户首次登录应用程序
- 用户在重置其密码时需输入其凭据。
- 应用程序首次请求访问资源时
- 需要 MFA 或其他条件访问策略时
let parameters = MSALInteractiveTokenParameters(scopes: kScopes, webviewParameters: self.webViewParamaters!)
self.applicationContext!.acquireToken(with: parameters) { (result, error) in /* Add your handling logic */}
其中: 说明 scopes
包含所请求的范围(对于 Microsoft Graph 为 ["https://microsoftgraph.chinacloudapi.cn/user.read"]
,对于自定义 Web API (api://<Application ID>/access_as_user
) 为[ "<Application ID URL>/scope" ]
)
acquireTokenSilent:以无提示方式获取访问令牌
应用不应该在用户每次请求令牌时都要求他们登录。 如果用户已登录,则此方法允许应用以静默方式请求令牌。
self.applicationContext!.getCurrentAccount(with: nil) { (currentAccount, previousAccount, error) in
guard let account = currentAccount else {
return
}
let silentParams = MSALSilentTokenParameters(scopes: self.kScopes, account: account)
self.applicationContext!.acquireTokenSilent(with: silentParams) { (result, error) in /* Add your handling logic */}
}
其中: 说明 scopes
包含所请求的范围(即针对 Microsoft Graph 的 ["https://microsoftgraph.chinacloudapi.cn/user.read"]
或针对自定义 Web API (api://<Application ID>/access_as_user
) 的[ "<Application ID URL>/scope" ]
)account
请求令牌时对应的帐户。 本快速入门介绍单帐户应用程序。 如果要构建多帐户应用,则需要定义相关逻辑,以使用 accountsFromDeviceForParameters:completionBlock:
并传递正确的accountIdentifier
来标识用于令牌请求的帐户
帮助和支持
如果需要帮助、需要报告问题,或者需要详细了解支持选项,请参阅面向开发人员的帮助和支持。
后续步骤
继续学习分步教程,在该教程中,你将生成一个从 Microsoft 标识平台获取访问令牌并使用它来调用 Microsoft Graph API 的 iOS 或 macOS 应用。