NXOAuth2Client 1.2.8

NXOAuth2Client 1.2.8

×

测试已测试✓
语言语言 Obj-CObjective C
许可证 BSD
发布最后发布2014年12月

由 Thomas Kollbach，nxtbgthng 维护。

NXOAuth2Client 1.2.8

  • 作者：
  • nxtbgthng

OAuth2Client

适用于 Mac OS X & iOS (Cocoa & Cocoa touch) 的 OAuth2 库。

描述

此库基于 OAuth2 规范草案 10。它实现了 原生应用程序配置文件，并通过内部或外部用户代理支持最终用户授权端点。此外，它还支持通过提示最终用户输入其用户名和密码，并直接使用它们获取访问令牌的用户凭证流。有关如何选择身份验证流的信息，请参阅代理的描述。

入门

获取源代码

获取源代码与进行以下操作一样简单：
git clone git://github.com/nxtbgthng/OAuth2Client.git

将库手动包括到您的 Xcode 项目中

iOS 项目

  • 将 OAuth2Client 文件夹放置在您的源根目录下
  • 将 OAuth2Client.xcodeproj 拖到项目中
  • 在您的构建目标下，选择 构建阶段 选项卡。
    • 在 目标依赖 下添加 OAuth2Client
    • 在 链接二进制与库 下，添加 libOAuth2Client.a
  • 在 构建设置 下，
    • 将 $(SRCROOT)/path/to/OAuth2Client 添加到 头文件搜索路径 中，设置为 递归
    • 将 -ObjC 添加到 其他链接器标志
  • #import "NXOAuth2.h"
  • 添加 Security.framework 作为构建依赖项

桌面 Mac 项目

  • 将 OAuth2Client.xcodeproj 拖到您的项目中
  • 将 OAuth2Client.framework 添加为构建依赖项
  • 添加 Security.framework 作为构建依赖项
  • 将 $(CONFIGURATION_BUILD_DIR)/$(CONTENTS_FOLDER_PATH)/Frameworks 添加到您的目标的框架搜索路径
  • 将您的目标链接到 OAuth2Client（将 OAuth2Client.xcodeproj 中的 OAuth2Client.framework 产物拖到您的目标的 链接二进制与库 中）
  • #import <OAuth2Client/NXOAuth2.h>

在桌面应用中将库作为框架使用尚未经充分测试。请报告任何问题并帮助改进库。

使用 OAuth2Client

配置您的客户端

配置您的客户端最佳位置是在 iOS 的 +[UIApplicationDelegate initialize] 或 macOS X 的 +[NSApplicationDelegate initialize]。在那儿，您可以为希望从应用程序获取访问权限的每个服务调用 -[NXOAuth2AccountStore setClientID:secret:authorizationURL:tokenURL:redirectURL:forAccountType:] 于共享的账户存储。账户类型是一个字符串，用作特定服务的标识符。

+ (void)initialize;
{
    [[NXOAuth2AccountStore sharedStore] setClientID:@"xXxXxXxXxXxX"
                                             secret:@"xXxXxXxXxXxX"
                                   authorizationURL:[NSURL URLWithString:@"https://...your auth URL..."]
                                           tokenURL:[NSURL URLWithString:@"https://...your token URL..."]
                                        redirectURL:[NSURL URLWithString:@"https://...your redirect URL..."]
                                     forAccountType:@"myFancyService"];
}

请查看 Wiki 以获取一些示例。

请求访问服务

在配置您的客户端后，您就可以请求访问这些服务中的任何一个了。NXOAuth2AccountStore 提供了三种不同的方法来完成这个任务

  • 用户名和密码

    [[NXOAuth2AccountStore sharedStore] requestAccessToAccountWithType:@"myFancyService"
                                                         username:aUserName
                                                         password:aPassword];

  • 外部浏览器

    [[NXOAuth2AccountStore sharedStore] requestAccessToAccountWithType:@"myFancyService"];

    如果您使用外部浏览器，则应用程序需要处理为账户类型注册的回调 URL。认证过程完成后，服务将重定向到该 URL。

  • 提供授权 URL 处理器

    [[NXOAuth2AccountStore sharedStore] requestAccessToAccountWithType:@"myFancyService"
                              withPreparedAuthorizationURLHandler:^(NSURL *preparedURL){
                                  // Open a web view or similar
                              }];

    使用授权 URL 处理器，您可以将 URL 在自己的网页中打开，或者进行一些关于认证的复杂操作。因此，您请求访问时需要向 NXOAuth2AccountStore 传递一个块。

成功时

在认证成功后，新的 NXOAuth2Account 对象将出现在 NXOAuth2AccountStore 的账户列表中。您将收到一个通知，类型为 NXOAuth2AccountStoreAccountsDidChangeNotification，例如，用于更新您的 UI。

[[NSNotificationCenter defaultCenter] addObserverForName:NXOAuth2AccountStoreAccountsDidChangeNotification
                                                  object:[NXOAuth2AccountStore sharedStore]
                                                   queue:nil
                                              usingBlock:^(NSNotification *aNotification){
                                                    // Update your UI
                                              }];

如果添加了账户，通知的 userInfo 字典将包含新的账户在 NXOAuth2AccountStoreNewAccountUserInfoKey。但请注意，此通知可以由其他事件（例如账户删除）触发。在这种情况下，此键将不会设置。

失败时

如果认证失败，则会发送一个包含 NSError 的类型为 NXOAuth2AccountStoreDidFailToRequestAccessNotification 的通知。

[[NSNotificationCenter defaultCenter] addObserverForName:NXOAuth2AccountStoreDidFailToRequestAccessNotification
                                                  object:[NXOAuth2AccountStore sharedStore]
                                                   queue:nil
                                              usingBlock:^(NSNotification *aNotification){
                                                    NSError *error = [aNotification.userInfo objectForKey:NXOAuth2AccountStoreErrorKey];
                                                    // Do something with the error
                                              }];

获取所有账户的列表

可以通过 NXOAuth2AccountStore 访问认证账户。可以是完整的列表，也可以是特定服务的账户列表或具有标识符的账户（可能缓存于用户设置中）。

for (NXOAuth2Account *account in [[NXOAuth2AccountStore sharedStore] accounts]) {
    // Do something with the account
};

for (NXOAuth2Account *account in [[NXOAuth2AccountStore sharedStore] accountsWithAccountType:@"myFancyService"]) {
    // Do something with the account
};

NXOAuth2Account *account = [[NXOAuth2AccountStore sharedStore] accountWithIdentifier:@"...cached account id..."];

每个 NXOAuth2Account 都有一个属性 userData，可以用来存储一些与该账户相关的信息。

NXOAuth2Account *account = // ... get an account
NSDictionary *userData = // ...

account.userData = userData;

此有效负载将随账户存储在钥匙串中。因此，它不应该太大。

调用请求

可以通过 NXOAuth2Request 使用用于服务的认证来调用请求。最方便的方法（见下文）是一个类方法，您可以将方法、资源以及一些参数（或 nil）传递给请求处理器和响应处理器（任选）。一个用于进度，另一个用于响应。账户用于认证，可以是 nil。然后调用一个不进行认证的普通请求。

[NXOAuth2Request performMethod:@"GET"
                    onResource:[NSURL URLWithString:@"https://...your service URL..."]
               usingParameters:nil
                   withAccount:anAccount
           sendProgressHandler:^(unsigned long long bytesSend, unsigned long long bytesTotal) { // e.g., update a progress indicator }
               responseHandler:^(NSURLResponse *response, NSData *responseData, NSError *error){
                   // Process the response
               }];

获取已签名的 NSURLRequest

在某些情况下，您必须回到“古老的”方法并使用一个 NSURLConnection。例如，如果您想下载一个大型文件。因此，NXOAuth2Request 允许您获取包含认证请求所需额外信息的 NSURLRequest。

NXOAuth2Request *theRequest = [[NXOAuth2Request alloc] initWithResource:[NSURL URLWithString:@"https://...your service URL..."]
                                                                 method:@"GET"
                                                             parameters:nil];
theRequest.account = // ... an account
                               
NSURLRequest *sigendRequest = [theRequest signedURLRequest];

[theRequest release];

// Invoke the request with you preferd method

全参数化文件上传

// Get fileSize
NSDictionary *fileAttributes = [[NSFileManager defaultManager] attributesOfItemAtPath:uploadFile.localDataFilePath error:nil];
NSNumber *fileSize = [fileAttributes valueForKey:NSFileSize];

// Create a stream wrapper for the upload file
NXOAuth2FileStreamWrapper* w =[NXOAuth2FileStreamWrapper
    wrapperWithStream:[NSInputStream inputStreamWithFileAtPath:uploadFile.localDataFilePath]
        contentLength:[fileSize unsignedLongLongValue]
             fileName:uploadFile.remoteFilename];

if([uploadFile.remoteFilename hasSuffix:@".json"])
    w.contentType = @"application/json";
else
    if([uploadFile.remoteFilename hasSuffix:@".jpg"])
        w.contentType = @"image/jpeg";

// POST Content-Disposition: form-data; name="file"; filename=uploadFile.remoteFilename
[NXOAuth2Request performMethod:@"POST" onResource:uploadFile.uploadURL usingParameters:@{@"file": w} withAccount:account
           sendProgressHandler:... responseHandler: ...];

贡献 & 提交拉取请求

欢迎补丁和提交拉取请求！对于审阅时间可能需要一些时间，但我们迟早会看到您的。

请注意，我们正在使用git-flow分支和发布模型，因此请针对develop分支创建提交拉取请求。

BSD许可

版权所有 © 2012, nxtbgthng GmbH

版权所有。

在以下条件满足的情况下，允许重新分配和使用源代码和二进制代码，修改或不修改：

  • 源代码的重新分配必须保留上述版权声明、本条件列表以及以下免责声明。
  • 二进制形式的重新分配必须以文档和/或其他与分发提供的材料中的形式复制上述版权声明、本条件列表和以下免责声明。
  • 未经事先书面许可，不得使用nxtbgthng的名称或其贡献者的名称为源自本软件的产品背书或推广。

本软件由版权持有者和贡献者“按原样”提供，并且明确或隐含的保证、包括但不限于适销性和对特定目的的适用性保证均不受影响。在任何情况下，不对因使用本软件而产生的任何直接、间接、偶然、特殊、示范性或后果性损害（包括但不限于替代产品或服务的采购；使用、数据或利润的损失；或业务中断）承担赔偿责任，不论何种原因和责任理论基础，即使已被告知此类损害的可能性。