README

Passage PHP SDK

1Password Passage SDK 为 PHP 开发者。
阅读文章 »

报告错误 · 请求功能

关于项目
- 构建工具
入门
- 先决条件
- 安装
使用
示例用法
贡献
许可
联系
致谢

关于项目

介绍 Passage SDK for PHP

无缝集成 1Password 的 Passage API
安全存储和检索机密
魔法链接认证实现
强大的错误处理
自动转换为原生 PHP DateTime 对象
中间件支持，便于集成
强大的 SDK 功能，增强 PHP 项目的安全性

(回到顶部)

入门

先决条件

首先，使用 PHP composer 创建一个 laravel/laravel 项目

composer
```
laravel new my-php-project
```

安装

创建一个 Passage 账户
创建一个新的 Passage 应用程序
获取您的应用程序的 <APP_ID> 和 <API_KEY>
将 <APP_ID> 和 <API_KEY> 添加到您的本地 .env 文件中
```
APP_ID=your_app_id
API_KEY=your_api_key
```
从 Packagist 安装包
```
composer require eludadev/passage
```
导入 Passage 类
```
use Eludadev\Passage\Passage;
```

创建 Passage 类的一个实例。
将 <AUTH_STRATEGY> 设置为 'COOKIES' (默认) 或 'HEADER'。

$passage = new Passage(env('APP_ID'), env('API_KEY'), '<AUTH_STRATEGY>' /* optional */);

(回到顶部)

使用

使用 Node.js 进行请求认证并管理 Passage 用户。

警告要使用 Passage PHP SDK，您需要您的 Passage 应用程序 ID。您可以在控制台中创建新的 Passage 应用程序。

注意假设您已按照上述先决条件创建了一个新的 laravel/laravel 项目，您可以通过打开 routes/web.php 文件并添加以下代码来快速开始使用此 SDK 在您的 API 路由中使用此 SDK：

use Illuminate\Http\Request;
use Eludadev\Passage\Passage;
use Illuminate\Support\Facades\Route;

Route::get('/passage', function (Request $request) {
    $passage = new Passage(env('APP_ID'), env('API_KEY'));
    return $passage->createMagicLink("example@domain.com", "/redirect");
});

请求认证

Passage 使得将 HTTP 请求与已认证用户关联变得容易。以下代码可用于验证请求是否由已认证用户发起。

use Illuminate\Http\Request;
use Eludadev\Passage\Passage;
use Illuminate\Support\Facades\Route;

// Authentication using Passage class instance
Route::get('authenticatedRoute', function (Request $request) {
    $passage = new Passage(env('APP_ID'), env('API_KEY'));

    try {
        // Authenticate request using Passage
        $userID = $passage->authenticateRequest($request);
        if ($userID) {
            // User is authenticated
            $userData = $passage->user->get($userID);
            return;
        }
    } catch (\Exception $e) {
        // Authentication failed
        return "Authentication failed!";
    }
});

默认情况下，Passage 从由 Passage Element 设置的 cookie 中查找用户 JWT（psg_auth_token）。如果您的应用程序使用授权头，则可以将以下选项传递给 Passage PHP SDK。

$passage = new Passage(env('APP_ID'), env('API_KEY'), 'HEADER');

使用 PHP 中间件进行请求认证

如果您使用了 laravel/laravel 项目，Passage 提供了一个可以直接使用的中间件。此中间件将进行请求认证，并在令牌无效时返回 401 未授权。如果成功，Passage 用户 ID 将可在响应中获取。以下代码显示了如何将 Passage 中间件用于 PHP 应用程序。

use Illuminate\Support\Facades\Route;
use Illuminate\Http\Request;

use Eludadev\Passage\Passage;
use Eludadev\Passage\Middleware\PassageAuthMiddleware;

// Example of passage middleware
Route::get('authenticatedRoute', function (Request $request) {
  $passage = new Passage(env('APP_ID'), env('API_KEY'));
  $userID = $request->userID;
})->middleware(PassageAuthMiddleware::class);

如果您在请求上下文中没有使用 eludadev/passage，或者您的应用程序以自定义方式传递 JWT，则可以直接将 JWT 传递给 validAuthToken 方法进行验证。

$userID = $passage->validAuthToken($token);

if ($userID) {
  //authenticated
}
// otherwise, unauthorized

应用程序信息

Passage SDK 提供了一种获取应用程序信息的方法。

use Eludadev\Passage\Passage;

