Skip to content

Creating Speedrun Roles

Jump to bottom
perpil edited this page Jun 9, 2024 · 25 revisions

Overview

To access the AWS console or get temporary credentials for the AWS CLI requires you to create AWS IAM roles and register them with Speedrun.

  1. Create a Speedrun linking role to prove you have access to an AWS account
  2. Register your AWS account with Speedrun.
  3. Create Speedrun IAM roles that specify the GitHub Organizations, Teams and Users who can assume the role and what AWS resources and actions they can access.

Create a role to prove access of AWS account

First create a role with name speedrun-account-and-role-linking. This role allows Speedrun to call GetRole on roles named speedrun-* in your AWS account. Speedrun uses it to inspect the trust policy on Speedrun roles to get the GitHub Organizations, Teams and Users that can assume a role. The trust policy only allows Speedrun to assume the role when you are authenticated with your GitHub account. This is how Speedrun proves you have access to the AWS account to register it. Only someone with access to the AWS account can create this role and associate it with your GitHub account.

Explanation of Role and Trust Policy

Role Policy

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow", // This allows speedrun
      "Action": "iam:GetRole", // To call iam:GetRole
      "Resource": "arn:aws:iam::YOUR_ACCOUNT_ID:role/speedrun-*" // On any role in your account with a name prefixed with speedrun-
    }
  ]
}

Trust Policy

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",  // This allows
      "Principal": [
        "SPEEDRUN_ACCOUNT_ID" // The Speedrun account
      ],
      "Action": "sts:AssumeRole",  // To assume this role
      "Condition": {
        "StringEquals": {
          "sts:ExternalId": [
            "YOUR_GITHUB_USERNAME" // If your GitHub username, matches one of these usernames
          ]
        }
      }
    },
    {
      "Effect": "Allow",  // In addition it allows
      "Principal": [
        "SPEEDRUN_ACCOUNT_ID"  // The Speedrun account
      ],
      "Action": "sts:SetSourceIdentity"  // To set the Source Identity when it assumes the role to your GitHub username
    }
  ]
}

Creating roles with CloudFormation (preferred)

This creates the necessary speedrun-account-and-role-linking, speedrun-ReadOnly and optionally will create the speedrun-Administrator roles using Cloudformation. Log into the AWS console in the account you want to register before running. Click through the prompts and accept that it will create IAM roles. Upon completion, proceed with register your account.

#link
https://us-east-1.console.aws.amazon.com/cloudformation/home?region=us-east-1#/stacks/quickcreate?templateURL=https://speedrun-prod-public-cfn-us-west-2.s3.us-west-2.amazonaws.com/speedrun-roles.yml&stackName=Speedrun-Roles&param_AuthorizedGitHubUsers=${user}&param_CreateAdministratorRole=~~~Create Administrator Role {"type":"checkbox", "default": false}~~~&param_EnableSpeedrunBetaEndpoint=~~~Enable Beta Endpoint {"type":"checkbox", "default": false}~~~

Creating roles with the CLI (alternate)

Note

To run the following commands, use the AWS CLI with credentials that allow iam:create-role, iam:put-role-policy and iam:attach-role-policy actions. If you don't know your AWS Account Id, follow these instructions.

This creates the necessary speedrun-account-and-role-linking role

#copy
~~~principalKey=Enable beta {"type":"checkbox", "default":false, "suppress": true, "transform":"value?'betaAndProd':'prod'"}~~~
aws iam create-role --role-name speedrun-account-and-role-linking --assume-role-policy-document '{ "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Principal": ${principal[principalKey]}, "Action": "sts:AssumeRole", "Condition": { "StringEquals": { "sts:ExternalId": "${user}" } } }, { "Effect": "Allow", "Principal": ${principal[principalKey]}, "Action": "sts:SetSourceIdentity" } ]}'
aws iam put-role-policy --role-name speedrun-account-and-role-linking --policy-name GetRole_Access_On_Speedrun_Roles --policy-document '{ "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Action": "iam:GetRole", "Resource": "arn:aws:iam::~~~awsAccountId=AWS Account Id {"transform":"value.trim()"}~~~:role/speedrun-*" } ] }'

Next create a role called speedrun-ReadOnly or speedrun-Administrator with the respective role policies. They will inherit the access permissions of the speedrun-account-and-role-linking role, so only your GitHub account can assume them. To enable other GitHub users, teams and organizations to assume roles after registering your account follow the instructions to modify the allowed ExternalIds in your role's trust policy and then sync it.

#copy
~~~principalKey=Enable beta {"type":"checkbox", "default":false, "suppress": true, "transform":"value?'betaAndProd':'prod'"}~~~
aws iam create-role --role-name speedrun-~~~roleType=Role Type {"type":"select", "options":["Administrator","ReadOnly"], "default":"ReadOnly"}~~~ --assume-role-policy-document '{ "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Principal": ${principal[principalKey]}, "Action": "sts:AssumeRole" }, { "Effect": "Allow", "Principal": ${principal[principalKey]}, "Action": "sts:SetSourceIdentity" } ]}'
aws iam attach-role-policy --role-name speedrun-${roleType} --policy-arn arn:aws:iam::aws:policy/${roleType}Access

Register Account with Speedrun

Invoke the Speedrun register/account api to register your account. Speedrun will attempt to assume the role you created above and verify that it can only assume the role when the ExternalId is set to your GitHub username.

#link
https://speedrun-api.us-west-2.nobackspacecrew.com/v1/register/~~~awsAccountId=AWS Account Id {"transform":"value.trim()"}~~~

Update settings with your account id and role name

