Getting Started – Yarkon Server

Before you start, we recommend you watch this short 5 minute video, taking you all the way from Sign-Up to the FREE tier of Yarkon Cloud to having an end user logging in using the Yarkon web browser application and securely accessing S3. The video also shows how to use branding with Yarkon, changing the looks of the client to match your brand.

The following step by step guide will walk you through the full installation and setup process of Yarkon Server.

Yarkon Server is an enterprise grade system, fully integrated with AWS IAM. As such, the set up process requires working knowledge of Unix server and AWS IAM. If you are not familiar with Unix, we offer as an alternative the Yarkon Cloud service, that is fully managed by us and does not require any install.

To get your Yarkon Server up and running, follow these steps:

1. Launch the Yarkon instance
2. Update CORS for S3
3. Choose security model
4. Add users to Yarkon
5. Secure the server
6. Customize the look and feel

Launch the Yarkon Instance

Set up a server

For your convenience, we offer a number of ways to set up a Yarkon Server.
Ultimately, all offer the same functionality, and all come with a 30 day FREE trial:

1. CloudFormation template
2. AWS Marketplace
3. Docker

CloudFormation template

To start your Yarkon Server FREE 30 day trial, go to the FREE Trial page, and launch an instance using the AWS CloudFormation template available. The process only takes a few moments, and when done, you will have a fully functional and ready to go Yarkon Server instance running in your AWS account.

Depending on where your EC2 instance is set up, it might be unable to communicate with resources inside the VPC. While this is more common with older setups, if you happen to encounter such a problem while running the CloudFormation process – usually reported as the error “Creating Security Group: You may not define rules between a VPC group and a non-VPC group” – please follow this document from Amazon to resolve.

AWS Marketplace

If you prefer to use the AWS Marketplace, go to the listing page, and subscribe to start the process for launching an instance. The process only takes a few moments, and when done, you will have a fully functional and ready to go Yarkon Server instance running in your AWS account.

Docker

In case you are using Docker to run your servers, and especially if you want to run Yarkon Server on a non-AWS server, use the Docker optimized Yarkon Server image, available from docker hub. Make sure to checkout the documentation before you start.

Set up the application

When the stack generation process is complete, get the URL for the newly launched instance from the Outputs tab of the stack details. Put this URL in the address box of a browser to complete the one page set up step.

Update CORS for S3

What is CORS?

Cross-origin resource sharing (CORS) defines a way for client web applications that are loaded in one domain to interact with resources in a different domain. When using Yarkon Server, enabling CORS is always necessary, so make sure to familiarize yourself with the subject by reading this document from Amazon.

Important: the ACLs and policies continue to apply when you enable CORS on the bucket. Changing the CORS rules for a bucket does not have any impact on its ACL and policies.

Enabling CORS Automatically

The recommended way to get all your CORS settings updated in bulk, is using the Yarkon Admin Console.

Using the Buckets view, start with analyzing the CORS status. Select all buckets using the checkbox selector, and click the Analyze CORS button. After you determined which buckets require update, select those only, and click the Update CORS button. In the pop-up form, specify the origin you want to set – or accept the default – and approve the change.

You only need to update the CORS rules for bucket you expect end users to be using with Yarkon.

Important: This feature will only work if in the principal policy you created for Yarkon you allowed the S3 actions required for CORS. If you did not, you can follow the steps below to handle the task manually.

Enabling CORS Manually

If you prefer to update the CORS rules for your S3 buckets manually using the Amazon Console, go to the S3 service, and for each bucket you need accessed by end users, click on the bucket, then go to the “Permissions” tab and use the “CORS Configuration” button to edit the CORS rules for that bucket.

Note that the changes do take a little bit of processing by Amazon, and it is also possible that due to browser caching, it might take a few minutes before you can access the newly updated bucket.

The CORS rule for Yarkon also includes the headers ETag and x-amz-server-side-encryption. These are required for properly handling downloads and encrypted documents.

All origins

