Assumable Roles

Learn how to configure AWS Assumable Roles in Code Ocean.

Overview

AWS IAM roles enable administrators to control user and group access to AWS resources, such as external datasets stored in Amazon S3 buckets or data stored in Amazon Redshift, without the need to manage and distribute personal secrets, such as access keys or passwords. IAM roles have permission policies that determine what they can and cannot do in AWS. Users can assume IAM roles to gain temporary security credentials to access AWS resources.

Code Ocean AWS Assumable Roles allows administrators to assign IAM roles to Code Ocean users through SAML SSO integration with their identity provider (IdP). After creating IAM roles in AWS, admins allow Code Ocean to assume these roles on behalf of users. Finally, through SAML assertions, admins map identity provider users and groups to IAM roles. Users can then assume their assigned IAM roles in capsule and pipeline runs.

The following diagram describes the configuration process:

The following diagram describes the assume role process for a Code Ocean user:

By leveraging assumable roles, administrators can define fine-grained access permissions, enforce security best practices, and maintain control over data access. This approach enhances security, reduces the risk of unauthorized access, and promotes a least privilege access model for accessing AWS resources within Code Ocean.

Configuration

Part 1 - AWS IAM Role

• Create an IAM role (AWS guide).

• Update the role's trust policy to allow assuming the role from AWS Batch:

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Principal": {
                "AWS": "arn:aws:iam::<aws_account_id>:root",
                "Service": "ecs-tasks.amazonaws.com"
            },
            "Action": "sts:AssumeRole"
        }
    ]
}

• Create and attach any required IAM policies. The following example policies grant read/write access to S3 (AWS guide).

Read/Write to S3 Example

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": [
                "s3:GetObject",
                "s3:ListBucket",
                "s3:PutObject",
                "s3:DeleteObject"
            ],
            "Resource": [
                "arn:aws:s3:::<bucket_name>",
                "arn:aws:s3:::<bucket_name>/*"
            ]
        }
    ]
}

Read from S3 Example

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": [
                "s3:GetObject",
                "s3:ListBucket",
            ],
            "Resource": [
                "arn:aws:s3:::<bucket_name>",
                "arn:aws:s3:::<bucket_name>/*"
            ]
        }
    ]
}

• Attach Code Ocean's IAM batch job policy to the role. You can find the policy from its name [CodeOcean-Stack-Name]-BatchJobPolicy-*******. Code Ocean's batch job policy is used to grant the necessary permissions to run pipelines in Code Ocean on AWS Batch.

Part 2 - Code Ocean

• Go to the Code Ocean deployment stack under the AWS CloudFormation console, click on Update.

• Select Use current template, click Next.

• In the IAM Configuration parameter section -> Assumable IAM roles parameter, enter the IAM role ARN that you want to allow Code Ocean the assume on behalf of users. If you want to insert more than one role, use commas to delimit between them.\

  

You can preconfigure the IAM roles during stack update even if the roles do not yet exist.

Part 3 - Identity Provider

• Configure SAML SSO integration between your identity provider and Code Ocean (How To).

• Assign IAM roles to users or groups in your identity provider. This step is IdP specific. See examples below.

• Configure the Code Ocean SAML application in your identity provider to include a SAML Attribute claim with the Name attribute set to https://aws.amazon.com/SAML/Attributes/Role. This attribute contains one or more AttributeValue elements that list the IAM role to which the user is mapped by your IdP. See examples below.

Example - Microsoft Entra ID (Azure AD)

1. Open the Microsoft Entra admin center.

2. Go to Home -> Applications -> App registrations and select the Code Ocean application.

3. Go to App roles and click on Create app role. Fill in the app role display name and description. Under Allowed member types select Users/Groups. Fill in the IAM role ARN under Value and click Apply.

4. Go to Home -> Applications -> Enterprise applications and select the Code Ocean application.

5. Go to Single Sign-on and click Edit under Attributes & Claims.

6. Click on Add new claim.

7. Enter Role under Name and https://aws.amazon.com/SAML/Attributes under Namespace. Select Attribute Source and user.assignedroles Source attribute. Click Save.

4. Go back to the Code Ocean enterprise application -> Users and groups and assign app roles to users and groups. You can assign multiple IAM roles to users or groups by assigning several app roles to the same user or group.

Example - Google Workspace:

1. Open the Google Workspace Admin console.

2. Go to Directory -> Users and press on More Options -> Configure custom attributes.

3. Add a Role attribute under an AWS category:\

   
4. Go to a user profile -> User Information -> Add the IAM Role attribute under the AWS tab:\

   
5. Go to your Code Ocean custom SAML app under Web and Mobile Apps. Edit the SAML Attribute Mapping section to map the custom AWS Role attribute to an App attribute https://aws.amazon.com/SAML/Attributes/Role:\

   
6. Go back to the main Code Ocean SAML app page, click on the User access section and activate the Service status:\