$passage = new Passage(env('APP_ID'), env('API_KEY'));
$appInfo = $passage->getApp();

用户管理

除了验证请求外，Passage PHP SDK 还提供了一种安全地管理用户的方式。这些功能需要使用 Passage API 密钥进行身份验证。API 密钥可以在 Passage 控制台 中进行管理。

当前用户可用的功能

获取用户信息（包括任何定义的用户元数据）
激活或停用用户（停用的用户将无法登录）
更新用户信息（电子邮件地址或电话号码）
删除用户
创建用户

警告 Passage API 密钥是敏感信息！您应该与其他应用程序机密一样安全地存储它们。

获取

use Illuminate\Http\Request;

use Eludadev\Passage\Passage;
use Eludadev\Passage\Middleware\PassageAuthMiddleware;

Route::get('authenticatedRoute', function (Request $request) {
$passage = new Passage(env('APP_ID'), env('API_KEY'));

$userID = $request->userID;
  $passageUser = $passage->user->get($userID);
return $passageUser->email;
})->middleware(PassageAuthMiddleware::class);

激活/停用

use Illuminate\Http\Request;

use Eludadev\Passage\Passage;
use Eludadev\Passage\Middleware\PassageAuthMiddleware;

Route::get('authenticatedRoute', function (Request $request) {
  $passage = new Passage(env('APP_ID'), env('API_KEY'));
  $userID = $request->userID;

  $deactivatedUser = $passage->user->deactivate($userID);
  $deactivatedUser->active; // false

  $activatedUser = $passage->user->activate($userID);
  $activatedUser->active; // true
})->middleware(PassageAuthMiddleware::class);

更新

use Illuminate\Http\Request;

use Eludadev\Passage\Passage;
use Eludadev\Passage\Middleware\PassageAuthMiddleware;

Route::get('authenticatedRoute', function (Request $request) {
  $passage = new Passage(env('APP_ID'), env('API_KEY'));

  $userID = $request->userID;
  $passageUser = $passage->user->update($userID, [
    'email' => 'testEmail@domain.com',
    'phone' => '+15005550006'
  ]);

  $passageUser->email; // testEmail@domain.com
  $passageUser->phone; // +15005550006
})->middleware(PassageAuthMiddleware::class);

删除

use Illuminate\Http\Request;

use Eludadev\Passage\Passage;
use Eludadev\Passage\Middleware\PassageAuthMiddleware;

Route::get('authenticatedRoute', function (Request $request) {
  $passage = new Passage(env('APP_ID'), env('API_KEY'));

  $userID = $request->userID;
  $deletedUser = $passage->user->delete($userID);
  $deletedUser; // true
})->middleware(PassageAuthMiddleware::class);

创建

use Eludadev\Passage\Passage;

$passage = new Passage(env('APP_ID'), env('API_KEY'));

$newUser1 = $passage->user->create('testEmail@domain.com');
$newUser1->email; // testEmail@domain.com

$newUser2 = $passage->user->create(phone:'+15005550006');
$newUser2->phone; // +15005550006

用户设备管理

当前可用的功能

列出用户的全部设备
从用户中吊销特定设备

列出设备

use Illuminate\Http\Request;

use Eludadev\Passage\Passage;
use Eludadev\Passage\Middleware\PassageAuthMiddleware;

Route::get('authenticatedRoute', function (Request $request) {
  $passage = new Passage(env('APP_ID'), env('API_KEY'));

  $userID = $request->userID;
  $devices = $passage->user->listDevices($userID);
  return $devices;
})->middleware(PassageAuthMiddleware::class);

吊销设备

use Illuminate\Http\Request;

use Eludadev\Passage\Passage;
use Eludadev\Passage\Middleware\PassageAuthMiddleware;

Route::get('authenticatedRoute', function (Request $request) {
  $passage = new Passage(env('APP_ID'), env('API_KEY'));

  $userID = $request->userID;
  $success = $passage->user->revokeDevice($userID, '<DEVICE_ID>');
  return $success; // true
})->middleware(PassageAuthMiddleware::class);

创建魔法链接

PHP SDK 可以用于为用户生成自定义的魔法链接（称为“智能链接”），这些链接可以嵌入到任何内容媒介中。要了解更多信息，请参阅我们关于智能链接的完整指南。

use Eludadev\Passage\Passage;

$passage = new Passage(env('APP_ID'), env('API_KEY'));