To enable access from all origins, use the * (the star character), like so:

<CORSConfiguration>
    <CORSRule>
        <AllowedOrigin>*</AllowedOrigin>
        <AllowedMethod>HEAD</AllowedMethod>
        <AllowedMethod>GET</AllowedMethod>
        <AllowedMethod>PUT</AllowedMethod>
        <AllowedMethod>POST</AllowedMethod>
        <AllowedMethod>DELETE</AllowedMethod>
        <ExposeHeader>ETag</ExposeHeader>
        <ExposeHeader>x-amz-server-side-encryption</ExposeHeader>
        <AllowedHeader>*</AllowedHeader>
        <MaxAgeSeconds>3000</MaxAgeSeconds>
    </CORSRule>
</CORSConfiguration>

Enabling for all origins is useful if you run different editions of Yarkon at the same time.

Specific origin

The following is the proper CORS rule to be used to enable access by Yarkon Server. Just replace the origin url with the DNS name you assigned Yarkon in your organization. If you did not assign a DNS name yet, either use the current DNS name of the server (that was generated by AWS), or allow CORS for all origins. You can revisit this step when you have the DNS all set.

<CORSConfiguration>
    <CORSRule>
        <AllowedOrigin>https://yarkon.mycompany.com</AllowedOrigin>
        <AllowedMethod>HEAD</AllowedMethod>
        <AllowedMethod>GET</AllowedMethod>
        <AllowedMethod>PUT</AllowedMethod>
        <AllowedMethod>POST</AllowedMethod>
        <AllowedMethod>DELETE</AllowedMethod>
        <ExposeHeader>ETag</ExposeHeader>
        <ExposeHeader>x-amz-server-side-encryption</ExposeHeader>
        <AllowedHeader>*</AllowedHeader>
        <MaxAgeSeconds>3000</MaxAgeSeconds>
    </CORSRule>
</CORSConfiguration>

Choose security model

Yarkon Server gets its permissions through IAM policies. It will never allow any end user more than the policy specify, and since the Yarkon server and client applications both only use the AWS API to communicate with the AWS back-end, neither can ever perform an action not explicitly allowed by the administrator. The administrator has full control over the permissions granted, and the flexibility is similar to what AWS IAM affords.

How does it work

Yarkon Cloud has three different Security Models, controlling user access to the S3 buckets:

• Shared security
• Federated security
• Integrated security

The Security Model is set using the Administration Page, Access Tab of the Yarkon Server application.

The following table explains the differences between them:

Yarkon gets its permissions based on a Principal AWS IAM entity. This entity is:

End users, using the Yarkon Client Application, get their permissions from AWS IAM entities as well, as following:

Important: End users only get S3 permissions. No other AWS service permissions are ever exposed to end users.

IAM Set up

When you deploy Yarkon Server using the provided CloudFormation template, or when subscribing through the AWS Marketplace, all required IAM policies are automatically generated for you, and there is no additional work required. If you are deploying Yarkon Server directly from an AMI or a Docker image, then you have to follow the Set up IAM policies guide to complete the IAM set up.

Choose the Security Model

Review the table above, and decide which use case is best for you. We recommend you’d start with the simpler Shared Security model and change later as needed. Note that when you change from the Shared model to either one of the Federated or Integrated models, you’d have to specify the IAM object for each user.

Add users to Yarkon

Any end user that needs access to S3 buckets using Yarkon, must be added to the system. Users who are not added to the system, or are not in status active, cannot log in to Yarkon. This is true also for set ups using SAML for Single-Sign-On. This allows the administrator to immediately revoke a user’s access as needed.

Adding Users

To add end user accounts, use the Users section from the left navigation pane, then click the Add button and fill in the details of each user. When using the Integrated or Federated Security Models, as we do in this guide, you have to specify the IAM name, group or role through which permissions are granted to the end user. This is not required if you use the simpler Shared Security Model.

