README

使用PHP实现的公民安全身份平台（SIP）API客户端。

什么是Civic

Civic是一个基于区块链的下一代安全身份管理平台。它允许用户在没有传统物理ID、基于知识的认证、用户名/密码和双因素硬件令牌的情况下进行身份验证。公民的Secure Identity Platform（SIP）使用经过验证的身份在网页和移动应用上进行多因素认证，而不需要用户名或密码。SIP为合作伙伴提供以下功能：

安全的公共或私有2FA用户登录，
具有定制流程的验证用户注册。

Civic的工作原理

个人下载Civic应用程序并完成针对Civic商业客户要求定制的身份验证过程。此过程验证个人信息（PII）以确保对身份的所有权，并收集足够的数据以建立Civic商业客户所需的可信度水平。换句话说，可能收集更多的PII以建立高可信度，例如护照、驾照和社会安全号码的扫描，而新用户可能只需收集最少的PII，例如仅电子邮件和手机号码，如果Civic商业客户只想验证用户是真实且唯一的。

验证后，用户现在被视为Civic会员，其经过验证的身份数据存储在用户设备上的Civic应用程序中，而非由Civic存储。Civic会员可以与Civic商业客户共享之前经过验证的身份数据，这些商业客户与Civic合作，利用区块链技术对Civic会员身份数据进行实时验证。

最终，Civic会员对其身份数据和选择与其共享谁和什么的控制权。

入门指南

为了将您的应用程序与Civic集成，您需要进行以下操作

1. 获取应用程序凭据（密钥）

前往 Civic合作伙伴门户。如果您已注册为Civic合作伙伴，您可以直接进行应用程序注册（选项B），否则您将需要提供一些公司详细信息以完成合作伙伴注册过程。

(A) 要成为合作伙伴，您需要提供公司名称、主要域名、主要联系人并接受开发者服务条款。重要：为了证明您有资格为公司创建账户，Civic要求您在注册Civic时使用公司电子邮件地址，并在注册过程中强制要求您的电子邮件域名与公司主要域名相匹配。
(B) 点击“新建应用程序”按钮，填写应用程序表单（应用程序名称、白名单域名、logo图片文件的完整URL）。提交表单后，您将获得应用程序凭据：App ID、签名密钥对、App Secret、加密密钥对。这些凭据将用于稍后配置Civic SIP客户端。

2. 安装civic-sip-php包

$ composer require blockvis/civic-sip-php

3. 实现用户代理（浏览器）功能

在您的页面上包含civic.sip.js脚本。这公开了一个全局对象，civic。

<link rel="stylesheet" href="https://hosted-sip.civic.com/css/civic-modal.css">

<script src="https://hosted-sip.civic.com/js/civic.sip.min.js"></script>

实例化civic.sip实例。

var civicSip = new civic.sip({ appId: 'Your Application ID' });

实现事件处理程序。

// Start scope request
$('button.js-signup').click(function(event) {
    civicSip.signup({ style: 'popup', scopeRequest: civicSip.ScopeRequests.BASIC_SIGNUP });
});

// Listen for data
civicSip.on('auth-code-received', function (event) {
    /*
        event:
        {
            event: "scoperequest:auth-code-received",
            response: "eyJ0eXAiOiJKV1QiLCJhbGciOiJFUzI1NksifQ.eyJqdGkiOiI2Y2EwNTEzMi0wYTJmLTQwZjItYTg2Yi03NTkwYmRjYzBmZmUiLCJpYXQiOjE0OTQyMjUxMTkuMTk4LCJleHAiOjE0OTQyMjUyOTkuMTk4LCJpc3MiOiJjaXZpYy1zaXAtaG9zdGVkLXNlcnZpY2UiLCJhdWQiOiJodHRwczovL3BoNHg1ODA4MTUuZXhlY3V0ZS1hcGkudXMtZWFzdC0xLmFtYXpvbmF3cy5jb20vZGV2Iiwic3ViIjoiY2l2aWMtc2lwLWhvc3RlZC1zZXJ2aWNlIiwiZGF0YSI6eyJjb2RlVG9rZW4iOiJjY2E3NTE1Ni0wNTY2LTRhNjUtYWZkMi1iOTQzNjc1NDY5NGIifX0.gUGzPPI2Av43t1kVg35diCm4VF9RUCF5d4hfQhcSLFvKC69RamVDYHxPvofyyoTlwZZaX5QI7ATiEMcJOjXRYQ",
            type: "code"
        }
    */

    // Encoded JWT Token is sent to the server
    const jwtToken = event.response;

    // Your function to pass JWT token to your server
    sendAuthCode(jwtToken);
});

