Download the PHP package bigfork/silverstripe-oauth-login without Composer
On this page you can find all versions of the php package bigfork/silverstripe-oauth-login. It is possible to download/install these versions without Composer. Possible dependencies are resolved automatically.
Download bigfork/silverstripe-oauth-login
More information about bigfork/silverstripe-oauth-login
Files in bigfork/silverstripe-oauth-login
Package silverstripe-oauth-login
Short Description SilverStripe logins via OAuth2, using the PHP League's OAuth2 client
License BSD-3-Clause
Informations about the package silverstripe-oauth-login
SilverStripe OAuth Login
SilverStripe OAuth2-based login functionality, based on the PHP League's OAuth2 client and the SilverStripe OAuth module.
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
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
NOTE: You must first configure your OAuth providers using the configuration options detailed in the SilverStripe OAuth2 module documentation.
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:
Customisation
You can customise the look of the login actions for each provider by creating the relevant template, following the naming convention FormAction_OAuth_<ProviderName>
. For example:
The Bigfork\SilverStripeOAuth\Client\Form\LoginForm
class also provides two extension points, updateFields
and updateActions
for further customisation.
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:
Concepts
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 email collisions sections for more information.
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
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:
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:
Multiple providers/accounts
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
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 = [email protected])”. 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 thanEmail
(for example,ID
) - Update the config for
GenericMemberMapper
for your providers, but omit theEmail
field - Create a custom mapper that doesn’t import email addresses
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: