3.3 Working With Endpoint Sessions

3.3.1 About Endpoint Sessions

Endpoint is any logical or physical unit which interacts with the authentication server. E.g., client computer, tablet device, smartphone, any software or system is an endpoint. Endpoint should create endpoint session on the server to start working. The appliance use endpoints’ sessions for checking what PC wants to get access, the appliance supports endpoint’s white lists for events, also the appliance can check the owner for an endpoint. The whitelist for events can restrict access to the endpoints, for example, if a workstation (as endpoint) is not added to the whitelist for the Windows or Mac OS event, the workstation cannot use advanced authentication. Each endpoint has an identifier and secret. Secret is a security value that is used for generating endpoint security hash. Security hash is used to start endpoint session. The algorithm for generating the secret hash is represented on the following picture.

Figure 3-1 Algorithm for generating the secret hash

After SHA-256 function, you should transform result to a HEX-value string. All parameters are string. All concatenation functions are string concatenation functions. The salt should be generated on the client side. It is advised to use a strong algorithm for generating the salt.

The following example shows how to generate secret hash.

Endpoint id = 42424242424242424242424242424242
Salt = e26eaecba7cbe186c08469f6ddbf6f6c0321651b53f80d8eb2c3b0d4e1c19c4c
Endpoint secret = 12345678
Middle result = e53e75ec3d48171abff1e4d2f0a5066e64fdbe11a4d3fd7c45810d7d93c26956 = SHA256(endpoint id + salt)
Result 3b5dac383282df6936f9350a01ad079096f777f5c44eda8e0c2e66bfc443ee26 = SHA256(endpoint secret + middle result)

The endpoint identifier and endpoint secret need to be very secure. This information should be kept in a secure place and parameters should be changed every time the information is compromised.

Endpoints can work with the server and provide user authentication after the endpoint session creation. The endpoint session has a lifetime, after this, the endpoint session will be deleted and the session will need to be renewed. All users can work with one endpoint session on one endpoint.

3.3.2 Create Endpoint Session

To create the endpoint session, use the following resource with URI:

/endpoints/{endpoint_id}/sessions

Resource is provided by HTTP POST. It has the following parameter.

Table 3-5 URI parameters for creating endpoint session.

URI Parameter	Description
endpoint_id	Endpoint identifier. Identifier of endpoint that creates endpoint session.

Resource accept JSON-object with these parameters.

Table 3-6 Parameters for creating endpoint session.

Parameter name	Description
salt	Client generated salt. This salt is used in secret hash generated algorithm.
endpoint_secret_hash	Generated secret hash by algorithm.
session_data	Any session data. This is a JSON-object with any parameters and structure.

The resource returns JSON-object with the following endpoint session identifier.

Table 3-7 JSON-object with created endpoint session.

Parameter name	Parameter description
endpoint_session_id	Endpoint session identifier. This is an identifier of the created endpoint session. It should be used for other methods.

Example

Endpoint with identifier “42424242424242424242424242424242” creates endpoint session. Endpoint has already generated salt and endpoint secret hash.

HTTP POST
https://authserver.example.com/api/v1/endpoints/42424242424242424242424242424242/sessions
Request
{
"salt":"2615c070937935246c6a91df70a8eb672b21d842a225621c9797a83bedf00a7b",
"endpoint_secret_hash":"38d55fb7a899dcef6cbec053df8f7673cb05068b9ee9d6a23ee759232b25cf4e",
"session_data":{}
}
Response
{
"endpoint_session_id":"IRx7UXwenytMn5B7fgRSH4k1s6PAAs0I"
}

3.3.3 Read Information About Endpoint Sessions

To read information about endpoint session, use the following resource with URI:

/endpoints/{endpoint_id}/sessions/{session_id}?salt={salt}&endpoint_secret_hash={endpoint_secret_hash}

Resource is provided by HTTP GET. It has the following parameters.

Table 3-8 URI parameters for reading information about endpoint session.

URI parameter name	Description
endpoint_id	Endpoint identifier. Identifier of endpoint which session will be read.
session_id	Session identifier. Identifier of endpoint session for reading.
salt Salt	It is used for generated endpoint secret hash
endpoint_secret_hash	Endpoint secret hash.

Resource returns JSON-object which contains the following information about endpoint session.

Table 3-9 JSON-object with information about endpoint session.

Parameter name	Description
sid	Endpoint session identifier, identifier of endpoint session
endpoint_id	Endpoint identifier
session_data	Session data, this data can be added on creating session, this is any JSON-object with any structure.

Example

We read the endpoint session information for endpoint with identifier “42424242424242424242424242424242”. Session identifier is ”T2Fv3FOvWojyBOZBlsik1d9RBDjDr9Rq”. Endpoint has already prepared secret hash and salt.

HTTP GET
https://authserver.example.com/api/v1/endpoints/42424242424242424242424242424242/sessions/T2Fv3FOvWojyBOZBlsik1d9RBDjDr9Rq?salt=279bc0da2a9da8afcfda50c2bc3f418218354020d73c00a6a088dea704ece3f9&endpoint_secret_hash=bfe7b1e1cad57525a9695f39eb5cff4d4dd7a42e039122c732adb151d097835c
Response
{
"sid":"T2Fv3FOvWojyBOZBlsik1d9RBDjDr9Rq",
"endpoint_id":"42424242424242424242424242424242",
"session_data":null
}

3.3.4 Delete Endpoint Session

To delete an endpoint session, use the following resource with URI:

/endpoints/{endpoint_id}/sessions/{session_id}?salt={salt}&endpoint_secret_hash={endpoint_secret_hash}

Resource is provided by HTTP DELETE. It has the following parameters.

Table 3-10 URI parameters for deleting endpoint session.

URI parameter name	Description
endpoint_id	Endpoint identifier. Identifier of endpoint which session will be deleted.
session_id	Session identifier. Identifier of endpoint session to be deteled.
salt Salt	It is used for generated endpoint secret hash.
endpoint_secret_hash	Endpoint secret hash.

Resource does not return any data. If the deletion is successful, the HTTP 200 status will be returned.

Example

Endpoint with identifier “42424242424242424242424242424242” deletes session with identifier “9Ml1ByqdIsCr3re5C0aivXR6ap20fNW8”.

HTTP
DELETE
https://authserver.example.com/api/v1/endpoints/42424242424242424242424242424242/sessions/9Ml1ByqdIsCr3re5C0aivXR6ap20fNW8?salt=4b470b4ee96630ced049a78d6488ee127b9d419f463530c63f3e1ee27226f721&endpoint_secret_hash=c2bf7b8288aa55de22baa9d077150d83b3460d5951a57d6e7ccf2a01f61bc9ec
Response
HTTP 200