User Stories

High level diagrams

Manufacturing process

Detailed flow

Details of logging in with JWT

Sequence overview

1. Client calls the Entone API to get a JWT used for logging in
2. Client sends login JWT token to Middleware
3. Middleware responds with two tokens that can be used to authenticate future requests

This is diagrammed in the section "user login" above.

Entone API

The View team will add a new function to the API with the following signature:

String ENTONE.stb.createJWT(algorithm, claim) 

Where claim is a object containing the payload of the JWT, algorithm is the mechanism to sign the signature.

The returned string is a JWT which is based64 encoded string. 

Parameters to pass to Entone API

The algorithm must be one of the values supported as the "alg" parameter in the JWT spec (here).  The only algorithm supported is RSA with sha-256 and so the algorithm parameter value should always be "RS256".

The client MUST use this format for the claim object:

$claim = [
    "iss"                => "EntoneAPI",
    "iat"                => time(),
    "exp"                => time() + TEN_MINUTES,
    "aud"                => "www.aminocom.com",
    "sub"                => "Serial number 123",
    'certificate'        => "String containing the STB public key"
    'batchCACertificate' => "String containing the STB batch CA certificate",
];

It will receive a JWT from EntoneAPI and must then call the MoveAPI endpoint as below.

MoveAPI

Endpoint

https://domain.tld/api/stb/auth

Validation rules

The MoveAPI must validate the JWT as follows:

1. Decode the JWT
2. Retrieve the supplied public key from the "certificate" claim
3. Retrieve the suppled CA certificate from the "batchCACertificate" claim
   1. If it is omitted then read the CA certificate for batch 0133 from disk
4. Verify that:
   1. The issuer is EntoneAPI
   2. The audience is www.aminocom.com
   3. The token has not expired
   4. The token was issued in the past, or otherwise within a tolerable window to allow for server time drift
   5. JWT was signed with the key you obtained in step 2
5. Verify that the CA certificate is signed by the Entone CA certificate
6. Obtain the "sub" claim
7. Find the user associated with the STB serial code indicated in the "sub"

It is important that the JWT is signed with the supplied key AND that the key was generated from the Entone root CA

Response

The Move Middleware will respond with two JWT tokens that can be used for authentication in future requests.  This is identical to DNA.

{
 "jwt": "jp0cnVlLCJjb21wYW55IjoiVG9wdGFsIiw...",
 "jwt_expiry": "Fri, 04 Dec 2015 16:01:07 +0000",
 "refresh_token": "WkiUzKELZ49eM7oWxAQK_ZX...",
 "refresh_token_expiry": "Fri, 04 Jan 2016 16:01:07 +0000",
 "client_keystore": "MIIKwIBAzCCoYCSqGSIb3...",
 "serial_no": "615500266162",
 "chipset_id": "8c10d4de5760",
 "mac": "8C10D4DE5761",
 "user_id": "email@example.com"
}

Logout STB

API to handle logout request of STB

Request

POST

https://customer.domain/api/stb/logout

POST Body

Please note that M is for Mandatory and O is for Optional. 

service_token

Headers

Please note that M is for Mandatory and O is for Optional.

Authorization: Bearer

Response

Link STB to a User

After user bought a STB this API need to be called. This API link or grant ownership of a STB to a user.

Request

POST

https://boox.fi/api/management/stb/link_user

POST Data Parameters

Please note that M is for Mandatory and O is for Optional.

serial_no

email

public_keys

Response

	"id": "123",
	"serial_no": "DNA-STB0001",
	"user": {
		"id": "10001",
		"email": "stb_user@dnastb.com"
	}
}

{
  "error" {
    "code": 9,
    "text": "Access to this resource is locked to IP addresses"
  }
}

Error Codes

Unlink STB from User

This API remove ownership of a STB from an user. Use cases: when user sells his/her device, when a device got stolen. 

Request

POST

https://customer.domain/api/management/stb/unlink_user

POST Data Parameters

Please note that M is for Mandatory and O is for Optional.

serial_no

email

Response

{
  "error" {
    "code": 9,
    "text": "Access to this resource is locked to IP addresses"
  }
}

Error Codes

Add New User Account

This API is used to add a new user account. Following rules apply:

• Email address or customer-id should not belong to any customer that is not in DELETED state; otherwise API will return an error.
• If the user with that email exists in DELETED state and his grace period is not expired, his previous registration state is restored.
• A new user is created in UNREGISTERED state.

Design Points (to be considered for future):

1. The main problem with making the two pin params as mandatory is that this feature is very specific to a customer requirements, while other frontends don't expect them. Therefore, we need a way so that both parties remain happy by giving a better design.
2. For that we should make it configurable whether the two params are mandatory. So for those who require those PINs, we will configure them as mandatory, so that if they are not provided by 3rd provisioning system when creating a new user API will return an error to provide the mandatory input param. While for others, we will configure them as optional so that if they don't provide the params, API will successfully create a user and set the pins in DB as NULL (empty).
3. It is easy to implement from effort point of view and much flexible and reliable

Request

Query Strings

Please note that M is for Mandatory and O for Optional.

Error Codes

Edit Existing User Account

This API is used to suspend or activate a user account. It can also be used to change the email or customer-id of an existing account. Following rules apply:

• A user in DELETED state is not updated.
• "email" and "cid" parameters should not belong to any existing user, even if the user in in DELETED state
• If a user is suspended, his state is changed to DISABLED
• If a DISABLED user is activated and grace period has not expired, then previous registration state is restored, otherwise his state is changed to UNREGISTERED
• In other cases, if a user is activated, his state changed to REGISTERED.

Request

Querystrings

Please note that M is for Mandatory and O for Optional.

Error Codes