Authenticate

Required to begin the VSA API Web Service session. The SessionID returned must be submitted with every method invoked during session. The SessionID is only valid when received from the same machine the authentication originates from.

A single record of the following fields is returned.

Automatic Logon During Authentication

When you authenticate through the API, you are automatically logged into VSA as well. If you are already logged into the VSA at authentication time, the 2 sessions are synchronized.  Either way, the result is the same – you end up with valid sessions in both worlds.

The VSA looks for the API's 26 digit SessionID on the query string of every VSA page. If the application redirects to a VSA page, the page displays without forcing the user to log in again. The syntax is:

URL?apiLogonGuid=12345678901234567890123456

For example:

http://someServer:123/Systemtab/SomePage?apiLogonGuid=12345678901234567890123456&SomeVar=SomeValue

API activity keeps the VSA session alive. However, since VSA does not assume there is always a need for an API session, VSA activity does not keep the API session alive.

The API uses the same timeout value as the VSA, which is maintained using the VSA's System > Logon Policy page, and has a system default value of 30 minutes.

Hashing Algorithm

With release 6.2, K2 has adopted the SHA-256 hashing algorithm for secure authentications. Previously the standard was SHA-1. See the Changing Passwords Used by External Applications topic of System online help for a general introduction to this enhancement.

• A newly created or reset password is hashed using SHA-256.
• Legacy passwords that have not been reset continue to require SHA-1.
• The HashingAlgorithm parameter in Authenticate defaults to SHA-1, if left blank.
• The Sample API C# Application and Sample API ASP Page provide an option to switch the hashing algorithm between SHA1 and SHA-256.
• VSA passwords can only be reset using the VSA application, not by the API.

  Warning: Changing a password used by a legacy external application will disable the integration until either the external application is updated to use the required SHA-256 hashing algorithm or a new SHA-1 credential is created and implemented. Ensure passwords used by external applications are not changed before the update is implemented. See Creating a New SHA-1 Credential for a Legacy External Application below.

Best Practices

To ensure a smooth migration from prior releases to this release, Kaseya recommends web services API client code be written or modified to attempt authentication using SHA-256 first, then SHA-1 second, in succession. This will ensure that the client code will be compatible with passwords created under current and prior versions of the VSA.

1. Set the HashingAlgorithm parameter in the Authenticate request to SHA-256. Ensure the password is hashed using SHA-256. Issue the Authenticate request. Check to see if a valid session ID was returned.
   • Authentication is successful if the SessionID parameter returns a non-zero value and the ErrorMessage parameter is blank.
   • Authentication is not successful if the SessionID parameter returns a zero value. Perform step 2.
2. Set the HashingAlgorithm parameter to SHA-1. Rehash the password value using SHA-1. Re-issue the Authenticate request. Check to see if a valid session ID was returned.

Creating a New SHA-1 Credential for a Legacy External Application

If you are running VSA v6.2 or later, and need to create an SHA-1 username and password that is compatible with a legacy external application, and that has not yet been updated to be compatible with v6.2 passwords, use one of the following procedures. You can either create a new master user and password, or reset just the password of an existing master user.

Note: You must have administrator privileges on the Kaseya Server. For security reasons, you cannot perform the following procedure remotely.

Creating a New Master User Account

1. Log in to the machine running the Kaseya Server.
2. Access the following web page:
   http://localhost/localAuth/setAccountV61.asp
3. Enter a new account name in the Master User Name field.
4. Enter a password in the Enter Password field and confirm it by re-typing it in the Confirm Password field.
5. Enter an email address in the Email Address.
6. Click Create.

The external application can now be updated to use the new user account and SHA-1 password to connect to the VSA.

Reset the Password of an Existing Master User Account

Note: The master user account cannot be disabled.

1. Log in to the machine running the Kaseya Server.
2. Access the following web page:
   http://localhost/localAuth/setAccountV61.asp
3. Enter an existing, enabled master account user name in the Master User Name field.
4. Enter a password in the Enter Password field and confirm it by re-typing it in the Confirm Password field.
5. Skip the Email Address. You cannot reset the email address of an existing user using this web page.
6. Click Create.

The external application can now be updated to use the new SHA-1 password to connect to the VSA.