PHPackages                             own3d/id - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Authentication & Authorization](/categories/authentication)
4. /
5. own3d/id

ActiveLibrary[Authentication & Authorization](/categories/authentication)

own3d/id
========

PHP OWN3D ID API Client for Laravel 5+

2.5.0(6mo ago)013.4k↓50%[1 issues](https://github.com/own3d/id/issues)1MITPHPPHP ^8.2

Since Jan 5Pushed 6mo ago2 watchersCompare

[ Source](https://github.com/own3d/id)[ Packagist](https://packagist.org/packages/own3d/id)[ RSS](/packages/own3d-id/feed)WikiDiscussions main Synced 1mo ago

READMEChangelog (10)Dependencies (8)Versions (45)Used By (1)

OWN3D ID
========

[](#own3d-id)

PHP OWN3D ID API Client for Laravel 5+

Table of contents
-----------------

[](#table-of-contents)

1. [Installation](#installation)
2. [OAuth2 Documentation](#oauth2-documentation)
3. [Remarks](#remarks)
4. [Socialite Event Listener](#socialite-event-listener)
5. [Configuration](#configuration)
6. [Examples](#examples)
7. [Documentation](#documentation)
8. [Development](#Development)

Installation
------------

[](#installation)

Install the own3d id package with composer:

```
composer require own3d/id

```

OAuth2 Documentation
--------------------

[](#oauth2-documentation)

You can find the documentation for OAuth2 [here](https://dev.own3d.tv/docs/authorization.html). There you can find all the information about registering your application and the scopes you can request.

Remarks
-------

[](#remarks)

In the StreamTV / OWN3D ID Library all SSO IDs are defined as strings. This comes from the origin that all IDs should become UUIDs. We will simply continue the id assignment on big-integers, since we never implemented this step. We recommend to store all ids as big-integers (20) in your database. It is not guaranteed that we will assign IDs incrementally.

### E-Mail Verification

[](#e-mail-verification)

Every oauth client needs to check itself if they need a (verified) email address from the user. The current email address can be fetched via `/api/users/@me`, it will be returned in the `email` attribute. To see if the email is verified by the user, you can lookup the `email_verified_at` attribute. If the `email` attribute is `null`, this means the user has no email associated with his account. You need to call `/api/users/@me/update-email` by yourself to assign and trigger the email verification process.

Socialite Event Listener
------------------------

[](#socialite-event-listener)

- Add `SocialiteProviders\Manager\SocialiteWasCalled` event to your `listen[]` array in `app/Providers/EventServiceProvider`.
- Add your listeners (i.e. the ones from the providers) to the `SocialiteProviders\Manager\SocialiteWasCalled[]` that you just created.
- The listener that you add for this provider is `'Own3d\\Id\\Socialite\\Own3dIdExtendSocialite@handle',`.
- Note: You do not need to add anything for the built-in socialite providers unless you override them with your own providers.

```
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,
    ],
];
```

Configuration
-------------

[](#configuration)

Copy configuration to config folder:

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

```

Add environmental variables to your `.env`

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

```

You will need to add an entry to the services configuration file so that after config files are cached for usage in production environment (Laravel command `artisan config:cache`) all config is still available.

**Add to `config/services.php`:**

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

Examples
--------

[](#examples)

#### Basic

[](#basic)

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

$own3dId->setClientId('abc123');

...
```

#### Setters

[](#setters)

```
$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 Tokens

[](#oauth-tokens)

```
$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();
```

#### Facade

[](#facade)

```
use Own3d\Id\Facades\Own3dId;

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

Documentation
-------------

[](#documentation)

### Oauth

[](#oauth)

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

### Users

[](#users)

```
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)
```

### Events

[](#events)

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

[**OAuth Scopes Enums**](src/Enums/Scope.php)

### Protecting Routes

[](#protecting-routes)

#### Via Middleware

[](#via-middleware)

OWN3D ID includes an [authentication guard](https://laravel.com/docs/8.x/authentication#adding-custom-guards) that will validate access tokens on incoming requests. Once you have configured the `api` guard to use the `own3d-id` driver, you only need to specify the `auth:api` middleware on any routes that should require a valid access token:

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

#### Multiple Authentication Guards

[](#multiple-authentication-guards)

If your application authenticates different types of users that perhaps use entirely different Eloquent models, you will likely need to define a guard configuration for each user provider type in your application. This allows you to protect requests intended for specific user providers. For example, given the following guard configuration the `config/auth.php` configuration file:

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

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

The following route will utilize the api-customers guard, which uses the customers user provider, to authenticate incoming requests:

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

### Token Scopes

[](#token-scopes)

Scopes allow your application's users to limit the actions a third-party application can perform on their behalf. For example, not all API consumers will need the ability to fetch entitlements.

#### Defining Scopes

[](#defining-scopes)

[Scopes](src/Enums/Scope.php) are registered globally by the OWN3D ID service. If a OWN3D first-party specific application needs a additional scope, then they need to define it in the OWN3D ID service.

#### Assigning Scopes To Tokens

[](#assigning-scopes-to-tokens)

When requesting an access token using the authorization code grant, consumers should specify their desired scopes as the `scope` query string parameter. The `scope` parameter should be a space-delimited list of scopes:

```
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);
});
```

#### Requesting all Tokens

[](#requesting-all-tokens)

When using the password grant or client credentials grant, you may wish to authorize the token for all of the scopes supported by your application. You can do this by requesting the `*` scope. If you request the `*` scope, the `can` method on the token instance will always return `true`. This scope may only be assigned to a token that is issued using the `password` or `client_credentials` grant:

```
TBD
```

### Checking Scopes

[](#checking-scopes)

> Using the `scopes` and `scope` middleware requires a authorization guard. For first-party apps, you may want to use a special [authentication guard](aultiple-authentication-guards) to create users dynamically. If you're interested in machine-to-machine authentication or want to skip the authorization guard, then have a look at [client credentials grant tokens](#client-credentials-grant-tokens).

OWN3D ID includes two middleware that may be used to verify that an incoming request is authenticated with a token that has been granted a given scope. To get started, add the following middleware to the `$routeMiddleware` property of your `app/Http/Kernel.php` file:

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

#### Check For All Scopes

[](#check-for-all-scopes)

The `Own3d\Id\Http\Middleware\CheckToken` middleware may be assigned to a route to verify that the incoming request's access token has all of the listed scopes:

```
use Own3d\Id\Http\Middleware\CheckToken;

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

#### Check For Any Scopes

[](#check-for-any-scopes)

The `Own3d\Id\Http\Middleware\CheckTokenForAnyScope` middleware may be assigned to a route to verify that the incoming request's access token has at least one of the listed scopes:

```
use Own3d\Id\Http\Middleware\CheckTokenForAnyScope;

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

#### Checking Scopes On A Token Instance

[](#checking-scopes-on-a-token-instance)

Once an access token authenticated request has entered your application, you may still check if the token has a given scope using the `tokenCan` method on the authenticated `App\Models\User` instance:

```
use Illuminate\Http\Request;

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

### Using OWN3D JWT as API Guard (New)

[](#using-own3d-jwt-as-api-guard-new)

```
/**
 * Bootstrap any application services.
 */
public function boot(): void
{
    Auth::viaRequest('jwt', function ($request) {
        return app(JwtRequestGuard::class)->authenticate($request);
    });
}
```

`config/auth.php`:

```
'api' => [
    'driver' => 'jwt',
    'provider' => 'users',
],
```

### Using OWN3D ID as API Guard (Deprecated)

[](#using-own3d-id-as-api-guard-deprecated)

If you want to accept OWN3D ID Access tokens within you API Server, you can easily add/modify your guards, to enable support. If you also want to generate users automatically in your local database, then use the `sso-users` provider within your `api` guard.

`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'],
    ],
],
```

After configure your guards, you need to register the `own3d-id` and `sso-users` drivers within your `AuthServiceProvider`.

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

public function boot()
{
    ...

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

Development
-----------

[](#development)

#### Run Tests

[](#run-tests)

```
composer test
```

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

#### Generate Documentation

[](#generate-documentation)

```
composer docs
```

###  Health Score

49

—

FairBetter than 95% of packages

Maintenance67

Regular maintenance activity

Popularity23

Limited adoption so far

Community14

Small or concentrated contributor base

Maturity78

Established project with proven stability

 Bus Factor1

Top contributor holds 88.5% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~47 days

Recently: every ~111 days

Total

38

Last Release

194d ago

Major Versions

1.9.2 → 2.0.02021-08-23

PHP version history (2 changes)1.0.0PHP ^7.4|^8.0

2.5.0PHP ^8.2

### Community

Maintainers

![](https://www.gravatar.com/avatar/03da561a330aa76d1a09096b2ee0c48ee53ca51d62fa0239469d9615b6855733?d=identicon)[ghostzero](/maintainers/ghostzero)

---

Top Contributors

[![ghostzero](https://avatars.githubusercontent.com/u/6547306?v=4)](https://github.com/ghostzero "ghostzero (100 commits)")[![StefanEnsmann](https://avatars.githubusercontent.com/u/9017068?v=4)](https://github.com/StefanEnsmann "StefanEnsmann (8 commits)")[![derpierre65](https://avatars.githubusercontent.com/u/7004269?v=4)](https://github.com/derpierre65 "derpierre65 (4 commits)")[![rico-ocepek](https://avatars.githubusercontent.com/u/24636384?v=4)](https://github.com/rico-ocepek "rico-ocepek (1 commits)")

---

Tags

oauthown3d

###  Code Quality

TestsPHPUnit

### Embed Badge

![Health badge](/badges/own3d-id/health.svg)

```
[![Health](https://phpackages.com/badges/own3d-id/health.svg)](https://phpackages.com/packages/own3d-id)
```

###  Alternatives

[flarum/core

Delightfully simple forum software.

211.3M1.9k](/packages/flarum-core)[kovah/laravel-socialite-oidc

OpenID Connect OAuth2 Provider for Laravel Socialite

2073.7k](/packages/kovah-laravel-socialite-oidc)[scaler-tech/laravel-saml2

SAML2 Service Provider integration for Laravel applications, based on OneLogin toolkit

2737.5k](/packages/scaler-tech-laravel-saml2)[aedart/athenaeum

Athenaeum is a mono repository; a collection of various PHP packages

245.2k](/packages/aedart-athenaeum)[truckersmp/steam-socialite

Laravel Socialite provider for Steam OpenID.

1516.7k](/packages/truckersmp-steam-socialite)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)