Yarkon Cloud

Overview

Yarkon Cloud is an online service allowing you the user to access your AWS S3 buckets using our HTML5 based front-end application. All you need is a web browser.

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.

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.

Getting Started

You should always start with the FREE Tier, so you can experience the product and ensure it is a good fit for your use case.

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 following step by step guide will walk you through the full installation and setup process of Yarkon Cloud.

Subscribe to Yarkon Cloud

Sign Up to the FREE Tier

To subscribe to the FREE tier, sign up from this site.

Note that your user-name should be in the format of an email - this is so that the system can send you a new temporary password in case you forget it.

When the one step sign up process is done, you should see the the overview page of the Yarkon Admin Console application.

Set up the IAM role and policies

Yarkon Cloud gets its permissions through IAM policies. It will never allow any end user more than the policy specify, and since the Yarkon cloud 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 Cloud application.

The following table explains the differences between them:

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

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

IAM Set up

As you can see in the above, there are few ways of setting up, depending on your use case and preferences. In the below, are specific guides for the different scenarios. You can definitely experiment with the settings and customize the following to best fit your own specific use case.

Create the Principal Policy

The recommended approach is to start with setting up an IAM policy. This policy can later be used with any of the security models supported by Yarkon Cloud, and should be the same for all. Follow these steps:

1. Using the AWS Console, go to the IAM service.
2. Create a new policy, name it something explicit, such as yarkon-console-policy.

The most generic policy - that is, one that would work for all security models - is:

{
    "Version": "2012-10-17",
    "Statement": [{
            "Sid": "AllowAllS3Actions",
            "Effect": "Allow",
            "Action": "s3:*",
            "Resource": "arn:aws:s3:::*"
        }, {
            "Sid": "AllowUIToDisplayIAMOptions",
            "Effect": "Allow",
            "Action": [
                "iam:List*",
                "iam:Get*"
            ],
            "Resource": "arn:aws:iam::<account-number>:*"
        }, {
            "Sid": "AllowTheRoleToGetPermissions",
            "Effect": "Allow",
            "Action": "sts:AssumeRole",
            "Resource": "arn:aws:iam::<account-number>:role/yarkons3-console-role"
        }, {
            "Sid": "AllowTheRoleToFederate",
            "Effect": "Allow",
            "Action": [
                "sts:GetFederationToken"
            ],
            "Resource": "arn:aws:sts::<account-number>:*"
        }
    ]
}

In all policies shown here, make sure to replace the <account-number> with your AWS account number. Your AWS account number is a 12 digit account ID. See this document from Amazon in case you do not have this ID handy.

Details (see the Sid attributes for reference):

AllowAllS3Actions - allows the Yarkon Cloud full access to S3. If you want to limit the usage of Yarkon in your organization to a predefined set of buckets, replace the statement with the below (and then replace the sample buckets yarkons3-finance and yarkons3-sales with yours):

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Sid": "AllowServerToIterateBuckets",
            "Effect": "Allow",
            "Action": "s3:ListAllMyBuckets",
            "Resource": "arn:aws:s3:::*"
        },
        {
            "Sid": "AllowServerToAccessSpecificBuckets",
            "Effect": "Allow",
            "Action": [
                "s3:ListBucket",
                "s3:GetBucketLocation"
            ],
            "Resource": [
                "arn:aws:s3:::yarkons3-finance",
                "arn:aws:s3:::yarkons3-sales"
            ]
        },
        {
            "Sid": "OptionalAllowServerToAutomaticallyUpdateCORS",
            "Effect": "Allow",
            "Action": [
                "s3:GetBucketCORS",
                "s3:PutBucketCORS"
            ],
            "Resource": [
                "arn:aws:s3:::yarkons3-finance",
                "arn:aws:s3:::yarkons3-sales"
            ]
        },
        {
            "Sid": "AllowUserActionsLimitedToSpecificBuckets",
            "Effect": "Allow",
            "Action": "s3:*",
            "Resource": [
                "arn:aws:s3:::yarkons3-finance/*",
                "arn:aws:s3:::yarkons3-sales/*"
            ]
        }
    ]
}

AllowUIToDisplayIAMOptions - only required when using Federated or Integrated security models. The Yarkon Cloud does not need IAM access when set to use the Shared security model. This setting has no impact on the permissions granted to end users. If you only intend to use the Shared model, you can remove it.

