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

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

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

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

3.0.0(3mo ago)1794.7k↓42.3%21[2 issues](https://github.com/bigfork/silverstripe-oauth-login/issues)2BSD-3-ClausePHPCI failing

Since Mar 1Pushed 1mo ago6 watchersCompare

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

READMEChangelogDependencies (4)Versions (19)Used By (2)

SilverStripe OAuth Login
========================

[](#silverstripe-oauth-login)

SilverStripe OAuth2-based login functionality, based on the PHP League's [OAuth2 client](http://oauth2-client.thephpleague.com/) and the [SilverStripe OAuth module](https://github.com/bigfork/silverstripe-oauth).

### What this module does

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

This module adds “Log in with <provider>” buttons to SilverStripe’s default login form, which will authenticate a user with the chosen provider. It also provides configurable access token scopes (or permission levels) and field mapping for storing user data on registration.

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

[](#installation)

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

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

[](#configuration)

**NOTE:** You must first configure your OAuth providers using the configuration options detailed in the [SilverStripe OAuth2 module documentation](https://github.com/bigfork/silverstripe-oauth#configuration).

To show a login button for a configured provider, you must add them to the new `Authenticator` class’ YAML configuration. The configuration has two options avaiable: `name` (shown on the “Login as X” button, how this is configured may change in future releases) and `scopes` (the desired scopes/permission levels for the access token).

Following on from the Facebook example in the [SilverStripe OAuth2 module documentation](https://github.com/bigfork/silverstripe-oauth#configuration):

```
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: 'v6.0'
Bigfork\SilverStripeOAuth\Client\Authenticator\Authenticator:
  providers:
    'Facebook': # Matches the key for '$%FacebookProvider' above
      name: 'The Facebooks'
      scopes: ['email', 'public_profile']
```

Customisation
-------------

[](#customisation)

You can customise the look of the login actions for each provider by creating the relevant template, following the naming convention `FormAction_OAuth_`. For example:

```

    Connect with Facebook

```

The `Bigfork\SilverStripeOAuth\Client\Form\LoginForm` class also provides two extension points, `updateFields` and `updateActions` for further customisation.

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

[](#error-handling)

When a provider returns successfully, but returns an error state (for example, when a user chooses to reject the permissions you’re asking for), this module will attempt to return the user to the login screen and display a human-readable error message. As each provider returns error messages in different formats, you may need to add your own error handler in the event that the default handler is unable to show a suitable message. For example:

```
Bigfork\SilverStripeOAuth\Client\Control\Controller:
  error_handlers:
    loginerrorhandler:
      priority: 10
      context: login
      class: 'MyLoginErrorHandler'
```

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

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

---

Concepts
--------

[](#concepts)

### Passports

[](#passports)

Each member that authenticates via an OAuth provider is assigned a “Passport” - a record which is unique to each OAuth account owner. This allows one SilverStripe account to be linked to multiple OAuth providers, or even linked to multiple individual accounts on the same provider. While both of those are possible, neither is the default behaviour for this module: by default, each new OAuth account will create a new SilverStripe member record. See the [multiple providers/accounts](#multiple-providers-accounts) and [email collisions](#email-collisions) sections for more information.

### Mappers

[](#mappers)

When the user registers for the first time with a provider, they will not yet have an associated `Member` record in the SilverStripe database. To create that record, this module attempts to copy information from the resource owner returned by the provider.

The default behaviour is to attempt to copy email, first name and surname, though this behaviour can be altered in one of two ways:

#### Using `GenericMemberMapper`

[](#using-genericmembermapper)

The default mapper (`Bigfork\SilverStripeOAuth\Client\Mapper\GenericMemberMapper`) will attempt to copy fields from a mapping array that can be configured in YAML, for example:

```
Bigfork\SilverStripeOAuth\Client\Mapper\GenericMemberMapper:
  mapping:
    'Facebook':
      'Town': 'Hometown' # Town is the SilverStripe db column, 'Hometown' is in the data returned by Facebook
      'Gender': 'Gender'
```

#### Using a custom mapper

[](#using-a-custom-mapper)

If more detailed or complex mapping is needed, you can create your own mapper class to handle it. Just implement `Bigfork\SilverStripeOAuth\Client\Mapper\MemberMapperInterface`, set up your mapping logic, and then register your new mapper in YAML:

```
Bigfork\SilverStripeOAuth\Client\Factory\MemberMapperFactory:
  mappers:
    'Facebook': 'Mysite\MyFacebookMapperClass'
```

### Multiple providers/accounts

[](#multiple-providersaccounts)

The default behaviour for this module is to treat each OAuth account as a separate SilverStripe account. This is because every website will have bespoke requirements on how multiple accounts should be treated, for example:

- If I sign up with Facebook, and then want to also link my Twitter account - which account’s information (i.e. name, email address) should take priority?
- If I want to link my Twitter account to SilverStripe account A, but it already belongs to SilverStripe account B because I already signed up with it, what happens? Should this be disallowed, or should account B be deleted?
- What if I’m a very awkward person and have two Facebook accounts that I want linked to the same SilverStripe account?

It is up to you if, or how, to handle scenarios like this. The typical solution would be to add buttons for “Link X Account” that are shown to users in their account once they’ve authenticated initially.

### Email collisions

[](#email-collisions)

As it’s possible, and likely, for users to have accounts for multiple OAuth providers that each have the same email address, you may encounter an error similar to *“Can't overwrite existing member #123 with identical identifier (Email = )”*. This is because the default behaviour for SilverStripe is to ensure that every member record has a unique email address. There are a few different ways to work around this:

- Change the `Member.unique_identifier_field` config setting to something other than `Email` (for example, `ID`)
- Update the config for [`GenericMemberMapper`](#using-genericmembermapper) for your providers, but omit the `Email` field
- Create a [custom mapper](#using-a-custom-mapper) that doesn’t import email addresses

### Replacing the default authenticator

[](#replacing-the-default-authenticator)

If you’d like to replace the default authenticator, or change the internal name of the oauth authenticator, you will need to reset the list of authenticators first. You can achieve this with the following approach:

```
---
Name: app-auth-reset
After:
  - '#oauthauthenticator'
---
SilverStripe\Core\Injector\Injector:
  SilverStripe\Security\Security:
    properties:
      Authenticators: null
---
Name: app-auth
After:
  - '#app-auth-reset'
---
SilverStripe\Core\Injector\Injector:
  SilverStripe\Security\Security:
    properties:
      Authenticators:
        myoauthname: '%$Bigfork\SilverStripeOAuth\Client\Authenticator\Authenticator'
```

###  Health Score

59

—

FairBetter than 99% of packages

Maintenance84

Actively maintained with recent releases

Popularity42

Moderate usage in the ecosystem

Community27

Small or concentrated contributor base

Maturity72

Established project with proven stability

 Bus Factor1

Top contributor holds 84.3% 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 ~192 days

Recently: every ~288 days

Total

18

Last Release

101d ago

Major Versions

0.3.0 → 1.0.02017-06-08

1.0.2 → 2.0.02019-01-28

1.x-dev → 2.1.02019-10-04

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 (75 commits)")[![mattclegg](https://avatars.githubusercontent.com/u/303487?v=4)](https://github.com/mattclegg "mattclegg (4 commits)")[![thats4shaw](https://avatars.githubusercontent.com/u/855269?v=4)](https://github.com/thats4shaw "thats4shaw (2 commits)")[![gurucomkz](https://avatars.githubusercontent.com/u/12028675?v=4)](https://github.com/gurucomkz "gurucomkz (2 commits)")[![tractorcow](https://avatars.githubusercontent.com/u/936064?v=4)](https://github.com/tractorcow "tractorcow (2 commits)")[![wernerkrauss](https://avatars.githubusercontent.com/u/1043925?v=4)](https://github.com/wernerkrauss "wernerkrauss (1 commits)")[![elliot-sawyer](https://avatars.githubusercontent.com/u/354793?v=4)](https://github.com/elliot-sawyer "elliot-sawyer (1 commits)")[![tiller1010](https://avatars.githubusercontent.com/u/42498429?v=4)](https://github.com/tiller1010 "tiller1010 (1 commits)")[![BLMaciej](https://avatars.githubusercontent.com/u/21364275?v=4)](https://github.com/BLMaciej "BLMaciej (1 commits)")

---

Tags

silverstripeoauthoauth2login

###  Code Quality

TestsPHPUnit

### Embed Badge

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

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

###  Alternatives

[axyr/silverstripe-adminlogin

Use a custom login screen to log in to the admin section

165.8k](/packages/axyr-silverstripe-adminlogin)

PHPackages © 2026

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