1-Authentication

Component 1: Authentication

XPress Roster uses OAuth 2.0 for ease of use and the ability to integrate with many user-provisioning systems. While the necessary technical interactions are demonstrated here, the A4L Community highly recommends using Client and/or Server packages based on your development environment to simplify your use of OAuth 2.0.

Getting a Token

In order to ensure interoperability and fit with the user stories we seek to support, xPress Roster solutions must support the creation of tokens through Password Grant. Tokens allow applications to submit credentials for synchronizing data. Tokens require a responsible user’s permission, which gives them the ability to give the indicated user one or more shortcuts to the requested data.

Tokens are similar to barcodes. When you look at a barcode, it’s not understandable, but when you have the right access and format, you can read it. A token requires two things: a key and a format. The key is what is passed first when you authenticate. This authentication is passed in HTTP calls using the sample formats below and a call to the REST interface.

Example Submission of Credentials

POST /token HTTP/1.1
Host: server.example.com
Content-Type: application/x-www-form-urlencoded
 
grant_type=password
&username=jsmith
&password=awesome
&client_id=s6BhdRkqt3
&client_secret=7Fjfp0ZBr1KtDRbnfVdmIw

The results of that call are similarly returned for processing as HTTP strings.

Below is an example of the JSON string returned. You should use OAuth libraries as you need for the systems you are building.

Example Return

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Cache-Control: no-store
Pragma: no-cache
 
{
  "access_token":"2YotnFZFEjr1zCsicMWpAA",
  "token_type":"bearer",
  "expires_in":3600,
  "refresh_token":"tGzv3JOkF0XG5Qx2TlKWIA",
  "example_parameter":"example_value"
}

Using the Token

When authentication is successful, and you have obtained your OAuth 2.0 token you may use it with SIF 3 in either of the standard ways: Bearer token in the HTTP Authorization header or access_token Query Parameter in your request. When servicing a request, it does not matter how your software received the access token, it is up to the software handling the request to verify the tokens validity and access level.

Example Header

Authorization : bearer 2YotnFZFEjr1zCsicMWpAA

Example Query Parameter

?access_token=2YotnFZFEjr1zCsicMWpAA

Other Information

Along with the OAuth response there may be one or more UUIDs returned that relate to the account being used. These take the form of <object name> + RefId and can be used to greatly reduce the number of interactions required to make requests. While this may be useful in some data synchronization scenarios we will take a deeper look at this in our mobile application user story.

Example Snippet from Response

  "xStaffRefId":"366F-4E03-8598-00424085D17A"

Component 2: Infrastructure–>