这个库，适用于 iOS 和 macOS 的 ADAL，将不再接收新的特性改进。取而代之的是，使用新的库 MSAL for iOS and macOS。
- 如果你正在开始一个新的项目，可以查阅 MSAL for iOS and macOS 文档 了解关于场景、用法和相关概念的详细信息。
- 如果你正在使用之前适用于 iOS 和 macOS 的 ADAL 库，可以按照此 迁移指南 来更新到 MSAL for iOS 和 macOS。
- 依赖 ADAL for iOS 和 macOS 的现有应用将继续工作。
Microsoft Azure Active Directory Authentication Library (ADAL) for iOS and macOS
=====================================
| 代码示例 | 参考文档 | 开发者指南 |
|---|
发布版本
我们建议保持 ADAL 的最新版本。检查最新版本的最佳地点是 GitHub 上的 发布页面，你还可以订阅 GitHub 的 Atom Feed，或者使用第三方工具如 Sibbell 在发布新版本时接收电子邮件。
获取最新版本的唯一批准方式是通过GitHub上的标记发行版，或依赖该数据的工具。例如 CocoaPods 可以让您更容易地设置项目依赖项并更新到最新版本。ADAL遵循 GitFlow分支模式。您决不应该从master分支以外的任何分支拉取ADAL版本进行发布，任何其他分支均为ADAL的开发或测试版本，这些版本可能会更改。
注意
-
要使用iOS 15，您至少需要版本5.0.0。但是，我们建议切换到版本6.0.0，因为5.0.0不再维护。
-
要使用iOS 10-11.3，您至少需要版本2.2.5。
-
要使用iOS 11.3-12.4，您至少需要版本2.6.3。
-
当使用Xcode 11构建时，要使用iOS 13+，您至少需要版本2.7.14或4.0.2。
-
ADAL支持iOS 10+和macOS 10.11+。在ADAL 4.0.0版本中删除了对iOS 9和macOS 10.10的支持。
-
WKWebView在iOS 12中，如果设备被锁定，则会断开网络连接。这是设计之初就决定的，无法配置。
iOS和macOS的ADAL SDK为您提供了仅用几行额外代码就为应用程序添加对工作账户支持的能力。此SDK为您的应用程序提供了完整的Microsoft Azure AD功能，包括对本机OAuth2协议的支持、用户级别同意的Web API集成以及双因素身份验证支持。最好的是，它是一个FOSS(免费和开源软件)，您可以参与我们构建这些库的开发过程。
贡献历史
示例和文档
我们在GitHub上提供了一系列完整的 示例应用程序 和 文档，以帮助您开始学习Azure身份系统。这包括Windows、Windows Phone、iOS、macOS、Android和Linux等本机客户端的教程。我们还提供了OAuth2、OpenID Connect、Graph API以及其他酷功能的完整教程。
Azure Identity 为 iOS 的示例在此处：https://github.com/AzureADSamples/NativeClient-iOS
社区帮助和支持
我们利用 Stack Overflow 与社区合作，支持 Azure Active Directory 及其 SDK，包括本 SDK！我们强烈建议您在 Stack Overflow 上提出您的问题（我们都在那里！）此外，浏览现有问题以查看是否有人之前提出过相同的问题。
我们建议您使用 "adal" 标签，这样我们就能看到它！这是 Stack Overflow 上关于 ADAL 的最新问答：http://stackoverflow.com/questions/tagged/adal
SSO 和条件访问支持
此库允许您的应用程序支持我们的 企业移动性套件，包括 条件访问，这样企业就可以在安全环境中使用您的应用程序。
要将您的应用程序配置为支持这些场景，请阅读此文档：如何在 iOS 上使用 ADAL 启用跨应用 SSO
安全报告
如果您发现我们的库或服务存在安全漏洞，请尽可能详细地报告给 [email protected]。您的提交可能符合通过 Microsoft 打赏计划 获得赏金的条件。请勿将安全漏洞发布在 GitHub Issues 或任何其他公开网站上。我们将在收到信息后不久与您联系。我们鼓励您通过访问 此页面 并订阅安全咨询警报来了解安全事件发生的时间。
贡献
所有代码均采用MIT许可，我们在GitHub上积极进行问题整理。我们热烈欢迎贡献和建议。您现在就可以克隆仓库并开始贡献。
快速开始
- 将仓库克隆到您的机器上
- 构建库或框架
- 将ADAL库或框架添加到您的项目中
下载
我们为使用此库使您的iOS项目具有多种选项变得简单。
选项1：Git Submodule
如果您的项目由git仓库管理，您可以将ADAL作为git子模块包含在内。首先查看GitHub发布页面以获取最新发布标签。使用该版本的代码将<latest_release_tag>替换。
git submodule add https://github.com/AzureAD/azure-activedirectory-library-for-objc adal
cd adal
git checkout tags/<latest_release_tag>
cd ..
git add adal
git commit -m "Use ADAL git submodule at <latest_release_tag>"
git push
我们建议仅同步到特定的发布标签，以确保您处于一个已知的良好点。我们不会支持发布标签之间的ADAL版本。
选项2：CocoaPods
您可以使用CocoaPods来保持ADAL在特定主版本上的更新。在您的Podfile中包含以下行
pod 'ADAL', '~> 6.0'
然后您可以运行pod install（如果是新的PodFile）或pod update（如果是现有的PodFile），以获取ADAL的最新版本。后续调用pod update也将更新到ADAL的最新发布版本。
ADAL正在使用子模块，所以如果你在Podfile中使用了ADAL的特定分支，你需要启用子模块，例如：
pod 'ADAL', :git => 'https://github.com/AzureAD/azure-activedirectory-library-for-objc', :branch => 'branch-name', :submodules => true
有关设置PodFile的更多信息，请参阅CocoaPods
选项 3: 源压缩包
要下载源代码的副本，首先确保您处于“master”分支，然后在右上角单击“克隆或下载”，然后单击“下载 ZIP”，或者您可以直接在这里下载
不建议这样做，因为它无法为您提供更新到最新版本的基础设施。
用法
缓存
iOS
Keychain 设置
在Xcode的导航器面板中单击您的项目。关闭您的应用程序目标并转到“功能”选项卡。滚到“密钥链共享”，打开开关。将“com.microsoft.adalcache”添加到该列表中。
或者，您可以通过将密钥链共享组设置为nil或您的应用程序的包ID来禁用密钥链共享。
[[ADALAuthenticationSettings sharedInstance] setDefaultKeychainGroup:nil];检查缓存
如果您需要检查应用中的缓存，您可以通过ADKeychainTokenCache接口来实现。
macOS
ADAL在macOS中不支持Keychain。默认的缓存实现将在进程生命周期内保留令牌，但它们不会被保留。如果需要保留令牌，您必须实现ADALTokenCacheDelegate并在创建AuthenticationContext时提供它
@protocol ADALTokenCacheDelegate <NSObject>
- (void)willAccessCache:(nonnull ADALTokenCache *)cache;
- (void)didAccessCache:(nonnull ADALTokenCache *)cache;
- (void)willWriteCache:(nonnull ADALTokenCache *)cache;
- (void)didWriteCache:(nonnull ADALTokenCache *)cache;
@end在这个委托中，您可以在缓存对象上调用-serialize和-deserialize来以NSData二进制流的形式保存或更新缓存。
快速上手
API的起点在ADALAuthenticationContext.h头文件中。ADALAuthenticationContext是用于获取、缓存和提供访问令牌的主要类。
如何快速从SDK获取令牌
+ (void)getToken:(void (^)(NSString*))completionBlock;
{
ADALAuthenticationError *error = nil;
authContext = [ADALAuthenticationContext authenticationContextWithAuthority:@"https://login.microsoftonline.com/common"
error:&error];
[authContext acquireTokenWithResource:@"https://graph.windows.net"
clientId:@"<Your Client ID>" // Comes from App Portal
redirectUri:[NSURL URLWithString:@"<Your Redirect URI>"] // Comes from App Portal
completionBlock:^(ADALAuthenticationResult *result)
{
if (AD_SUCCEEDED != result.status){
// display error on the screen
[self showError:result.error.errorDetails];
}
else{
completionBlock(result.accessToken);
}
}];
}将令牌添加到authHeader以访问API
NSMutableURLRequest *request = [[NSMutableURLRequest alloc] initWithURL:yourAppURL];
NSString *authHeader = [NSString stringWithFormat:@"Bearer %@", accessToken];
[request addValue:authHeader forHTTPHeaderField:@"Authorization"];
NSOperationQueue *queue = [[NSOperationQueue alloc] init];
[NSURLConnection sendAsynchronousRequest:request
queue:queue
completionHandler:^(NSURLResponse *response, NSData *data, NSError *error)
{
// Process Response Here
}];代理身份验证
如果您的应用程序需要条件访问或证书身份验证（当前处于预览状态）支持，您必须设置您的 AuthenticationContext 和 redirectURI，以便能够与 Azure Authenticator 应用进行通信。
在您的上下文中启用代理模式
代理是针对每个身份验证上下文启用的。如果您希望 ADAL 调用代理，您必须设置您的凭据类型
/*! See the ADCredentialsType enumeration definition for details */
@property ADALCredentialsType credentialsType;AD_CREDENTIALS_AUTO 设置将允许 ADAL 尝试调用代理，而 AD_CREDENTIALS_EMBEDDED 将阻止 ADAL 调用代理。
注册 URL 模式
ADAL 使用 URL 来调用代理并返回到您的应用程序。为了完成这个往返，您需要为应用程序注册一个 URL 方案。我们建议使 URL 方案相对独特，以最大限度地减少其他应用程序使用相同 URL 方案的可能性。
<key>CFBundleURLTypes</key>
<array>
<dict>
<key>CFBundleTypeRole</key>
<string>Editor</string>
<key>CFBundleURLName</key>
<string>com.MSOpenTech.MyTestiOSApp</string>
<key>CFBundleURLSchemes</key>
<array>
<string>x-msauth-mytestiosapp</string>
</array>
</dict>
</array>
LSApplicationQueriesSchemes
ADAL 使用 –canOpenURL: 来检查设备上是否已安装代理。在 iOS 9 中，Apple 锁定了应用程序可以查询的方案。您需要在 info.plist 文件中的 LSApplicationQueriesSchemes 部分添加“msauth”和 "msauthv3"。请注意，当使用 Xcode 11+ 编译时，需要 "msauthv3" 方案。
<key>LSApplicationQueriesSchemes</key>
<array>
<string>msauth</string>
<string>msauthv3</string>
</array>
重定向 URI
这将附加到您的重定向 URI 的一些额外要求。您的重定向 URI 必须以正确格式存在。
<app-scheme>://<your.bundle.id>
ex: x-msauth-mytestiosapp://com.microsoft.mytestiosapp
此重定向 URI 需要在应用门户上注册为有效重定向 URI。另外，还需要注册第二个“msauth”形式以处理 Azure Authenticator 中的证书身份验证。
msauth://code/<broker-redirect-uri-in-url-encoded-form>
ex: msauth://code/x-msauth-mytestiosapp%3A%2F%2Fcom.microsoft.mytestiosapp
支持 iOS 13
如果您已采用 UISceneDelegate，您必须在 scene:openURLContexts: 方法中添加一个 ADAL 回调.
这使 ADAL 能够从 Microsoft Authenticator 应用程序获取响应。
例如
- (void)scene:(UIScene *)scene openURLContexts:(NSSet<UIOpenURLContext *> *)URLContexts
{
UIOpenURLContext *context = URLContexts.anyObject;
NSURL *url = context.URL;
NSString *sourceApplication = context.options.sourceApplication;
[ADALAuthenticationContext handleADALResponse:url sourceApplication:sourceApplication];
}如果您尚未使用 UISceneDelegate 功能，您可以忽略此步。
诊断
日志
ADAL 严重依赖日志来诊断问题。强烈建议您设置 ADAL 日志回调并提供一种方式，以便用户在遇到身份验证问题时可以提交日志。
日志回调
您可以设置一个回调来捕获 ADAL 日志并将其集成到自己的应用程序的日志中
/*!
The LogCallback block for the ADAL logger
@param logLevel The level of the log message
@param message A short log message describing the event that occurred, this string will not contain PII.
@param additionalInfo A longer message that may contain PII and other details relevant to the event.
@param errorCode An integer error code if the log message is an error.
@param userInfo A dictionary with other information relevant to the log message. The information varies,
for most error messages the error object will be in the "error" key.
*/
typedef void (^LogCallback)(ADAL_LOG_LEVEL logLevel,
NSString *message,
NSString *additionalInfo,
NSInteger errorCode,
NSDictionary *userInfo);否则，ADAL 默认输出到 NSLog，这将打印信息到控制台。
示例日志消息
ADAL iOS 的消息部分格式为 ADALiOS [时间戳 - 关联_id] 消息
ADAL [2015-06-22 19:42:53 - 1030CB25-798F-4A6F-97DF-04A3A3E9DFF2] ADAL API call [Version - 2.1.0]
提供关联 ID 和时间戳对于跟踪问题非常有帮助。唯一可靠的获取它们的地方是来自 ADAL 日志。
日志级别
- ADAL_LOG_LEVEL_NO_LOG (禁用所有日志)
- ADAL_LOG_LEVEL_ERROR (默认级别，只有发生错误时才打印信息)
- ADAL_LOG_LEVEL_WARNING (警告)
- ADAL_LOG_LEVEL_INFO (库入口点，带参数和各种密钥链操作)
- ADAL_LOG_LEVEL_Verbose (API 跟踪)
要在您的应用程序中设置日志级别，请调用 +[ADALLogger setLevel:]
[ADALLogger setLevel:ADAL_LOG_LEVEL_INFO]网络跟踪
您可以使用各种工具来捕获 ADAL 生成的 HTTP 流量。如果您熟悉 OAuth 协议或需要向 Microsoft 或其他支持渠道提供诊断信息，这非常有用。
Charles 是在 OS X 中使用最简单的 HTTP 跟踪工具。使用以下链接设置 Charles，以便正确记录 ADAL 网络流量。为了使其有用，您需要配置 Charles，以记录未加密的 SSL 流量。注意：以此方式生成的跟踪可能包含高度敏感的信息，如访问令牌、用户名和密码。
如果您的账户是生产环境，请不要与第三方共享这些跟踪。如果您需要将跟踪提供给某人以获得支持，请使用您不介意共享的用户名和密码的临时账户重现问题。
ADALAuthenticationError
当发生错误时，ADALAuthenticationErrors 将被提供给 ADALAuthenticationResult 的 error 属性中的所有回调。它们可以用于让应用程序向用户显示更详细的错误信息，但是 ADAL 错误信息未本地化。所有 ADAuthenticationErrors 都会通过 ADAL 日志记录器记录。
##常见问题
使用 ADAL 库的应用程序因以下异常崩溃
*** 应用程序终止，未捕获的异常 'NSInvalidArgumentException'，原因：'+[NSString isStringNilOrBlank:]: unrecognized selector sent to class 0x13dc800'
解决方案：请确保将 "-ObjC" 标志添加到应用程序 "其他链接器标志" 构建设置中。有关更多信息，请参阅 Apple 关于使用静态库的文档
https://developer.apple.com/library/ios/technotes/iOSStaticLibraries/Articles/configuration.html#//apple_ref/doc/uid/TP40012554-CH3-SW1.
登录信息无法保留，缓存总是返回空
解决方案：要么将 "com.microsoft.adalcache" 密钥链共享权限添加到您的应用程序中，要么在 ADAuthenticationSettings 中传递您的应用程序捆绑ID以禁用密钥链共享
[[ADALAuthenticationSettings sharedInstance] setDefaultKeychainGroup:nil];ADAL 在 iOS 9 及更高版本中不断返回 SSL 错误
iOS 9增加了应用程序传输安全（ATS）。ATS限制了应用程序访问互联网，除非它们满足包括TLS 1.2和SHA-256在内的多个安全要求。它还阻止了依赖于自签名的证书来破解SSL的网络跟踪。禁用ATS必须在应用程序的info.plist文件中完成，有关NSAppTransport info.plist键的更多信息，请参阅文档。
许可证
版权（C）所有微软公司保留所有权利。在MIT许可证（以下简称“许可证”）下许可；
我们尊重并遵守微软开源行为准则
该项目采用了微软开源行为准则。有关更多信息，请参阅行为准则常见问题解答或与[email protected]联系，提出任何额外的问题或意见。