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
Provider location where the user will be redirected after clicking LOGIN button/icon in our system
Access Token URL
Location required to gain access to access token used to safely exchange data between the provider and our system
User Details URL
Link used to gather information about the currently logged in user
Client unique identifier given by your provider
Secret key given by your provider (should not be published to anyone)
Defines the information that needs to be requested from the user during the authorization process
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
Token Issuer ID
Issuer who provided a token so that it can be validated by our application
Token Keys URL
URL from where keys should be fetched to decrypt information stored in the token
User Details URL
If this is not provided then, where available, the information will be taken from the token id
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:
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
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
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 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:
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
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.
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.