README

PHP OWN3D ID API Client for Laravel 5+

目录

1. 安装
2. OAuth2 文档
3. 备注
4. Socialite 事件监听器
5. 配置
6. 示例
7. 文档
8. 开发

安装

使用 composer 安装 own3d id 包

composer require own3d/id

OAuth2 文档

您可以在这里找到 OAuth2 的文档。在那里，您可以找到有关注册您的应用程序和您可以请求的作用域的所有信息。

备注

在 StreamTV / OWN3D ID 库中，所有 SSO ID 都定义为字符串。这源于所有 ID 应该成为 UUID 的原因。我们将继续在 big-integers 上进行 id 分配，因为我们从未实现过这一步骤。我们建议将所有 id 存储为数据库中的 big-integers (20)。我们无法保证我们将按顺序分配 ID。

电子邮件验证

每个 OAuth 客户端都需要自己检查是否需要从用户那里获取（已验证的）电子邮件地址。当前电子邮件地址可以通过 /api/users/@me 获取，它将在 email 属性中返回。要检查电子邮件是否被用户验证，您可以查找 email_verified_at 属性。如果 email 属性为 null，则表示用户没有与其账户关联的电子邮件。您需要自己调用 /api/users/@me/update-email 以分配并触发电子邮件验证过程。

Socialite 事件监听器

• 将 SocialiteProviders\Manager\SocialiteWasCalled 事件添加到您的 app/Providers/EventServiceProvider 中的 listen[] 数组中。
• 将您的监听器（即提供者）添加到您刚刚创建的 SocialiteProviders\Manager\SocialiteWasCalled[] 中。
• 您为此提供者添加的监听器是 'Own3d\\Id\\Socialite\\Own3dIdExtendSocialite@handle',。
• 注意：除非您用您自己的提供者覆盖它们，否则您不需要为内置的社交提供商添加任何内容。

use SocialiteProviders\Manager\SocialiteWasCalled;
use Own3d\Id\Socialite\Own3dIdExtendSocialite;

/**
 * The event handler mappings for the application.
 *
 * @var array
 */
protected $listen = [
    SocialiteWasCalled::class => [
        // add your listeners (aka providers) here
        Own3dIdExtendSocialite::class,
    ],
];

配置

将配置复制到配置文件夹

$ php artisan vendor:publish --provider="Own3d\Id\Providers\Own3dIdServiceProvider"

将环境变量添加到您的 .env

OWN3D_ID_KEY=
OWN3D_ID_SECRET=
OWN3D_ID_REDIRECT_URI=${APP_URL}/login/callback

您需要在服务配置文件中添加一个条目，以便在将配置文件缓存在用于生产环境的文件中使用之后（Laravel 命令 artisan config:cache），所有配置仍然可用。

添加到 config/services.php

'own3d-id' => [
    'client_id' => env('OWN3D_ID_KEY'),
    'client_secret' => env('OWN3D_ID_SECRET'),
    'redirect' => env('OWN3D_ID_REDIRECT_URI')
],

示例

基本

$own3dId = new Own3d\Id\Own3dId();

$own3dId->setClientId('abc123');

...

设置器

$own3dId = new Own3d\Id\Own3dId();

$own3dId->setClientId('abc123');
$own3dId->setClientSecret('abc456');
$own3dId->setToken('abcdef123456');

$own3dId = $own3dId->withClientId('abc123');
$own3dId = $own3dId->withClientSecret('abc123');
$own3dId = $own3dId->withToken('abcdef123456');

OAuth 令牌

$own3dId = new Own3d\Id\Own3dId();

$own3dId->setClientId('abc123');
$own3dId->setToken('abcdef123456');

$result = $own3dId->getAuthedUser();

$user = $userResult->shift();

$own3dId->setToken('uvwxyz456789');

$result = $own3dId->getAuthedUser();

$result = $own3dId->withToken('uvwxyz456789')->getAuthedUser();

外观

use Own3d\Id\Facades\Own3dId;

Own3dId::withClientId('abc123')->withToken('abcdef123456')->getAuthedUser();

文档

Oauth

public function retrievingToken(string $grantType, array $attributes)

用户

public function getAuthedUser()
public function setAuthedUserEmailAddress(string $email)
public function getUserById(string $id)
public function getUsersByEmail(string $email)
public function getUserConnections(array $parameters = [])
public function getUserConnectionByPlatformId(string $platform, string $id)

事件

public function sendEvent(string $type, array $data, string $version)

OAuth 范围枚举

保护路由

通过中间件

OWN3D ID 包含一个认证守卫，它将在传入请求上验证访问令牌。一旦您已配置 api 守卫以使用 own3d-id 驱动程序，您只需在需要有效访问令牌的任何路由上指定 auth:api 中间件即可。

Route::get('/user', function () {
    //
})->middleware('auth:api');

多个认证守卫

如果您的应用程序认证不同类型的用户，这些用户可能使用完全不同的 Eloquent 模型，那么您可能需要为您的应用程序中的每个用户提供者类型定义一个守卫配置。这允许您保护针对特定用户提供者的请求。例如，给定以下守卫配置文件 config/auth.php

