AWS Credentials

Workbench | Enhanced Advanced

Workbench can provide user-specific AWS credentials for sessions that are tied to their Single Sign-On credentials. This has several advantages:

Workbench uses the AWS web identity federation mechanism to set these credentials in individual sessions. This mechanism is also what powers AWS integrations like IAM Roles for Service Accounts (the blessed IAM solution for Kubernetes) and GitHub Actions.

Requirements

Important

Currently, this feature is only supported for RStudio Pro and VS Code sessions.

You must:

  • Be using OpenID Connect Authentication to authenticate users.
  • Have the Job Launcher enabled and the launcher-sessions-callback-address setting configured correctly.
  • As an administrator, have the ability to create IAM resources in the AWS account(s) that users will access.

AWS Configuration

Note

This guide uses the AWS console as an example, but there are many, many ways to create AWS resources. Choose a method in line with your organization’s IT and security policies.

Create an IAM Identity Provider for Workbench

We need to teach specific AWS roles to trust the OpenID Connect tokens issued to Workbench users. Doing so requires creating an IAM identity provider in each of the AWS accounts users will access.

Using the AWS console:

  1. Navigate to the IAM service in the AWS console.
  2. Select Identity providers from the sidebar, and then click Add provider.
  3. Choose the OpenID Connect provider type.
  4. In Provider URL, enter the value of Workbench’s auth-openid-issuer option.
  5. In Audience, enter the value of Workbench’s client-id option.
  6. Click Add provider.

Create IAM Roles for Workbench Users to Assume

We also need to create one or more IAM roles to use this identity provider.

Using the AWS console:

  1. Navigate to the IAM service in the AWS console.
  2. Select Roles from the sidebar, and then click Create role.
  3. Choose the Web identity role type.
  4. Under Identity provider, select the identity provider you created above.
  5. Under Audience, select the only non-blank option (which should match what you created above).
  6. Click Next, skip adding permissions for now, and click Next again.
  7. Enter a role name and description, then click Create role.

If you inspect the newly-created role, you should be able to view the Trust relationships tab and verify that the policy looks something like the following:

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Principal": {
                "Federated": "arn:aws:iam::<account_id>:oidc-provider/<auth-openid-issuer>"
            },
            "Action": "sts:AssumeRoleWithWebIdentity",
            "Condition": {
                "StringEquals": {
                    "<auth-openid-issuer>:aud": "<client-id>"
                }
            }
        }
    ]
}

At this point, you can add permissions to the role, either by attaching existing policies or by adding an inline policy.

Exposing AWS Roles to Workbench Users

There are two existing methods to assign AWS roles to Workbench users:

  1. On a manual, per-user basis by a Workbench admin using the CLI.
  2. Via custom OAuth 2.0 claims on the OpenID Connect tokens returned by your Single Sign-On provider.

We strongly suggest using OAuth 2.0 claims, but the CLI can be used as a fallback, for testing, or to experiment with the feature among individual users before rolling it out more widely.

Important

AWS roles that are specified in an OAuth 2.0 claim when a user logs in will always overwrite anything set via the CLI. This is primarily for security purposes: the Single Sign-On provider is usually the source of truth about access control in an organization, and Workbench respects that.

OpenID Connect Configuration

Workbench checks for the aws_role_arn and aws_role_session_name claims on the OpenID Connect token it receives when a user logs in, and uses these to set the correct AWS credentials. If aws_role_arn is an array of strings (rather than a single string), then users have the ability to choose between multiple roles when starting a new session.

Attaching custom claims to ID tokens is highly provider-specific. For example, see Okta’s documentation on custom claims.

Setting AWS Roles via the CLI

You can also set AWS roles (as a comma-separated list) for users via the Workbench server management utility:

$ sudo rstudio-server set-aws-role-arns <username> \
  arn:aws:iam::012345678900:role/data-scientist,arn:aws:iam::012345678900:role/biostats-group

and to inspect the result:

$ sudo rstudio-server get-aws-role-arns <username>

or to unset them entirely:

$ sudo rstudio-server unset-aws-role-arns <username>

Refreshing AWS Credentials

OpenID Connect tokens expire, normally after an hour or so. This can be frustrating for users in active sessions, since requests to AWS will stop working after this point.

Workbench supports automatically refreshing the credentials that it provides to sessions (via the OAuth 2.0 refresh flow), but it cannot do so by default.

To request OpenID Connect tokens that can be refreshed automatically, use the auth-openid-scopes option to ask your SSO provider for an additional “refresh” token. For most providers (including Okta and Microsoft Entra ID), the scope that grants a refresh token is offline_access.

/etc/rstudio/rserver.conf
auth-openid-scopes=offline_access
Back to top