If you publish your stories directly from Shorthand to an Amazon service, you will need to provide Shorthand with your choice of one of two Amazon identification credentials: either access/secret keys or IAM Role authentication. We recommend IAM Role authentication as it is the more secure of the two methods.
What is IAM Role authentication?
The role-based authentication method involves Shorthand creating an AWS role that you grant access to your Amazon S3 bucket.
This role exists solely for a specific S3 publishing configuration (a new role is generated for each configuration).
Unlike conventional access/secret keys, this AWS role can only be utilized by Shorthand (conventional keys can be wielded by whomever holds them).
If you already have a publishing configuration that uses access/secret keys, you do not need to change your existing S3 publishing configurations, however we strongly recommend changing to IAM role-based authentication as the minimal effort will yield a greater increase in security.
How to set up an S3 Publishing Configuration with IAM Role Authentication
If you are the 'Owner' or 'Admin' of your Shorthand workspace, you'll find your publishing options by clicking your user avatar on the right-side of the dashboard and selecting "Publishing Options":
From the Workspace settings panel that appears, in the section labelled "Workspace publishing options", create a new Amazon S3 configuration by clicking the green button (or, if you are changing an existing configuration, there will be a button labelled "EDIT" rather than "CREATE").
Within the form, provide details to define this publishing location (a meaningful name and description, etc) and choose the "IAM Role" option listed under "AUTHENTICATION METHOD".
Upon selecting "IAM Role" you'll notice the read-only IAM Role ID field, which will be auto-populated after the form is saved.
Save the form, and you'll be prompted with the generated IAM Role ID (What Amazon also calls an ARN).
The generated role ID is Shorthand's access authorisation to your S3 bucket.
You may wish to press the "COPY" button next to the ID, as the next step will involve placing that long ID string into a form at AWS.
Log in to your AWS account and locate where to set permissions for your S3 bucket:
Scroll down and edit the bucket policy.
...and then in the bucket policy add the following (replacing the highlighted parts with the IAM Role ID you copied from the form at Shorthand, along with the bucket name you supplied in that form):
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Principal": {
"AWS": "[REPLACE THIS WITH IAM ROLE ID]"
},
"Action": [
"s3:ListBucket",
"s3:GetBucketAcl"
],
"Resource": [
"arn:aws:s3:::[REPLACE THIS WITH BUCKET NAME]"
]
},{
"Effect": "Allow",
"Principal": {
"AWS": "[REPLACE THIS WITH IAM ROLE ID]"
},
"Action": [
"s3:PutObject",
"s3:PutObjectAcl",
"s3:GetObject",
"s3:GetObjectAcl",
"s3:DeleteObject"
],
"Resource": [
"arn:aws:s3:::[REPLACE THIS WITH BUCKET NAME]/*"
]
}
]
}
NOTE: If you haven't already disabled the strict "Block Public Access" settings you will need to do so in order for your published stories to be viewable. The option is provided directly above the policy editing.
Once the policy is configured, return to Shorthand and press the "VERIFY" button located under the newly created publishing configuration.
The verification process will simulate publishing to the bucket to confirm that the right permissions are set at AWS. If successful, the blue setup prompt will disappear and be replaced by a notification that the bucket is ready for publishing.