OAuth Authentication*

Requirements

  • You have your own OAuth server set up
  • The domain the OAuth server authenticates the user onto is the same domain on which BidJS is located
  • The auth token is published either as a cookie or localStorage item
  • If using a cookie, the cookie domain and path should allow access on the domain on which BidJS is located
  • You expose an endpoint on your OAuth server to return a user based on token (commonly referred to as a /userendpoint)

Setup

  1. Contact support@bidlogix.net, supplying us with your above-mentioned user endpoint for your OAuth server, we will then update this on your account
  2. Ensure your BidJS implementation has the required OAuth Options, as seen within the Javascript Options section
  3. Your BidJS application should then no longer use the traditional login modal with your OAuth login page


SSO Overview

The sections below describe the authentication flow used when a BidJS customer has their own OAuth 2.0 based server to provide authentication.

In the diagrams, below:

  • JS Client refers to the browser when on a page running the JavaScript code provided by Bidlogix
  • BidJS API refers to the server where the BidJS API is hosted
  • Auth Server refers to the customer OAuth 2.0 server
  • OAuth Token refers to the token generated by the Auth Server
  • BidJS Token refers to the token generated by the JS Client for its own internal authentication

PreAuthenticated:

This scenario is common when a user has already authenticated before visiting a page with the JS Client embedded.
It requires the authentication token be available in a predefined location.

The diagram below shows the following steps:

  1. On initialisation of the JS Client, the configuration will be read, including any OAuth related configuration. This configuration will contain the name of the OAuth Token, and its location i.e. local storage or cookie.
  2. The JS Client retrieves the OAuth Token from the predefined location as per the configuration.
  3. If the OAuth Token doesn't exist, the user is treated as unauthenticated, otherwise it is then exchanged for a BidJS Token
    1. The BidJS API will call the User Info endpoint on the Auth Server, passing the OAuth Token in an Authorization header.
    2. Upon receipt of a valid user response from the User Info endpoint, the BidJS API uses the user model to fetch the corresponding BidJS user (if a BidJS user does not exist the information received from the end point is used to create a new one).
    3. The BidJS API then generates a BidJS Token and returns it to the JS Client.
  4. Subsequent requests for protected resources on the BidJS API have this BidJS Token in a header, which allows the server to identify the user.
    Before each request, BidJS will check that the OAuth Token used to authenticate with still exists, and has not changed. If this has changed, the authentication procedure will begin once more.



UnAuthenticated with Protected Actions:

This scenario is common when a user attempts to perform an action on the JS Client which requires authentication, but they have not yet logged in.
Once we have the token, the flow resumes from step 3 in the previous scenario.

The diagram below shows the following steps:

  1. The initial request to login from the JS Client causes the user to be directed to the Login URL specified in the JS Client configuration. The user is redirected to the Auth Server. For example, using Google as the Auth Server:
    https://accounts.google.com/o/oauth2/v2/auth?redirect_uri=<redirect uri>&prompt=consent&response_type=code&client_id=<client id>&scope=email+profile&state=<referer page>
  2. The Auth Server either:
    1. Renders a login form if the user is not authenticated
    2. Detects a valid token as a header in the request, and is treated as logged in
  3. After successful login redirects the user back to the 'redirect_uri' (the page the user was previously on), ensuring that the OAuth Token is placed into the predefined location.
  4. The JS Client then begins the "PreAuthenticated" flow above.




Logout

For every request made to the BidJS API, a check will be made to see if the original OAuth Token still exists in the predefined location.

If the OAuth Token does not exist, we will assume that the user has logged out of the parent site, and so will be logged out of the JS Client.

If the OAuth Token exists, but has changed, the JS Client will reauthenticate the user with the new OAuth Token.


Json Response Requirements:

Our Oauth implementation has a limitation in terms of the JSON we can consume from your user endpoint. This means we need your JSON response to include the specific fields listed below:

  • Required Fields: Email address, Forename, Surname, Address Line 1, City, Postcode, Country, Tel (Daytime)
  • Additional, Optional Fields: username, externalRef, Company Name, Address Line 2, County

Important:

As long as your SSO user is created on the bidlogix/BidJS side with the above, Required Fields, your users will not be sent to My Settings. If any of the Required Fields are missing (other than email address, which is always required) then the user will be prompted to complete the data within My Settings upon logging in for the first time.

Example of JSON with all fields:

{  "Email address": "johndoe@domain.co.uk",  "Forename": "John",  "Surname": "Doe",  "Company Name": "Company",  "Address Line 1": "House Number",  "Address Line 2": "Street",  "City": "City",  "County": "County",  "Postcode": "XXYY11",  "Country": "Country",  "Tel (Daytime)": "000000000",  "username": "testUsername",  "externalRef": "testRef"}