A random password can be generated by the system, or a password can be set by the administrator. If email integration is enabled, the credentials will be communicated to the user using the email entered as the username. Otherwise, the administrator has to communicate the password to the newly created user.

Strong passwords can be enforced using the Administration page, Identity tab.

Import users

Yarkon also supports bulk import of users, using a standard CSV (comma delimited) file. Simply use the Upload button from the Users form. The format is described in the user interface.

When users are being added in bulk, and even if you have email integration set up, welcome emails will not be sent. This is to protect your account from being flagged by your email provider as a spammer; while this is not common, it might happen when using some providers who limit the rate of emails sent.
Instead, Yarkon will set up all user accounts added in bulk with the password “Password” (the word password, with the P capitalized). The administrator should communicate this place holder password to the end users. They will be required to change their password on first login.

Email support – Optional

Yarkon supports optional email integration. The email service is used to enable self-management of accounts by end users. In case a user forgets her password, she can reset her password using the client application, and receive a newly created auto-generated temporary password to her email inbox. Also, when a new user is added to the system, a welcome email with the credentials and login url will be automatically sent.

If you do not set up the email integrations, users would not be able to reset their password, and you will have to communicate the account credentials to the end user upon account creation. Otherwise, there is no impact – users can always change their password on their own.

Yarkon can work with any SMTP email server, as well as with AWS SES email service. Use the Administration EMail form to set up your email integration. In the images below you can see a sample for how email is setup with an SMTP server as well as with the AWS SES Service.

Secure the Server

Just like any other web server, Yarkon Server should accessed over HTTPS. During the trial period, you can access it over HTTP (not secure), but make sure to implement HTTPS before making it generally available to users.

Once you have your SSL certificate ready, you can set up HTTPS access, following one of these methods:

Using a Load Balancer

The AWS best practice for SSL termination is to use an Elastic Load Balancer (or an Application Load Balancer). This approach allows you to use an AWS provisioned certificate, and is also somewhat more efficient in terms of instance load. It does, however, require an ELB, which incurs a small cost.

To implement this approach, complete the following steps:

1. Turn on an ELB (or an ALB).
2. Define a TCP route from port 443 (default HTTPS) to port 80 (default HTTP) on the instance.
3. Set up the cert – either an AWS provisioned, or upload yours.
4. Close any direct access to the instance on port 80, except traffic from the load balancer.
5. Set up a DNS name for the load balancer.
6. Make sure to update your CORS settings to this DNS name.

Using a Reverse Proxy

A very common approach is to use a reverse proxy such as Nginx. Yarkon Server is a standard web server, so if this is how you handle other servers in your account, simply do the same for it.

Install a Cert on the instance

If you prefer to run the server without a proxy, you can install your SSL cert directly on it. After uploading the cert and the key files to the server, you need to update the runtime environment variables to let Yarkon Server know where to load the cert from. For the complete details, see: Yarkon Server TLS.

Customize the look and feel

Using Yarkon, you can customize the appearance, content and features available to the client application.

Branding

Yarkon Server supports branding (AKA, “white labeling”) of the Yarkon client application. Use the Branding form to define your theme, and see how the client would look like using the available preview. Once you are done, click the Update Active Theme button.

Your changes will be reflected in the client application when users log in the next time.

For an example of how a branded Yarkon would look like, check out this link.

Bucket display names

One of the issues with S3 is the requirement for bucket names to be globally unique. All the good names are already taken, it seems.

While we cannot change that, Yarkon does allow you to define a Display Name for your buckets, which will be shown in the UI instead of whatever S3 made you name the bucket. Use the Buckets form to enable this feature, then set the display name for any bucket listed.

Features

By default, there are a number of features that the Yarkon Client supports, but are disabled. For instance, some advanced bucket actions, such as tagging or changing logging are not available to end-users. If in your organization you prefer to allow some or all of these extra capabilities to your end users, use the Features form to enable them. Once you are done, click the Apply Changes button.

Your changes will be reflected in the client application when users log in the next time.

If after following these steps you are still having issues getting your server to run, please contact us.