IAM Role Method

To use the IAM Role method, you need to:

• Set browser access to the S3 bucket (CORS).

• Create data access permissions (IAM policy).

• Configure storage credentials in ICA.

• Create the IAM role and OIDC provider.

• Create a storage configuration in ICA.

• To use copy and move operations, you need to add the necessary policy statements in the S3 bucket policy.

Optionally

• It is best practice to block public access to the S3 bucket.

• If your bucket is KMS-enabled, follow the additional steps described here.

1 - Configure Bucket CORS Permission

ICA requires cross-origin resource sharing (CORS) permissions to write to the S3 bucket for uploads via the browser. Refer to Configuring cross-origin resource sharing (CORS) (expand the Using the S3 console section) documentation for instructions on enabling CORS via the AWS Management Console.

In the cross-origin resource sharing (CORS) section, enter the following content.

[
    {
        "AllowedHeaders": [
            "*"
        ],
        "AllowedMethods": [
            "HEAD",
            "GET",
            "PUT",
            "POST",
            "DELETE"
        ],
        "AllowedOrigins": [
            "https://ica.illumina.com"
        ],
        "ExposeHeaders": [
            "ETag",
            "x-amz-meta-custom-header"
        ]
    }
]

2 - Create Data Access Permission - AWS IAM Policy

ICA requires specific permissions to access data in an AWS S3 bucket. These permissions are contained in an AWS IAM Policy.

Permissions

Refer to the Creating policies on the JSON tab documentation for instructions on creating an AWS IAM Policy via the AWS Management Console (on AWS go to IAM > Policies > create policy). Use the configuration below during the process, tab one shows the code for unversioned buckets, tab two the code for versioned and versioning-suspended buckets.

Unversioned buckets

Paste the JSON policy document below. Note the example below provides access to all object prefixes in the bucket.

Replace <YOUR_BUCKET_NAME> with the name of the S3 bucket you created for ICA. Replace <YOUR_FOLDER_NAME> with the name of the folder in your S3 bucket.

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": [
                "s3:PutBucketNotification",
                "s3:ListBucket",
                "s3:GetBucketNotification",
                "s3:GetBucketLocation"
            ],
            "Resource": [
                "arn:aws:s3:::<YOUR_BUCKET_NAME>"
            ]
        },
        {
            "Effect": "Allow",
            "Action": [
                "s3:PutObject",
                "s3:GetObject",
                "s3:RestoreObject",
                "s3:DeleteObject",
                "s3:GetObjectTagging",
                "s3:PutObjectTagging"
            ],
            "Resource": "arn:aws:s3:::<YOUR_BUCKET_NAME>/<YOUR_FOLDER_NAME>/*"
        },
        {
            "Effect": "Allow",
            "Action": [
                "sts:GetFederationToken"
            ],
            "Resource": [
                "*"
            ]
        }
    ]
}

Versioned/Suspended Buckets

(Optional) Set policy name to "illumina-ica-admin-policy"

To create the IAM Policy via the AWS CLI, create a local file named illumina-ica-admin-policy.json containing the policy content above and run the following command. Be sure the path to the policy document (--policy-document) leads to the path where you saved the file:

aws iam create-policy --policy-name illumina-ica-admin-policy --policy-document file://illumina-ica-admin-policy.json

3 - Create ICA Storage Credential

To connect your S3 account to ICA, you need to add a storage credential in ICA which will generate the RoleSessionName prefix.

From the ICA home screen, navigate to System Settings > Credentials > Create > Storage Credential to create a new storage credential.

1. Select AWS_Role as type and provide a name for the storage credential.

2. Choose Generate to create the RoleSessionName prefix. Once generated, you can download it with the Download to Excel button or copy and paste it by unmasking the prefix with the eye symbol on the right. You will need this RoleSessionName in the next step.

You can only download or copy this value now during creation. Once this dialog box closes after saving, you can no longer access this value.

