- IAM RolesAnywhere Examples
Our intended audience assumes an existing understanding of AWS IAM Services, and experience with the provided template configuration languages.
No experience/knowledge with tls certificates is required, although it is useful for providing enhanced security.
We recommend fully reviewing IAM RolesAnywhere Security documentation to create a mature and secure solution
AWS Identity and Access Management Roles Anywhere provides a secure way for your workloads such as servers, containers, and applications that run outside of AWS to obtain temporary AWS credentials. Your workloads can use the same IAM policies and roles you have for native AWS applications to access AWS resources. Using IAM Roles Anywhere eliminates the need to manage long-term credentials for workloads running outside of AWS.
To use IAM Roles Anywhere, your workloads must use X.509 certificates issued by their certificate authority (CA) . You register the CA with IAM Roles Anywhere as a trust anchor to establish trust between your public key infrastructure (PKI) and IAM Roles Anywhere. If you don't manage your own PKI system, you can use AWS Certificate Manager Private Certificate Authority to create a CA and then use that to establish trust with IAM Roles Anywhere.
This guide describes the IAM Roles Anywhere operations that you can call programmatically. For more information about IAM Roles Anywhere, see the IAM Roles Anywhere User Guide.
| Resource | Description | Default value | Adjustable |
|---|---|---|---|
| Combined rate of trust anchor requests | The maximum transactions per second for ListTrustAnchors, CreateTrustAnchor, GetTrustAnchor, UpdateTrustAnchor, DeleteTrustAnchor, EnableTrustAnchor, and DisableTrustAnchor requests combined. | 1 per second | Yes |
| Combined rate of profile requests | The maximum transactions per second for ListProfiles, CreateProfile, GetProfile, UpdateProfile, DeleteProfile, EnableProfile, and DisableProfile requests combined. | 1 per second | Yes |
| Combined rate of subject requests | The maximum transactions per second for ListSubjects and GetSubject requests combined. | 1 per second | Yes |
| Combined rate of tagging requests | The maximum transactions per second for TagResource, UntagResource, and ListTagsForResource requests combined. | 1 per second | Yes |
| Combined rate of CRL requests | The maximum transactions per second for ListCrls, GetCrl, ImportCrl, UpdateCrl, DeleteCrl, EnableCrl, and DisableCrl requests combined. | 1 per second | Yes |
| Rate of CreateSession requests | The maximum transactions per second for CreateSession requests. | 10 per second | Yes |
| Trust anchors | The maximum number of trust anchors that you can create within an account. | 50 | Yes |
| Profiles | The maximum number of profiles that you can create within an account. | 250 | Yes |
| CRLs per trust anchor | The maximum number of Certificate Revocation Lists (CRLs) that you can create per trust anchor within an account. | 2 | No |
| Certificates per trust anchor | The maximum number of certificates that you can create per trust anchor within an account. | 2 | No |
This repo will include code examples for IAM RolesAnywhere deployment with:
- OpenSSL Bash Scripts to generate Certificates
- AWS CLI Deployment Sample
AWS CloudFormation Sample- Terraform AWS Provider Sample
- Bash IAM RolesAnywhere Authentication Sample
This repo is created to provide a set of sample code and scripts, that can be copied and repurposed for use within environments, and pipelines.
For this reason, there is no basic "install process", only guidelines for use.
| Directory | Description |
|---|---|
| aws_cli | AWS CLI scripts for creating IAM RolesAnywhere Resources |
| cloudformation | AWS Cloudformation Template to create IAM RolesAnywhere Resources |
| create_cert | Bash script to create Certificates for IAM RolesAnywhere Authentication |
| download_signing_helper | Bash script to dowload Sign-In Helper app |
| terraform | Terraform AWS Provider configuration files to create IAM RolesAnywhere Resources |
The directory contains two bash scripts.
This script references a number of input variables to create a self-signed certificate.
| Variable | Description |
|---|---|
| VAR_PREREQ_SOFTWARE | List of packages to check for, default is only openssl |
| VAR_CERT_COUNTRYNAME | Two digit country name (i.e. US, or CA) |
| VAR_CERT_STATEPROVINCE | Full name of State or Province |
| VAR_CERT_LOCALITY | Locality, such as city or area |
| VAR_CERT_ORGNAME | Organizations full Name |
| VAR_CERT_OU | Organizational Unit/Department |
| VAR_CERT_COMMONNAME | Common Name, does not have to be a fqdn for this purpose |
| VAR_CERT_CN | fqdn |
| VAR_CERT_OU2 | Additional OU that is used for authentication validation (i.e. home) |
The certificate is created by providing variables and executing the script. The sample scripts/configuration files included in this repository may reference the created artifacts, however it is recommended that the script be cusomtized with desired output location.
Simple script that will remove any generated certificate files from testing.
Q: Why do we include AWS CLI, when our preferred method is using IaC?
A: There are many reasons why we include CLI, but primarily our IaC development process with new (or new to us) API's/Services is to experiment with CLI first, and then create Cloudformation/Terraform templates. This way our testing is abstracted from potential tooling issues, and coverage from IaC. At times coverage is lacking from IaC, and although CLI does not provide management of deployed resources, it does at least provide a versioned approach with consistant and repeatable use.
IAM RolesAnywhere requires a custom trust policy to be used.
For our example, we have added a Condition for StringEquals to ensure our certificate for use contains the OU:home as an example of how we can lock down acccess based on certificate content. This example is specific to our test case, is not required, and can be easily customized to meet your requirements.
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Principal": {
"Service": "rolesanywhere.amazonaws.com"
},
"Action": [
"sts:AssumeRole",
"sts:TagSession",
"sts:SetSourceIdentity"
],
"Condition": {
"StringEquals": {
"aws:PrincipalTag/x509Subject/OU": "home"
}
}
}
]
}This is a simple deployment script, for deployment. It accepts a small set of variables to generate the requried resources.
| Variables | Description |
|---|---|
| VAR_IAMROLENAME | Role-name to be used. This is repurposed with suffixes add for reference in the script |
| VAR_509CERT | This should contain your rootCA Private Certificate. It should start with the -----BEGIN CERTIFICATE----- statement and end with -----END CERTIFICATE----- |
| VAR_IAMPOLICIES_LIST | A list of managed IAM Policies to attach to the IAM Role |
| VAR_IAMPATH | The path for the role. It must begin and end with a forward slash |
| VAR_IAMROLEDESCRIPTION | A short, friendly desription for the Role. i.e. "Dev Pipeline Role" |
The sample script will then:
- Create the IAM Role
- Attach the IAM Policies to the IAM Role
- Create the RolesAnywhere Trust Anchor with the x509 certificate data
- Create the RolesAnywhere Profile and associates it with the IAM Role
The Terraform samples utilizes three providers to create an end-to-end deployment skeleton:
| Filename | Description |
|---|---|
| iam.tf | Configuration file that creates IAM and IAM RolesAnywhere resources |
| my.tfvars.sample | Sample of tfvars for consumption by terraform |
| terraform.tf | Terraform and Providers configuration |
| tls.tf | Configuration file that creates the certificates |
| variables.tf | Configuration file that defines the variables |
Certificate Management is handled via the tls.tf configuration file, creating self-signed certificates.
We output three key certificate files. Two files are use by the aws_signing_helper helper binary, and one file is consumed within the terraform.
The direct export of files to local disk is a design artifact of providing sample templates, and a better practice would be to utilize externalized vault storage (i.e. parameter store) for these values to manage risk.
The file rootCA.pem is created in tls.tf
resource "local_file" "rootca_pem" {
content = tls_self_signed_cert.ca.cert_pem
filename = "${path.module}/rootCA.pem"
}This is then consumed within the iam.tf configuration file to be associated with the trust anchor
resource "aws_rolesanywhere_trust_anchor" "name" {
enabled = true
name = "${var.iam.name_prefix}-anchor"
source {
source_type = "CERTIFICATE_BUNDLE"
source_data {
x509_certificate_data = local_file.rootca_pem.content
}
}
}These two files are generated for consumption by the aws_signing_helper script.
resource "local_file" "server_key" {
content = tls_private_key.cert.private_key_pem
filename = "${path.module}/server.key"
}
resource "local_file" "server_pem" {
content = tls_locally_signed_cert.cert.cert_pem
filename = "${path.module}/server.pem"
}The aws_signing_helper script uses these for --certificate and --private-key parameters
./aws_signing_helper credential-process \
--certificate ./terraform/server.pem --private-key ./terraform/server.key \
--trust-anchor-arn "$VAR_TRUST_ANCHOR_ARN" \
--profile-arn "$VAR_PROFILE_ARN" \
--role-arn "$VAR_ROLE_ARN"The template provide generates a single IAM Role as an example, and associates the ReadOnly managed IAM Policy to it.
IAM RolesAnywhere Trust Anchor is created, and matched to the x509 certificate created in the tls.tf configuration file, then an IAM RolesAnywhere Profile is associated to the IAM Role originally generated.
The ARN's for for these three resources are required for the aws_signing_helper script.
The aws_signing_helper requires three variables for authentication.
- IAM RolesAnywhere Trust Anchor ARN
- IAM RolesAnywhere Profile ARN
- IAM Role ARN
For external integration, our templates includes these as specific Terraform Outputs
output "trust_anchor_arn" {
value = aws_rolesanywhere_trust_anchor.name.arn
}
output "trust_profile_arn" {
value = aws_rolesanywhere_profile.test.arn
}
output "iam_role" {
value = aws_iam_role.this.arn
}AWS Provides the aws_signing_helper tool that provides an easy to use CLI method for obtaining temporary credentials for login.
We provide a sample shell script for using this tool to generate a temporary credential set with the generated certificates.
The shell script needs the relevant IAM Role and IAM RolesAnywhere ARN's provided to it as variables:
VAR_TRUST_ANCHOR_ARN=""
VAR_PROFILE_ARN=""
VAR_ROLE_ARN=""The shell script contains a simple function to authenticate with:
- update
--certificatewith the path to your ownserver.pemfile - update the
--private-keywith the path to your ownserver.keyfile
get-credentials () {
./aws_signing_helper credential-process \
--certificate ./terraform/server.pem --private-key ./terraform/server.key \
--trust-anchor-arn "$VAR_TRUST_ANCHOR_ARN" \
--profile-arn "$VAR_PROFILE_ARN" \
--role-arn "$VAR_ROLE_ARN"
}Once the variables are updated, and then certificate and private-key locations corrected, the script can be executed.
By default it will only echo the obtained keys into the shell session. We do provide a function export them also, but it is important to remember these are designed as sample templates and by default the session authentication remains in the executed sub shell.
