SevenPassSDK 2.0.0

SevenPassSDK 2.0.0

×

测试测试✓
语言语言 SwiftSwift
许可证 MIT
发布最后发布2016年11月
SwiftSwift版本3.0.1
SPM支持SPM✗

由 Philipp Ebner 维护。

 
依赖项
Locksmith~> 3.0
JWTDecode~> 2.0
JSONWebToken~> 2.0.1
 

SevenPassSDK 2.0.0

  • 由
  • Jan Votava

7pass-ios-sdk

7Pass iOS SDK 是一个用于与 7Pass SSO 服务交互的 Swift 库。您可以使用此库来对您的应用程序进行身份验证，并利用7Pass SSO服务提供的现有功能。

使用方法

要运行示例项目，请克隆仓库，然后首先从 Example 目录运行 pod install。

安装

SevenPassSDK 通过 CocoaPods 提供。要安装它，只需将以下行添加到您的 Podfile 中

source 'https://github.com/CocoaPods/Specs.git'

use_frameworks!

target 'MyApp' do
  pod 'SevenPassSDK'
end

运行示例应用程序

为了展示库的函数功能，有一个可用的示例应用程序。该应用程序配置为针对 7Pass 的 QA 实例运行，并使用测试凭证（Example/SevenPassSDK/SsoManager.swift）。在测试期间请随意使用这些凭证，但在发行应用程序之前您需要获得真实凭证。

要获取真实凭证，您首先需要联系7Pass技术团队。

一旦您有凭证，可以继续在 Example 目录中输入

pod install

然后在 XCode 中打开 SevenPassSDK.xcworkspace 项目，选择 SevenPassSDK-Example 建构配置并运行它。

现在示例应用程序应在配置的设备（或模拟器）中启动，并提供几个标签页，每个标签页都实现了您可能在应用程序中使用的功能。

使用方法

强烈建议您查看示例应用程序以了解如何使用 API。

如果您开始开发，针对 7Pass SSO 服务的非实时实例工作总是一个好主意。在这种情况下，我们将使用 QA 环境。在您向公众发布应用程序之前，别忘了切换到生产环境。

首先，让我们使用示例配置初始化库

let configuration = SevenPassConfiguration(
    consumerKey: "56a0982fcd8fb606d000b233",
    consumerSecret: "2e7b77f99be28d80a60e9a2d2c664835ef2e02c05bf929f60450c87c15a59992",
    callbackUri: "oauthtest://oauth-callback",
    environment: "qa"
)

let sso = SevenPass(configuration: configuration)

身份验证流程

该库提供了多种用户登录方式。每次登录的结果最终都是一个 TokenSet 实例。一个 TokenSet 表示服务器将返回的三个不同的令牌类型。

  1. 访问令牌 - 此令牌证明用户的身份，因此几乎包含库执行的每个远程调用中。每个访问令牌只有效2小时。之后无法使用。

  2. 刷新令牌 - 此令牌可以用来获取一个包含新鲜访问令牌的新 TokenSet。其过期时间为90天，每次使用都会自动延长。但是，如果令牌过期了，你需要让用户重新登录。

  3. 身份令牌 - 此令牌包含有关登录用户的信息（声明）。例如，你可以获取用户ID、姓名、电子邮件等。

通常不需要担心当前 TokenSet 的使用方法，但你需要在使用前确保其有效性。

sso.authorize(
    scopes: ["openid", "profile", "email"],
    success: { tokenSet in
        // tokenSet.accessToken?.isExpired()
        // tokenSet.refreshToken?.isExpired()
    },
    failure: { error in
        print(error.localizedDescription)
    }
)

如果该访问令牌是新鲜的，你可以使用该令牌集进行API调用。之后，你可以使用该 TokenSet 来初始化API客户端。

let accountClient = sso.accountClient(tokenSet)

否则，你需要使用刷新令牌进行刷新。

let refreshTokenString = tokenSet.refreshToken!.token

sso.authorize(refreshToken: refreshTokenString,
    success: { tokenSet in
        // Do some stuff
    },
    failure: errorHandler
)

