Yarkon S3 SDK

Details

Yarkon S3 is a web based user interface for Amazon S3. It is currently being offered in a number of configurations, ranging from a stand-alone client web application to a hosted cloud based solution.

The core component of the system, the Yarkon web control, is ideal for organizations which have already implemented an S3 based solution, and require an integrated, highly functional, web based front end, that can be seamlessly integrated within their existing platform.

The Yarkon web control offers the same features and capabilities of the Yarkon Web Edition, and requires the user and session management to be handled by the host application. The interface uses standard HTML5 and CSS technology, and is therefore fully customizable to match the look and feel of the container.

The reference documentation for the Yarkon SDK is available for download.

Pre-requisites

The Yarkon web control is an HTML5 control. It would work in any web application, provided that you can do the following:

  1. Embed it in a DIV or other HTML element.
  2. Provide it with authorization based on your web application authentication

Setup and Configuration

The specifics depend on your host application. Usually, the assets (CSS, images and JS files) should be placed together with your other assets, in a place your server can access when rendering the HTML content for the clients. The `` elements in the HTML template included should be modified to reflect the appropriate paths to these assets.

The HTML template links to few external resources from public CDNs. For instance, it requires font-awesome from cdnjs.cloudflare.com. If you prefer to host these resources locally, or you already do that anyway, add these resources to your assets and adjust the links in the template accordingly.

Architecture and Control Flow

The following schema describes a common use of the Yarkon SDK, hosted by a web application.

This web application is responsible for the authentication phase. When the Yarkon web control is rendered, it will make an outbound call to get its AWS API keys. Using the user session data, the host application should be able to provide the keys corresponding to this user’s account permissions. Yarkon will follow up with another call to get the list of buckets allowed for this user.

See the sections below for the full details.

Authentication

Authentication, meaning accepting user credentials and verifying that they are correct, are the sole responsible of the hosting application (your application). Yarkon does not maintain any user session – it is delegated and managed by the hosting application.

It is your responsibility to manage session timeouts as needed.

Authorization

Authorization, meaning what is the authenticated user allowed to do, is handled using AWS API keys. It is your responsibility to provide Yarkon with the credentials that represent the permissions granted to the user to access your S3 buckets. You also must provide Yarkon with the list of buckets the user has permission to access.

The mechanism used by Yarkon is JavaScript callbacks. The sample HTML provided includes sample code that you should replace with your logic. The code can be static server side generated, use a RESTful API call, or any other method that would result in returning the data required, which is documented in the code sample. There are two method you must implement:

getCredentials

Replace the body of the sample code with logic that would return the AWS API key credentials for the currently signed in user. Your application should be able to tell who the user is based on some session management cookie, the URL, tag embedded in the host page, or a similar method.

    // Should return JSON with this format:
    // {
    //  "credentials": {
    //   "accessKeyId": accessKeyId,
    //   "secretAccessKey": secretAccessKey,
    //   "sessionToken": sessionToken
    //  },
    //  "region": null
    // }
    document.getCredentials = function(callback) {
        $.getJSON("data/sample-keys.json", function(data) {
            callback(null, data);
        });
    };

The response must include the accessKeyId and the secretAccessKey.

It is highly recommended to use short lived temporary credentials, if your application is capable of doing so. This will result in the temporary credentials returned in the aforementioned fields, and the sessionToken passed as well. If you elect to use the user keys, the sessionToken field should be null.

The region field is optional. If you decide to pass it in, it should be the region code as defined by AWS. The current list of these codes is available from Amazon here: http://docs.aws.amazon.com/general/latest/gr/rande.html. The code is the value listed in the table in the Region column. For instance, the "US East (Ohio)” region has the code "us-east-2”.

getBucketList

This method should return the list of buckets available to the user, as a JavaScript array. The returned values should be the bucket names, as they are in S3.

    // This method should return the list of buckets available to the
    // current user. The `credentials` object is the same one returned
    // from the `getCredentials` function.
    // Should return an array with the following format:
    // ['bucket-A', 'bucket-B', 'bucket-C']
    document.getBucketList = function(credentials, callback) {
        callback(null, [
            'yarkon-finance',
            'yarkon-operations',
            'yarkon-sales'
        ]);
    };

You can simply implement this logic on the server side by granting the user API keys the "listAllMyBuckets” permission and then call S3.listBuckets(), but this approach creates a security concern in case you don’t want the user to be able to see buckets she does not have access to. While users will never be able to access buckets they don’t have permissions to, for some organizations, even seeing these buckets is a security concern. If in your case you do not want users to see a bucket unless they have explicit access to it, you must implement your server side logic to be able to get a list of these buckets without granting the API keys the "listAllMyBuckets” permission. One way of doing it is to keep a mapping of the user to her allowed buckets in your database. Alternatively, you can query the AWS IAM service.

Licensing

Yarkon SDK is licensed on a per server basis. Any server on which the software is installed, require to have its own license. For instance, if your web application is installed on two web servers behind a load balancer, the Yarkon SDK assets would have to be installed on both servers. In this case, you would require to purchase two (2) licenses.

The license is named and non-transferrable. It includes one (1) year of free upgrades, including access to all bug fixes and new releases of the same product as the one covered by the license. This coverage can be extended past the one year expiration date, for a standard, 30% of the then price of the Yarkon SDK.

Changes may be made to any of the files in the package, except the JavaScript file, yarkon.sdk.js.

Pricing

The current price of the Yarkon SDK is $2,500. It includes a license to install the software on one (1) server; you can use the software for an unlimited number of end-users, in any configuration, as long as it is served from that single server.

Price changes go into effect immediately.

Restrictions

It is required that the copyright statement, as well as credits given to open source software used by Yarkon, be available to the end user. You are not required to keep the Help | About menu option, or any other link to yarkons3.com visible. Instead – to satisfy this requirement – it is acceptable to place a link that will open the About form. See the `yarkon.sdk.embedded.html` file for an example.

What is Included

In the SDK package, we include the following:

  1. A named, non-transferrable, licensed version of the software. Your name will be visible in the About page of the Yarkon application.
  2. A sample HTML file, demonstrating how to embed the Yarkon component into a web application. It gives you full control over the main application menu, size and placement.
  3. A sample CSS file, demonstrating how to customize the look and feel of the Yarkon component to match the overall style of the container.
  4. This End User License Agreement.

As long as you use the software as-is, meaning that the client functionality available to the end-users is similar to what we offer in the free product, Yarkon Web Edition, the aforementioned should suffice for you to have a Yarkon web component embedded in your HTML application, with a look and feel matching the container.

What is Not Included

We do not offer the source code or any other part of the IP for sale. Any required modifications and customization, excluding CSS or changes to the HTML wrapper, must be handled by us, through our Professional Services.

The SDK does not include any add-on.

Frequently Asked Questions

  • Where can I see the user manual for the client application?
    We add to our documentation all the time, and enhance it as needed. To get a good understanding of how to use the Yarkon web client application, please check out one of the tours:
  • What are the known limitations of Yarkon?
    See the limitations page for a list of current known limits on using Yarkon.
  • Suppose I encounter an issue, can you help?
    Absolutely. We have a good experience with organizations being able to set up the application without assistance, but your situation might be unique. Please contact us with any question you might have.