Now set the AWS Account Id for Classic to your account id and Role to speedrun-Administrator or speedrun-ReadOnly in Speedrun settings

#settings
//This will launch settings

Creating custom roles

If you want to create a role with a custom policy, call it something prefixed with speedrun- and set the trust policy to:

#copy
{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",  // This allows
      "Principal": [
        "${speedrunProdAccountId}" // The Speedrun account
      ],
      "Action": "sts:AssumeRole",  // To assume this role
      "Condition": {
        "StringEquals": {
          "sts:ExternalId": [
            "${user}" // If your GitHub username, matches one of these usernames
          ]
        }
      }
    },
    {
      "Effect": "Allow",  // In addition it allows
      "Principal": [
        "${speedrunProdAccountId}"  // The Speedrun account
      ],
      "Action": "sts:SetSourceIdentity"  // To set the Source Identity when it assumes the role to your GitHub username
    }
  ]
}

To allow access to users, groups and orgs other than yourself, modify the allowed ExternalIds.

Addendum

Cloudformation Template Download

This helper will build a Cloudformation template with the necessary speedrun-account-and-role-linking, speedrun-ReadOnly and optionally speedrun-Administrator roles. Upload it using the Cloudformation console, call it Speedrun-Roles and click through the prompts and accept that it will create IAM roles. Upon completion, proceed with register your account.

#download {"ignoreErrors":true, "saveAs":true, "filename": "speedrun-cfn.yml.txt"}
AWSTemplateFormatVersion: '2010-09-09'
Description: Create Speedrun Roles

Resources:
  SpeedrunAccountAndRoleLinking:
    Type: AWS::IAM::Role
    Properties:
      AssumeRolePolicyDocument:
        Version: "2012-10-17"
        Statement:
          - Effect: Allow
            Principal:
              AWS:
                - '${speedrunProdAccountId}'
            Action:
              - 'sts:AssumeRole'
            Condition:
              StringEquals:
                'sts:ExternalId':
                  - '${user}'
          - Effect: Allow
            Principal:
              AWS:
                - '${speedrunProdAccountId}'
            Action:
              - 'sts:SetSourceIdentity'
      Description: Role to register this account with Speedrun and sync role permissions
      Policies:
        - PolicyName: AllowSpeedrunToGetPermissionsForSpeedrunRoles
          PolicyDocument:
            Version: "2012-10-17"
            Statement:
              - Effect: Allow
                Action: 'iam:GetRole'
                Resource: !Sub 'arn:aws:iam::${AWS::AccountId}:role/speedrun-*'
      RoleName: 'speedrun-account-and-role-linking'
  SpeedrunReadOnly:
    Type: AWS::IAM::Role
    Properties:
      AssumeRolePolicyDocument:
        Version: "2012-10-17"
        Statement:
          - Effect: Allow
            Principal:
              AWS:
                - '${speedrunProdAccountId}'
            Action:
              - 'sts:AssumeRole'
            Condition:
              StringEquals:
                'sts:ExternalId':
                  - '${user}'
          - Effect: Allow
            Principal:
              AWS:
                - '${speedrunProdAccountId}'
            Action:
              - 'sts:SetSourceIdentity'
      Description: Role to enable Speedrun to authorize users ReadOnly access to this account
      ManagedPolicyArns:
        - arn:aws:iam::aws:policy/ReadOnlyAccess
      RoleName: 'speedrun-ReadOnly'
~~~Create Administrator Role {"type":"checkbox", "transform":"value?\"  SpeedrunAdministrator:\\n    Type: AWS::IAM::Role\\n    Properties:\\n      AssumeRolePolicyDocument:\\n        Version: \\\"2012-10-17\\\"\\n        Statement:\\n          - Effect: Allow\\n            Principal:\\n              AWS:\\n                - '${speedrunProdAccountId}'\\n            Action:\\n              - 'sts:AssumeRole'\\n            Condition:\\n              StringEquals:\\n                'sts:ExternalId':\\n                  - '${user}'\\n          - Effect: Allow\\n            Principal:\\n              AWS:\\n                - '${speedrunProdAccountId}'\\n            Action:\\n              - 'sts:SetSourceIdentity'\\n      Description: Role to enable Speedrun to authorize users Administrator access to this account\\n      ManagedPolicyArns:\\n        - arn:aws:iam::aws:policy/AdministratorAccess\\n      RoleName: 'speedrun-Administrator'\\n\":''"}~~~

Getting your AWS Account Id

You can get this in the upper right of the AWS console, or by running the following command.

#copy
aws sts get-caller-identity --query "Account" --output text

Assume a role in another account

This command will setup your CLI to use a role in a different account

#copy
export $(printf "AWS_DEFAULT_REGION=${region} AWS_ACCESS_KEY_ID=%s AWS_SECRET_ACCESS_KEY=%s AWS_SESSION_TOKEN=%s" \
$(aws sts assume-role \
--role-arn arn:${partition}:iam::~~~Destination Account~~~:role/~~~orgRole=Role {"default":"OrganizationAccountAccessRole"}~~~ \
--role-session-name "CreateRoles" \
--query "Credentials.[AccessKeyId,SecretAccessKey,SessionToken]" \
--output text))

#srConfig
{
  "principal" : {
      "betaAndProd": "{ \"AWS\": [\"${speedrunBetaAccountId}\", \"${speedrunProdAccountId}\"]}",
      "prod" : "{\"AWS\": [\"${speedrunProdAccountId}\"]}"
  },
  "speedrunBetaAccountId": "531576858710",
  "speedrunProdAccountId": "453798891045"
}
Clone this wiki locally