Click or drag to resize

Example 1: Connect and authenticate a user

This example provides how to connect and authenticate to the server. Basically there are two methods supported:

  1. Authenticating using a Service Account: uses a certificate to sign the authentication credentials and is best used with server to server applications.

  2. Authenticating using OAuth: is best used for client to server applications that allows a user to authenticate without exposing their credentials to the client application.

In the following sections, its depicted in details how to authenticate a user to the Workspaces' services.

Authenticating using a Service Account

To Start a session using service account, you must first know the username or email address of the user the request will be made on the behalf of, the issuer id for the Service account, and determine for how long the signed token will be valid. You will also need the certificate to use when signing the data.It assumes that you have already copied the public key to the Workspaces server(see the section on "Using Service Accounts" for more information on that). How an application determines or aquires a user's email address would be up to the application. The issuer is the identifier assigned when the service account was created in the Workspaces Admin console. This issuer would be in the format com.watchdox.system.xxxx.yyyy where xxxx and yyyy are some set of numbers and letters- for example, com.watchdox.system.fadd.3015. The expiration time represents the number of minutes for which the token should be valid.

With this information in hand and creating an instance of ApiSession, a simple call to a StartSessionWithServiceAccount method in ApiSession will return the loginResult.The server returns a "Success" LoginResult if the session starts successfully:

ApiSession apiSession = new new ApiSession(serverUrl);
LoginResult loginResult =
    apiSession.StartSessionWithServiceAccount(username,
                                              serviceAccount,
                                              expiresInMinutes,
                                              certificate);
Authenticating using OAuth

To Start a session using OAuth, you must first know the email address to pass to service provider, null or empty if not known and to be determined during the OAuth process. Its also optional to provide refresh token and showUiIfRefreshFails(indicates whether to show UI if refresh token exists but the refresh fails).

After creating an instance of ApiSession and making StartSessionWithOAuth method call, an OauthBrowser window pop ups to receive an authentication email and password. Once the user provides a correct email and password, the pop up widow will close and the StartSessionWithOAuth method returns a "Success" LoginResult if the session starts successfully.

ApiSession apiSession = new new ApiSession(serverUrl);
LoginResult loginResult = apiSession.StartSessionWithOAuth(email);