Introduction

When building applications that need to interact with AWS services, you have two main options for authentication: Access Keys or IAM Roles. This tutorial focuses on using IAM roles, which is the recommended and more secure approach for applications running on AWS infrastructure.

IAM roles allow your applications to obtain temporary credentials automatically, eliminating the need to store long-lived access keys in your code, configuration files, or environment variables. This significantly reduces the security risk of credential exposure.

Why Use IAM Roles Instead of Keys?

How IAM Roles Work

When your application runs on AWS infrastructure (EC2, ECS, Lambda, EKS, etc.), it can assume an IAM role through the AWS metadata service. Here’s the flow:

1. Role Assignment: An IAM role is attached to your AWS resource (EC2 instance, ECS task, Lambda function, etc.)
2. Credential Request: Your application requests credentials from the AWS metadata service
3. Automatic Provisioning: AWS automatically provides temporary credentials (access key, secret key, session token)
4. SDK Usage: The AWS SDK automatically detects and uses these credentials
5. Automatic Refresh: Credentials are automatically refreshed before expiration

Accessible AWS Services

IAM roles can access over 200+ AWS services depending on the permissions granted to the role. Your application can interact with virtually any AWS service using IAM role credentials through the AWS SDKs.

Popular Services by Category

Setting Up IAM Roles

You can create IAM roles either through the AWS Management Console (manual) or using AWS CLI/API (programmatic). Choose the method that works best for you.

Method 1: Using AWS Management Console (Step-by-Step)

Method 2: Using AWS CLI (Programmatic)

Step 1: Create an IAM Role

First, create an IAM role with the necessary permissions for your application:

# Using AWS CLI
aws iam create-role \
    --role-name MyAppRole \
    --assume-role-policy-document '{
        "Version": "2012-10-17",
        "Statement": [{
            "Effect": "Allow",
            "Principal": {
                "Service": "ec2.amazonaws.com"
            },
            "Action": "sts:AssumeRole"
        }]
    }'

Step 2: Attach Permissions Policy

Attach a policy that grants the permissions your application needs:

# Example: Allow S3 read/write access
aws iam put-role-policy \
    --role-name MyAppRole \
    --policy-name S3AccessPolicy \
    --policy-document '{
        "Version": "2012-10-17",
        "Statement": [{
            "Effect": "Allow",
            "Action": [
                "s3:GetObject",
                "s3:PutObject",
                "s3:DeleteObject"
            ],
            "Resource": "arn:aws:s3:::my-app-bucket/*"
        }]
    }'

Step 3: Create Instance Profile (for EC2)

For EC2 instances, create an instance profile and attach the role:

# Create instance profile
aws iam create-instance-profile --instance-profile-name MyAppInstanceProfile

# Add role to instance profile
aws iam add-role-to-instance-profile \
    --instance-profile-name MyAppInstanceProfile \
    --role-name MyAppRole

# Attach to EC2 instance
aws ec2 associate-iam-instance-profile \
    --instance-id i-1234567890abcdef0 \
    --iam-instance-profile Name=MyAppInstanceProfile

Python Applications (boto3)

Python applications using boto3 automatically use IAM roles when running on AWS infrastructure. No configuration is needed!

Basic Usage

Simply create your boto3 clients without specifying credentials:

import boto3

# boto3 automatically uses IAM role credentials when available
s3_client = boto3.client('s3')
dynamodb_client = boto3.client('dynamodb')

# Use the clients normally
response = s3_client.list_buckets()
print(response['Buckets'])

Django/Flask Example

In a Django or Flask application, initialize AWS clients at startup:

# settings.py (Django) or app.py (Flask)
import boto3

# Initialize AWS clients - they'll use IAM role automatically
S3_CLIENT = boto3.client('s3')
DYNAMODB_CLIENT = boto3.client('dynamodb')
SES_CLIENT = boto3.client('ses')

# In your views/views.py
def upload_file(request):
    file = request.FILES['file']
    S3_CLIENT.upload_fileobj(
        file,
        'my-bucket',
        f'uploads/{file.name}'
    )
    return JsonResponse({'status': 'success'})

Explicit Region Configuration

You can specify the region while still using role credentials:

import boto3

# Specify region, credentials come from IAM role
s3_client = boto3.client(
    's3',
    region_name='us-east-1'
)

Local Development

For local development, boto3 will look for credentials in this order:

1. Environment variables (AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY)
2. Shared credentials file (~/.aws/credentials)
3. IAM role (if running on EC2/ECS/Lambda)