civicSip.on('user-cancelled', function (event) {
    /*
        event:
        {
          event: "scoperequest:user-cancelled"
        }
    */
});

// Error events
civicSip.on('civic-sip-error', function (error) {
    // handle error display if necessary.
    console.log('Error type = ' + error.type);
    console.log('Error message = ' + error.message);
});

4. 实现应用程序服务器功能

使用 Blockvis\Civic\Sip\Client 与您的应用程序凭据交换从用户浏览器发送的授权代码 $jwtToken 以获取请求的用户数据。

use Blockvis\Civic\Sip\AppConfig;
use Blockvis\Civic\Sip\Client;

// Configure Civic App credentials.
$config = new AppConfig(
    'Your Application ID',
    'Your Application Secret',
    'Your Application Private Signing Key'
);

// Instantiate Civic API client with config and HTTP client.
$sipClient = new Client($config, new \GuzzleHttp\Client());

// Exchange Civic authorization code for requested user data.
$userData = $sipClient->exchangeToken($jwtToken);

返回的 UserData 值对象的示例

UserData {
  -userId: "36a59d10-6c53-17f6-9185-gthyte22647a"
  -items: array:2 [
    0 => UserDataItem {
      -label: "contact.personal.email"
      -value: "user.test@gmail.com"
      -isValid: true
      -isOwner: true
    }
    1 => UserDataItem {
      -label: "contact.personal.phoneNumber"
      -value: "+1 555-618-7380"
      -isValid: true
      -isOwner: true
    }
  ]
}

您可以通过以下方式遍历数据项

foreach ($userData->items() as $dataItem) {
    echo $dataItem->label() . ' = ' . $dataItem->value() . PHP_EOL;
}

您还可以通过它们的标签访问单个数据项。请注意，userId 是 UserData 对象的属性，不包括在数据项数组中。

$userId = $userData->userId();
$email = $userData->getByLabel('contact.personal.email')->value();
$phone = $userData->getByLabel('contact.personal.phoneNumber')->value();

Civic 集成

目前，只有 Civic Hosted 选项可供合作伙伴集成。这是最简单的集成路线，因为它提供了一种类似于传统 oAuth2 授权代码流的流程，Civic 扮演授权服务器的角色。此选项提供了一种安全解决方案，并最大限度地减少了合作伙伴所需的服务器端开发。

以下用户注册示例解释了一般的 Civic Hosted 选项代码流。

注册。 用户点击您网站页面上“使用 Civic 注册”按钮。事件处理程序调用 Civic JS 库中的方法以启动注册。
弹出窗口。 显示一个包含 QR 码的模态框。向 Civic 服务器发出请求以生成您的范围请求的 QR 码。
QR 码。 在提供代码之前，服务器会检查 iframe 的父文档的域名是否与合作伙伴账户中设置的域名白名单相匹配。QR 码在浏览器和用户的智能手机之间建立桥梁。
扫描。 用户使用 Civic 移动应用程序扫描 QR 码，并被提示授权或拒绝范围请求。提示突出显示正在请求的数据和请求方。
授权请求。 授权请求后，数据被发送到 Civic 服务器。
离线验证。 Civic SIP 服务器验证从用户移动应用程序收到的证明的真实性和完整性。这个过程证明了用户数据是由 Civic 证明的，并且用户目前正在控制与数据相关的私钥。
在区块链上验证。 然后，Civic 服务器验证这些证明在区块链上仍然有效且未被撤销。
加密和缓存。 数据被加密并缓存在 Civic 服务器上。一旦这些数据被缓存，iframe 的轮询请求将收到包含 JWT 令牌的授权代码的响应。CivicJS 浏览器端库将令牌传递给父文档。然后，您的网站负责将 JWT 令牌传递到您的服务器。
授权代码交换。 在您的服务器上使用 Civic SIP 客户端（此库）与 Civic SIP 服务器通信，并交换请求的用户数据的授权代码（AC）。SIP 服务器首先验证 JWT 令牌，确保它是由 Civic 签发的，正在由正确的应用程序 ID 使用，并且令牌上的过期时间尚未过期。然后验证封装的 AC 并返回加密的缓存数据。
解密。 您的服务器接收到加密的数据，然后使用您的应用程序密钥进行解密。结果将包含 userId 和请求的任何数据（例如电子邮件、手机号码等）。
完成用户注册。 在这一点上，您可以存储必要的数据，并将用户重定向到您的应用程序的登录体验。

对于随后的登录，可以从 UserData 值对象中使用的 userId 将用户与您的账户系统相关联。

许可证

软件在 MIT 许可证下授权。

blockvis / civic-sip-php

维护者

详细信息