Payroll Integration
  • Introduction
  • Authentication
    • Testing the Client Id & Secret
    • Retrieving a Refresh and Access Token
    • Switching Users
  • Available APIs
    • Payroll API V1.0 Methods
    • Postman Import
  • Integrating Timesheet Applications
    • Login Management
    • Select an Employer
    • Mapping Hourly Rates and Employees
    • Storing the mapping for future use
    • Creating Hourly Payments in BrightPay
    • End 0f Financial Year Behaviour
  • Payroll Scenario Simulation
    • Payroll Simulation Request Headers
    • Payroll Simulation Scenarios
  • Configuring BrightPay for Testing
    • Setting up an Organisation and Employer
    • Setting up Employees
    • Setting up a Payment Schedule
    • Configuration Summary
  • Managing Errors
    • Error Responses
    • Error Code Definitions
  • Secure Design Requirements
Powered by GitBook
On this page
  1. Authentication

Switching Users

PreviousRetrieving a Refresh and Access TokenNextAvailable APIs

Last updated 7 months ago

Users may have more than one BrightID (e.g. have multiple usernames, emails & passwords registered with the Bright Identity Provider). For example, a user may work for a bureau and complete payroll for multiple customers. Therefore, they may end up moving Timesheet data into BrightPay for more than one customer. Or a user may complete the accounts for one customer and payroll for a different customer. The user may use different BrightIDs for each customer for security.

In order to get an Access Token to integrate with the BrightPay API your application must provide a URL that links to the Bright Identity Provider. On clicking the link the user's browser will be navigated to the Bright Identity Provider. The Bright Identity Provider may challenge for the user's credentials or may automatically log the user in. Once the user is authenticated (with the Bright Identity Provider) the process then redirects the browser back to your website, and your application can extract the Authorization Code and use it to get an Access Token.

Note during this process the user may be automatically logged in by the Bright Identity Provider (if they have authenticated with it recently). There is also an option on the Bright Identity Provider Login screen called “remember me”, which will again encourage the Bright Identity Provider to automatically log the user in.

If the user is automatically logged in by the Bright Identity Provider then, if the user has more than one BrightID, they may not know which account they have been logged in as. This is obviously confusing for users, as they may assume they are logged in under a particular account but then start seeing data being retrieved that is connected to a different account.

The user can fix this themselves by navigating their browser to the Bright Identity Provider Logout URL to manually log out. However, this is a poor user experience as it is confusing and frustrating. This is a common problem when integrating with OAuth 2 and so it is likely to be an issue when integrating your application with Bright products.

A better design is to, after the user is authenticated, display the name/email of the user who is currently logged in (this can be retrieved from the end point api/v1/Payroll/GetCurrentUserSummary). The user can then easily see which account is logged in. Then, in case the wrong user account is logged in, provide a "Switch User" button to allow users to switch the Bright ID that is logged in (and that tokens are being issued on behalf off).

The "Switch User" button should contain a hyperlink pointing at a URL similar to below:

https://login.brightsg.com/login.brightsg.com/B2C_1A_BPOL_SIGNIN_PROD/oauth2/logout?post_logout_redirect_uri=https://yourdomain/BrightAuthenticationBounce

The fragment https://login.brightsg.com/login.brightsg.com/B2C_1A_BPOL_SIGNIN_PROD/oauth2/logout? will log the user out of the Bright Identity Provider. Then the fragment post_logout_redirect_uri=https://yourdomain/BrightAuthenticationBounce will redirect the user’s browser (after the logout at Bright Identity Provider) back to an endpoint on your site. The endpoint on your site should then automatically redirect the user’s browser to the end point generated at.

This will mean that when the user clicks the “Switch User” button, the browser will redirect across a few webpages but will end up at the Login screen at the Bright Identity Provider. The user will then be challenged for credentials.

Initial Login Url