# For local development, use AWS CLI profiles
# ~/.aws/credentials
[default]
aws_access_key_id = YOUR_ACCESS_KEY
aws_secret_access_key = YOUR_SECRET_KEY

# Or set environment variables
export AWS_PROFILE=my-profile

Ruby on Rails Applications

Ruby applications using the aws-sdk gem automatically use IAM roles when running on AWS infrastructure.

Installation

# Gemfile
gem 'aws-sdk-s3'
gem 'aws-sdk-dynamodb'
gem 'aws-sdk-ses'

# Or install the full SDK
gem 'aws-sdk'

Basic Usage

Create AWS clients without credentials – they’ll use the IAM role automatically:

# config/initializers/aws.rb
require 'aws-sdk-s3'
require 'aws-sdk-dynamodb'

# Clients automatically use IAM role credentials
Aws.config.update({
  region: 'us-east-1'
})

S3_CLIENT = Aws::S3::Client.new
DYNAMODB_CLIENT = Aws::DynamoDB::Client.new

Rails Controller Example

# app/controllers/files_controller.rb
class FilesController < ApplicationController
  def upload
    file = params[:file]
    
    S3_CLIENT.put_object(
      bucket: 'my-app-bucket',
      key: "uploads/#{file.original_filename}",
      body: file.read
    )
    
    render json: { status: 'success' }
  end
  
  def list
    response = S3_CLIENT.list_objects_v2(
      bucket: 'my-app-bucket',
      prefix: 'uploads/'
    )
    
    render json: { files: response.contents.map(&:key) }
  end
end

Rails Model Example

# app/models/user.rb
class User < ApplicationRecord
  def save_to_dynamodb
    DYNAMODB_CLIENT.put_item(
      table_name: 'users',
      item: {
        user_id: id,
        email: email,
        name: name,
        created_at: created_at.iso8601
      }
    )
  end
  
  def self.find_in_dynamodb(user_id)
    response = DYNAMODB_CLIENT.get_item(
      table_name: 'users',
      key: { user_id: user_id }
    )
    response.item
  end
end

Local Development

# config/initializers/aws.rb
require 'aws-sdk-s3'

if Rails.env.development?
  # Use credentials from ~/.aws/credentials or environment variables
  Aws.config.update({
    region: 'us-east-1',
    credentials: Aws::SharedCredentials.new(profile_name: 'default')
  })
else
  # Production: Use IAM role (automatic)
  Aws.config.update({
    region: 'us-east-1'
  })
end

S3_CLIENT = Aws::S3::Client.new

Node.js / MERN Stack Applications

Node.js applications using the AWS SDK for JavaScript automatically use IAM roles when running on AWS infrastructure.

Installation

# Using npm
npm install @aws-sdk/client-s3 @aws-sdk/client-dynamodb

# Or install individual service clients as needed
npm install @aws-sdk/client-ses
npm install @aws-sdk/client-sns

Basic Usage (AWS SDK v3)

The modern AWS SDK v3 automatically uses IAM role credentials:

// config/aws.js
import { S3Client } from '@aws-sdk/client-s3';
import { DynamoDBClient } from '@aws-sdk/client-dynamodb';

// Clients automatically use IAM role credentials
export const s3Client = new S3Client({ region: 'us-east-1' });
export const dynamoDBClient = new DynamoDBClient({ region: 'us-east-1' });

Express.js Example

// routes/files.js
import express from 'express';
import { PutObjectCommand, ListObjectsV2Command } from '@aws-sdk/client-s3';
import { s3Client } from '../config/aws.js';

const router = express.Router();

router.post('/upload', async (req, res) => {
  try {
    const file = req.files.file;
    
    const command = new PutObjectCommand({
      Bucket: 'my-app-bucket',
      Key: `uploads/${file.name}`,
      Body: file.data
    });
    
    await s3Client.send(command);
    res.json({ status: 'success' });
  } catch (error) {
    res.status(500).json({ error: error.message });
  }
});

router.get('/list', async (req, res) => {
  try {
    const command = new ListObjectsV2Command({
      Bucket: 'my-app-bucket',
      Prefix: 'uploads/'
    });
    
    const response = await s3Client.send(command);
    res.json({ files: response.Contents.map(item => item.Key) });
  } catch (error) {
    res.status(500).json({ error: error.message });
  }
});

export default router;

MongoDB + AWS Integration Example

// services/notification.js
import { SESClient, SendEmailCommand } from '@aws-sdk/client-ses';
import User from '../models/User.js';

