Set up the IAM role and policies for Yarkon Cloud

Yarkon gets its permissions through IAM policies. It will never allow any end user more than the policy allows; since Yarkon only uses the AWS API to communicate with the AWS backend, it can never 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.

Once you are done with the Getting Started Guide, you might want to revisit the IAM structure you built, and enhance it so it can support more advanced scenarios, especially around flexible end user security settings. 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/yarkon-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 should 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, yarkon-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.

This is an advanced IAM configuration. Make sure you are familiar with IAM before using these policies.

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.