README

此仓库包含一个开源的PHP SDK，允许您从PHP应用程序中访问 Ukey1 API。

!!! 注意：3.0.0版本之前的版本已被弃用，自2017年11月15日起不再工作 !!!

关于Ukey1

Ukey1 是一个身份验证和数据保护服务，旨在增强网站的安全性。该服务旨在帮助您遵守欧盟通用数据保护条例 (GDPR)。

此PHP SDK的Ukey1流程

用户点击“登录”按钮

您可以使用我们的统一登录按钮

SDK向我们的API发送连接请求并获取唯一的网关URL
用户被重定向到Ukey1网关
用户使用他们喜欢的解决方案登录并授权您的应用程序
用户被重定向回预定义的URL
SDK检查结果并获取唯一的访问令牌
就是这样 - 用户已认证（您的应用程序可以调用API以获取用户数据）

API规范

要求

安装

您可以使用 Composer 安装Ukey1 PHP SDK（推荐选项）。运行以下命令

$ composer require asaritech/ukey1-php-sdk

用法

首先，您需要凭证（应用程序ID 和 密钥）。在我们的仪表板中，我们还建议激活尽可能多的保护措施。

登录/注册/登录 - 一个按钮搞定所有

您的应用程序可能看起来像这样（当然，这是可选的）

<html>
  <head>
    <!-- ... -->
    <link rel="stylesheet" type="text/css" href="https://code.ukey1cdn.com/ukey1-signin-button/master/css/ukey1-button.min.css" media="screen">
  </head>
  <body>
    <!-- ... -->
    <a href="login.php" class="ukey1-button">Sign in via Ukey1</a>
    <!-- ... -->
  </body>
</html>

连接请求

您的脚本 login.php 向我们的端点 /auth/v2/connect 发出请求。

session_start();

use \Ukey1\App;
use \Ukey1\Endpoints\Authentication\Connect;
use \Ukey1\Endpoints\Authentication\SystemScopes;
use \Ukey1\Generators\RandomString;

// Set your domain name including protocol
//App::setDomain("http://example.org"); // if not provided, it will be set automatically

define("APP_ID", "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx");
define("SECRET_KEY", "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx");

// Don't forget to use try/catch, the SDK may throw exceptions

try {
  // Entity of your app
  $app = new App();
  $app->setAppId(APP_ID)
    ->setSecretKey(SECRET_KEY);

  // You need a request ID (no need to be unique but it's better)
  // It may be a random string or number
  // But it may also be your own reference ID
  // Maximum length is 64 bytes (=128 chars)
  $requestId = RandomString::generate(64); 

  // This is an URL for redirection back to the app
  // Do you know what is absolutely perfect?
  // - it may be unique
  // - it may contain query parameters and/or fragment
  $returnUrl = "http://example.org/login.php?action=check&user=XXX#fragment";

  // You can check what permissions you can ask (useful for development purposes)
  $systemModule = new SystemScopes($app);
  $permissions = $systemModule->getAvailablePermissions();
  //print_r($permissions);exit;

  // Endpoint module
  $connectModule = new Connect($app);
  $connectModule->setRequestId($requestId)
    ->setReturnUrl($returnUrl)
    ->setScope([
      "country",
      "language",
      "firstname",
      "surname",
      "email",
      "image"
    ]);
  $connectId = $connectModule->getId(); // $connectId is our reference ID (UUID, exactly 36 chars)

  // Store $requestId and $connectId in your database or session, you will need them later
  $_SESSION["requestId"] = $requestId;
  $_SESSION["connectId"] = $connectId;

  // Redirect user to Ukey1 Gateway
  $connectModule->redirect();

} catch (\Exception $e) {
  echo "Unfortunatelly, an error was occured: " . $e->getMessage();
  exit;
}

访问令牌和用户详情请求

一旦用户授权您的应用程序，Ukey1会将用户重定向回您指定的URL。如果用户取消请求，也会执行相同的操作。

URL将类似于这样： http://example.org/login.php?action=check&user=XXX&_ukey1[request_id]={REQUEST_ID}&_ukey1[connect_id]={CONNECT_ID}&_ukey1[code]={CODE}&_ukey1[result]={RESULT}&_ukey1[signature]={SIGNATURE}#fragment 其中 REQUEST_ID 是之前使用的 $requestId，CONNECT_ID 是之前使用的 $connectId，CODE 是用于获取访问令牌的一次性代码，RESULT 可能是 authorized 或 canceled，而 SIGNATURE 是安全签名。

session_start();

use \Ukey1\App;
use \Ukey1\Endpoints\Authentication\AccessToken;
use \Ukey1\Endpoints\Authentication\User;

define("APP_ID", "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx");
define("SECRET_KEY", "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx");

// Don't forget to use try/catch, the SDK may throw exceptions

