IN THIS ARTICLE
Configuring AWS Credentials
These instructions assume that you have (or will have) administrative access to an AWS account. For more information, see the for instructions on creating an account, the guide and . If you already have an AWS account, but you do not have administrative access to it, see your AWS account administrator.
The expectation is that, by the end of this guide and its linked resources, you will:
- Understand how to set up AWS credentials for RUNLOOP.
- Understand how to control permissions for AWS users via policies and groups.
- Understand steps to take around team setup.
- Have a sense about how to manage credentials during the development and release/distribution phases of your project.
To set up an individual user, you will need to:
- Create the required IAM user.
- Add any AWS permissions required.
- Export the credentials to the local environment.
To set up credentials for a team, you will need to:
- Set up users and IAM credentials.
- Create user groups.
- Add AWS IAM users to the appropriate user group.
- Add AWS permissions to the user groups.
Once the preceding tasks are complete, users can export their credentials to their local environment.
Working with AWS credentials
You will need to provide AWS credentials for users. You can choose between short-term and long-term credentials. Long-term credentials are convenient during the development process. They’re easier to configure, but you need to be careful they are kept secure. Short-term credentials are generally recommended when you distribute your builds to external users because they have a finite lifetime. For more information, refer to the AWS guide on .
To provision long-term credentials, create an AWS Identity and Access Management (IAM) user with programmatic credentials and follow the section of this guide covering setting up AWS credentials as an individual that user for RUNLOOP. See the general AWS guide on for more information.
To provide short-term credentials, use or to generate . The AWSClientAuth Gem provides configuration points for using Amazon Cognito in RUNLOOP.
To provide access via IAM roles, see the documentation for more information and follow for setup information.
It is strongly recommend to not use your AWS account root user for day-to-day tasks. Instead, create users or roles in IAM with the required permissions for your use cases. Best practice is to change users’ access keys regularly and follow the practice of least-privileges. For more information on managing access keys, see in the AWS IAM User Guide.
Setting up AWS credentials as an individual
This section assumes you have an set up in your AWS account.
The steps in this guide cover how to use an IAM user with long term programmatic credentials to use in RUNLOOP. If you don’t have IAM access keys configured, use the AWS Console to generate and download new access keys for an existing or new IAM user using the steps shown in the AWS reference guide for .
If you want to use short-term credentials for working with AWS, please see setup information in the AWSClientAuth Gem.
Choose from the following options to set up a user’s AWS credentials for use in RUNLOOP. If you are using remember to set the profile in the project settings.
Option 1: Create a named profile using the AWS CLI
RUNLOOP recommends using the
(CLI) (version 2) to manage the import and configuration of AWS credentials. If you have not configured credentials or a region on your computer, the easiest way to satisfy this requirement is to use the AWS configure command:
aws configure
Using this command you can provide your AWS access key ID, secret access key, and default region manually when prompted.
Alternatively, when you create new access keys for a user, you are given the option to download the keys as a CSV. You can then automatically import them using the AWS import CLI command (requires AWS CLI version 2):
aws configure import --csv file://credentials.csv
This will create a named profile based on the name of the IAM user in your credentials file.
You can control which profile is used by default in the AWS CLI either by setting a [default] or through the use of the
environment variable.
For more information on using AWS CLI configure commands, see in the AWS CLI User Guide.
You can also utilize IAM roles by defining role based profiles. Refer to for information.
Option 2: Configure local credentials using config files
If you have an automated process or other provisioning mechanism, you can place pre-configured user credentials in the standard AWS config files.
Manually create or edit the ~/.aws/config and ~/.aws/credentials files (on macOS or Linux) or %USERPROFILE%\.aws\config and %USERPROFILE%\.aws\credentials files (on Windows) to include the credentials and a default region.
First, in ~/.aws/config or %USERPROFILE%\.aws\config set your default region:
[default]
region=us-west-2
Second, in ~/.aws/credentials or %USERPROFILE%\.aws\credentials set up
as needed. You can configure a default profile that is used when no profile is explicitly referenced in commands.
[default]
aws_access_key_id=AKXXXXXXXXXXX
aws_secret_access_key=xxXXXXXXBF/2Zp9Utk/h3yCo8nvbEXAMPLEKEY
Option 3: Use environment variables to provide credentials
You can also provide AWS credentials using environmental variables:
| Variable | Description |
|---|---|
AWS_ACCESS_KEY_ID | The AWS access key id to use. |
AWS_SECRET_ACCESS_KEY | The AWS secret key id to use. |
AWS_SESSION_TOKEN | The AWS session token to use (optional). If you are working with short-term credentials you will need to include the session token. |
AWS_DEFAULT_REGION | The default AWS region. |
For more information on using environment variables for credentials, see in the AWS CLI User Guide.
Option 4: Use RUNLOOP console variables to provide credentials
This method will only work when using an RUNLOOP runtime binary (Launcher and Editor). Credentials can be provided directly by setting the cl_awsAccessKey and cl_awsSecretKey Console Variables (CVARs), as follows:
Editor.exe +cl_awsAccessKey AKXXXXXXXXXXX +cl_awsSecretKey xxXXXXXXBF/2Zp9Utk/h3yCo8nvbEXAMPLEKEY
Note: Because of a console variable string size limitation, providing a session token is not currently supported.
| CVar | Description |
|---|---|
cl_awsAccessKey | The AWS access key id to use. |
cl_awsSecretKey | The AWS secret key id to use. |
Setting a default profile to use in RUNLOOP
If your development machine is configured with named profiles in your local AWS credentials file, you can set a profile to be automatically used with RUNLOOP on a per-project basis. This profile should be set in the AWS Core configuration settings file and will then be used by default each time the RUNLOOP Editor starts.
You can use the following commands to list your defaults and all named profiles (requires AWS CLI version 2):
// Show the current defaults.
aws configure list
// Show all the named profiles.
aws configure list-profiles
Controlling user permissions
All AWS IAM users are given permissions through the attachment of managed or inline IAM polices. See .
We recommend that you adhere to the following guidelines:
- Only use an admin user when absolutely necessary, such as when deploying and provisioning AWS resources. An admin user is defined here as a user with full permissions on an AWS account.
- Grant on your AWS users, so they only have the minimum set of permissions on specific resources they require. This is controlled through setting of managed IAM policies and other mechanisms.
- Update managed policies to grant or revoke the appropriate permissions as you add and remove AWS resources.
Creating IAM user groups
To make managing permissions easier, we recommend that you create . User groups let you specify permissions for multiple users at a time, which can make it easier to manage the permissions for groups of users.
Create user groups using the AWS Console, the AWS CLI, AWS CloudFormation templates or using the AWS Cloud Development Kit (AWS CDK). We recommend you create at least two user groups to work with AWS in RUNLOOP:
- Admins - These are the administrators who own and manage AWS resources. Typically, they will perform updates and manage key resources.
- Users - These are the users who can take action on the resources, as part of normal gameplay or a simulation.
To create a user group using the AWS Console
- Open the IAM console from .
- In the IAM console’s navigation pane, choose Groups.
- Choose Create New Group.
- On the Set Group Name page, for Group Name, enter a name for the new group.
- Choose Next Step.
- On the Attach Policy page, either choose Next Step without attaching any policies, or attach any current policies that are relevant to the group.
- Choose Create Group.
To create a user group using the AWS CLI
- Install and configure the AWS CLI as above, see .
- Generate a user group.
aws iam create-group --group-name MyUserGroup
To create user groups using the AWS CDK examples
The AWS CDK stacks defined in the AWS Core Gem will autogenerate sample Admins and Users user groups for you. By default, these groups are named RUNLOOP-AWS-PROJECT-Admins and RUNLOOP-AWS-PROJECT-Users.
See the AWS CDK setup instructions for more details.
Adding users to a user group
You can add users to IAM User Groups using either the AWS Console or the AWS CLI. See for full details.
You can quickly add users via the CLI as follows:
aws iam add-user-to-group --group-name MyGroup --user-name MyNewUser
Attaching permissions to a user group
You can attach IAM policies to a user group to control the permissions they have access to. This can be done using either the AWS Console, the AWS CLI, AWS CloudFormation template or with the AWS CDK. See to attach permissions using the AWS Console or AWS CLI.
Working with RUNLOOP AWS CDK examples
If you deploy both the Core and example stack from the AWS Core Gem you can see examples of user permissions that were automatically generated by the generate_user_policy and generate_admin_policy functions. The user permissions are automatically attached to the user groups by a call to __grant_access.
See the AWS CDK documentation for more details.
The AWS feature gems, such as AWS Metrics Gem, during deployment automatically create managed policies for users and admins that can then be attached manually to the appropriate user group.
To attach managed policies to user groups using the AWS Console
- Open the AWS Console at .
- Navigate to the desired stack in a region.
- Choose the Resources tab.
- Look for resources with the type
AWS::IAM::ManagedPolicyin the stack and record the policy name. - Open the IAM console at .
- Select user groups.
- Choose a user group.
- Select permissions, then choose add permissions, then select attach polices.
- Filter for policy to attach and select it.
- Choose Attach Policies.
To attach managed policies to user groups using the AWS CLI
- in your AWS account.
- in a specific stack.
- Search for the
AWS::IAM::ManagedPolicyresources and record the physical ID of the resource, which will be in the form of the policy ARN. - to the user groups as desired.
Example CLI commands:
aws cloudformation describe-stacks --region <region>
aws cloudformation list-stack-resources --stack-name <feature stack> --region <region>
aws iam attach-group-policy --group-name <group name> --policy-arn <policy arn>
Setting up credentials for a team
Note:You can use instead of IAM to enable multiple users within a single AWS account to work with RUNLOOP. In this usage pattern, the single AWS account serves as the management account for an organization in AWS Organizations, and that organization has no member accounts. To use AWS SSO, follow the guide and the instructions in . For related information, see the and guides.
To set up a team, repeat the instructions for individual users above to:
- Create relevant IAM user groups. See the Creating IAM user groups instructions in this topic.
- Provide any permissions required to access AWS resources to those user groups.
- Create any IAM users and distribute credentials using the instructions above for individual users as a guide.
- Add users to the relevant user groups to grant them permissions they require.
Please read Working with AWS credentials to decide the right method for providing AWS IAM credentials for your RUNLOOP project.
Running your RUNLOOP project on Amazon EC2
If you are running your project on Amazon EC2, you can utilize the to authenticate calls made to AWS. Using the IAM role from the Amazon EC2 instance profile lets you avoid configuring AWS credentials on the machine through less secure methods like supplying them as user data at deploy time or remotely accessing the machine to manually set up a profile.
To use Amazon EC2 instance role credentials with your project:
- Create an Amazon EC2 through the or AWS CLI. An instance profile is essentially a container for an IAM role that your Amazon EC2 instance can assume to make calls to AWS.
- Provide the associated IAM role with any required to access the AWS resources that your RUNLOOP project needs.
- Attach the instance profile to the Amazon EC2 instance(s) running your RUNLOOP project. You can attach it to a new instance or you can .
The AWS Core Gem also requires that the AllowAWSMetadataCredentials setting be set to true before it will query the
for credentials. By default, it is set to false to prevent unwanted calls to the Amazon EC2 IMDS endpoint when running your RUNLOOP project locally or on non-Amazon EC2 compute.
Note:If the environment variableAWS_EC2_METADATA_DISABLEDis set totrue, this will override theAllowAWSMetadataCredentialssetting and you will be unable to use credentials from the instance profile. For more information about this environment variable, refer to the HttpRequestor Gem.
To turn on AllowAWSMetadataCredentials in AWSCore:
Add it to your
awscoreconfiguration.setregproject settings file at the following path:{ "Amazon": { "AWSCore": { "ProfileName": "testprofile", "ResourceMappingConfigFileName": "default_aws_resource_mappings.json", "AllowAWSMetadataCredentials": true, // example of value set to "true" } } }OR set it to true via the command line when directly invoking the launcher:
./MyGame.ServerLauncher.exe --regset="/Amazon/AWSCore/AllowAWSMetadataCredentials=true"
Additional resources
- For general help with AWS CLI configuration commands, see .
- For help with configuring credentials for the AWS C++ SDK, see .
- For help with managing permissions for AWS resources, see .
- See the IAM documentation for help with and .