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

OpenID Connect specific settings

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