当然，你需要确保刷新令牌本身也是新鲜的。如果不是，就无法获取新鲜的访问令牌，并需要让用户重新登录。如果你使用Web视图流程，并且用户在7Pass上有活跃的会话，有很大几率他们会立刻返回而无需填写凭据。

由于相同的令牌集可以在多个天内使用，因此你应该保存该令牌集而不是强迫用户每次都重新登录。你可以使用一个实用工具类将令牌集保存到密钥链中。

let tokenSetCache = SevenPassTokenSetCache(configuration: sso.configuration)

// Load token set from a keychain
let tokenSet = tokenSetCache.load()

// Store token set in the keychain
tokenSetCache.tokenSet = tokenSet
tokenSetCache.save()

// Delete token set
tokenSetCache.delete()

1. 使用Web视图登录

用户登录的最基本方式是使用Web视图。

sso.authorize(
    scopes: ["openid", "profile", "email"],
    success: { tokenSet in
        // Do some stuff
    },
    failure: errorHandler
)

该代码将打开提供的Web视图，它将导航到7Pass的登录对话框。从这里，用户有几种选择，可以直接使用他的凭据，或者使用Google/Facebook。

处理完成后，Web视图将自动关闭，并在回调中提供结果。

处理成功完成后，我们可以使用获得的 tokenSet 来初始化API客户端。

2. 使用登录名和密码登录

如果您想为用户提供更多原生体验，该库提供使用用户的7Pass登录名和密码（grant_type = password）登录。这种方式，您可以自己使用iOS小部件设计登录表单。

sso.authorize(
    login: login.text!,
    password: password.text!,
    scopes: ["openid", "profile", "email"],
    success: { tokenSet in
        // Do some stuff
    },
    failure: errorHandler
)

3. 使用社交登录

在某些情况下，如果用户已经使用其他服务（目前支持的服务是Facebook或Google）登录，您可以使用 social 流程。

在此流程中，您提供从其他服务收到的访问令牌，7Pass将确保创建新的7Pass账户（包含所有用户详细信息）或识别现有的7Pass账户。

sso.authorize(
    providerName: "facebook",
    accessToken: "foobarbaz",
    scopes: ["openid", "profile", "email"],
    success: { tokenSet in
        // Do some stuff
    },
    failure: errorHandler
)

4. 自动登录

如果您已经拥有有效的 TokenSet（例如来自密码或社交登录）或有效的 autologin_token，并且想在WebView中创建用户会话，可以使用 autologin 方法。

默认情况下，此方法设置 response_type = "none"

5. 注销

从应用程序的角度来看，当你拥有新的TokenSet时，用户已登录。为了注销用户，只需要“忘记”令牌。可选地，您还可以在WebView中销毁用户的会话。

要使用它，只需调用

sso.destroyWebviewSession(failure: errorHandler)

处理interaction_required错误

请注意，如果用户尚未接受客户端或客户端所属服务的所有必要同意，则通过用户名和密码或社交媒体方法登录可能会失败，并且必须在您的错误处理回调中处理这种情况。

func errorHandler(error: NSError) {
    // Let autologin handle interaction_required errors
    if let errorMessage = error.userInfo["error"] as? String where errorMessage == "interaction_required" {
        let autologinToken = error.userInfo["autologin_token"] as! String

        self.sso.autologin(
            autologinToken: autologinToken,
            scopes: ["openid", "profile", "email"],
            params: ["response_type": "id_token+token"],
            success: { tokenSet in
                // Do some stuff
            },
            failure: errorHandler
        )
    }

    // Handle other errors
}
使用有效的tokenSet登录

TokenSet必须包含有效的access_token和id_token

sso.autologin(tokenSet,
    scopes: ["openid", "profile", "email"],
    rememberMe: false,
    success: { tokenSet in
        // Do some stuff
    },
    failure: errorHandler
)
使用自动登录令牌登录

当服务器返回interaction_required错误时使用。

sso.autologin(
    autologinToken: "AUTOLOGINTOKEN",
    scopes: ["openid", "profile", "email"],
    params: ["response_type": "id_token+token"],
    success: { tokenSet in
        // Do some stuff
    },
    failure: errorHandler
)

账户客户端

