README

Almefy API的简单PHP包装器。

快速指南

以下是如何在PHP项目中集成Almefy以方便测试的简化指南。我们正在准备一份全面的文档，涵盖所有可能的用例和参数。请耐心等待。

请注意：此文档正在不断完善中，目前针对PHP 5.6提供向后兼容性。

先决条件

要成功初始化PHP客户端，您需要从Almefy获取API密钥和API密钥。

# Example .env Data

ALMEFY_KEY=...
ALMEFY_SECRET=...

安装

Almefy PHP SDK作为almefy/sdk软件包在Packagist上可用。在终端中，从项目的根目录运行composer require almefy/sdk，然后您就完成了。如果您无法使用composer，您可以从GitHub下载最新版本。目前支持的最小PHP版本是5.6。

客户端初始化

一旦在项目中安装了SDK，您需要创建一个客户端对象。以下示例假设您将密钥存储在某个环境变量中

$client = new \Almefy\Client($_ENV['ALMEFY_KEY'], $_ENV['ALMEFY_SECRET']);

身份注册

在用户账户可以使用Almefy应用程序之前，它需要注册并配置设备。注册Almefy账户的最简单方法是通过包含注册QR码的电子邮件发送给用户。一个好的起点可以在受保护区域内放置一个“使用Almefy登录”按钮，该按钮在后台触发以下过程

try {
    $enrollmentToken = $client->enrollIdentity('john.doe');
    
} catch (\Almefy\Exception\TransportException $e) {
    echo 'Could not connect to Almefy service: '.$e->getMessage();
}

返回的$enrollmentToken对象提供了一个公开的base64ImageData成员，其中包含可用于任何HTML电子邮件的base64编码图像数据。

如果启用，您还可以使用Almefy API发送不带自定义电子邮件客户端兼容模板的通用注册电子邮件

try {
    $client->enrollIdentity('john.doe', array(
        'sendEmail' => true
        'sendEmailTo' => 'john.doe@example.com'
    ));
    
} catch (\Almefy\Exception\TransportException $e) {
    echo 'Could not connect to Almefy service: '.$e->getMessage();
}

注意：有关所有可用选项，请参阅API注册参考。

此过程创建或使用现有身份，并发送包含QR码的注册电子邮件，需要使用Almefy应用程序扫描以进行配置。完成后，注册完成，用户即可使用Almefy应用程序进行身份验证。

前端

将以下几行代码添加到您的HTML前端中，以显示用于身份验证的Almefy图像。

<!-- Place this HTML code wherever the Almefy image should appear -->
<div data-almefy-auth
     data-almefy-key="5bbf4923faf099a3515a40d9b0e6e6e32c890ef6cd7a8a120657c2f49d2341fe"
     data-almefy-auth-url="/path/to/auth-controller"></div>

<!-- Load the JavaScript library -->
<script src="https://cdn.almefy.com/js/almefy-0.8.1.js"
        integrity="sha384-ouDeQdWqj/ZXOHf8xdH+qmWP9h+0zE7VDRWw3X7uanj81OpYvAh4fjNnQ90gA2Ba"
        crossorigin="anonymous"></script>

身份验证

配置在data-alemfy-auth-url中的身份验证控制器将接收来自Almefy API的X-Almefy-Authorization头。在控制器中需要做的第一件事是从头中提取令牌并进行解码（它也会进行验证）。

// Get the JWT from header
$jwt = $request->headers->get('X-Almefy-Authorization');

// decode it
$token = $client->decodeJwt($jwt);

注意：出于兼容性原因（例如Apache网络服务器不会将其转发给PHP进程），JWT通过X-Almefy-Authorization头提供，但也使用标准的Authorization: Bearer ...头。

接下来，您应该检查尝试进行身份验证的用户是否在您自己的身份管理系统内，并且是否有权限进行身份验证。这属于您的业务逻辑，以下仅为示例

// $userRepository is any PHP class used for database queries 
$user = $userRepository->retrieveByUsername($token->getIdentifier());

// Check any internal business logic
if (!$user->isEnabled() || !$user->isSubscriptionActive()) {
    return false;
}

最后且重要的一步是在Almefy系统中验证并确认身份验证尝试

if (!$client->verifyToken($token)) {
    // Authentication attempt could not be verified or is invalid
    return false;
}

注意：出于安全原因，任何网络或服务器错误都会始终返回false。

在此阶段，您可以通过设置会话变量等方式对用户进行身份验证，并将其重定向到受保护区域。

许可证

Almefy PHP SDK在Apache许可证下进行许可，版本2.0。

almefy / sdk

维护者

详情