With the storage credentials created, a storage configuration can be created using the secret credential. Refer to the instructions to Create a Storage Configuration for details.

4 - Create AWS IAM Role

You need to create the IAM role which ICA will assume to access your S3 bucket. See this AWS documentation for instructions on creating an AWS IAM Role via the AWS Management Console. This Role will allow to delegate permissions to ICA to connect to your S3 storage for the required duration.

Open your IAM console and perform the steps below:

1. Copy the Trust Policy below to an editor and update the following values:

   • <your AWS Account ID> is your AWS client account number.

   • <region-alias> must be taken from the OIDC reference table below. For example, us-east-1 for United States.

   • <OIDC provider ID> must be taken from the OIDC reference table below. For example 10FBA7EDEB5930CCFC300EF5AC3DB2FE for United States

   • <namespace> must be taken from the OIDC reference table below. For example, use1 for United States.

   • <session name prefix> must be replaced with the session name prefix value generated in the previous step, Create ICA storage credential. Keep the -* at the end. This prefix works as an proof of identity for the requesting process and ensures the role can only be granted if the requesting process provides a session name starting with this prefix. If a process with a different session name prefix requests the role, it will be automatically denied. This is an additional layer of security.

2. Choose Roles > Create role and choose Custom Trust Policy.

3. Paste the edited Trust Policy.

4. Select the Permission Policy created in Create AWS IAM Policy.

5. Give your role a name to indicate what it is to be used for (for example Illumina_ICA_Role) and preferably a description so other users will know what the IAM role will be used for.

6. Click create to create the role.

7. Open your created role and choose Edit (top right) to set the role time to 12 hours instead of the default 1 hour.

If the role time is not set to 12 hours, the storage configuration will not go online.

1. Copy the ARN from your created role summary as this will be needed in the Storage Configuration in ICA

Trust Policy

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Principal": {
                "Federated": "arn:aws:iam::<your AWS Account ID>:oidc-provider/oidc.eks.<region-alias>.amazonaws.com/id/<OIDC Provider ID>"
            },
            "Action": "sts:AssumeRoleWithWebIdentity",
            "Condition": {
                "StringLike": {
                    "oidc.eks.<region-alias>.amazonaws.com/id/<OIDC Provider ID>:sub": "system:serviceaccount:<namespace>:irsa-<namespace>-gds*",
                    "oidc.eks.<region-alias>.amazonaws.com/id/<OIDC Provider ID>:aud": "sts.amazonaws.com",
                    "sts:RoleSessionName": "<session name prefix>-*"
                }
            }
        }
    ]
    }

Example

    {
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Principal": {
                "Federated": "arn:aws:iam::123456789:oidc-provider/oidc.eks.us-east-1.amazonaws.com/id/10FBA7EDEB5930CCFC300EF5AC3DB2FE"
            },
            "Action": "sts:AssumeRoleWithWebIdentity",
            "Condition": {
                "StringLike": {
                    "oidc.eks.us-east-1.amazonaws.com/id/10FBA7EDEB5930CCFC300EF5AC3DB2FE:sub": "system:serviceaccount:use1:irsa-use1-gds*",
                    "oidc.eks.us-east-1.amazonaws.com/id/10FBA7EDEB5930CCFC300EF5AC3DB2FE:aud": "sts.amazonaws.com",
                    "sts:RoleSessionName": "mUlP0AqBmwf9CMpjEUFY7J2z60sdveP-*"
                }
            }
        }
    ]
    }

OIDC Reference table

Region Name	OIDC provider ID	OIDC Provider ARN	Region Alias	Namespace
Australia (AU)	F4CD1AEAE6E0820F305F0230FAF6319C	arn:aws:iam:::oidc-provider/oidc.eks.ap-southeast-2.amazonaws.com/id/F4CD1AEAE6E0820F305F0230FAF6319C	ap-southeast-2	aps2
Canada (CA)	4E70F8E1A204A4B2A22E4F7BA9A06D27	arn:aws:iam:::oidc-provider/oidc.eks.ca-central-1.amazonaws.com/id/4E70F8E1A204A4B2A22E4F7BA9A06D27	ca-central-1	cac1
Germany (EU)	FD40D1945EBD71D8433A98C0CE04E625	arn:aws:iam:::oidc-provider/oidc.eks.eu-central-1.amazonaws.com/id/FD40D1945EBD71D8433A98C0CE04E625	eu-central-1	euc1
India (IN)	4C3E0D308DB6DA9625FF938C57DAB3B6	arn:aws:iam:::oidc-provider/oidc.eks.ap-south-1.amazonaws.com/id/4C3E0D308DB6DA9625FF938C57DAB3B6	ap-south-1	aps1
Japan (JP)	31343141B6F8EA41F379AE795CFA7638	arn:aws:iam:::oidc-provider/oidc.eks.ap-northeast-1.amazonaws.com/id/31343141B6F8EA41F379AE795CFA7638	ap-northeast-1	apn1
Singapore (SG)	4839F25C2D7F1765F0523616EB33711F	arn:aws:iam:::oidc-provider/oidc.eks.ap-southeast-1.amazonaws.com/id/4839F25C2D7F1765F0523616EB33711F	ap-southeast-1	aps1
South Korea (KR)	F2F941225297CB2CD58E91A45ED1362D	arn:aws:iam:::oidc-provider/oidc.eks.ap-northeast-2.amazonaws.com/id/F2F941225297CB2CD58E91A45ED1362D	ap-northeast-2	apn2
UK (GB)	CC52F03C88D774F70AB9D2E2BABDF225	arn:aws:iam:::oidc-provider/oidc.eks.eu-west-2.amazonaws.com/id/CC52F03C88D774F70AB9D2E2BABDF225	eu-west-2	euw2
United States (US)	10FBA7EDEB5930CCFC300EF5AC3DB2FE	arn:aws:iam:::oidc-provider/oidc.eks.us-east-1.amazonaws.com/id/10FBA7EDEB5930CCFC300EF5AC3DB2FE	us-east-1	use1

5 - Create OpenID Connect (OIDC) Identity Provider

An OpenID Connect identity provider is a trusted resource that provides identity tokens. This allows AWS to know which external identities are allowed to obtain the temporary roles. Here you connect your regional ICA instance (see table below) so that it can obtain the required role to access your storage. For more information on OIDC providers, see OIDC entity providers on AWS.

Open your IAM console and perform the steps below:

• Under IAM > Identity Providers > Add provider.

• Select OpenID Connect as provider and enter the Provider URL which matches your ICA/S3 location from the table below.

• For Audience, enter sts.amazonaws.com and click on Add Provider.

• Verify that the arn from the newly created OIDC provider matches the arn from the Trust Policy above.

See below for an example of how the OIDC provider and IAM role Trusted entities look

OIDC Provider Locations

Region	OIDC Provider URL
Australia (AU)	https://oidc.eks.ap-southeast-2.amazonaws.com/id/F4CD1AEAE6E0820F305F0230FAF6319C
Canada (CA)	https://oidc.eks.ca-central-1.amazonaws.com/id/4E70F8E1A204A4B2A22E4F7BA9A06D27
Germany (EU)	https://oidc.eks.eu-central-1.amazonaws.com/id/FD40D1945EBD71D8433A98C0CE04E625
India (IN)	https://oidc.eks.ap-south-1.amazonaws.com/id/4C3E0D308DB6DA9625FF938C57DAB3B6
Japan (JP)	https://oidc.eks.ap-northeast-1.amazonaws.com/id/31343141B6F8EA41F379AE795CFA7638
Singapore (SG)	https://oidc.eks.ap-southeast-1.amazonaws.com/id/4839F25C2D7F1765F0523616EB33711F
South Korea (KR)	https://oidc.eks.ap-northeast-2.amazonaws.com/id/F2F941225297CB2CD58E91A45ED1362D
UK (GB)	https://oidc.eks.eu-west-2.amazonaws.com/id/CC52F03C88D774F70AB9D2E2BABDF225
United States (US)	https://oidc.eks.us-east-1.amazonaws.com/id/10FBA7EDEB5930CCFC300EF5AC3DB2FE

6 - S3 Bucket Policy

Connecting your S3 bucket to ICA does not require any additional bucket policies.

What if you need a bucket policy for use cases beyond ICA?

The bucket policy must then support the essential permissions needed by ICA without inadvertently restricting its functionality.

Be sure to replace the following fields:

• YOUR_BUCKET_NAME: Replace this field with the name of the S3 bucket you created for ICA.

• YOUR_ACCOUNT_ID: Replace this field with your account ID number.

• YOUR_IAM_ROLE: Replace this field with the name of your IAM role created for ICA.

{
     "Version": "2012-10-17",
     "Statement": [
         {
             "Effect": "Deny",
             "Principal": {
                 "AWS": "*"
             },
             "Action": [
                 "s3:PutObject",
                 "s3:GetObject",
                 "s3:RestoreObject",
                 "s3:DeleteObject",
                 "s3:DeleteObjectVersion",
                 "s3:GetObjectVersion",
                 "s3:GetObjectTagging",
                 "s3:PutObjectTagging"
             ],
             "Resource": "arn:aws:s3:::YOUR_BUCKET_NAME/*",
             "Condition": {
                 "ArnNotLike": {
                     "aws:PrincipalArn": [
                         "arn:aws:iam::YOUR_ACCOUNT_ID:role/YOUR_IAM_ROLE",
                         "arn:aws:sts::YOUR_ACCOUNT_ID:federated-user/*"
                     ]
                 }
             }
         }
     ]
 }

In this example, restriction is enabled on the bucket policy to prevent any kind of access to the bucket. However, there is an exception rule added for the IAM role that ICA is using to connect to the S3 bucket. The exception rule is allowing ICA to perform the above S3 action permissions necessary for ICA functionalities.

Additionally, the exception rule is applied to the STS federated user session principal associated with ICA. Since ICA leverages the AWS STS to provide temporary credentials that allow users to perform actions on the S3 bucket, it is crucial to include these STS federated user session principals in your policy's whitelist. Failing to do so could result in 403 Forbidden errors when users attempt to interact with the bucket's objects using the provided temporary credentials.

7 - Block Public Access to S3 bucket (optional)

By default, public access to the S3 bucket is allowed. For increased security, it is advised to block public access with the command below. Change <YOUR_BUCKET_NAME> to the name of your S3 bucket.

aws s3api put-public-access-block --bucket <YOUR_BUCKET_NAME> --public-access-block-configuration "BlockPublicAcls=true,IgnorePublicAcls=true,BlockPublicPolicy=true,RestrictPublicBuckets=true"

To block public access to S3 buckets on account level, you can use the AWS Console on the Amazon Web Services website.

8 - Enabling Cross-Account Access for Copy and Move Operations

ICA uses AssumeRole to copy and move objects from a bucket in an AWS account to another bucket in another AWS account. To allow cross account access to a bucket, the following policy statements must be added in the S3 bucket policy (tab one below shows the code for unversioned buckets, tab two the code for versioned and versioning-suspended buckets.)

Be sure to replace the following fields:

• <ASSUME_ROLE_ARN>: Replace this field with the ARN of the cross account role you want to give permission to. Refer to the table below to determine which region-specific Role ARN should be used.

• <YOUR_BUCKET_NAME>: Replace this field with the name of the S3 bucket you created for ICA.

Unversioned

  {
        "Version": "2012-10-17",
        "Statement": [
            {
                "Sid": "AllowCrossAccountAccess",
                "Effect": "Allow",
                "Principal": {
                    "AWS": "<ASSUME_ROLE_ARN>"
                },
                "Action": [
                    "s3:PutObject",
                    "s3:DeleteObject",
                    "s3:ListMultipartUploadParts",
                    "s3:AbortMultipartUpload",
                    "s3:GetObject",
                    "s3:GetObjectTagging",
                    "s3:PutObjectTagging"
                ],
                "Resource": [
                    "arn:aws:s3:::<YOUR_BUCKET_NAME>",
                    "arn:aws:s3:::<YOUR_BUCKET_NAME>/*"
                ]
            }
        ]
    }

Versioned or Suspended

The ARN of the cross account role you want to give permission to is specified in the Principal. Refer to the table below to determine which region-specific Role ARN should be used.

Region	Role ARN
Australia (AU)	arn:aws:iam::079623148045:role/ica_aps2_crossacct
Canada (CA)	arn:aws:iam::079623148045:role/ica_cac1_crossacct
Germany (EU)	arn:aws:iam::079623148045:role/ica_euc1_crossacct
India (IN)	arn:aws:iam::079623148045:role/ica_aps3_crossacct
Indonesia (ID)	arn:aws:iam::079623148045:role/ica_aps4_crossacct
Israel (IL)	arn:aws:iam::079623148045:role/ica_ilc1_crossacct
Japan (JP)	arn:aws:iam::079623148045:role/ica_apn1_crossacct
Singapore (SG)	arn:aws:iam::079623148045:role/ica_aps1_crossacct
South Korea (KR)	arn:aws:iam::079623148045:role/ica_apn2_crossacct
UK (GB)	arn:aws:iam::079623148045:role/ica_euw2_crossacct
United Arab Emirates (AE)	arn:aws:iam::079623148045:role/ica_mec1_crossacct
United States (US)	arn:aws:iam::079623148045:role/ica_use1_crossacct

Enable Copying Object Tags (optional)

You can enable copying object tags when performing Copy, Move, Archive and Unarchive Operations within the same account or across accounts when using your own S3 storage.

If you want to use copying of your tags,

• Contact Illumina support to enable TaggingPermissionType on the ICA Storage Configuration record associated with the S3 bucket with Object tags.

• Verify you have the required permission in your policies

  • In the configuration above, the s3:GetObjectTagging and s3:PutObjectTagging are part of the IAM Policy.

  • s3:GetObjectTagging and s3:PutObjectTagging are part of the S3 Bucket policy.

  • For cross-account copy or move operations, s3:GetObjectTagging and s3:PutObjectTagging are included in the cross-account access bucket policy.

Troubleshooting

The table below show some typical error situations and how to resolve them. After performing the configuration update suggested below, perform the validate action (System Settings > Storage > select your storage > Manage > Validate) to quickly see if this has resolved your issue.

Error	Possible Solution
GetTempraryCredentaislAsync Failed with STS error	Not Authorized to perform sts:AssumeRoleWithWebIdentity can indicate an error in the address of the service account that issued the token. Please verify the line "oidc.eks.<region-alias>.amazonaws.com/id/<OIDC Provider ID>:sub": "system:serviceaccount:<namespace>:irsa-<namespace>-gds*", for errors in the namespace of your IAM Role.
Invalid Role Session Duration Set Maximum session Duration to 12 hours.	This error indicates an incorrect IAM Role session duration. By default it is 1 hour, but It must be set to 12 hours.
Access Forbidden not authorized to perform s3:GetBucketLocation	If the cause is no identity-based policy allows the s3:GetBucketLocation action, the issue might be that the permission policy attached to your role does not point to the correct bucket. Please verify the line "Resource": ["arn:aws:s3:::YOUR_BUCKET_NAME"] has the correct bucket name in the IAM Policy