Authentication

This topic describes procedures needed to begin and end an authenticated session with the DM NVX API.

NOTES:

  • Most of the following procedures use Postman as an example API development environment program. While these procedures can apply to any API development environment program, the actual implementation may vary by program. Refer to the program's documentation for more information on using it begin or end an authentication session with the device.
  • With authentication enabled, connection can be established only via HTTPS on port 443 and/or a WebSocket to access the web service. Unless a valid certificate has been installed on the device, the client must accept self‑signed certificates.
  • Manual authentication is only required if you are using a library to access the web service. If the component is built into the Crestron Web UI framework, authentication is handled automatically via HTTPONLY cookies described below.

Authenticate via HTTPS

The following procedures describe how to begin and end an authenticated sessions using HTTPS.

Begin a Session

Send an HTTPS GET request to the server hostname with the URL set to the login page /userlogin.html. This GET request is handled before it is redirected to HTTPS.

Copy the value of the TRACKID cookie. This cookie must be entered as a header in the following POST request.

Next, send an HTTPS POST request to the server hostname with the URL set to the login page /userlogin.html. The POST request must include the following information:

  • Headers
    • Add a Cookie header with a value of TRACKID=[value], where [value] is the value of the TRACKID cookie shown in the image above.
    • Add an Origin header with a value of [deviceip], where [deviceip] is the IP address of the device.
    • Add a Referer header with a value of [deviceip]/userlogin.html, where [deviceip] is the IP address of the device.
  • Body
    • Enter the admin login credentials for the device in URL‑encoded format as raw data. The login key is the username value and the passwd key is the password value. Refer to the following sample syntax.
    • Copy
      login=<username>&&passwd=<password>

If the POST request is valid, the server returns a 200 OK response.

The response contains a CREST-XSRF-TOKEN header. This header must be copied and used for subsequent POST requests as described in Make API Calls.

The response also contains authentication cookies that must be saved, as they will be required on all the subsequent requests. The following HTTPONLY cookies must be saved by the client for any API call:

  • AuthByPasswd
  • TRACKID
  • iv
  • tag
  • userid
  • usrstr

All cookies besides AuthByPasswd will be set only once during the authentication POST response and will not change as long as the session is valid. AuthByPasswd will change on the subsequent requests, so the cookie must be updated on the client when it changes.

NOTE: By default, Postman saves all HTTPONLY cookies provided in the authentication response automatically so they can be reused throughout the session. If this behavior has been disabled or if using a different API development environment program that does not support this behavior, the cookies must be added manually to any subsequent requests.

If invalid credentials are provided or if the session times out, the server returns a 403 Forbidden response.

End a Session

To end the session, send a GET request to /logout. The server removes all authentication cookies. Manually removing all cookies and closing the connection will also end the session.

Sample Client-Side Code

Refer to the following JavaScript client-side code for receiving device information:

Copy
const request = require('request');

const deviceHostname = 'https://172.30.1.1'; // Device addressconst
loginPage = deviceHostname + '/userlogin.html'; // Login page url
let postOptions = {
    url: loginPage,
    jar: true,    // Saves the cookies for subsequent requests
    agentOptions: {
        rejectUnauthorized: false    // To accept self signed certificates
    },
    form: {
        login: 'admin',    // User credentials
        passwd: 'admin'
    }
};

request.post(postOptions, (error, response, body) => {
    // Error handling
    if (error) {
        console.log('error: ' + response.statusCode);
        console.log(body);
        return;
    }
    // Valid crendentials will cause the server to respond with a redirect to root
    if (response.statusCode === 302 && (response.headers["location"] === '/')) {
        let getOptions = {
            url: deviceHostname + '/Device/DeviceInfo', // URL for the deviceinfo
            jar: true,
            agentOptions: {
                rejectUnauthorized: false
            },
        };
        // Requested data will be in the response body
        request.get(getOptions, (err, resp, bdy) => {
            if (resp.statusCode && resp.statusCode === 200 && bdy) {
                console.log(bdy);
            }
        });
    }
});

Authenticate via WebSockets

The following procedures describe how to begin and end an authenticated sessions using a WebSocket.

Begin a Session

Authenticating via a WebSocket uses the same initial connection procedure as described in Authenticate via HTTPS. Perform the procedure in this section prior to upgrading the connection to a WebSocket.

After issuing a successful HTTPS POST request to the server hostname with the URL set to the login page /userlogin.html and after storing the required HTTPONLY cookies, the connection must be upgraded to a WebSocket from the headers.

NOTE: Connecting to the API via a WebSocket is possible only if authentication is enabled.

Refer to the following cURL syntax for an example of the required headers.

Copy
curl "wss://[IP address]/websockify"  -H "Upgrade: websocket"  -H "Connection: Upgrade" -H "Host: [host IP address]" -H "User-Agent: advanced-rest-client"  -H "Origin: [IP address]"  -H "Referer: [IP address]/userlogin.html"  -H "Sec-WebSocket-Version: 13"   -H "Accept-Encoding: gzip, deflate, br"   -H "Accept-Language: en-US,en;q=0.9"   -H "Sec-WebSocket-Key: [value]"   -H "Sec-WebSocket-Extensions: permessage-deflate; client_max_window_bits"

Once the HTTPS connection is established, a handshake occurs and the connection gets upgraded to a WebSocket.

Device URL after Handshake: wss://$ipofthedevice/websockify (encrypted)

The following handshake response is provided:

If invalid credentials are provided or if the session times out, the server returns a 403 Forbidden response.

End a Session

To end the session, send a GET request to /logout. The server removes all authentication cookies. Manually removing all cookies and closing the connection will also end the session.