Yarkon Server is a self-hosted solution, meaning that you (the customer) host all components of the system in your AWS account. It is a completely stand alone solution, that you install on an EC2 instance within your VPC, and from thereon operates independently. Yarkon Server runs on a single instance in your account, without any external dependencies.
Use Yarkon to upload, download and share documents, manage buckets and create folders – anything that you normally do with S3 – with a fluent, intuitive and feature rich user experience, similar to what you have when using your PC. Drag & drop, context menus, copy-paste, multiple upload/download, it is all there.
Yarkon enables everyone in your organization to use your S3 storage without provisioning access to the AWS console/account and without sharing any sensitive keys with end users; all that while strictly following the permissions granted by the account administrator using the IAM service, and with full support to groups and roles.
Yarkon Server does not require access to any AWS access keys. The server gets its permissions through its assigned IAM role. This approach ensures that your security credentials cannot be accessed, even if the Yarkon Server is somehow compromised. End-users never have to enter AWS access keys, or even be assigned any.
The system consists of two main modules:
- Yarkon Web Client application, the front end used by all end-users.
- Yarkon Admin Console server, responsible for user permission management, and for serving the HTML files to the end clients. This module is hosted in our cloud.
To learn more about the client experience with Yarkon, please use the Demo Application - it is using the infrastructure of Yarkon Cloud and is functionally identical to it.
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.
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:
- 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.
We currently offer three subscription levels:
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 necessary, unless when using the Proxy mode, 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
x-amz-server-side-encryption. These are required for properly handling downloads and encrypted documents.
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.
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>
When running Yarkon Server in Proxy mode as is described in the VPC Endpoints Configuration, you do not need to enable CORS for your buckets. If for whatever reason you decide to not enable CORS, you will have to use the Proxy mode to allow your end users to access S3 buckets.
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:
|Security Model||Description||Use Case|
|Shared Security||All end users have the same S3 permissions. These permissions are defined by the security credentials provided to Yarkon, through an IAM user.||This model is most applicable for smaller organizations where all users have the same access level. Another common use case is when setting up Yarkon on a departmental level, and all users are granted similar permissions.|
|Integrated Security||Different users have different S3 permissions. You can define user access at the user, group or role level.||This model is most applicable for larger organizations where users have specific permissions, based on their job requirements. Another common use case is when Yarkon is used to provide access to external users that should have limited access compared to internal users.|
|Federated Security||Different users have different S3 permissions. You can define user access at the user, group or role level.||This model is most applicable for larger organizations where users have specific permissions, based on their job requirements. A common use case is when Yarkon is used as a Private Hosting solution and you want to control a AWS account that is not the same as the one where the instance is running.|
For more, please checkout the security models documentation page.
IAM Set up
When you deploy Yarkon 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 that 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. Please follow the section Federated/Integrated Security Model in the Yarkon Cloud documentation for the full details.
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.
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.
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:
- Turn on an ELB (or an ALB).
- Define a TCP route from port 443 (default HTTPS) to port 80 (default HTTP) on the instance.
- Set up the cert - either an AWS provisioned, or upload yours.
- Close any direct access to the instance on port 80, except traffic from the load balancer.
- Set up a DNS name for the load balancer.
- 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.
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.
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.