iOS Swift API

支持库使开发与 Alfresco 产品协同工作的 iOS 应用程序更加容易。

安装

这些库可以通过 Cocoapods 以独立的框架的形式使用。

转到项目文件夹，在终端中输入 pod init 创建 pod 文件，然后编辑它，并添加以下内容

source 'https://cdn.cocoapods.org/'

后跟您想要的 pod 配置。例如：pod 'AlfrescoAuth' pod 'AlfrescoContent'

有关如何设置 Cocoapods 的更多详细信息，请参阅官方文档。

我们在发布库时使用语义化版本化。您可以在这里了解更多信息。

这些库需要 iOS 12+ 和 Swift 5+。

入门

获取启动的最简单方法是查看包含的 示例应用程序。

示例演示了如何使用身份服务进行身份验证，以及如何将其与 API 绑定集成以发起第一请求。

应用程序应该与您安装的身份服务正常工作，但可能不匹配您当前的配置，因此如果遇到任何问题，请编辑 AuthenticationParameters.swift。

身份验证

auth模块提供了一些抽象层，以便与Alfresco身份服务和工作基本身份验证进行交互。

基本身份验证

对于基本身份验证，你需要构建一个自己的用户界面来收集凭据。除了样本应用中使用的一些结构外，库本身提供的功能并不多。

SSO身份验证

对于SSO，您需要在用户登录后显示一个WebView，然后在最后收集令牌。

要使其工作，需要几个步骤。

在Keycloak中注册移动端clientID

注意，此步骤是可选的，因为它可能已经被您的管理员处理。

首先，您需要在身份服务中定义一个客户端，该客户端将服务于移动应用。访问Keycloak管理界面并导航到客户端页面。添加一个新客户端条目，并记下客户端ID值。保存条目，然后在下一页中，搜索“有效的重定向URI”字段。该特定字段的值应为以下格式：clientID://custom-domain-name/auth。

在您的移动应用中注册重定向URI

确保已设置的重定向URI在移动客户端的设置中也有镜像。为此，打开您的项目中的Info.plist文件，并添加以下结构

• 添加一个类型为Array的'URL types'键
• 将一个新的类型为Dictionary的键作为'URL types'的子依赖项添加
• 将一个类型为String的'URL Schemes'键作为之前项的子依赖项添加，其值为之前设置的重定向URI。

如需更多信息，请参阅我们的示例应用。

调用AlfrescoAuth API

首先，您需要在视图中模型中使用您的配置初始化授权模块，并调用认证方法。配置对象需要与身份服务中的配置匹配。

class MyLoginViewModel {
  init() {
    alfrescoAuth = AlfrescoAuth.init(configuration: authConfig)
  }
  ...
}

接下来，在授权模块上调用pkceAuth方法，传递您希望显示SSO Webview的视图控制器和接收更新的委托类。

class  MyLoginViewModel {
  func login(in viewController: UIViewController) {
    alfrescoAuth.pkceAuth(onViewController: viewController, delegate: self)
  }
}

extension MyLoginViewModel: AlfrescoAuthDelegate {
  func didReceive(result: Result<AlfrescoCredential, APIError>, session: AlfrescoAuthSession?) {
    switch result {
      case.success(let credential):
        // Store credential and session object
  ...
      case .failure(let error):
        ...
    }
}

登录成功后，服务器将通过您在Info.plist中设置的回调URI回调您的令牌。

授权响应URL通过- (**BOOL**)application:(UIApplication *)app openURL:(NSURL *)url options:(NSDictionary<UIApplicationOpenURLOptionsKey, **id**> *)options应用代理方法返回给应用，因此您需要将其通过当前授权会话传递。

在AlfrescoSession对象上调用resumeExternalUserAgentFlow方法，并将openURL方法提供的URL传递。

您可以通过查看我们的示例应用来查看一种处理此方法的示例。

认证后

由于认证是独立的步骤，我们强烈建议在让用户进入应用之前，在didReceive之后进行额外的验证。

此时您可以考虑检查，如个人信息或权限，这可能需要调用Alfresco服务，从而验证您的认证会话是否工作正常。

保持会话对象存活

根据所期望的认证模式，会话对象可能需要在对象图中保持活跃。这在PKCE认证模式下同样是有效的。

在认证完成后，AlfrescoAuth模块将提供一个AlfrescoSession对象，该对象在会话活跃期间应被引用。这是您需要序列化以保留授权状态的唯一对象。

注销登录

通常情况下，您只需销毁持久化凭据，但在SSO的情况下，会话必须被使无效，或者用户将无法经过凭据提示再次登录。

为此，只需在AlfrescoAuth模块上调用注销方法，提供用户最后设置的凭据。

class  MyLoginViewModel {
  func logOut(onViewController viewController: UIViewController, lastKnownCredential: AlfrescoCredential, delegate: AlfrescoAuthDelegate) {
    alfrescoAuth.logout(onViewController: viewController, delegate: self, forCredential: lastKnownCredential)
  }
}

extension MyLoginViewModel: AlfrescoAuthDelegate {
  func didLogOut(result: Result<Int, APIError>) {
    ...
  }
}

重新认证

在SSO的情况下，刷新令牌可能会过期，或者远程操作者可能会使ID服务中的用户会话无效。

即使在基本认证场景中，如果密码被更改，这也可能发生。

当这种情况发生时，我们建议您提示用户他们需要重新登录。

对于基本认证来说，您需要自己决定集成方式；但对于SSO来说，有一个特别的重新认证流程。

class  MyLoginViewModel {
  func refreshSession(delegate: AlfrescoAuthDelegate) {
    // The session object is the same one provided after the successfull log in
    if let session = self.session {  
      alfrescoAuth.pkceRefresh(session: session, delegate: self)
    }
  }
}

成功后，新会话将通过didReceive(result:, session:)再次返回，并在更新存储的凭据后，您可以允许用户继续他们的活动。

内容服务API

内容模块提供了API绑定，用于与Alfresco内容服务一起使用。

该模块包括对搜索和核心的绑定，以便更容易集成到大多数应用程序中。

要开始使用该模块，您首先需要在业务逻辑层中导入它，然后将basePath静态属性设置为指向正确的Alfresco实例。

此外，您应提供一个凭据集合，您可以将凭据作为customHeaders属性的组成部分附加，或者使用credential: URLCredential?属性。

现在只需获取一项服务并发出您的请求

class RecentsViewModel {
  func fetchRecentsList() {
    AlfrescoContentAPI.customHeaders = ["Authorization": authorizationHeaderValue()]
    SearchAPI.search(queryBody:"my querry", ...) {
      if let entries = result?.list?.entries {
        // handle results
      }
    }
  }
}

有关API的更多信息，请阅读我们的文档

开发

我们非常愿意接受您对此项目的补丁和贡献。

代码审查

所有外部提交都需要正式审查。我们使用GitHub的pull request来进行这一点。更多有关如何使用pull request的信息，请参阅GitHub帮助。