Authenticating Users

PerformanceBridge provides a Single Sign On system across applications. It also provides both authentication and role based authorization. Authentication is entirely controlled by platform customers and PB integrates with those systems (e.g. ActiveDirectory). Role based authorization is determined within PerformanceBridge. Employee records are mapped to a lexicon of clinical roles that are common to all customers. These are combined within the API to provide a simplified scheme for single sign on.

Warning - To utilize these endpoints your application must be deployed within the same cookie domain as PerformanceBridge. For PerformanceBridge applications this is handled by the PerformanceBridge infrastructure. However, for those hosting their own applications this will likely require communication with the PerformanceBridge team.

The flow of calls required for authentication is represented in the sequence diagram below.

Documenting the sequence diagram markup (www.websequencediagrams.com): App->PerformanceBridge: /user/cookie_name PerformanceBridge->App: {"cookie_name": "exampleCookie"} App<->Browser: read cookie "exampleCookie" App->PerformanceBridge: /user/validate_and_authorize PerformanceBridge->App: {... "authenticate": false, "redirect": "https://pb.sso.com"} App->Browser: redirect: "https://pb.sso.com" Browser->PerformanceBridge: enter login credentials PerformanceBridge->Browser: success, redirect: original app url App->PerformanceBridge: /user/cookie_name App<->Browser: read cookie "exampleCookie" App->PerformanceBridge: /user/validate_and_authorize PerformanceBridge->App: {"authenticate": true, "authorize": true, employee_id: 5} App->Browser: deliver content

auth flow sequence diagram

The first step in using the authentication/authorization endpoints is getting the cookie where the auth token is stored. The cookie name is set by the API and can be retrieved via the /user/cookie_name endpoint. Once you have the cookie name you will use it to get the cookie value. Doing this is different for every language and web framework.

With the cookie's value in hand (even if it's null) you can then validate the cookie against the /user/validate_token or /user/validate_and_authorize endpoints. We'll use validate_and_authorize in order to check for both a valid token and valid clinical roles in one request.

Note - The value of the cookie is encrypted by PerformanceBridge. Both the key and initialization vector for the encryption is unique per customer. As such the information contained therein is only accessible via API calls that use the backchannel authentication scheme.

When a user is not authenticated or authorized the /user/validate_and_authorize endpoint still returns 200. The HTTP codes like 401 unauthorized are reserved for the application level authentication. To determine if a user is authenticated and/or authorized you will need to look at the response body.

Example of a user with both access and rights

{
  "authenticate": true,
  "authorize": true,
  "username": "attendingbob1",
  "employee_id": 1
}

Example of a user that does not have access (potentially not logged in yet)

{
  "authenticate": false,
  "redirect": "https://sso.login.example.com"
}

You will need to check both the "authenticate" and "authorize" keys to confirm the status of the user. If both values are true the user has access and rights. If the "authenticate" is false then you should redirect to the location specified by "redirect" key.

If the user is authenticated ("authenticate" == true) but not authorized ("authorize" == false) then you should respond with an unauthorized notification to the user. This response is up to the applications to provide.

If the user is both authenticated and authorized you should proceed to render the response to their request.

Authorization

Authorization is determined by a mapping of employees to clinical roles. The object specified can be as simple as a list of roles that are authorized or a combination of boolean logic. The simple list is an implied or but you can create nested structures to account for "meta" clinical roles such as "supervisor". Below is an example of a more complex roles structure. For more information about the schema see the endpoint documentation.

{
  "or": [
    {"and", ["attending","radiologist"]},
    {"and", ["supervisor","nurse"]}
  ]
}