AllowTheRoleToGetPermissions - only required when using the Integrated security model. You can remove it if using any of the other models. Also, the role name specified, yarkons3-console-role assumes this is the name you'd be using for the IAM role required (see below). If you choose a different name, make sure to update here.

AllowTheRoleToFederate - only required when using the Federated security model. You can remove it if using any of the other models.

You can further restrict what any end user would be able to do when using the Yarkon web client application. To do so, update the statement AllowAllS3Actions (or AllowUserActionsLimitedToSpecificBuckets) to have more explicit set of permissions. For instance, if you want all users to have at most read-only access to a specific bucket, update the Action attribute in the policy to [ "s3:Get*", "s3:List*" ].

Create the Principal Role

If you plan on using the Integrated security model, you also need to create the role that would be used. If you would be using the Shared or Federated security models, you should skip this step.

To create the IAM role:

1. Using the AWS Console, go to the IAM service.
2. Create a new role, name it something explicit, such as yarkon-console-role.
3. For the Permissions, attach the policy you created to this role.
4. Edit the Trust relationship for the role using the below policy (the Sid named AllowAssumeRole is what was added):

{
    "Version": "2012-10-17",
    "Statement": [{
        "Effect": "Allow",
        "Principal": {
            "Service": "ec2.amazonaws.com"
        },
        "Action": "sts:AssumeRole"
    },
    {
        "Sid": "AllowAssumeRole",
        "Effect": "Allow",
        "Principal": {
            "AWS": "arn:aws:iam::<account-number>:root"
        },
        "Action": "sts:AssumeRole"
    }]
}

Create the Principal User

Yarkon Cloud is using AWS API credentials (often referred to as "access keys") to integrate with AWS. This final step will generate these credentials.

Important: The AWS access keys you are about to provision in the next step are used by the Yarkon Admin Console only. They are never shared with the end users. End users only get short lived temporary access credentials that are based on the permissions granted to these access keys.

To get these credentials:

1. Using the AWS Console, go to the IAM service.
2. Create a new user, name it something explicit, such as yarkon-console-user.
3. Make sure to enable Programmatic access access for this user by checking the box under AWS access type.
4. For the Permissions, attach the policy you created to this user.
5. When the user is created, you will be given the API credentials associated with it. Keep these for the next step.

Next, you want to enter the credentials into Yarkon Cloud. Use the Administration page, Access tab, and enter the credentials. Make sure to validate the credentials using the Validate button. If you are using the Integrated security model, choose it, and then select the IAM role you created from the drop down list.

You should be all set now.

Troubleshooting

AWS IAM is very powerful and flexible, but this might lead to complexity in setting up the polices. When using custom IAM policies, you might encounter cases where it is difficult to tell what would be the actual permissions granted to a user or group. In case this happens, or in case an end-user using Yarkon encounters a permission related problem that is a result of a behavior different than what the administrator intended, the best way to proceed is to use the IAM Policy Simulator made available by Amazon. Using this advanced tool, the administrator can simulate the actual permissions granted to an end-user, and apply the proper corrections.

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 Cloud, 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 Cloud.

<CORSConfiguration>
    <CORSRule>
        <AllowedOrigin>https://app.yarkons3.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>

Implement user and group level permissions

In the following we will go over the most common use cases for Yarkon Cloud, and provide sample policies to help you get started.

By default, Yarkon Cloud is using the Shared security model. It is simple, and works out of the box, without a need to make any additional updates to IAM on top of what was already done. Use the Administration page, Access tab to change the security model.

Shared Security Model

In this case, all users share the same permissions, as were defined in the principal policy of the cloud in the step IAM Set up. There is no need to make any additional updates in AWS IAM.

Federated/Integrated Security Model

In these security models, the permissions granted to a user are set by IAM policies. Later, you will associate these policies through either an IAM user, IAM group or IAM role with the users you'd be adding to Yarkon in the step Add users to Yarkon. In this step, we will be building these policies, following some common use cases.

User level permissions

To control S3 permissions at the user level, follow these steps:

