AWS authentication

All AWS adapters use AWS Signature Version 4 authentication. Set auth_method to "aws_authentication" in the service instance configuration. Three authentication mechanisms are supported, described below.

If you change authentication methods, update the service instance configuration accordingly and merge the changes back into the adapter repository.

AWS Signature 4 service account authentication

Also known as standard credential signing using an Adapter Role or Pod Role.

When aws_access_key and aws_secret_key are provided in the service instance configuration (Adapter Role), the adapter uses those credentials to sign all calls. When they are not provided, the adapter falls back to AWS environment variables (Pod Role in SaaS environments). If the Pod Role lacks permission for a given call, that call fails with an authentication error.

1
"authentication": {
2
  "auth_method": "aws_authentication",
3
  "aws_access_key": "aws_access_key",
4
  "aws_secret_key": "aws_secret_key",
5
  "aws_session_token": "aws_session_token"
6
}

AWS Security Token Service (STS)

STS authentication uses standard credentials to assume a different IAM role on each call. This is also referred to as standard credential plus STS assume-role, using a Global Role or Task Role.

Flow: Adapter Role → Global or Task Role(s), or Pod Role → Task Role(s).

The adapter uses the aws_access_key and aws_secret_key from the service instance configuration (Adapter Role) to make an STS AssumeRole request. The resulting Task Role is then used to sign the actual API call. The Adapter Role must have permission to assume the Task Role, or calls fail. When no access key or secret key is provided, the adapter uses AWS environment variables (Pod Role) to attempt the assume-role operation.

Global role

To use the same role for all calls, define it in the service instance configuration:

1
"authentication": {
2
  "aws_iam_role": "arn:aws:iam::1234567:role/my_role"
3
}

Task-level role (dynamic)

To specify a different role per call, use adapter methods with the STSRole suffix and pass STS parameters into the method. You must still provide aws_access_key and aws_secret_key in the service instance configuration.

1
{
2
  "RoleArn": "arn:aws:iam::1234567:role/my_role",
3
  "RoleSessionName": "mySession"
4
}

STS endpoint and proxy configuration

STS calls go to sts.amazonaws.com or a regional endpoint such as sts.us-east-1.amazonaws.com. By default, traffic routes over the internet. To route through your network instead, configure the aws_sts object in the service instance configuration.

Set proxy to point to the AWS load balancer or a proxy that forwards to AWS STS. If the load balancer points to the global STS service (sts.amazonaws.com), also set endpoint to match, or the STS certificate will be rejected due to a hostname mismatch.

For cross-organizational role assumption, provide an externalId agreed upon by both organizations for additional security. This can be set globally in aws_sts or passed dynamically in the STS Params object on the task.

For the standard AWS partition, the STS region is typically us-east-1, but this is configurable.

1
"authentication": {
2
  "aws_sts": {
3
    "region": "us-east-1",
4
    "endpoint": "<sts certificate endpoint>",
5
    "proxy": "<proxy/loadbalancer ip>",
6
    "externalId": "<sts external id>"
7
  }
8
}

AWS IAM role

IAM role authentication uses an internal AWS metadata call to obtain credentials. No access key or secret key is required in the service instance configuration. Because the adapter makes a call to the AWS instance metadata service (169.254.169.254), theItential Platform server must be running on or have network access to an AWS instance.

Use adapter methods with the STSRole suffix and provide the role ARN in the RoleName variable. You can also set a global IAM role in the service instance configuration using aws_iam_role.

Supported scenarios:

• IAM to internal AWS server — using either a Task Role (roleName) or Adapter Role (aws_iam_role)
• Adapter Role assumes Task Role — IAM fetches the Adapter Role credentials; STS is used to assume the Task Role
• Pod Role assumes Adapter Role, which assumes Task Role — STS is used for both assume-role operations

1
"authentication": {
2
  "auth_method": "aws_authentication",
3
  "aws_iam_role": "role_arn"
4
}

Set up the IAM role on the AWS instance

IfItential Platform is running inside Docker on an AWS instance, increase the metadata hop limit to allow the container to reach the instance metadata service:

$
aws sso login --profile aws-bota-1
$
# export aws keys for CLI access
$
$
aws ec2 modify-instance-metadata-options \
>
  --instance-id i-0e150236026b7c45d \
>
  --http-put-response-hop-limit 3 \
>
  --http-endpoint enabled \
>
  --region us-east-1

To create and attach an IAM role to your instance:

1. In the AWS console, navigate to your service instance and select it.
2. Choose Actions → Security → Modify IAM Role.
3. Click Create New IAM Role and create a role with the following settings:
   • Trusted entity type: AWS service
   • Use case: <service>
4. Attach the required service policies to the role and save it.
5. Return to Actions → Security → Modify IAM Role and associate the new role with your instance.

Troubleshooting

• Verify that you copied the correct access key, secret key, and session token, with no leading or trailing spaces.
• Enable debug-level logging for the adapter inItential Platform Admin Essentials.
• Enable auth_logging in the adapter properties inItential Platform Admin Essentials. This adds two additional log entries: FULL_REQUEST (all call options including authentication headers and the full URL) and FULL_BODY (the complete request payload immediately before it is sent, including any authentication data added to the body). These entries are the most useful for diagnosing AWS signature and credential issues.
• Review the logs for the following entries:
  • FULL_REQUEST — confirms the correct authentication headers and URL are being sent.
  • FULL_BODY — confirms the payload including authentication data is accurate.
  • CALL RETURN — shows what the external system returned.
• Credentials are masked by the adapter in standard logs. Verify values directly in the service instance configuration.
• Disable auth_logging when you are done. Leaving it enabled logs sensitive credential data.
• To verify IAM connectivity to the AWS instance metadata service from theItential Platform server, run:

$
TOKEN=`curl -v -X PUT "http://169.254.169.254/latest/api/token" \
>
  -H "X-aws-ec2-metadata-token-ttl-seconds: 21600"` \
>
  && curl -v -H "X-aws-ec2-metadata-token: $TOKEN" \
>
  http://169.254.169.254/latest/meta-data/iam/security-credentials/<rolename>