const sesClient = new SESClient({ region: 'us-east-1' });

export async function sendWelcomeEmail(userId) {
  const user = await User.findById(userId);
  
  const command = new SendEmailCommand({
    Source: '[email protected]',
    Destination: {
      ToAddresses: [user.email]
    },
    Message: {
      Subject: { Data: 'Welcome!' },
      Body: {
        Text: { Data: `Welcome ${user.name}!` }
      }
    }
  });
  
  await sesClient.send(command);
}

React Frontend (Using Backend API)

Important: Never use AWS credentials in frontend code. Always make API calls through your backend, which uses the IAM role.

// React component
import React, { useState } from 'react';
import axios from 'axios';

function FileUpload() {
  const [file, setFile] = useState(null);
  
  const handleUpload = async () => {
    const formData = new FormData();
    formData.append('file', file);
    
    // Backend uses IAM role to upload to S3
    await axios.post('/api/files/upload', formData);
  };
  
  return (
    <div>
      <input type="file" onChange={(e) => setFile(e.target.files[0])} />
      <button onClick={handleUpload}>Upload</button>
    </div>
  );
}

Local Development

// config/aws.js
import { S3Client } from '@aws-sdk/client-s3';
import { fromIni } from '@aws-sdk/credential-providers';

const isDevelopment = process.env.NODE_ENV === 'development';

export const s3Client = new S3Client({
  region: 'us-east-1',
  // In development, use AWS profile
  // In production, automatically uses IAM role
  ...(isDevelopment && {
    credentials: fromIni({ profile: 'default' })
  })
});

Java Applications

Java applications using the AWS SDK for Java automatically use IAM roles when running on AWS infrastructure.

Maven Dependency

<!-- pom.xml -->
<dependencies>
    <dependency>
        <groupId>software.amazon.awssdk</groupId>
        <artifactId>s3</artifactId>
        <version>2.20.0</version>
    </dependency>
    <dependency>
        <groupId>software.amazon.awssdk</groupId>
        <artifactId>dynamodb</artifactId>
        <version>2.20.0</version>
    </dependency>
</dependencies>

Spring Boot Example

// Application.java
@SpringBootApplication
public class Application {
    public static void main(String[] args) {
        SpringApplication.run(Application.class, args);
    }
}

// config/AwsConfig.java
@Configuration
public class AwsConfig {
    @Bean
    public S3Client s3Client() {
        // Automatically uses IAM role when running on AWS
        return S3Client.builder()
            .region(Region.US_EAST_1)
            .build();
    }
    
    @Bean
    public DynamoDbClient dynamoDbClient() {
        return DynamoDbClient.builder()
            .region(Region.US_EAST_1)
            .build();
    }
}

// service/FileService.java
@Service
public class FileService {
    @Autowired
    private S3Client s3Client;
    
    public void uploadFile(String bucket, String key, byte[] data) {
        PutObjectRequest request = PutObjectRequest.builder()
            .bucket(bucket)
            .key(key)
            .build();
        
        s3Client.putObject(request, RequestBody.fromBytes(data));
    }
}

Go Applications

Go applications using the AWS SDK for Go automatically use IAM roles when running on AWS infrastructure.

Installation

go get github.com/aws/aws-sdk-go-v2/service/s3
go get github.com/aws/aws-sdk-go-v2/service/dynamodb
go get github.com/aws/aws-sdk-go-v2/config

Basic Usage

package main

import (
    "context"
    "github.com/aws/aws-sdk-go-v2/aws"
    "github.com/aws/aws-sdk-go-v2/config"
    "github.com/aws/aws-sdk-go-v2/service/s3"
)

func main() {
    // Load default config - automatically uses IAM role on AWS
    cfg, err := config.LoadDefaultConfig(context.TODO(),
        config.WithRegion("us-east-1"),
    )
    if err != nil {
        panic(err)
    }
    
    // Create S3 client
    client := s3.NewFromConfig(cfg)
    
    // Use the client
    result, err := client.ListBuckets(context.TODO(), &s3.ListBucketsInput{})
    if err != nil {
        panic(err)
    }
    
    for _, bucket := range result.Buckets {
        println(*bucket.Name)
    }
}

Best Practices

1. Principle of Least Privilege

Only grant the minimum permissions your application needs. Don't use "Action": "*" or "Resource": "*" unless absolutely necessary.

// ❌ Bad: Too permissive
{
    "Effect": "Allow",
    "Action": "s3:*",
    "Resource": "*"
}