1. Using the AWS Console, go to the IAM service.
2. Create a new user. Important: this user need not have any access to the AWS console, so don't check any of the boxes in AWS Access Type.
3. For the policy, use something like the below, showing how to give access to a single bucket only - just rename the <bucket-name> place-holder in the policy to your bucket name. The policy can be inline or attached.

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": [
                "s3:ListBucket",
                "s3:GetBucketLocation"
            ],
            "Resource": "arn:aws:s3:::<bucket-name>"
        },
        {
            "Effect": "Allow",
            "Action": [
                "s3:PutObject",
                "s3:PutObjectAcl",
                "s3:GetObject",
                "s3:GetObjectAcl",
                "s3:DeleteObject",
                "s3:ListMultipartUploadParts",
                "s3:AbortMultipartUpload"
            ],
            "Resource": "arn:aws:s3:::<bucket-name>/*"
        }
    ]
}

When you create the Yarkon user in the step Add users to Yarkon, in the "Add User" form, make sure to set the "IAM Type" to "User" and then select the user name you just created from the drop down.

Group level permissions - Basic

To control S3 permissions at the group level, follow these steps:

1. Using the AWS Console, go to the IAM service.
2. Create a new group.
3. For the policy, use something like the below, showing how to give access to a single bucket only - just rename the <bucket-name> place-holder in the policy to your bucket name. The policy can be inline or attached.

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": [
                "s3:ListBucket",
                "s3:GetBucketLocation"
            ],
            "Resource": "arn:aws:s3:::<bucket-name>"
        },
        {
            "Effect": "Allow",
            "Action": [
                "s3:PutObject",
                "s3:PutObjectAcl",
                "s3:GetObject",
                "s3:GetObjectAcl",
                "s3:DeleteObject",
                "s3:ListMultipartUploadParts",
                "s3:AbortMultipartUpload"
            ],
            "Resource": "arn:aws:s3:::<bucket-name>/*"
        }
    ]
}

When you create the Yarkon user in the step Add users to Yarkon, in the "Add User" form, make sure to set the "IAM Type" to "Group" and then select the group name you just created from the drop down.

Group level permissions - Advanced

If you already have a group based permission structure in AWS (or would like to build one), you can follow this alternative:

1. Using the AWS Console, go to the IAM service.
2. Create a new group.
3. Add the policy as below.
4. Create a new user and place it in the group you just created. This user will assume the permissions of the group.

When you create the Yarkon user in the step Add users to Yarkon, in the "Add User" form, make sure to set the "IAM Type" to "User" and then select the user name you just created from the drop down.

This more advanced approach allows you to "compose" user permissions using group membership, as well as override these permissions using inline and attached policies at the IAM user level.

Folder level permissions

AWS IAM allows great flexibility. The following annotated example policy shows how to create a policy that allows a user full access to a specific folder only, while disallowing any access, not even listing, of any other folder. In this example, the folder was named based on the user name, and is placed in a shared home folder.

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Sid": "AllowUserToSeeHomeBucket",
            "Action": [
                "s3:GetBucketLocation"
            ],
            "Effect": "Allow",
            "Resource": [
                "arn:aws:s3:::<bucket-name>"
            ]
        },
        {
            "Sid": "AllowSeeingUserFolder",
            "Action": "s3:ListBucket",
            "Effect": "Allow",
            "Resource": "arn:aws:s3:::<bucket-name>",
            "Condition": {
                "StringEquals": {
                    "s3:prefix": "home/john/",
                    "s3:delimiter": [
                        "/"
                    ]
                }
            }
        },
        {
            "Sid": "AllowListingOfUserFolder",
            "Action": [
                "s3:ListBucket"
            ],
            "Effect": "Allow",
            "Resource": [
                "arn:aws:s3:::<bucket-name>"
            ],
            "Condition": {
                "StringLike": {
                    "s3:prefix": [
                        "home/john/*"
                    ]
                }
            }
        },
        {
            "Sid": "AllowAllS3ActionsInUserFolder",
            "Effect": "Allow",
            "Action": [
                "s3:*"
            ],
            "Resource": [
                "arn:aws:s3:::<bucket-name>/home/john/*"
            ]
        }
    ]
}

Yarkon respects the standard AWS substitution for a user name ${aws:username}, so it you have AWS user names defined for the users, you can use a single policy to handle all users. And that's pretty cool.

Shared bucket for B2B

Suppose you are using Yarkon for your business and your end users work for vendors that are clients of yours. You want to have all your vendors using a single bucket named acme-vendors, with each having their own folder in it, but without allowing one vendor to see, or even know, about any other vendor.

While completely fulfilling this requirement is actually not possible with IAM - as any experienced AWS IAM administrator would tell you - it is definitely possible with Yarkon, thanks to the extra policy processing handled by the Yarkon server application. To illustrate how this would be done, consider the following sample structure:

