PHPackages                             bigfork/silverstripe-oauth - 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. bigfork/silverstripe-oauth

ActiveSilverstripe-vendormodule[Authentication & Authorization](/categories/authentication)

bigfork/silverstripe-oauth
==========================

SilverStripe OAuth2 authentication, based on the PHP League's OAuth2 client

3.0.0(4mo ago)899.2k↓26.3%12[3 issues](https://github.com/bigfork/silverstripe-oauth/issues)1BSD-3-ClausePHPCI failing

Since Mar 1Pushed 4mo ago5 watchersCompare

[ Source](https://github.com/bigfork/silverstripe-oauth)[ Packagist](https://packagist.org/packages/bigfork/silverstripe-oauth)[ RSS](/packages/bigfork-silverstripe-oauth/feed)WikiDiscussions master Synced 3w ago

READMEChangelogDependencies (3)Versions (16)Used By (1)

SilverStripe OAuth
==================

[](#silverstripe-oauth)

SilverStripe OAuth2 authentication, based on the PHP League's [OAuth2 client](http://oauth2-client.thephpleague.com/).

### What this module does

[](#what-this-module-does)

This module includes the base functionality for fetching access tokens. It provides methods for creating requests to OAuth providers, fetching access tokens with various scopes/permissions, and registering handlers for dealing with the returned tokens.

### What this module doesn’t do

[](#what-this-module-doesnt-do)

This module does not provide “Log in with <provider>” buttons, “Fetch contacts from <provider>” buttons, or any other functionality for actually interacting with providers - it only fetches tokens that will allow you to do that. It’s up to you to install the appropriate packages for third-party providers, and to implement functionality that makes use of the access tokens to fetch data from those providers.

If you’re looking for “Log in with <provider>” functionality, take a look at the add-on for this module: [SilverStripe OAuth Login](https://github.com/bigfork/silverstripe-oauth-login).

This module also does not store access tokens in the database. If this is a requirement of your application, you will need to build your own models to handle this, and set up appropriate token handlers.

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

[](#installation)

This module must be installed with composer. Run `composer require bigfork/silverstripe-oauth:*` from the command line, and then run a `dev/build`.

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

[](#configuration)

Providers are registered as `Injector` services using SilverStripe’s YAML configuration. This allows you to specify an “internal” name (passed around in URLs and session data), a PHP class for the provider (that extends `League\OAuth2\Client\Provider\AbstractProvider`), and constructor parameters & class properties.

For example, to setup Facebook as a provider, first install the [Facebook OAuth2 package](https://github.com/thephpleague/oauth2-facebook), and then add the following to your YAML config:

```
SilverStripe\Core\Injector\Injector:
  Bigfork\SilverStripeOAuth\Client\Factory\ProviderFactory:
    properties:
      providers:
        'Facebook': '%$FacebookProvider'
  FacebookProvider:
    class: 'League\OAuth2\Client\Provider\Facebook'
    constructor:
      Options:
        clientId: '12345678987654321'
        clientSecret: 'geisjgoesingoi3h1521onnro12rin'
        graphApiVersion: 'v2.6'
```

Note that in the above example, the required `redirectUri` constructor argument is missing. This module will automatically update the service configuration to add this argument to all providers, to save having to update the URL when moving between environments/domain names. If the `redirectUri` argument is present, it will not be overridden.

---

Usage
-----

[](#usage)

##### If you’re looking for “Log in with <provider>” functionality, take a look at the add-on for this module: [SilverStripe OAuth Login](https://github.com/bigfork/silverstripe-oauth-login).

[](#if-youre-looking-for-log-in-with-provider-functionality-take-a-look-at-the-add-on-for-this-module-silverstripe-oauth-login)

In order to actually interact with an OAuth token, you’ll need to register a token handler (which implements `Bigfork\SilverStripeOAuth\Client\Handler\TokenHandler`) to do so as part of the callback process. Each handler has an optional numeric priority (to control the order in which they are called), and a “context”. The context option is used to ensure that the handler is only run when certain actions are performed, and matches up to the context parameter specified when issuing a token request (see the [Helper](#helper) section). Handlers registered with a context of `*` will always be called, regardless of the context provided.

Below is an example of a token handler responsible for fetching events from a user’s Facebook profile, and how to register it. We use the context parameter to ensure that the handler is only run when performing this action (we don’t want it to run when the user is logging in, for example).

Here we register our token handler, with a context named `import_events`:

```
Bigfork\SilverStripeOAuth\Client\Control\Controller:
  token_handlers:
    importeventshandler:
      priority: 1
      context: 'import_events'
      class: 'ImportEventsHandler'
```

Next, we need to build an authorisation URL with that context specified:

```
use Bigfork\SilverStripeOAuth\Client\Helper\Helper;

// Build a URL for fetching a Facebook access token with the required 'user_events' permission
// Will return a URL like: http://mysite.com/oauth/authenticate/?provider=Facebook&context=import_events&scope%5B2%5D=user_events
$url = Helper::buildAuthorisationUrl('Facebook', 'import_events', ['user_events']);
echo "Import events from Facebook";
```

When the user returns from Facebook, our token handler will be called as part of the callback process:

```
use Bigfork\SilverStripeOAuth\Client\Handler\TokenHandler;
use League\OAuth2\Client\Provider\Facebook;
use League\OAuth2\Client\Token\AccessToken;

class ImportEventsHandler implements TokenHandler
{
    public function handleToken(AccessToken $token, Facebook $provider)
    {
        $baseUrl = 'https://graph.facebook.com/v2.8';
        $params = http_build_query([
            'fields' => 'id,name,start_time',
            'limit' => '5',
            'access_token' => $token->getToken(),
            'appsecret_proof' => hash_hmac('sha256', $token->getToken(), '{facebook-app-secret}'),
        ]);
        $response = file_get_contents($baseUrl.'/me/events?'.$params);
        $data = json_decode($response, true);

        $this->importEvents($data);
    }
}
```

Throwing an exception from the `handleToken()` method will result in all other handlers being cancelled, the exception message being logged, and a "400 Bad Request" error page being shown to the user. The method can also return an instance of `SS_HTTPResponse` which will be output to the browser after all remaining handlers have been run.

Error handling
--------------

[](#error-handling)

Sometimes, OAuth providers may return errors that have been caused by the user. The most common example of this is when a user rejects granting the permissions you’ve requested. As each provider provides error messages in different ways, you’ll need to build your own error handling logic. Error handlers can be registered similarly to token handlers, for example:

```
Bigfork\SilverStripeOAuth\Client\Control\Controller:
  error_handlers:
    importeventserrorhandler:
      priority: 1
      context: 'import_events'
      class: 'ImportEventsErrorHandler'
```

```
use Exception;
use League\OAuth2\Client\Provider\AbstractProvider;
use SilverStripe\Control\HTTPRequest;
use SilverStripe\Security\Security;

class ImportEventsErrorHandler implements ErrorHandler
{
    public function handleError(AbstractProvider $provider, HTTPRequest $request, Exception $exception)
    {
        if ($request->getVar('error_message')) {
            return Security::permissionFailure(null, $request->getVar('error_message'));
        }
    }
}
```

Error logging
-------------

[](#error-logging)

By default, fatal OAuth errors will be logged to PHP’s error log. You can set up your own logging by overriding the `Psr\Log\LoggerInterface.oauth:` Injector service definition. For example, to log errors to an `oauth.log` file:

```
---
After: silverstripe-oauth-logging
---
SilverStripe\Core\Injector\Injector:
  Psr\Log\LoggerInterface.oauth:
    calls: null # Reset - without this, the below "calls" would be merged in instead of replacing the original
---
After: silverstripe-oauth-logging
---
SilverStripe\Core\Injector\Injector:
  Psr\Log\LoggerInterface.oauth:
    calls:
      pushDisplayErrorHandler: [ pushHandler, [ '%$OAuthLogFileHandler' ] ]
  OAuthLogFileHandler:
    class: Monolog\Handler\StreamHandler
    constructor:
       - '../oauth.log'
       - 'error'
```

SameSite / POST cookies
-----------------------

[](#samesite--post-cookies)

Some providers, like Apple, will redirect back to your site with a POST request. When this happens, the default browser behaviour is not to send cookies with the request, meaning that it’s not possible to verify the request as the user’s session is lost. There are two ways to work around this:

1. Mark your session cookie as `SameSite=None; Secure` as detailed [here](https://docs.silverstripe.org/en/4/developer_guides/cookies_and_sessions/sessions/#samesite-attribute)
2. Set the following YAML value:

```
Bigfork\SilverStripeOAuth\Client\Control\Controller:
  enable_samesite_workaround_redirect: true
```

When this is enabled, your site will handle the POST that it receives from your OAuth provider by redirecting the user via a GET request. When this GET request is issued, the site once again has access to the user’s session cookie so the authorisation process can continue as normal.

###  Health Score

54

—

FairBetter than 97% of packages

Maintenance68

Regular maintenance activity

Popularity39

Limited adoption so far

Community24

Small or concentrated contributor base

Maturity71

Established project with proven stability

 Bus Factor1

Top contributor holds 92.8% 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 ~233 days

Recently: every ~224 days

Total

15

Last Release

138d ago

Major Versions

0.3.0 → 1.0.02017-06-08

1.x-dev → 2.0.02019-02-22

2.x-dev → 3.0.02026-02-06

### Community

Maintainers

![](https://avatars.githubusercontent.com/u/203294386?v=4)[-> lozcalver](/maintainers/kinglozzer)[@kinglozzer](https://github.com/kinglozzer)

![](https://avatars.githubusercontent.com/u/1774129?v=4)[Colin Richardson](/maintainers/feejin)[@feejin](https://github.com/feejin)

---

Top Contributors

[![lozcalver](https://avatars.githubusercontent.com/u/1655548?v=4)](https://github.com/lozcalver "lozcalver (64 commits)")[![aletail](https://avatars.githubusercontent.com/u/3344301?v=4)](https://github.com/aletail "aletail (1 commits)")[![elliot-sawyer](https://avatars.githubusercontent.com/u/354793?v=4)](https://github.com/elliot-sawyer "elliot-sawyer (1 commits)")[![shoosah](https://avatars.githubusercontent.com/u/5318710?v=4)](https://github.com/shoosah "shoosah (1 commits)")[![thats4shaw](https://avatars.githubusercontent.com/u/855269?v=4)](https://github.com/thats4shaw "thats4shaw (1 commits)")[![tractorcow](https://avatars.githubusercontent.com/u/936064?v=4)](https://github.com/tractorcow "tractorcow (1 commits)")

---

Tags

Authenticationsilverstripeoauthoauth2

###  Code Quality

TestsPHPUnit

### Embed Badge

![Health badge](/badges/bigfork-silverstripe-oauth/health.svg)

```
[![Health](https://phpackages.com/badges/bigfork-silverstripe-oauth/health.svg)](https://phpackages.com/packages/bigfork-silverstripe-oauth)
```

###  Alternatives

[league/oauth2-google

Google OAuth 2.0 Client Provider for The PHP League OAuth2-Client

42222.6M157](/packages/league-oauth2-google)[calcinai/oauth2-xero

Xero OAuth 2.0 Client Provider for The PHP League OAuth2-Client

103.3M4](/packages/calcinai-oauth2-xero)[bigfork/silverstripe-oauth-login

SilverStripe logins via OAuth2, using the PHP League's OAuth2 client

1897.4k2](/packages/bigfork-silverstripe-oauth-login)

PHPackages © 2026

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