try {
  $app = new App();
  $app->setAppId(APP_ID)
      ->setSecretKey(SECRET_KEY);

  // Endpoint module
  // You needs $requestId and $connectId that you previously stored in your database or session
  // WARNING: DO NOT use values from GET query - the SDK will test if GET parameters are equal to those you provide here...
  $tokenModule = new AccessToken($app);
  $tokenModule->setRequestId($_SESSION["requestId"])
    ->setConnectId($_SESSION["connectId"]);
  $check = $tokenModule->check(); // returns true if user authorized the request

  if ($check) {
    $accessToken = $tokenModule->getAccessToken();

    // You can also get token expiration (in usual case it's only few minutes) and the list of granted permissions
    //$accessTokenExpiration = $tokenModule->getAccessTokenExpiration();
    //$grantedScope = $tokenModule->getScope();

    // You can now unset request ID and connect ID from session or your database
    unset($_SESSION["requestId"], $_SESSION["connectId"]);

    // Now you can read user's data
    $userModule = new User($app);
    $userModule->setAccessToken($accessToken);

    // If you don't need any personal data but ID, you can get user's ID without any other request (because it's stored in access token)
    $userId = $userModule->getId();

    // If you need more data, the following method will trigger request to get them
    $user = $module->getUser();

    $scope = $user->getScope();
    $firstname = $user->getFirstname();
    $surname = $user->getSurname();
    $language = $user->getLanguage();
    $country = $user->getCountry();
    $email = $user->getEmail();
    $image = $user->getImageUrl();

    // For other permissions (if applicable) you can use general `get()` method
    $customScope = $user->get("another-available-scope");

    // ... more your code ...
  } else {
    // The request has been canceled by user...
  }

} catch (\Exception $e) {
  echo "Unfortunatelly, an error was occured: " . $e->getMessage();
  exit;
}

高级功能

私人用户

此功能也称为 Extranet用户（必须在Ukey1仪表板中启用），当您希望将Ukey1集成到您的私人应用程序中，其中只有预定义的用户可以访问时（通常是在公司Extranet内的员工）很有用。

流程类似。首先，在您的私人应用程序中，您需要有一个简单的用户管理。不需要密码，只需角色（如果适用）、我们的用户ID（您通常会在流程结束时获得）和Extranet引用ID。此引用ID用于将来删除用户。

在您的用户管理中，当您创建新用户时，您还必须向我们的端点 /auth/v2/extranet/users 发送POST请求。

session_start();

use \Ukey1\App;
use \Ukey1\Endpoints\Authentication\ExtranetUsers;

// Set your domain name including protocol
//App::setDomain("http://example.org"); // if not provided, it will be set automatically

define("APP_ID", "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx");
define("SECRET_KEY", "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx");

// Don't forget to use try/catch, the SDK may throw exceptions

try {
  // Entity of your app
  $app = new App();
  $app->setAppId(APP_ID)
    ->setSecretKey(SECRET_KEY);

  // Endpoint module
  $extranetModule = new ExtranetUsers($app);
  $extranetModule->setEmail("employee@example.org")
    ->setLocale("en_GB");
  $referenceId = $extranetModule->getReferenceId(); // $referenceId is our extranet reference ID (UUID, exactly 36 chars)

  // Store $referenceId in your database, you may need it later when you want to delete the user
  // Meanwhile, Ukey1 have just sent an email with the invitation link

  // Next steps?
  // - user clicks to the invitation link
  // - user signs in to Ukey1 gateway
  // - user is redirected back to homepage (or separated login page) of your app
  // - you can directly initiate a standard Connection request (and redirect to Ukey1)
  // - user is already logged in Ukey1, so they only must authorize your app
  // - That's it!

} catch (\Exception $e) {
  echo "Unfortunatelly, an error was occured: " . $e->getMessage();
  exit;
}

为了安装目的（即在没有用户存在于您的用户管理数据库中时），Ukey1仪表板中应用程序的所有者会自动授权登录您的应用程序。只需像公共应用程序一样登录即可。

请注意，每个环境为此功能都是独立的，因此当您在测试环境中添加新用户时，如果需要，您必须再次为生产环境添加他们（反之亦然）。

示例

您想要一个工作示例吗？您可以下载并尝试 ukey1-php-sdk-example。

许可协议

此代码在MIT许可下发布。请参阅LICENSE文件以获取详细信息。

贡献

如果您想成为此PHP SDK的贡献者，请首先联系我们（见以下电子邮件）。请注意，我们遵循[PSR-2]。如果您想为您喜欢的语言中的另一个SDK工作，我们也很乐意了解您！

联系方式

欢迎报告任何问题。如果您想贡献或有发现关键错误，请直接给我们写信至developers@asaritech.com。

asaritech / ukey1-php-sdk

维护者

详细信息