Microsoft Azure Active Directory Authentication Library (ADAL) for iOS
注意：ADAL 1.x 已进入维护模式。我们建议尽快更新到 2.x。
如何使用 Cocoapods 更新您的应用程序（推荐）
如果您的库正在使用 1.2 版本，确保以下行位于您的应用程序根目录中的 Podfile 文件中：
pod 'AdalLib', '~> 1.2'
完成后，运行 pod update 命令来更新您的应用程序。
如何使用源更新您的应用程序
- 从您需要的任务下载最新代码。
- 在 XCode 11 或更高版本的项目中，点击 File -> Add Files
- 在出现的 Finder 中，导航到您下载 ADAL 源的位置。转到 ADAL 文件夹，选择
ADAL.xcodeproj并点击 Add。 - 您会在左侧的项目列表中看到另一个名为
ADAL.xcodeproj的项目。 - 在您的应用程序的“链接框架和库”的通用项目设置中，确保ADALiOS.a已列出，并且字体颜色不是红色。红色字体表示Xcode找不到库，您需要通过移除条目并重新添加来更新位置。
- 如果它不在那里或字体颜色是红色，请按“+”图标。您应该看到可用库中的ADALiOS.a。选择它，然后点击确定。
- 可选：如果您想使用框架，也可以选择框架版本。请确保您选择的是iOS目标，而不是框架的Mac目标。
- 编译并测试您的应用程序。
=====================================
ADAL SDK for iOS和Mac OS X使您能够通过几行额外的代码为应用程序添加对工作帐户的支持。此SDK为您的应用程序提供了Microsoft Azure AD的全部功能，包括对OAuth2行业标准协议的支持、与用户级别同意的Web API集成以及双因素身份验证支持。最好的是，它是FOSS（免费和开源软件），这样您可以在我们构建这些库的同时参与开发过程。
贡献历史
示例和文档
我们在GitHub上提供了一套完整的示例应用程序和文档，以帮助您开始学习Azure Identity系统。 这包括针对如Windows、Windows Phone、iOS、OSX、Android和Linux等原生客户端的教程。我们还提供了对OAuth2、OpenID Connect、Graph API和其他出色功能的完整指南。
您的iOS Azure Identity示例在此： https://github.com/AzureADSamples/NativeClient-iOS
社区帮助和支持
我们利用Stack Overflow与社区合作来支持Azure Active Directory及其SDK，包括这个！我们强烈建议您在Stack Overflow上提问（我们都在那里！）同时浏览现有问题，看看是否有人以前提出过类似的问题。
我们建议您使用"adal"标签，这样我们就可以看到它了！这是Stack Overflow上关于ADAL的最新问答：http://stackoverflow.com/questions/tagged/adal
贡献
所有代码均在MIT许可下，并且在GitHub上积极进行问题分类。我们热情欢迎贡献和反馈。您现在可以克隆仓库开始贡献。
快速开始
- 克隆仓库到您的机器
- 构建库
- 将ADALiOS库添加到您的项目中
- 将ADALiOSBundle中的storyboards添加到您的项目资源中
- 将libADALiOS添加到“链接库”阶段。
##下载
我们为您提供了多种方式在iOS项目中使用此库。
###选项1：源码包
要下载源代码的副本，请点击页面右侧的“下载ZIP”或点击此处。
###选项2：CocoaPods
pod 'AdalLib', '~> 1.2'
用法
在Xcode项目中设置密钥链共享权限
在Xcode的导航器窗格中点击您的项目。单击您的应用程序目标，然后选择“能力”选项卡。滚动到“密钥链共享”，并切换为开启。将“com.microsoft.adalcache”添加到该列表中。
或者，您也可以通过将密钥链共享组设置为应用程序的包ID来禁用密钥链共享。
[[ADAuthenticationSettings sharedInstance] setSharedCacheKeychainGroup:@"<your.bundle.id.here>"];ADAuthenticationContext
API 的起点在 ADAuthenticationContext.h 头文件中。ADAuthenticationContext 是用于获取、缓存和提供访问令牌的主要类。
如何从 SDK 中快速获取令牌
ADAuthenticationContext* authContext;
NSString* authority;
NSString* redirectUriString;
NSString* resourceId;
NSString* clientId;
+(void) getToken : (BOOL) clearCache completionHandler:(void (^) (NSString*))completionBlock;
{
ADAuthenticationError *error;
authContext = [ADAuthenticationContext authenticationContextWithAuthority:authority
error:&error];
NSURL *redirectUri = [NSURL URLWithString:redirectUriString];
if(clearCache){
[authContext.tokenCacheStore removeAll];
}
[authContext acquireTokenWithResource:resourceId
clientId:clientId
redirectUri:redirectUri
completionBlock:^(ADAuthenticationResult *result) {
if (AD_SUCCEEDED != result.status){
// display error on the screen
[self showError:result.error.errorDetails];
}
else{
completionBlock(result.accessToken);
}
}];
}将令牌添加到 authHeader 以访问 API
+(NSArray*) getTodoList:(id)delegate
{
__block NSMutableArray *scenarioList = nil;
[self getToken:YES completionHandler:^(NSString* accessToken){
NSURL *todoRestApiURL = [[NSURL alloc]initWithString:todoRestApiUrlString];
NSMutableURLRequest *request = [[NSMutableURLRequest alloc]initWithURL:todoRestApiURL];
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) {
if (error == nil){
NSArray *scenarios = [NSJSONSerialization JSONObjectWithData:data options:0 error:nil];
todoList = [[NSMutableArray alloc]init];
//each object is a key value pair
NSDictionary *keyVauePairs;
for(int i =0; i < todo.count; i++)
{
keyVauePairs = [todo objectAtIndex:i];
Task *s = [[Task alloc]init];
s.id = (NSInteger)[keyVauePairs objectForKey:@"TaskId"];
s.description = [keyVauePairs objectForKey:@"TaskDescr"];
[todoList addObject:s];
}
}
[delegate updateTodoList:TodoList];
}];
}];
return nil; } 诊断
日志
ADAL 严重依赖日志来诊断问题。强烈建议您设置 ADAL 日志回调，并为用户提供在出现身份验证问题时提交日志的方法。
日志回调
您可以设置一个回调来捕获 ADAL 日志，并将其集成到您自己的应用程序的日志中
[ADLogger setLogCallBack:^(ADAL_LOG_LEVEL logLevel, NSString *message, NSString *additionalInformation, NSInteger errorCode) {
//HANDLE LOG MESSAGE HERE
}]否则，ADAL 默认输出到 NSLog，这将在控制台打印消息。
示例日志消息
ADAL iOS的消息部分格式为ADALiOS [时间戳 - 关联ID] 消息
ADALiOS [2015-06-22 19:42:53 - 1030CB25-798F-4A6F-97DF-04A3A3E9DFF2] ADAL API call [Version - 1.2.5]
提供关联ID和时间戳对于跟踪问题至关重要。唯一可靠地获取它们的地方是来自ADAL日志。
日志级别
- ADAL_LOG_LEVEL_NO_LOG (禁用所有日志)
- ADAL_LOG_LEVEL_ERROR (默认级别，仅在发生错误时输出信息)
- ADAL_LOG_LEVEL_WARNING (警告)
- ADAL_LOG_LEVEL_INFO (库入口点，带有参数和关键链操作)
- ADAL_LOG_LEVEL_Verbose (API追踪 )
要在您的应用程序中设置日志级别，请调用+[ADLogger setLevel:]
[ADLogger setLevel:ADAL_LOG_LEVEL_INFO]网络追踪
您可以使用各种工具来捕获ADAL生成的HTTP流量。如果您熟悉OAuth协议或需要向Microsoft或其他支持渠道提供诊断信息，这非常有用。
Charles是最容易使用的OSX HTTP追踪工具。使用以下链接设置它以正确记录ADAL网络流量。为了使其有用，必须配置Charles来记录未加密的SSL流量。注意：以这种方式生成的跟踪可能包含高度敏感的信息，例如访问令牌、用户名和密码。
如果您正在使用生产帐户，请勿将这些跟踪与第三方共享。如果您需要向某人提供跟踪以获取支持，请使用您不介意共享的用户名和密码的临时帐户重现问题。
ADAuthenticationError
当发生错误时，ADALError将提供在ADAuthenticationResult的error属性中所有回调的所有ADAuthenticationError。它们可用于使应用程序向用户显示更详细的信息，但是ADAL错误消息没有本地化。所有ADAuthenticationError都以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中通过传递您的应用程序包标识来禁用钥匙串共享
[[ADAuthenticationSettings sharedInstance] setSharedCacheKeychainGroup:@"<your.bundle.id.here>"];在iOS 9及更高版本中，ADAL持续返回SSL错误
iOS 9增加了App Transport Security (ATS)。ATS限制了应用程序访问互联网，除非它们满足包括TLS 1.2和SHA-256在内的几个安全要求。它还阻止了依赖于自签名证书破解SSL的轨迹网络。需要在应用程序的info.plist文件中禁用ATS，有关更多信息请参阅关于NSAppTransport info.plist键的文档。
许可
版权(c) 微软开源技术公司。保留所有权利。在Apache许可证2.0版本下许可（“许可证”）;