Yarkon Server – Set up the IAM role and policies

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 Server has three different security models it can use:

  • 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:

ModelDescriptionBenefitsChallenges
Shared
  • All end users in your account have the same access permissions.
  • Simple to implement.
  • Cannot have different permissions for different users.
Federated
  • Different users can have different permissions, using IAM users, groups and roles.
  • Very flexible, complete control over users permissions.
  • Can be used cross account.
  • Requires good knowledge of IAM.
  • Cannot be on EC2 with IAM role.
Integrated
  • Different users can have different permissions, using IAM users, groups and roles.
  • Very flexible, complete control over users permissions.
  • Does not require API keys, therefore most secure.
  • Requires good knowledge of IAM.
  • Must use EC2 with IAM role.

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

ModelPrincipalHow to assign
Shared
  • IAM user with API credentials, or
  • EC2 only, with IAM role
  • Provide credentials through environment variables, or
  • EC2 only: Run the instance with the IAM role.
Federated
  • IAM user with API credentials
  • Provide credentials through environment variables, or
  • EC2 only: Run the instance with the IAM role.
Integrated
  • EC2 only, with IAM role
  • EC2 only: Run the instance with the IAM role.

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

ModelEnd users permissionsHow to assign
SharedSame as PrincipalAutomatic, no action needed
FederatedBased on IAM user, group or roleAssociate user with permissions using Yarkon Server.
IntegratedBased on IAM user, group or roleAssociate user with permissions using Yarkon Server.

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 the server, 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 Server, 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>:*"
        }, {
            "Sid": "AllowUsingSESForEmail",
            "Effect": "Allow",
            "Action": "ses:SendRawEmail",
            "Resource": "*"
        }
    ]
}

Details (see the Sid attributes for reference):

AllowAllS3Actions – allows the Yarkon Server 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:

{
    "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 Server 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. Note that you have to replace the placeholder <account-number> with your AWS account number (it is usually a 12 digit number).

AllowTheRoleToGetPermissions – only required when using the Integrated security model. You can remove it if using any of the other models. Note that you have to replace the placeholder <account-number> with your AWS account number (it is usually a 12 digit number). 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. Note that you have to replace the placeholder <account-number> with your AWS account number (it is usually a 12 digit number).

AllowUsingSESForEmail – only required if you intend to use Email integration, and would be using AWS SES as your mail server. If you do not intend to integrate Yarkon Server with an email server, or will be using a standard SMTP server, you can remove this section.

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*" ].

EC2 Instance with an IAM Role

When using an EC2 instance, if you can run it with a IAM role, it is the simplest and most secure way – because no API credentials are required, hence there is no risk these credentials would be compromised.

When you launch the instance, make sure to associate the aforementioned Yarkon IAM role just created with the instance. For more on IAM IAM roles, read this document from Amazon.

If you are using an EC2 instance, but cannot associate it with the Yarkon IAM role, follow the instructions below for the setup for Non EC2 server.

The next and final step is 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). Note that you have to replace the placeholder <account-number> with your AWS account number (it is usually a 12 digit number):
{
    "Version": "2012-10-17",
    "Statement": [{
        "Sid": "",
        "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"
    }]
}

Launch the EC2 instance with this IAM role.

Non EC2 server

When using a unix server (or an EC2 instance without an IAM role), credentials are provided to the application using the environment.

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.
You will only need to use these access credentials once, during the set up of Yarkon, as described later on in this guide.

The first step is 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 present the credentials to the running application. There are two ways to accomplish that, choose whichever is simpler for your use case.

  1. Use a config file. The file should be placed in the folder ~/.aws/credentials and include the API credentials created. If you are not familiar with AWS credential files, follow this document from Amazon.
  2. Provide the environment variables when launching the application. This topic will be covered in the section Run the instance for the first time, and you can also review this document from Amazon.

Next Step – Run the instance for the first time
Go back to Getting Started