本栏目下相关链接 | ||||
Discuz! Passport 接口技术文档 | ||||
从 Discuz! 4.0.0 RC4 版本开始,Discuz! 内嵌了一个独特的 Passport(通行证) 接口,利用此接口,用户将很容易将论坛与其他应用 程序整合,而实现统一登录与退出、用户数据共享、积分同步等功能。可以整合的应用程序包括内容管理系统(CMS)、商城系统、游戏系统等 等,如您对这方面功能有兴趣或有需求,请继续阅读本文档。 Discuz! Passport 的优点
Discuz! Passport 系统使用了 Discuz! 独有的技术,并不等同于以往使用过的一些方法,与传统的实现方式相比,具备(不限于)以下优势:
Discuz! Passport 的局限
您在开始利用 Discuz! Passport 进行二次开发时,需要了解这个系统的局限性,以对未来的工作进行正确的评估与安排。
| ||||
Discuz! Passport 原理与流程 | ||||
假设已设置如下变量或参数
开启通行证后的用户登录流程
开启通行证后的用户退出流程
开启通行证后的用户注册流程
| ||||
Discuz! Passport 参数规格与加密方式 | ||||
私有密匙(passport_key) 由于一些关键参数采用了 GET 方式进行传递,即便两次 header 跳转并不会直接将链接显示在外面,但我们仍然对关键的参数进行了加密,私有 密匙共有两个作用:其一是供下面提到的可逆加密算法(AzDGCrypt)进行数据的加解密;其二是生成不可逆验证字串(verify),以防止关键信息被 伪造。 在启用 Discuz! Passort 后,您需要在应用程序和 Discuz! 后台配置两处私有密匙,这两处的内容必须完全相同,这样应用程序和论坛之间才能 正常通信。私有密匙决定了加密算法的强度,因此密匙长度请不要小于 10 个字节,并包含字母、数字和符号,以保证系统的安全。 加密算法 Discuz! Passport 采用 Azerbaijan Development Group(AzDG)开发的可逆加密算法 AzDGCrypt 对用户资料进行加密。如提供正确的私有密匙, 可通过本加密算法对数据进行加密及解密,因此只要保证私有密匙的保密性,即可确保数据传递过程中的安全。以下为 Discuz! Passport 中应用到 的可逆加密算法,为了生成可以被 Discuz! Passport 正确解密的 auth 字串,需要将如下函数放置于应用程序中,并可在登录及注册时调用。 passport_encrypt()是加密函数,用法为 passport_encrypt($txt, $key),其中 $txt 是待加密的字串,$key 是私有密匙。
passport_encode()是将数组转换合成为字串形式存储的函数:变量名和数值之间用等号连接,如果数值包含特殊字符,使用 urlencode() 将其转码; 多个变量间使用 & 分割。例如原始数组内容为 array('username' => 'abc', 'email' => 'my+discuz@gmail.com'),经过 passport_encode() 编码后 结果为 username=abc&email=my%2Bdiscuz%40gmail.com。 信息字串(auth)
应用程序在收到登录或注册请求,并读取到用户资料后,请按如下的要求将用户资料及部分其他信息存放于一个数组之中。数组各键值的含义为: 以上参数中,以黑体下划线显示的 time、username、password、email 是必须传递的参数,缺少上述参数 Passport 将无法正常工作;其他的参数是可选的,如果 不传递某些参数,则 Passport 会进行识别,自动不更新没有传递的参数所在的字段;所有数值,请提供原始值,而非经过反斜线转义(addslashes)后 的结果。 把上述信息存放于数组中,假定为如下的形式:
将其经过如下的加密变换,即可得到 auth 的值:
其中,passport_encode() 在前文已做了说明,用于将数组内容存放于特定的格式,$passport_key 是私有密匙。 切记:由于 $auth 中可能含有等号、加号等特殊字符,请将 $auth 经过 rawurlencode() 编码后再在 URL 中传递,否则可能会产生问题。 导向字串(forward) 导向字串用于通知 Discuz! Passport 在完成自身操作后,返回到哪一个 URL 地址,例如 http://www.myforums.com/forumdisplay.php?fid=2。 如果 forward 为空,则默认导向到应用程序的首页 切记:由于 $forward 中可能含有冒号、问号、等号等特殊字符,请将 $forward 经过 rawurlencode() 编码后再在 URL 中传递,否则可能会 产生问题。 验证字串(verify) 验证字串用户检验 auth 和 forward 两个参数的合法性,避免非法构造参数进行破坏的可能。无论 auth 和 forward 变量是否存在,验证字串
(verify)的值均为:
其中,$action 是当前执行的 Passport 操作,如 login 等等;$auth 是用户信息加密后,并经 rawurlencode() 之前的内容;$forward 是经 rawurlencode() 前的导向字串;$passport_key 是私有密匙。如果 verify 的值不匹配,则 Passport 拒绝进行下一步操作。 | ||||
Discuz! Passport 设置与启用 | ||||
内置关联 Discuz! 以战略合作的方式,与业内知名的产品实现了 Passport 关联,目前内置了 SiteEngine 建站引擎(http://www.siteengine.net)和 Shopex 通用型网上商店系统(http://www.shopex.cn)的相关接口,这样用户只须透过在两套软件中简单的设置,即可开启这些关联。 其他应用程序 由于 Discuz! Passport 的高可扩展性和平台无关性,使得您可以参照前文的说明,稍稍改动小部分的代码,便将任何 B/S 模式的应用程序与 Discuz! 进行关联。 参数设置 您可以在 Discuz! 系统设置中,看到相应的通行证设置功能,在 Discuz! 合作伙伴的软件中,也可以找到这些设置入口。相关的操作已比较简单, 在此不再详细叙述。 特别说明 如果您先运营了论坛,后与其他应用程序启用了 Passport 关联,由于之前论坛中的用户数据没有同步,您需要先写一个导入程序,将论坛的用户 数据导入到应用程序的用户表中,否则以往在论坛注册的用户将无法通过 Passport 登录。已成功关联后新注册的用户无此问题。 在开启了 Discuz! 通行证后,您仍然可以通过 logging.php?action=login 这个链接来登录论坛,以备调试之用,但页面上显示的链接将改为应用程序 的登录 URL。注意:开启通行证后,建议您通过 Discuz! 选项关闭论坛本身的注册功能,以免用户通过论坛注册而产生无法同步的问题。 您可以在 Discuz! 的 api/passport.php 找到 Discuz! Passport 的全部源程序,您也许通过他更好的理解 Passport 的原理,更快的完成应用程序与 Discuz! 之间的整合。 | ||||
典型错误提示 | ||||
Illegal request 非法请求,当验证字串 verify 不匹配时会产生此提示。可能是应用程序与 Discuz! 配置的私有密匙不同,或是通过 URL 传递前,未将必要的参数
(如 auth、forward 等)进行 URL 编码,也有可能是使用了经过 URL 编码的参数值用来计算 verify 的 md5 值造成。以 PHP 语言为例,正确的代码
应当是类似于的如下的格式:
Lack of required parameters auth 内容解密后,缺少必要的信息 time、username、password、email。 Request expired 请求过期。当前服务器时间与应用程序提交过来的 time 之差大于 Discuz! Passport 中设置的请求有效期。可能是使用以往的代码非法尝试,也可能是 由于应用程序和 Discuz! 论坛所在的两台服务器,时间设置有误造成。 Invalid action 没有指定 Passport 所执行的 action。 |