Single sign on is used to give users an ability to use one login credential to access multiple applications. For example you can login securely in to the BookingLive System by using your Google account.


Setting up an OAuth Provider


Currently there are 4 types of providers supported:


  • OAuth2 - generic OAuth/OAuth2 provider 

  • OpenID Connect - OpenID on top of OAuth2

  • Facebook - facebook open graph provider

  • Microsoft Azure Generic - Microsoft Azure Active Directory plus B2C


Please note that the Facebook provider is specifically used for Facebook single sign on and Azure while based on OpenID Connect should be used only for Microsoft Active Directory services. OAuth2 and OpenID Connect are generic providers that can be setup with almost all providers like Google.


You should get all the configuration information from the specific provider that you are setting up. Here is brief description of each of the settings that are required:


OAuth2 or OpenID Connect


Name

Required/Optional

Description

Authorization URL

Required

Provider location where the user will be redirected after clicking LOGIN button/icon in our system

Access Token URL

Required

Location required to gain access to access token used to safely exchange data between the provider and our system

User Details URL

Required

Link used to gather information about the currently logged in user

Client ID

Required

Client unique identifier given by your provider

Client Secret

Required

Secret key given by your provider (should not be published to anyone)

Scope

Required

Defines the information that needs to be requested from the user during the authorization process 

Redirect URI

Leave blank

In most cases you should not change this URL and keep it empty, but it might be required to whitelist this URL for security reasons in your provider configuration to validate if it is safe for them to send sensitive information to our server



OpenID Connect specific settings


Name

Required/Optional

Description

Token Issuer ID

Required

Issuer who provided a token so that it can be validated by our application

Token Keys URL

Required

URL from where keys should be fetched to decrypt information stored in the token

User Details URL

Optional

If this is not provided then, where available, the information will be taken from the token id



Discovery document

OpenID defines a discovery document that can be used to fetch to all the configuration which simplifies the whole configuration. 


Please note that our current implementation only fetches the discovery document at the time of configuring the provider, so if the provider changes the details inside the discovery document, provider settings in the BookingLive system needs to be reconfigured.

OpenID Connect automatically includes openid scope.



Configuring Member Fields Mapping


Member field mapping is used to map provider specific user details with the ones available in the BookingLive system that are gathered during the sign in process.


Local fields refer to field in the BookingLive system and they are already predefined.

Provider fields are ones coming from the provider and they are represented as simple text representation.


Supported Local fields:

  • FirstName

  • Surname

  • Email

  • Locale

  • HouseNumber

  • Street

  • County

  • Town

  • PostCode

  • Country

  • SocialTitle

  • Gender

  • Dob

  • Telephone

  • MobileTelephone

  • TelephoneOther

  • OrganisationName

  • JobTitle

  • Nationality

  • EthnicOrigin

  • EthnicOriginOther

  • Nationality


Example of correct Member Field Map for one field:


  • Local Field: FirstName; Provider Field: given_name

  • Local Field: Surname; Provider Field: family_name


Additionally Provider field support array/list values. What that means is that if the provider sends multiple values in one field instead of just one you can map it to specific item in the list. 


List format: field[index]

Please note that the first element in list is always 0


Giving an example, Microsoft Azure Active Directory B2C sends “emails” and because our system requires a single email we have to map it to specific item from the list that was sent to the system. 


Using our format to map this field we would have to define it in the following way:


  • Local Field: Email; Provider Field: emails[0] 


This will map first element inside emails to the Email field in our system


Please refer to specific provider documentation for possible fields/claims.



Sign in process and OAuth Passport


Passport


OAuth Passport is a unique identifier for a user given by the configured provider during sign in process. We use this identifier to match it with Member records in our system. Please have in mind that one Member might have more than one Passport.


Token Handlers


Token handlers controls what happens after the token has been exchanged successfully with the provider.

Currently only "login" type token handlers are supported and they are responsible for retrieving member details, updating and eventually loging in using the Passport.


There are three variants of login handlers in the system that manage member details in a slightly different manner:


  • Bigfork\SilverStripeOAuth\Client\Handler\LoginTokenHandler

    • Our SSO integration checks the system for an existing Passport that was sent by the provider.

    • If it already exists in our system that means that that Member with that Passport has been already logged in into BookingLive system in the past and we can log them in directly, or

    • If the Passport does not exists then we will create a Member, map the user details given by the provider and link that Passport with newly created Member


  • LoginTokenHandler

    • Same as the previous above one, but additionally as our system use Email to uniquely identify a member and assuming that Email field has been mapped and a Member with that Email has been already found in our system we will just link that Member to the Passport and log them in without updating/overwriting their details.

    

  • AutoSyncLoginTokenHandler

    • Same as the previous provider but the Member details get updated on every login regardless if user is new or already existing in the system

    


Note: If none of the token handlers are specified by default "LoginTokenHandler" is being used


Microsoft Azure Active Directory [WIP]


Microsoft Azure Generic provider is based on OpenID Connect, but the important addition to it is the fact that it supports a password reset B2C custom policy. 

Microsoft Azure Password Reset is used with conjunction with Microsoft Azure Generic provider and cannot work as a standalone SSO provider.

It handles user request for a password reset on the custom policy provider page. 


Microsoft Azure to support B2C custom policies requires the client application to handle that custom request by again executing the authentication again using a configured custom policy.



System configuration


To configure the SSO option of your choice, you must have an admin account for your site as you will need to input data onto our system.


Once logged into your site visit https://{yourdomain}/admin/addons/ - or navigate to the page by Settings > Add-Ons > Oauth Providers 



Once here, please use the drop down to select your provider and Add that to the list


You should now be presented with a list of fields where you will need to fetch and inupt the relevant columns. The best method here is to create a fetch document from the portal you are using and import that to our system to fill all fields out automatically.


Field Mapping & Token Handlers

Once you have input all details on the previous page, please hit SAVE. You will then be presented with additional tabs at the top. You will need to move onto the next tab Member Mapping Fields - please map any fields across as nessesary. Guide above and the same