Stormpath iOS SDK

Stormpath（https://stormpath.com/），一款用于身份验证和授权的框架的 iOS SDK。

要求

iOS 8.0+ / Xcode 8.0+（Swift 3）

设置

Stormpath 的 iOS SDK 允许开发者快速将身份验证和令牌管理集成到他们的应用程序中。

我们不断迭代和改进 SDK，因此请随时发送您的反馈！您可以通过 [email protected]，或者在问题跟踪器上请求功能。

安装

使用

要查看 SDK 的实际使用，您可以尝试下载 Stormpath iOS 示例 项目。我们已经构建了相同的两次，一次在 Objective-C 中，另一次在 Swift 中，以便您了解如何使用 SDK。

导入框架

对于 Swift 项目

import Stormpath

对于 Objective-C 项目

#import "Stormpath-Swift.h"

配置 Stormpath

iOS SDK（v3）利用 Stormpath 客户端 API 来满足其身份验证需求。您需要登录到 Stormpath 管理控制台 以获取您的客户端 API 详细信息。转到应用程序 > 策略 > 客户端 API，并确保它已启用。复制您的客户端 API URL，并在 Xcode 项目中设置它

Swift

Stormpath.sharedSession.configuration.APIURL = URL(string: "https://edjiang.apps.stormpath.io")!

Objective-C

[[SPHStormpath sharedSession] configuration].APIURL = [[NSURL alloc] initWithString:@"https://edjiang.apps.stormpath.io"];

用户注册

为了注册一个用户，实例化一个 RegistrationForm 对象。Stormpath 需要一个 email 和 password 来注册。

let newUser = RegistrationForm(email: "[email protected]", password: "ExamplePassword")

然后，只需在 Stormpath 类上调用注册方法

Stormpath.sharedSession.register(account: newUser) { (account, error) -> Void in
    guard let account = account where error == nil else {
        //The account registration failed
        return
    }
    // Do something with the returned account object, such as save its `href` if needed. 
    // Registering a user will not automatically log them in. 
}

注意：Stormpath的回调总是在主线程上执行，因此您可以直接在回调中更改UI。

登录

要登录，从用户那里收集电子邮件（或用户名）和密码，然后将它们传递给登录方法

Stormpath.sharedSession.login(username: "[email protected]", password: "ExamplePassword") { success, error in
    guard error == nil else {
        // We could not authenticate the user with the given credentials. Handle the error. 
        return
    }
    // The user is now logged in, and you can use the Stormpath access token to make API requests!
}

使用社交提供者登录

Stormpath也支持使用各种社交提供者登录，例如Facebook、Google、LinkedIn、GitHub等。为此，有两种流程可供选择

1. 让Stormpath处理社交登录。
2. 使用社交提供者的iOS SDK获取访问令牌，并将其传递给Stormpath进行登录。

我们已使设置社交登录无需使用社交提供者SDK变得极为简单，但如果您需要使用它们的SDK来获取登录以外的更多功能，则应使用流程#2（并直接跳转到使用社交提供者SDK）。

在Stormpath中配置您的社交目录

要设置您的社交目录，请参阅Stormpath客户端API指南中的社交登录。

设置您的Xcode项目

在您的Xcode项目中，您需要创建一个URL配置文件，以便登录过程可以回调到您的应用程序。转到项目的“信息”选项卡。在“URL类型”下，添加一个新条目，并在URL方案表单字段中输入您的客户端API的DNS标签的反向。例如，如果您的客户端API DNS标签是edjiang.apps.stormpath.io，请输入io.stormpath.apps.edjiang。

在Stormpath管理控制台的应用程序设置中，将该URL添加为“授权回调URL”，追加://stormpathCallback。根据先前的示例，我会使用io.stormpath.apps.edjiang。

此外，请在Xcode项目中的AppDelegate中添加以下方法

// iOS 9+ link handler
func application(_ app: UIApplication, open url: URL, options: [UIApplicationOpenURLOptionsKey: Any]) -> Bool {
    return Stormpath.sharedSession.application(app, open: url, options: options)
}

// iOS 8 and below link handler. Needed if you want to support older iOS
func application(_ application: UIApplication, open url: URL, sourceApplication: String?, annotation: Any) -> Bool {
    return Stormpath.sharedSession.application(application, open: url, sourceApplication: sourceApplication, annotation: annotation)
}

启动社交登录

现在，您可以通过调用下面这个方法来启用登录界面：

Stormpath.sharedSession.login(provider: .facebook) { (success, error) -> Void in
    // This callback is the same as the regular Stormpath.login callback. 
    // If the user cancels the login, the login was never started, and
    // this callback will not be called.
}

使用社交提供者SDK

如果您正在使用Facebook SDK或Google SDK来为您的应用程序，请按照它们的设置说明操作。一旦您使用其SDK成功登录，就可以使用以下方法将访问令牌发送到Stormpath并登录您的用户。

Stormpath.sharedSession.login(provider: .facebook, accessToken: FBSDKAccessToken.currentAccessToken().tokenString) { (success, error) -> Void in
    // Same callback as above
}

Stormpath.sharedSession.login(provider: .google, accessToken: GIDSignIn.sharedInstance().currentUser.authentication.accessToken) { (success, error) -> Void in
    // Same callback as above
}

使用访问令牌

您可以使用访问令牌来访问任何需要身份验证的API端点。它存储为Stormpath对象上的属性，作为Stormpath.sharedSession.accessToken。如果您需要刷新它，请使用Stormpath.sharedSession.refreshAccessToken()。根据您所使用的网络库，以下是如何使用访问令牌的方法：

NSURLSession

var request = URLRequest(URL: url)
request.setValue("Bearer " + accessToken ?? "", forHTTPHeaderField: "Authorization")

Alamofire

let headers = ["Authorization": "Bearer " + accessToken ?? ""]
Alamofire.request(url, method: .get, headers: headers)

注意：从iOS 9 SDK开始，苹果默认启用了应用传输安全。如果你正在针对http端点进行开发，你需要将它禁用。对于生产环境，你应该始终使用你的API端点为https。

账户数据

Stormpath框架集成提供用于检索个人资料信息的默认端点。使用me来获取账户数据。

Stormpath.sharedSession.me { account, error in
    guard let account = account where error == nil else {
        // We might not be logged in, the API is misconfigured, the API is down, etc
        return
    }
    // Success! We have the account object.
}

登出

登出很简单。这将从用户的设备中删除访问令牌和刷新令牌，并向服务器发起API请求以删除。

Stormpath.sharedSession.logout()

密码重置

要重置用户的密码，首先需要收集他们的电子邮件。然后将该电子邮件按如下方式传递给resetPassword函数：

Stormpath.sharedSession.resetPassword(email: "[email protected]") { success, error in
    guard error == nil else {
        // A network or API problem occurred. 
        return
    }
    // We succeeded in making the API request. 
}

错误处理

在使用Stormpath时，可能会由于几个原因遇到错误。

1. 网络错误 - 由于某些原因，网络请求失败。
2. 用户错误 - 由于用户输入导致的错误，例如：“用户名或密码无效”。
3. API错误 - API配置错误或返回了不可识别的响应。

如果发生网络错误，Stormpath将向你的代码返回与NSURLSession关联的NSError。否则，Stormpath将返回StormpathError，这是NSError的子类。

对于用户错误，StormpathError将包含API响应的HTTP错误代码（通常是400），并将localizedDescription设置为用户可读的错误消息，该消息可以安全地显示给用户。

在特殊情况下，StormpathError将具有代码0或1。这些是开发者错误，不应显示给用户。0代表“Stormpath SDK错误”，这很可能是Stormpath SDK中的错误，应向我们报告。1代表“API响应错误”，意味着API以意外的方式响应。这通常意味着你的后端集成配置不正确。

使用Info.plist配置Stormpath

StormpathConfiguration可用于将Stormpath指向特定的API URL。虽然您可以直接修改对象，但您也可以在Info.plist中将配置放入。要添加Stormpath配置，右键单击Info.plist，然后单击“打开为源代码”。在最后一个</plist>标签之前，粘贴以下代码：

<key>Stormpath</key>
<dict>
    <key>APIURL</key>
    <string>https://:3000</string>
</dict>

您可以修改这些值中的任何一个，StormpathConfiguration将在首次初始化时加载这些值。

处理多个会话

Stormpath可用于存储多个用户账户，即使是针对使用Stormpath的多个API服务器。这对您正在制作的多租户应用程序很有用，该应用程序允许用户在不同的账户下同时登录。

要使用此功能，不要使用Stormpath.sharedSession，而是使用自定义标识初始化Stormpath

Stormpath(identifier: "newSession")

这将创建一个具有默认配置（与应用程序的其他部分共享）的Stormpath实例，该实例将在iOS Keychain中自己的分区中存储accessTokens和refreshTokens。

您可以使用此标识符在应用中识别包含在Stormpath中的用户会话，并正确地在应用打开之间恢复它。

注意：Stormpath.sharedSession 的标识符为“默认”，因此请勿将其用作 Stormpath 另一个实例的标识符。

许可证

本项目采用 Apache 2.0 许可协议 开源。请参阅 LICENSE 文件获取详细信息。