'api' => [
    'driver' => 'own3d-id',
    'provider' => 'users',
],

'api-customers' => [
    'driver' => 'own3d-id',
    'provider' => 'customers',
],

以下路由将使用 api-customers 守卫，它使用 customers 用户提供者来认证传入请求

Route::get('/customer', function () {
    //
})->middleware('auth:api-customers');

令牌作用域

作用域允许您的应用程序的用户限制第三方应用程序代表他们执行的操作。例如，并非所有 API 消费者都需要获取所有权的权限。

定义作用域

作用域（Scopes）由OWN3D ID服务全局注册。如果一个OWN3D一方特定的应用需要额外的作用域，那么它们需要在OWN3D ID服务中定义。

将作用域分配给令牌

当使用授权代码授权请求访问令牌时，消费者应该将所需的范围作为scope查询字符串参数指定。该scope参数应该是用空格分隔的作用域列表

Route::get('/redirect', function () {
    $query = http_build_query([
        'client_id' => 'client-id',
        'redirect_uri' => 'http://example.com/callback',
        'response_type' => 'code',
        'scope' => 'user:read connections',
    ]);

    return redirect('https://id.stream.tv/oauth/authorize?' . $query);
});

请求所有令牌

当使用密码授权或客户端凭证授权时，您可能希望授权令牌支持您应用程序的所有作用域。您可以通过请求*作用域来完成此操作。如果请求*作用域，则令牌实例上的can方法始终返回true。此作用域只能分配给使用password或client_credentials授权发布的令牌

TBD

检查作用域

使用scopes和scope中间件需要一个授权守卫。对于一方应用，您可能想使用特殊的认证守卫来动态创建用户。如果您对机器到机器认证感兴趣或想要跳过授权守卫，请查看客户端凭证授权令牌。

OWN3D ID包含两个中间件，可用于验证传入请求是否使用具有给定作用域的令牌进行认证。要开始，将以下中间件添加到您的app/Http/Kernel.php文件中的$routeMiddleware属性

'scopes' => \Own3d\Id\Http\Middleware\CheckScopes::class,
'scope' => \Own3d\Id\Http\Middleware\CheckForAnyScope::class,

检查所有作用域

scopes中间件可以分配给路由以验证传入请求的访问令牌是否具有列出的所有作用域

Route::get('/test', function () {
    // Access token has both "user:read" and "connections" scopes...
})->middleware(['auth:api', 'user:read,connections']);

检查任何作用域

scope中间件可以分配给路由以验证传入请求的访问令牌是否至少具有列出的一个作用域

Route::get('/test', function () {
    // Access token has either "user:read" or "connections" scope...
})->middleware(['auth:api', 'scope:user:read,connections'])

在令牌实例上检查作用域

一旦访问令牌认证请求进入您的应用程序，您仍然可以使用认证的App\Models\User实例上的tokenCan方法检查令牌是否有给定的作用域

use Illuminate\Http\Request;

Route::get('/orders', function (Request $request) {
    if ($request->user()->tokenCan('user:read')) {
        //
    }
});

客户端凭证授权令牌

客户端凭证授权适用于机器到机器认证。例如，在API上执行维护任务。

在您的应用程序可以通过客户端凭证授权发布令牌之前，您需要请求客户端凭证授权客户端。您可以通过给developers@stream.tv发邮件来完成此操作。

然后，为了使用此授权类型，您需要将CheckClientCredentials中间件添加到您的app/Http/Kernel.php文件中的$routeMiddleware属性

use Own3d\Id\Http\Middleware\CheckClientCredentials;

protected $routeMiddleware = [
    'client' => CheckClientCredentials::class,
];

然后，将中间件附加到路由

Route::get('/test', function (Request $request) {
    ...
})->middleware('client');

要限制路由的访问权限，以特定作用域为条件，您可以在将client中间件附加到路由时提供逗号分隔的所需作用域列表

Route::get('/test', function (Request $request) {
    ...
})->middleware('client:user:read,your-scope');

将OWN3D ID用作API守卫

如果您想在您的API服务器中接受OWN3D ID访问令牌，您可以轻松地添加/修改您的守卫，以启用支持。如果您还希望在本地数据库中自动生成用户，则在api守卫中使用sso-users提供者。

config/auth.php:

'guards' => [
    ...

    'api' => [
        'driver' => 'own3d-id',
        'provider' => 'sso-users',
    ],
],

'providers' => [
    ...

    'sso-users' => [
        'driver' => 'sso-users',
        'model' => App\Models\User::class,
        'fields' => ['name', 'email', 'email_verified_at'],
    ],
],

配置您的守卫后，您需要在您的AuthServiceProvider中注册own3d-id和sso-users驱动程序。

use Illuminate\Http\Request;
use Own3d\Id\Auth\Own3dSsoUserProvider;
use Own3d\Id\Own3dId;

public function boot()
{
    ...

    Own3dIdGuard::register();
    Own3dSsoUserProvider::register();
}

开发

运行测试

composer test

BASE_URL=xxxx CLIENT_ID=xxxx CLIENT_KEY=yyyy CLIENT_ACCESS_TOKEN=zzzz composer test

生成文档

composer docs