Security Options

The Crestron Fusion API service relies on the client application for authentication. Instead of authenticating users, the API Service authenticates the client application using a simple shared passcode. This passcode is set in the API section of the Configuration Web Client.

The following security options are available:

  • Unencrypted security token
  • Encrypted security token
  • No security

Unencrypted Security Token

This level of security is set when the Enable API Security check box is checked and the Encrypt Security Tokens check box is unchecked. This configuration must never be used without implementing Secure Socket Layer (SSL).

Under this configuration, the client applications request a security token from the API Service that is sent on all requests. The security token request must contain a set of comma-separated Crestron Fusion role names to access object-level security. The Crestron.Fusion.API.Security namespace contains details on the URI. The token is not encrypted and is susceptible to replay attacks without SSL.

Encrypted Security Token

Encrypted security tokens are necessary when the Crestron Fusion API Service is not using SSL to prevent replay attacks from malicious requests. This level of security is set when the Enable API Security check box is checked and the Encrypt Security Tokens check box is checked.

After receiving a security token from the API Service, the client application must perform the following:

  1. Decrypt the security token using the shared passcode and save the user ID.
  2. Encrypt the user’s ID and the current UTC date and time in RFC3999 format (before every subsequent request to the server). The algorithm is MD5.
  3. Set the encrypted string to the ?auth= query string variable in the request URI.

Upon receiving the request, the server decrypts the security token and compares it with the time it was sent to the server to the server time adjusted for UTC. The number entered in the Token Timeout field determines the number of seconds the server time can differ before the request is rejected.

No Security

Although it is never advised in production, security can be turned off for development purposes by unchecking the Enable API Security check box. All client requests then impersonate the default administrator account.

NOTE: It is not recommended in production to turn off the security.

Testing the Resource Data API

After enabling the API with no security, verify the functionality by opening a browser and navigating to http://<server-name>/fusion/apiservice/rooms. A list of rooms is displayed that are in Crestron Fusion. If there is no response from the Crestron Fusion API, contact the Crestron Fusion Support Group (FSG) at (855-754-5962) or e-mail fsg@crestron.com.