README

2FAS SDK让您的PHP应用程序与API交互变得简单。最新的2FAS SDK版本可在Github上找到。2FAS SDK需要PHP版本5.4或更高。

按照以下步骤将您的应用程序与2FAS集成

1. 安装和配置
2. 用户配置
3. 使用身份验证

SDK的完整文档可在此处找到

安装和配置

先决条件

在开始使用此SDK之前，您必须创建一个账户并拥有一个用于身份验证的令牌。

安装

SDK只能通过composer安装。您可以使用require命令将PHP SDK添加到您的composer.json文件中

composer require twofas/sdk

如果您使用的是像Symfony或Laravel这样的框架，2FAS SDK可能会自动为您加载并准备好在应用程序中使用。如果您在一个不处理自动加载的环境中使用Composer，如果上述安装命令已使用，您可以要求从Composer创建的“vendor”目录中的自动加载文件。

升级

如果您正在升级主版本，请参阅升级指南。

创建SDK客户端

<?php
// Required if your environment does not handle autoloading
require __DIR__ . '/vendor/autoload.php';

// Copy from your 2FAS dashboard
$token = 'XXXXXXXXXXXXXXXXXXXXXXXXX...';

$sdk = new \TwoFAS\Api\Sdk($token);

加密

2FAS中的所有敏感数据都在客户端加密，我们无法解密它们。因此，在发送到2FAS之前，您应该使用我们的方法对它们进行加密，并将加密密钥保存在您的存储中。我们提供开箱即用的AES加密。您需要做的是实现ReadKey接口，该接口从您的存储（例如环境变量、数据库）中检索数据。请记住，密钥是字节格式，因此您应该在保存之前对其进行编码，在读取后对其进行解码 - 您可以使用例如base64_encode和base64_decode函数。如果您想将密钥存储在环境文件中，您可以生成并将字符串粘贴到文件中，然后仅从您的存储中检索环境变量

<?php
//generate AES Key
$key = new \TwoFAS\Encryption\AESGeneratedKey();
echo base64_encode($key->getValue()); //paste to your environment file

//only retrieve key from storage
class EnvStorage implements \TwoFAS\Encryption\Interfaces\ReadKey
{
  public function retrieve()
  {
    return new \TwoFAS\Encryption\AESKey(base64_decode(getenv('AES_KEY')));
  }
}

用户配置

创建集成用户

您的每个用户都应该在2FAS中以集成用户的形式表示，因此您必须将您的本地用户ID设置为集成用户的外部ID

<?php
// SDK client has to be created

$myStorage = new EnvStorage();
$integrationUser = new \TwoFAS\Api\IntegrationUser();
$integrationUser->setExternalId(123); //This is your local user id

$sdk->addIntegrationUser($myStorage, $integrationUser);

生成二维码

我们的主要和默认认证方法是TOTP。要使用它，您需要根据此文档生成QR码，并配置您的移动应用，并将数据存储在集成用户中。我们的SDK允许您根据您的字符串生成QR码。

<?php

$qrClient = new \TwoFAS\Api\QrCode\EndroidQrClient();
$generator = new \TwoFAS\Api\QrCodeGenerator($qrClient);

$uri = 'otpauth://totp/Acme:foo@example.com?secret=JBSWY3DPEHPK3PXP&issuer=Acme';
$imgSrc = $generator->generateBase64($uri);

//in html:
//<img src="{{ $imgSrc }}">

配置集成用户

在使用认证之前，您必须配置以下认证方法之一：totp、sms/vms或email。为此，您需要验证用户是否提供了正确的代码。例如，我们将开启TOTP认证并验证由移动应用生成的代码。

<?php
// SDK client has to be created

$totpSecret = 'JBSWY3DPEHPK3PXP'; // from QR Code
$totpCode = '210866'; // from text input, generated by mobile app
$authentication = $sdk->requestAuthViaTotp($totpSecret);
$result = $sdk->checkCode([$authentication->id()], $totpCode);

if ($result->accepted()) {
  // update user, described below
} else {
  // check other result types and handle them
}

对于其他认证方法，情况类似，但您必须使用我们的其他认证方法通过sms/vms或email发送代码。请注意，sms/vms方法需要付费，因此您必须在2FAS仪表板上添加您的信用卡才能正常工作。

每次认证有效期为15分钟，提供的代码可以检查最多5次。

更新集成用户

配置成功后，您必须更新您的集成用户中的数据。

<?php
// SDK client has to be created

$myStorage = new MyStorage();
$localUserId = 123;
$integrationUser = $sdk->getIntegrationUserByExternalId($myStorage, $localUserId);
$integrationUser
  ->setTotpSecret('JBSWY3DPEHPK3PXP') //if you're configuring TOTP
  ->setPhoneNumber($this->formatNumber('+48 555 088013')) //if you're configuring SMS/VMS
  ->setEmail('foo@example.com'); //if you're configuring EMAIL

$sdk->updateIntegrationUser($myStorage, $integrationUser);

使用认证

创建认证和检查代码

如果您的集成用户已成功配置，您可以使用它作为登录过程的第二因素来开启认证。认证过程看起来与配置非常相似，但您需要使用集成用户中的密钥而不是QR码中的密钥。

<?php
// SDK client has to be created

$totpCode = '210866'; // from text input, generated by mobile app
$authentication = $sdk->requestAuthViaTotp($integrationUser->getTotpSecret());
$result = $sdk->checkCode([$authentication->id()], $totpCode);

if ($result->accepted()) {
  // authentication ok, log in user
} else {
  // forbidden, check other result types and handle them
}

备份代码

2FAS还允许您使用可打印的备份代码进行认证，在您没有移动设备的情况下登录到您的网站。您可以同时生成5个备份代码，每个代码只能使用一次。

<?php
// SDK client has to be created

//generate codes
$codes = $sdk->regenerateBackupCodes($integrationUser);

//open authentication
$authentication = $sdk->requestAuthViaTotp($integrationUser->getTotpSecret());

//check code
$backupCode = 'XXXX-XXXX-XXXX'; // from text input
$result = $sdk->checkBackupCode($integrationUser, [$authentication->id()], $backupCode);

if ($result->accepted()) {
  // authentication ok, log in user
} else {
  // forbidden, check other result types and handle them
}