Authentication using Service Accounts

Service Accounts provide an alternative means of authenticating requests sent to the Workspaces server. Using a service account removes the need to have a user's password in order to authenticate a user. When using a Service Account you can configure Workspaces to allow groups of users based on their email domain(s) and/or specific users access to their Workspaces accounts.

Steps for creating a Service Account

Create or obtain a SSL certificate. There are a number of ways to do this including using tools like OpenSSL to create a Self-Signed certificate, or you can purchase a commercial certificate from any number of certificate providers.
Extract the Public key from the certificate. You'll need this to paste the Public key into the Workspaces Admin console.
Configure the Service Account in Workspaces.
While logged in to the Workspaces Admin Console as an administrator:
1. Navigate to Service Accounts under Authentication on the left-hand side, and click the + icon.
2. Under System accounts:
  1. In the Public key field, copy and paste the contents of the Public key. Depending on how the certificate was generated and the public key displayed, the key may be bracketed by a set of tags such as -----BEGIN PUBLIC="" KEY----- and -----END PUBLIC="" KEY-----. Do not include these tags when copying the pubilc key.
  2. In the System accounts field, enter a list of user email addresses that will be allowed to authenticate using this service account. Separate each address with a space. If you only want to authenticate groups of users using theiremail domain this field may be left blank.
  3. In the Domain system accounts field, enter a list of email domains that will be allowed to authenticate using this service account. Separate each domain with a space. If you only want specific users to be able to authenticate this field may be left blank.
  4. In the Algorthm dropdown, select the algorithm that was used to create the certificate.
  5. Click Apply to save the Service Account configuraiton.
In your application code use the StartSessionWithServiceAccount method on ApiSession to authenticate a session.

Authenticating using StartSessionWithServiceAccount

Once the Service Account has been created in the Workspaces Admin Console clients can connect using the certificate. The StartSessionWithServiceAccount method on ApiSession provides the means to start a session using the Service Account. This method will construct an authentication token and validate that the specified user has access to use the service account to make requests to the server. If they do then LoginResult will return with "Success". For further details see Example 1.

Copy

ApiSession apiSession = new new ApiSession(serverUrl);
LoginResult loginResult =
    apiSession.StartSessionWithServiceAccount(username,
                                              serviceAccountName,
                                              expiresInMinutes,
                                              certificate);

Using OpenSSL to create a certificate

Run the openssl applicaiton to create a certificate and private key file. In the example below <PRIVATEKEY> represents the name of the file where the private key will be stored. <CERTIFICATE> represents the name of the file where the certificate will be stored.

When you run the openssl command you will be prompted for several pieces of information used in creating the certificate.

Copy

openssl req -newkey rsa:2048 -nodes -keyout <PRIVATEKEY> -x509 -out <CERTIFICATE>

Run openssl again to display the public key.

Copy

openssl rsa -in <PRIVATEKEY> -pubout

The output will look something like the example shown below. The public key is the text shown between the -----BEGIN PUBLIC KEY----- and -----END PUBLIC KEY----- tags.

Copy