Panel |
---|
borderColor | #3D3D3D |
---|
bgColor | #F4F4F4 |
---|
titleColor | #3D3D3D |
---|
borderWidth | 0 |
---|
titleBGColor | #3D3D3D |
---|
borderStyle | solid |
---|
|
ON THIS PAGE |
Like many REST frameworks, the The BSN REST API uses a refresh-token system the OAUTH 2.0 framework to handle client authentication. This page describes how to build BSN token authorization for BSN into a client application.
Note |
---|
|
The BSN user model distinguishes between "persons" and "users": - A "person" is tied to a single set of login credentials, but is not exclusively linked to any one network (each network is an independent set of users, files, presentations, etc.).
- A "user" is an instance of a person that is associated with a single network.
This user model allows persons who belong to multiple networks to log in to them using a single set of credentials. |
...
In many cases, it also requires two token-authentication requests, as described below. |
Authentication Workflow
These steps outline how to a client application should carry out authorization with the BSN REST API:
- The client application makes a POST call to the
/Token/token
endpoint. The POST body includes , among other parameters, a a username
and password
pair entered by the user.- If the user entered the network name along with his or her their username and password, the client application includes the network name is included in the
username
(e.g. "username=exampleNetwork/
exampleUser@brightsignexampleUser@brightsign.biz"
). Otherwise, the network will need to be specified in a second POST call (see step 2a below).
- If the credentials are valid, the server returns a code 200 with a response body that includes
access_token
, expires_in
, and refresh_token
values. - The If a network name was not specified in step 1, the response body includes will also include a
networkNames
array that lists networks associated with the specified username
. The client application provides the list of networks to the user and allows him or her to select one. It then makes a second POST to the /token/
endpoint endpoint with network name included in the username
(e.g. "username=exampleNetwork/exampleUser@brightsign.biz"
).
- If less than half of the
expires_in
time has elapsed (in seconds), and the client application has retained the access_token
value in local storage, it includes the access_token
in the "Authorization" header of each request to a BSN endpoint. The value of the "Authorization" header is specified as "Bearer {token_value}".- If more than half of the
expires_in
time has elapsed, or if the access_token
is not located in local storage, the client application makes a POST call to the /token/
endpoint endpoint with the refresh_token
value. - If the
refresh_token
is not located in local storage, or if the expires_in
time has elapsed (indicated by a 401 return from the server), the application indicates to the user that access to the BSN connection has been dropped (without loss of unsaved user data). It then prompts the user to enter access credentials again and returns to step 1 of the authentication process.
Note |
---|
|
The expires_in value may be changed on the server at any time, or it may be randomized on each authentication return. Therefore, the token expiration time should not be hardcoded on the client application; the application should store the expires_in value along with the Access/Refresh token and calculate a new token-refresh interval on every return. |
/token
POST
Posts user credentials or a refresh token to the /token endpoint. If the credentials are valid, the server returns an access/refresh token that is included with all other BSN REST calls for authentication.
Note |
---|
|
Unlike other BSN REST endpoints, the /token endpoint does not accept a trailing slash. |
Request Body
username
: The BSN username. If this is a User Authentication Request, the network name preceeds the username (e.g. "exampleNetwork/exampleUser@brightsign.biz").
password
: The password associated with the username.network
: The network to which the returned token should grant access. This entry can can be used for either the initial User Authentication Request, or to switch to another network that the user belongs to upon token renewal.grant_type
: The type of grant being presented in exchange for the access token. This value must be set to "password"
.client_id
: The client identifier. This value is currently not used by the server.client_secret
: The client secret. This value is currently not used by the server.refresh_token
: The refresh token to include when renewing the access token. When the refresh_token
entry is included, the password
does not need to be used.
Response Body
[string] access_token
: The authorization token to use with endpoint calls until half of the expires_in
time period has elapsed[string] token_type
: The OAuth 2.0 token type, which will always be returned as "bearer"
[integer] expires_in
: The lifetime (in seconds) of the authorization token [string] refresh_token
: The token to use for re-authentication when more than half of the expires_in
time period has elapsed.[string[]]scope
: An array that lists the scope granted by the token. A successful Person Authentication Response will include the "Self"
value only, while a successful User Authentication Response will contain both "Full"
and "Self"
values. [string] userLogin
: The username
included in the request body [integer] userId
: The user identifier, which may be used in subsequent requests. This entry is only returned for User Authentication Requests. [integer] personId
: The person identifier [string[]] networkNames
: An array of networks to which the person (i.e. the account associated with the login credentials) belongs. This entry is only returned for Person Authentication requests.[string] .issued
: The date and time the authorization/refresh token was issued (formatted as "[3-letter weekday], dd mmm yyyy hh:mm:ss [3-letter timezone]"
)[string] .expires
: The date and time the authorization/refresh token expires (formatted as "[3-letter weekday], dd mmm yyyy hh:mm:ss [3-letter timezone]"
)
Examples
Person Authentication Request
The client application makes this authorization request when it does not have the network name. A successful response will include a list of network names.
Code Block |
---|
POST https://api.brightsignnetwork.com/2017/01/REST/token
Host: api.brightsignnetwork.com
Content-Type: application/www-form-urlencoded
Content-Length: 158
Accept: application/xml
grant_type=password&client_id=AuthenticationTest&client_secret=9955ED3C-7F6E-4AF9-BFFE-CD6AAB42347B&username=exampleUser@brightsign.biz&password=admin&scope=self |
Person Authentication Response – Success
Note that the response includes the networkNames
list.
Code Block |
---|
HTTP/1.1 200 OK
Server: nginx/1.8.0
Date: Fri, 03 Feb 2017 23:02:00 GMT
Content-Type: application/json;charset=UTF-8
Content-Length: 688
Connection: keep-alive
Vary: Accept-Encoding
Cache-Control: no-cache
Pragma: no-cache
Expires: -1
Access-Control-Allow-Origin: *
{
"access_token":"N8VVpu1fefCtgKjxmD79pvmVMh5yB69xROUlGUJQLhDDpIN_k_qs3AuW5NvG22SWCBL-cPGuWeGUKDW-e0RUbyavL6I",
"token_type":"bearer",
"expires_in":899,
"refresh_token":"ee6c055a441047e99e5e2c3dde63fa4c",
"scope":"Self",
"userLogin":"exampleUser@brightsign.biz",
"personId":13898,
"networkNames":"AuthenticationTest1,AuthenticationTest2,AuthenticationTest3",
".issued":"Fri, 03 Feb 2017 23:02:00 GMT",
".expires":"Fri, 03 Feb 2017 23:17:00 GMT"
} |
Person Authentication Response – Failure, Invalid Credentials
Code Block |
---|
HTTP/1.1 400 Bad Request
Server: nginx/1.8.0
Date: Fri, 03 Feb 2017 23:16:17 GMT
Content-Type: application/json;charset=UTF-8
Content-Length: 95
Connection: keep-alive
Cache-Control: no-cache
Pragma: no-cache
Expires: -1
Access-Control-Allow-Origin: *
{
"error":"invalid_grant",
"error_description":"The specified User ID or Password is incorrect."
} |
User Authentication Request
The client application makes this authorization request when it has the network name, which can be retrieved either from user entry or from a Person Authentication Request. Note that the response body includes the roleName
parameter, which allows the client application to determine the permissions scope and available functionality for the user.
Code Block |
---|
POST https://api.brightsignnetwork.com/2017/01/REST/token
Host: api.brightsignnetwork.com
Content-Type: application/www-form-urlencoded
Content-Length: 178
Accept: application/xml
grant_type=password&client_id=AuthenticationTest&client_secret=9955ED3C-7F6E-4AF9-BFFE-CD6AAB42347B&username=AuthenticationTest1/exampleUser@brightsign.biz&password=admin&scope=full |
User Authentication Response – Success
Code Block |
---|
HTTP/1.1 200 OK
Server: nginx/1.8.0
Date: Fri, 03 Feb 2017 23:37:26 GMT
Content-Type: application/json;charset=UTF-8
Content-Length: 823
Connection: keep-alive
Vary: Accept-Encoding
Cache-Control: no-cache
Pragma: no-cache
Expires: -1
Access-Control-Allow-Origin: *
{
"access_token":"N8VVpu1fefCtgKjxmD79pvmVMh5yB69xROUlGUJQLhDDpIN_k_qs3AuW5NvG22SWCBL-cPGuWeGUKDW-e0RUbyavL6I",
"token_type":"bearer",
"expires_in":899,
"refresh_token":"375671af51fa44fabb5b4a353d4f8488",
"scope":"Full,Self",
"networkName":"AuthenticationTest1",
"userLogin":"exampleUser@brightsign.biz",
"userId":18537,
"personId":13898,
"roleName":"Administrators",
".issued":"Fri, 03 Feb 2017 23:37:26 GMT",
".expires":"Fri, 03 Feb 2017 23:52:26 GMT"
} |
User Authentication Response – Failure, Invalid Credentials
Code Block |
---|
HTTP/1.1 400 Bad Request
Server: nginx/1.8.0
Date: Fri, 03 Feb 2017 23:33:03 GMT
Content-Type: application/json;charset=UTF-8
Content-Length: 95
Connection: keep-alive
Cache-Control: no-cache
Pragma: no-cache
Expires: -1
Access-Control-Allow-Origin: *
{
"error":"invalid_grant"
,"error_description":"The specified User ID or Password is incorrect."
} |
Renew Access Token Request
Code Block |
---|
POST https://api.brightsignnetwork.com/2017/01/REST/token
Host: api.brightsignnetwork.com
Content-Type: application/www-form-urlencoded
Content-Length: 151
Accept: application/xml
grant_type=refresh_token&client_id=AuthenticationTest&client_secret=9955ED3C-7F6E-4AF9-BFFE-CD6AAB42347B&refresh_token=375671af51fa44fabb5b4a353d4f8488 |
Renew Access Token Response – Success
Code Block |
---|
HTTP/1.1 200 OK
Server: nginx/1.8.0
Date: Fri, 03 Feb 2017 23:50:26 GMT
Content-Type: application/json;charset=UTF-8
Content-Length: 823
Connection: keep-alive
Vary: Accept-Encoding
Cache-Control: no-cache
Pragma: no-cache
Expires: -1
Access-Control-Allow-Origin: *
{"access_token":"N8VVpu1fefCtgKjxmD79pvmVMh5yB69xROUlGUJQLhDDpIN_k_qs3AuW5NvG22SWCBL-cPGuWeGUKDW-e0RUbyavL6I",
"token_type":"bearer",
"expires_in":899,
"refresh_token":"375671af51fa44fabb5b4a353d4f8488",
"scope":"Full,Self",
"networkName":"AuthenticationTest1",
"userLogin":"exampleUser@brightsign.biz",
"userId":18537,
"personId":13898,
"roleName":"Administrators",
".expires":"Sat, 04 Feb 2017 00:05:26 GMT",
".issued":"Fri, 03 Feb 2017 23:50:26 GMT"
} |
Renew Access Token Response – Failure, Invalid Refresh Token
Code Block |
---|
HTTP/1.1 400 Bad Request
Server: nginx/1.8.0
Date: Fri, 03 Feb 2017 23:55:43 GMT
Content-Type: application/json;charset=UTF-8
Content-Length: 87
Connection: keep-alive
Cache-Control: no-cache
Pragma: no-cache
Expires: -1
Access-Control-Allow-Origin: *
{
"error":"invalid_grant",
"error_description":"The specified Refresh Token is invalid."
} |
Example API Call with Authorization
The access token is included in the "Authorization" header of each API request. The token value is prefixed with the "Bearer" specification.
Code Block |
---|
GET https://api.brightsignnetwork.com/2017/01/REST/Devices/ HTTP/1.1
Accept-Encoding: gzip,deflate
Origin: https://localhost/
Authorization: Bearer 79ADEgjjEOpSOsgQ1kpqYL0O3R8vnh27q22ltp7hyTgTQPWxdjrHD
Host: api.brightsignnetwork.com
Connection: Keep-Alive
User-Agent: Apache-HttpClient/4.1.1 (java 1.5) |