• acme-vendors (bucket)
  • acme-vendor-east (folder)
    • CT (folder)
    • NJ (folder)
    • NY (folder)
  • acme-vendor-central (folder)
    • CO (folder)
    • KY (folder)
    • TX (folder)
  • acme-vendor-west (folder)
    • CA (folder)
    • OR (folder)
    • WA (folder)

And suppose you need the following roles defined:

• An administrator user to manage all vendors, with full access to all folders.
• An administrator user for each vendor, with full access to the vendor folder and its sub-folders.
• An end user for each vendor, with limited read only access to the vendor folder and its sub-folders.

The following policies will get the job done (shown for acme-vendor-east only, it is similar for the others).

The policy for the system administrator:

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Sid": "AllowUserToSeeLocationOfBucket",
            "Action": [
                "s3:GetBucketLocation"
            ],
            "Effect": "Allow",
            "Resource": [
                "arn:aws:s3:::acme-vendors"
            ]
        },
        {
            "Action": "s3:ListBucket",
            "Effect": "Allow",
            "Resource": "arn:aws:s3:::acme-vendors"
        },
        {
            "Effect": "Allow",
            "Action": [
                "s3:*"
            ],
            "Resource": [
                "arn:aws:s3:::acme-vendors/*"
            ]
        }
    ]
}

The policy for the vendor's administrator:

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Sid": "AllowUserToSeeLocationOfBucket",
            "Action": [
                "s3:GetBucketLocation"
            ],
            "Effect": "Allow",
            "Resource": [
                "arn:aws:s3:::acme-vendors"
            ]
        },
        {
            "Sid": "AllowRootAndHomeListingOfVendorsBucket",
            "Action": "s3:ListBucket",
            "Effect": "Allow",
            "Resource": "arn:aws:s3:::acme-vendors",
            "Condition": {
                "StringEquals": {
                    "s3:prefix": "acme-vendor-east/",
                    "s3:delimiter": [
                        "/"
                    ]
                }
            }
        },
        {
            "Sid": "AllowListingOfUserFolder",
            "Action": [
                "s3:ListBucket"
            ],
            "Effect": "Allow",
            "Resource": [
                "arn:aws:s3:::acme-vendors"
            ],
            "Condition": {
                "StringLike": {
                    "s3:prefix": [
                        "acme-vendor-east/*"
                    ]
                }
            }
        },
        {
            "Sid": "AllowAllS3ActionsInUserFolder",
            "Effect": "Allow",
            "Action": [
                "s3:*"
            ],
            "Resource": [
                "arn:aws:s3:::acme-vendors/acme-vendor-east/*"
            ]
        }
    ]
}

The policy for the vendor's end user:

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Sid": "AllowUserToSeeLocationOfBucket",
            "Action": [
                "s3:GetBucketLocation"
            ],
            "Effect": "Allow",
            "Resource": [
                "arn:aws:s3:::acme-vendors"
            ]
        },
        {
            "Sid": "AllowRootAndHomeListingOfVendorsBucket",
            "Action": "s3:ListBucket",
            "Effect": "Allow",
            "Resource": "arn:aws:s3:::acme-vendors",
            "Condition": {
                "StringEquals": {
                    "s3:prefix": "acme-vendor-east/",
                    "s3:delimiter": [
                        "/"
                    ]
                }
            }
        },
        {
            "Sid": "AllowListingOfUserFolder",
            "Action": [
                "s3:ListBucket"
            ],
            "Effect": "Allow",
            "Resource": [
                "arn:aws:s3:::acme-vendors"
            ],
            "Condition": {
                "StringLike": {
                    "s3:prefix": [
                        "acme-vendor-east/*"
                    ]
                }
            }
        },
        {
            "Sid": "AllowReadOnlyS3ActionsInUserFolder",
            "Effect": "Allow",
            "Action": [
                "s3:head*",
                "s3:get*"
            ],
            "Resource": [
                "arn:aws:s3:::acme-vendors/acme-vendor-east/*"
            ]
        }
    ]
}

Note that the Yarkon Web Application, when used by an end user that belongs to this vendor, will see the folder acme-vendor-east as the root, and not the bucket.

You can use these policies as a basis for more advanced variations of this approach.

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 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, you also 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. The credentials will be communicated to the user using the email entered as the username.

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, welcome emails will not be 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.

Customize the look and feel

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

Branding

Yarkon Cloud 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.