现在您已经有了账户的TokenSet，您已经可以识别用户并继续使用您实际的应用程序。然而，您可以请求有关用户的更多信息。每个方法调用对应于7Pass上的一个端点，您被鼓励查看文档。

let accountClient = sso.accountClient(tokenSet)

获取账户的详细信息

您可以通过请求账户的详细信息来进行的简单远程调用。

accountClient.get("me",
    success: { json, response in
        print(json)
    },
    failure: errorHandler
)

请注意，您可能不需要请求额外的用户详细信息，因为最基础的详细信息已经在TokenSet的ID Token中，作为TokenSet的一部分存在。这通常取决于您的应用程序需求。

tokenSet.idTokenDecoded

刷新accountClient TokenSet

Account client是SevenPassRefreshingClient的一个实例，它为您无缝处理令牌刷新。

可选地，可以将其作为参数提供给accountClient方法。

let accountClient = sso.accountClient(
  tokenSet,
  tokenSetUpdated: { tokenSet in
    // Save new tokens
    tokenSetCache.tokenSet = tokenSet
    tokenSetCache.save()
  }
)

凭证客户端

凭证客户端可以用于执行各种与特定账户无关的行政管理任务。例如，您可以验证电子邮件地址是否未被使用或密码是否足够安全等。获取此类客户端不需要与用户交互，它基于您的客户端凭证发放。

与Account客户端一样，您将收到有效的TokenSet，但该令牌集不包含任何其他内容，仅为访问令牌，其有效性将限制在15分钟内。由于令牌集没有刷新令牌，因此如果需要，15分钟后有必要请求新的令牌。

sso.authorize(
    parameters: [
        "grant_type": "client_credentials",
    ],
    success: { tokenSet in
        // Do some stuff
    },
    failure: errorHandler
)

一旦您有了令牌集，您就可以获取凭证客户端并调用可用的方法。

let credentialsClient = sso.credentialsClient(tokenSet)

检查电子邮件的可用性

验证提供的电子邮件地址，并返回它是否可用于使用。您可以使用此方法在注册过程中立即向用户提供反馈。有关更多信息，请参阅文档。

deviceClient.post("checkMail",
    parameters: [
        "email": login.text!,
        "flags": [
            "client_id": sso.configuration.consumerKey
        ]
    ],
    success: { json, response in
        if let error = json["data"]?["error"] as? String {
           // E-Mail is invalid
        }
    },
    failure: errorHandler
)

响应中还包含一个建议的电子邮件地址，以便您能够轻松地为用户在地址中出错时提供“您是指x吗？”的功能。

检查密码的有效性

在注册表单的下一步，您可能想要提供有关提供的密码有效性的反馈。您可以在文档中找到所有要求和建议的响应代码。

deviceClient.post("checkPassword",
    parameters: [
        "password": password.text!
    ],
    success: { json, response in
        if let errors = json["data"]?["errors"] as? [String] {
            // Password is not valid, got array of errors
        }
    },
    failure: errorHandler
)

创建新账户

最后，您可以直接创建您的专属账户。唯一必需的参数是一个有效的电子邮箱地址和一个密码。如果您不想强制用户输入密码，可以请求一个自动生成的密码（在这种情况下，只需电子邮件地址即可）。

deviceClient.post("registration",
    parameters: [
        "email": login.text!,
        "password": password.text!,
        "flags": [
            "client": [
                "id": sso.configuration.consumerKey, // Associate with a service
                "agb": true, // Accept ToS consents (user should given permissions beforehand)
                "dsb": true, // Accept privacy policy consents (user should given permissions beforehand)
                "implicit": true // Accept implicit optins
            ]
        ]
    ],
    success: { json, response in
        // Account creation status returned in json constant
    },
    failure: errorHandler
)

高级用法

定制WebView

创建自己的自定义类实现SevenPassURLHandlerType协议，并将该实例传递给SevenPass初始化。

let sso = SevenPass(configuration: configuration, urlHandler: YourWebViewController())

开发者

OAuthSwift自定义分支

此库包含OAuthSwift库的自定义分支，可以使用Carthage下载和构建，要重新构建，请执行

carthage update --platform iOS

许可

SevenPassSDK根据MIT许可证提供。有关更多信息，请参阅LICENSE文件。