README

为您的PHP应用程序提供GoInstant认证。

这是JWT令牌的实现，与GoInstant用户和认证指南中指定的内容一致。

此库不打算作为通用JWT库；请参阅JWT-php。在编写本文时，GoInstant支持JWT IETF草案第8版。

安装

通过Composer

使用 Composer 安装很简单

  ./composer.phar require goinstant/goinstant-auth:dev-master

如果您的框架还没有这样做，您可以通过以下方式自动加载composer模块（假设这在一个名为 main.php 的文件中，位于您的项目目录中）。

  require_once 'vendor/autoload.php';

通过ZIP文件

如果您不想使用Composer，我们建议您从GitHub下载最新版本的ZIP文件。解压ZIP文件后，您应该会得到一个名为 GoInstant 的目录。将此目录复制到您的项目库中。

  cd ~/Downloads
  unzip php-goinstant-auth-*.zip

  cp -a php-goinstant-auth-*/GoInstant /path/to/your/project/GoInstant

然后，在需要使用的地方引入 Signer.php 文件。请注意，您可能需要根据项目布局调整路径。

  require_once 'GoInstant/Auth/Signer.php';

使用方法

创建一个签名解析器会解析并存储您的GoInstant应用程序密钥。应用程序密钥应该是base64url或base64字符串格式。要获取您的密钥，请访问您的goinstant仪表板并点击您的应用。

请记住，密钥需要像密码一样处理！ 不要与您的用户共享它！

  use \GoInstant\Auth\Signer;
  $signer = new Signer($secretKey);

然后，您可以使用这个 $signer 创建任意数量的令牌。您应该将 example.com 替换为您的网站域名。组是可选的。

  $token = $signer->sign(array(
    'domain' => 'example.com', // TODO: replace me
    'id' => $user->id,
    'displayName' => $user->fullName(),
    'groups' => array(
      array(
        'id' => 'room-'.$roomId,
        'displayName' => 'Room '.$roomId
      )
    )
  ));

然后，您可以将此直接嵌入到您的goinstant连接JavaScript中。JWT格式在URL和HTML环境中都是安全的，因为它只包含符合 /^[a-zA-Z0-9_\-.]+$/ 的字符

<script type="text/javascript">
  (function() {
    // using a var like this prevents other javascript on the page from
    // easily accessing or stealing the token:
    var opts = {
      user: "<?php echo $token ?>",
      rooms: [ ... ]
    };
    var url = 'https://goinstant.net/YOURACCOUNT/YOURAPP'

    goinstant.connect(url, opts, function(err, connection) {
      if (err) {
        throw err;
      }
      runYourApp(connection);
    });
  }());
</script>

方法

`__construct($signKey)`

从密钥构建一个 GoInstantAuth "签名者" 实例。

`sign($userData, $extraHeaders=array())`

创建一个JWT作为紧凑序列化的JWS。可以在同一对象上多次调用，从而节省您每次都要加载您的GoInstant应用程序密钥。

$userData 是一个数组，包含以下必需字段，以及您想要包含在JWT中的任何其他自定义字段。

domain - 您网站的域名
id - 您网站上此用户的唯一、永久身份
displayName - 初始显示给此用户的名称
groups - 组的数组，每个组都需要
- id - 此组的唯一ID，这在定义 GoInstant ACLs 时非常有用
- displayName - 显示此组的名称

$extraHeaders 是完全可选的。它用于定义您希望包含的任何额外的 JWS头字段。

技术细节

sign() 方法中的 $userData 映射到以下JWT声明。GoInstant中使用的声明权威列表可在用户和认证指南中找到。

domain -> iss（标准声明）
id -> sub（标准声明）
displayName -> dn（GoInstant私有声明）
groups -> g（GoInstant私有声明）
- id -> id（GoInstant私有声明）
- displayName -> dn（GoInstant私有声明）
'goinstant.net' -> aud（标准声明） 自动添加

对于 sign() 中的 $extraHeaders 参数，此库将覆盖 alg 和 typ 头。

贡献

如果您想对 php-goinstant-auth 进行贡献或修改，以下是一个快速指南，帮助您开始。

开发依赖项

PHP >= 5.3（建议5.5）
Composer >= 1.0.0-alpha7

设置

通过GitHub下载并安装composer依赖项

git clone git@github.com:goinstant/php-goinstant-auth.git
cd php-goinstant-auth

如果您在Mac上开发，您可能希望通过 brew install 命令使用Mac Homebrew安装php和composer。否则，请遵循Composer下载页面上的说明。

composer install || ./composer.phar install

测试

测试是用PHPUnit编写的。测试文件位于 Tests/ 目录中。

运行测试

vendor/bin/phpunit

如果您的PHP没有加载XDebug扩展，则可能在覆盖步骤失败。您可以从 phpunit.xml 中删除覆盖步骤，或编辑您的 php.ini 以包含XDebug扩展。XDebug可以通过PEAR或通过Mac Homebrew安装。

发布

当将master发布到新的 $VERSION（一个semver）时

编辑composer.json以提升版本号
git add -u && git commit -m "$VERSION"
git tag $VERSION
git push origin master
git push --tags

转到 https://packagist.org.cn/packages/goinstant/goinstant-auth 并确认已发布。

支持

通过电子邮件联系 GoInstant支持或访问freenode上的 #goinstant。

对于负责任的披露，请通过电子邮件联系 GoInstant安全。

要提交错误或提出补丁，请直接使用github。

法律

根据3条款BSD许可证授权

goinstant / goinstant-auth

维护者

详细信息