// ✅ Good: Specific permissions
{
    "Effect": "Allow",
    "Action": [
        "s3:GetObject",
        "s3:PutObject"
    ],
    "Resource": "arn:aws:s3:::my-app-bucket/*"
}

2. Use Resource-Based Policies When Possible

For services like S3, SNS, and SQS, you can use resource-based policies in addition to IAM role policies for defense in depth.

3. Separate Roles for Different Environments

Use different IAM roles for development, staging, and production environments. This limits the blast radius if a role is compromised.

# Development role
MyAppRole-Dev

# Staging role
MyAppRole-Staging

# Production role
MyAppRole-Prod

4. Monitor Role Usage

Enable CloudTrail to monitor when roles are assumed and what actions are performed. Set up CloudWatch alarms for unusual activity.

5. Use Service-Specific Roles

For Lambda functions, ECS tasks, and other services, use service-specific roles rather than EC2 instance roles when possible.

6. Handle Credential Errors Gracefully

Your application should handle cases where credentials might not be available (e.g., during local development).

# Python example
import boto3
from botocore.exceptions import NoCredentialsError

try:
    s3_client = boto3.client('s3')
    response = s3_client.list_buckets()
except NoCredentialsError:
    print("AWS credentials not found. Please configure credentials.")
    # Fallback logic or exit gracefully

7. Use IAM Roles for Cross-Account Access

When your application needs to access resources in another AWS account, use cross-account IAM roles instead of sharing access keys.

Troubleshooting

Problem: "Unable to locate credentials"

Possible causes and solutions:

• Not running on AWS infrastructure: Use AWS CLI profiles or environment variables for local development
• Role not attached: Verify the IAM role is attached to your EC2 instance, ECS task, or Lambda function
• Instance profile missing: For EC2, ensure an instance profile is created and attached

Problem: "Access Denied" errors

Possible causes and solutions:

• Insufficient permissions: Check the IAM role's policy to ensure it has the required permissions
• Resource ARN mismatch: Verify the resource ARN in your policy matches the actual resource
• Condition restrictions: Check if there are IAM conditions (like IP restrictions) blocking access

Problem: Credentials expiring too quickly

IAM role credentials typically last 1 hour for EC2 and can be configured up to 12 hours for other services. The AWS SDK automatically refreshes credentials before expiration. If you're seeing expiration issues:

• Check that your SDK version is up to date (older versions may have refresh issues)
• Verify the metadata service is accessible from your application
• For Lambda, ensure the execution role has proper permissions

Debugging Tips

# Check if role is attached to EC2 instance
aws ec2 describe-instances --instance-ids i-1234567890abcdef0 \
    --query 'Reservations[0].Instances[0].IamInstanceProfile'

# Test role permissions
aws sts get-caller-identity

# View current credentials (from EC2 instance)
curl http://169.254.169.254/latest/meta-data/iam/security-credentials/

# Get temporary credentials
curl http://169.254.169.254/latest/meta-data/iam/security-credentials/MyAppRole

Questions & Answers

Common questions about using IAM roles in applications:

{
    "Effect": "Allow",
    "Action": "s3:GetObject",
    "Resource": "arn:aws:s3:::my-bucket/*",
    "Condition": {
        "IpAddress": {
            "aws:SourceIp": "203.0.113.0/24"
        }
    }
}

const isProduction = process.env.NODE_ENV === 'production';

if (isProduction) {
  // EC2: Uses IAM role automatically
  config.credentials = fromNodeProviderChain();
} else {
  // Local: Uses named profile with access keys
  config.credentials = fromIni({ profile: 'temp_profile' });
}

if (process.env.DB_PASSWORD) {
  // Local: use password authentication
  dbConfig.password = process.env.DB_PASSWORD;
} else {
  // Production: use IAM auth token
  const signer = new Signer({ hostname, port, username, credentials });
  dbConfig.password = await signer.getAuthToken();
}

# Create instance profile
aws iam create-instance-profile --instance-profile-name MyAppProfile

# Add role to it
aws iam add-role-to-instance-profile \
    --instance-profile-name MyAppProfile \
    --role-name MyAppRole

# Attach to EC2 instance
aws ec2 associate-iam-instance-profile \
    --instance-id i-0123456789 \
    --iam-instance-profile Name=MyAppProfile

const snsClient = new SNSClient({ region: 'us-east-1' });
const sqsClient = new SQSClient({ region: 'us-east-1' });
const sesClient = new SESClient({ region: 'us-east-1' });
// All automatically use IAM role on EC2