$magicLink = $passage->createMagicLink('newEmail@domain.com', '/custom-path/1234');

// use Magic Link URL
$magicLink->url;

(回到顶部)

示例用法

我们在 React 和 PHP 后端上构建了一个示例全栈应用程序。要开始，请打开以下目录：cd ./examples

警告在继续执行这些步骤之前，请确保您的本地机器已安装 PHP 和 Composer。

配置新的 Passage 项目

创建一个新 Passage 项目。请确保输入 https://:3000 作为域名，以及 /dashboard 作为重定向 URL。

更新现有的 Passage 项目

转到您的项目设置。

输入 https://:3000 作为域名，以及 /dashboard 作为重定向 URL，以及 / 作为登录 URL。

运行服务器

转到后端目录：cd ./backend
安装依赖项：composer install
复制环境变量文件：cp .env.example .env
在 .env 中替换您的 Passage 凭据
```
PASSAGE_APP_ID=
PASSAGE_API_KEY=
```
运行服务器：php artisan serve

运行前端

转到前端目录：cd ./frontend
安装依赖项：yarn
复制环境变量文件：cp EXAMPLE.env .env
在 .env 中替换您的 Passage 凭据
```
REACT_APP_PASSAGE_APP_ID=
```
运行服务器：yarn start

工作原理

以下是驱动 PHP 后端的代码

// routes/api.php

<?php

use Eludadev\Passage\Errors\PassageError;
use Eludadev\Passage\Passage;
use Illuminate\Http\Request;
use Illuminate\Support\Facades\Route;

// This route handles the authentication process for the '/auth' endpoint

Route::post('/auth', function (Request $request) {
    try {
        // Create a new instance of the Passage class using the Passage API credentials from the environment variables
        $passage = new Passage(env('PASSAGE_APP_ID'), env('PASSAGE_API_KEY'), 'HEADER');

        // Authenticate the request using the Passage API
        $userId = $passage->authenticateRequest($request);

        if ($userId) {
            // If authentication is successful, retrieve user data using the Passage API
            $userData = $passage->user->get($userId);

            // Determine the identifier based on the user data (email or phone)
            $identifier = $userData['email'] ? $userData['email'] : $userData['phone'];

            // Return the authentication status and identifier
            return [
                'authStatus' => 'success',
                'identifier' => $identifier
            ];
        }
    } catch (PassageError $e) {
        // Catch any errors that occur during the authentication process and echo the error message
        echo $e->getMessage();

        // Return the authentication failure status
        return [
            'authStatus' => 'failure'
        ];
    }
});

对于这个特定的示例，我们选择在 Laravel 框架上构建服务器，但 Passage PHP SDK 可以在任何一个 PHP 框架上工作。

前端调用 localhost:8000/api/auth URL，提取认证头，解码 JWK 令牌，并检索用户 ID。然后，它调用 Passage API 以获取更多用户信息，例如电子邮件和电话号码。

所有这些操作都由 PHP SDK 在后台完成，因此您无需担心复杂的细节。

(回到顶部)

贡献

贡献是开源社区如此出色的学习、灵感和创造之地的原因。您所做的任何贡献都将被 大力赞赏。

如果您有使本项目更完善的建议，请fork此仓库并创建一个pull request。您也可以简单地创建一个带有“enhancement”标签的问题。别忘了给项目点个star！再次感谢！

fork项目
创建功能分支（git checkout -b feature/AmazingFeature）
提交您的更改（git commit -m '添加一些AmazingFeature'）
推送到分支（git push origin feature/AmazingFeature）
打开pull request

(回到顶部)

许可

遵循MIT许可协议发布。更多信息请参阅LICENSE。

(回到顶部)

联系

Younes Laaroussi - Telegram - hello@eluda.dev

项目链接：https://github.com/eludadev/Passage

(回到顶部)

致谢

非常感谢1Password和Hashnode为这次精彩的黑客马拉松提供支持！这对我和所有参与者来说都是一次乐趣无限、收获颇丰的学习经历，希望未来还能再次举办！❤️

(回到顶部)

eludadev / passage

维护者

详细信息

README

Passage PHP SDK

关于项目

入门

先决条件

安装

使用

请求认证

使用 PHP 中间件进行请求认证

应用程序信息

用户管理

用户设备管理

创建魔法链接

示例用法

配置新的 Passage 项目

更新现有的 Passage 项目

运行服务器

运行前端

工作原理

贡献

许可

联系

致谢