BSN.cloud Authentication

Owned by BrightSign TechDocs
Last updated: May 02, 2022
5 min read

ON THIS PAGE

The BSN.cloud REST API uses the OAUTH 2.0 framework to handle client authentication. This page describes how to build BSN.cloud token authorization into a client application.

Note

The BSN.cloud 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 Endpoint

Authentication calls are carried out on the /REST/Token endpoint: https://api.bsn.cloud/2019/03/REST/token

The token received from this call can be used with the BSN.cloud, B-Deploy, and Remote DWS servers.

Authentication Workflow

These steps outline how a client application should carry out authorization with the BSN.cloud REST API.

Person Authentication

Person authentication is the first step if the user has not created a network or does not know which network to select. If the user already has a network (and knows which network they wish to access), the authentication process can begin with network authentication (see below).

  1. The client application makes a POST call to the /token endpoint. The POST body includes a username and password for the user.
  2. If the credentials are valid, the server returns code 200 with a response body that includes access_token, expires_in, and refresh_token values. 
    1. The response body also includes a networkNames array that lists networks associated with the specified username. At this point the client application gives the user the opportunity to select a network (or create a new one by calling POST on the /self/networks/ endpoint).

Network Authentication

Network authentication occurs once the user has determined which network they wish to access.

  1. The client application makes a POST call to the /token endpoint with the network name included in the username value (e.g. "username=exampleNetwork/exampleUser@brightsign.biz").
  2. 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.cloud endpoint. The value of the "Authorization" header is specified as "Bearer {token_value}".
    1. 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 with the refresh_token value.
    2. 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.cloud 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.cloud REST calls for authentication.

Note

Unlike other BSN.cloud REST endpoints, the /token endpoint does not accept a trailing slash. 

Request Headers

  • Accept-Encoding: gzip,deflate
  • Content-Type: application/x-www-form-urlencoded
  • Accept: application/json


Request Body

  • [string] username: The BSN.cloud username. If this is a network authentication request, the network name precedes the username (e.g. "exampleNetwork/exampleUser@brightsign.biz").
  • [string] password: The password associated with the username
  • [string] grant_type: This value must be "password".
  • [string] 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.
  • [string] client_id

  • [string] client_secret

    Note

    The client_id and client_secret values are provided by BrightSign and used by partners to create networks for their customers.

Response Body

  • [string] access_token: The authorization token to use with endpoint calls
  • [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]")

/provisioning/setups/tokens/

POST 

Posts a network-access token to the /provisioning/setups/tokens/ endpoint. If the token is valid, the server returns a device-registration token, which allows the client to provision players for the BSN.cloud network via B-Deploy.

Request Headers

  • Accept-Encoding: gzip,deflate
  • Content-Type: application/x-www-form-urlencoded
  • Accept: application/json

Request Body

  • [string] grant_type: This value must be "user_access_token".
  • [string] user_access_token: The network-access token, which is returned by a POST to the /token endpoint.
  • [string] client_id

  • [string] client_secret

Response Body

  • [string] token: The device-registration token
  • [string] scope: The token scope, which is currently always "cert"
  • [string] validFrom: The start of the validity date for the token. The date/time is formatted as yyyy-mm-ddThh:mm:ss.sssZ.
  • [string] validTo: The end of the validity date for the token. The date/time is formatted as yyyy-mm-ddThh:mm:ss.sssZ.

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.

POST /2019/03/REST/Token/? HTTP/1.1
Host: brightsignnetwork.com:8443
Accept-Encoding: gzip,deflate
Content-Type: application/x-www-form-urlencoded
Accept: application/json

grant_type=password&client_id=aE%2382%40gE&client_secret=a3feabP1-FijA-eShl-WPab-xsAGFlraal6C&username=user%example.com&password=aU%2362%40bk

Person Authentication Response – Success

Note that the response includes the networkNames list.

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

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.

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=aE%2382%40gE&client_secret=a3feabP1-FijA-eShl-WPab-xsAGFlraal6&username=AuthenticationTest1/user@example.biz&password=admin&scope=full

User Authentication Response – Success

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":"N8VVpu1fefCaxKjxmD79pvmVMh5yB69xROUlGUJQLhDDpIN_k_qs3AuW5NvG22SWCBL-cPGuWeGUKDW-e0RUbyavL6I",
"token_type":"bearer",
"expires_in":899,
"refresh_token":"375671af51fa44fabb4b1a353d4f8488",
"scope":"Full,Self",
"networkName":"AuthenticationTest1",
"userLogin":"user@example.com",
"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

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

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=aE%2382%40gE&client_secret=a3feabP1-FijA-eShl-WPab-xsAGFlraal6&refresh_token=375671af51fa44fabb5b4a353d4f8488

Renew Access Token Response – Success

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":"user@example.com",
"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

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.

GET /2019/03/REST/Devices/ HTTP/1.1
Host: brightsignnetwork.com
Authorization: Bearer Y0yosoHhDDpqU3VimXuSmkehnZxzjK6TpGDY7g18KB6UDSzhrx6IzCGxhLVDxsu3raK622rHszHQNLjNEDHVrMnlWrdxGpkc21UqBe4bgwGFGKljhd122r7Q379sV1vI,Bearer MJDbxHOpYTKyiVCEzZXJb8zEoQsfqURIFnsMaB3E7h8br9XXMSiEfdN3CPMbmUcm1ZPzmZGkCGGyEU5iMgA7dJI438shXRQB44TR6AhhNo7Yt7xiJdTvhzFjQH9gpvFI
Accept: application/json
Accept-Encoding: gzip,deflate
User-Agent: PostmanRuntime/7.11.0
Cache-Control: no-cache
Postman-Token: 45fdd891-8112-4d6d-a44e-99d7e6c2d4a2,f80bd2bf-65d4-4302-ac17-e7348965fc20
Host: preview.brightsignnetwork.com
Connection: keep-alive
cache-control: no-cache