Authentication - Managed Tokens

This enhancement introduces managed tokens to APIEngine.

This applies to release 94+ and is not applicable to be patched to any prior version.

Managed tokens have an optional expiration date and require database authentication with every APIEngine route call.

UserId versus Token

1. Every token is unique.
2. Every token must link to a UserId.
3. A single UserId may be linked to multiple (unique) tokens.

This allows flexibility in your token management.

For example, you could have a generic UserId that handles all ALARM.COM communications, then create a new token for each of your ALARM.COM accounts.

Dealer Restrictions

Programs 2202 and 2203, as well as ALIAS tokens, are restricted by Dealer Profile.

The Dealer Profile is found in the Users tab of program 1811. In the following screenshot, user JAKE6 is constrained by dealer profile 'DBP'.

The User's Dealer Profile must include the Dealer specified in another User's Personnel record. In the following screenshot Personnel record FRANKA01 is associated to Dealer 1001.

Dealer profile DBP, therefore, must have authority to Dealer 1001 in order to ALIAS any users tied to Personnel record FRANKA01.

1. APIEngine

Authentication

POST /api/v1/auth/basic

manage

New optional bool parameter. When true, the token is added to the Token Maintenance program and verified with every route request.

Example 1

USER1 creates an unmanaged token for USER1 that expires according to the APIEngine settings.

{

"username":"USER1",

"password":"user1_password"

}

Example

USER1 creates a token for USER1 that is managed, with no expiration.

{

"username":"USER1",

"password":"user1_password",

"manage":true

}

expiration_minutes

An existing optional integer parameter.

If the parameter is missing, or if the value is 0, then the default time specified in the APIEngine settings used.

Any value less than 1 (including 0 and negative numbers) is treated the same way: the default time specified in the APIEngine settings is used. A requested value above 1440 minutes is capped at 24 hours. These limits apply to unmanaged tokens.

A managed token carries no expiration inside the token itself. Its expiration is held in Token Management (2202), where the expiration_minutes value is recorded and can be changed with Set Expiration. The database can also make a token managed automatically, through the _manage value returned by api3_user_token_authorize.

Example 1

USER1 attempts to create a non-expiring token by passing -1; the value is treated the same as 0 and the APIEngine Settings default is applied

{

"username":"USER1",

"password":"user1_password",

"expiration_minutes":-1

}

Example 2

USER1 creates a token that expires based on the APIEngine Settings value.

{

"username":"USER1",

"password":"user1_password",

"expiration_minutes":0

}

Example 3

USER1 creates a token that expires in 6 hours

{

"username":"USER1",

"password":"user1_password",

"expiration_minutes":360

}

alias

New, optional, string parameter. If this parameter exists, and has a value, then the caller is using their credentials to create a token for the user defined in parameter alias.

Example 1

USER1 creates a token on behalf of USER2. The token is valid for X minutes.

{

"username":"USER1",

"password":"user1_password",

"alias":"USER2"

}

Example 2

USER1 creates a token on behalf of USER2. The token is valid for 6 hours.

{

"username":"USER1",

"password":"user1_password",

"alias":"USER2",

"expiration_minutes":360

}

Example: All Parameters

USER1 creates a token on behalf of USER2. The token is valid for 6 hours and is verified with every route request.

{

"username":"USER1",

"password":"user1_password",

"alias":"USER2",

"expiration_minutes":360,

"manage": true

}

Authorization

Decrypted Tokens will identify themselves as either managed or unmanaged.

Unmanaged tokens use only the self-contained expiration as validation.

Managed tokens require an additional call to the data server to verify that the token is still valid. See the following section of this document for more on managing tokens within SBN.

Token Resolution Order

v96 and later (APIEngine 1.0): when a request reaches a protected route, APIEngine looks for the token in this order, taking the first non-empty value:

1. A route parameter, if the attribute was constructed with one.
2. Authorization: Bearer <token> header.
3. User-Token header (legacy).
4. ?user-token= query string (or user-token form field on form posts).
5. AuthToken cookie.

v95 and earlier read the User-Token header, then the user-token query string, then the user-token form field. An Authorization: Bearer header is not read.

Tokens are signed with HS256 using the TokenSecret value from apiengine.settings.

1. SBN

All authentication (token creation) is done through the ApiEngine.

You must have the correct APIEngine URL in SBN option api_eng to effectively use program 2202.

Token Management (2202)

Shows all tokens (restricted by dealer) with filtering by UserId and Token.

New

Set Expiration

Toggle

Toggles the Active flag on the currently-selected row.

Check Token

The following token validation fails because the token's Active flag is off.

The following token validation fails because the token expiration is in the past.

Copy Token to Clipboard

Copies the token to your Windows clipboard. This is useful when you want to use the token outside of SBN.

Activity

Token Activity (2203)

Shows all activity (restricted by dealer) with filtering by UserId and Token.

Double-clicking a row will automatically filter by that row's UserId and Token.

The Clear button blanks out the UserId and Token filter fields.

Background Task

Deletes expired token activity records.

1. SBNAnywhere / API3

There is no API3 interface for Token Management or Token Activity.