Add documentation for IAM role authentication

Signed-off-by: Kiera Jost <kjost@splunk.com>

app-config.yaml

@@ -167,7 +167,6 @@ integrations:
     - host: amazonaws.com
       accessKeyId: ${AWS_ACCESS_KEY_ID}
       secretAccessKey: ${AWS_SECRET_ACCESS_KEY}
-      #roleArn:
 
 catalog:
   rules:

docs/integrations/aws-s3/locations.md

@@ -26,3 +26,15 @@ awsS3:
 
 Then make sure the environment variables `AWS_ACCESS_KEY_ID` and
 `AWS_SECRET_ACCESS_KEY` are set when you run Backstage.
+
+Users with multiple AWS accounts may want to use a role for S3 storage that is
+in a different AWS account. Using the roleArn parameter as seen below, you can
+instruct the AWS S3 reader to assume a role before accessing S3:
+
+```yaml
+awsS3:
+  - host: amazonaws.com
+    accessKeyId: ${AWS_ACCESS_KEY_ID}
+    secretAccessKey: ${AWS_SECRET_ACCESS_KEY}
+    roleArn: 'arn:aws:iam::xxxxxxxxxxxx:role/example-role'
+```

packages/backend-common/src/reading/AwsS3UrlReader.ts

@@ -26,7 +26,6 @@ import {
 } from './types';
 import getRawBody from 'raw-body';
 import { AwsS3Integration, ScmIntegrations } from '@backstage/integration';
-import { constant } from 'lodash';
 
 const parseURL = (
   url: string,
@@ -83,13 +82,13 @@ export class AwsS3UrlReader implements UrlReader {
     private readonly s3: S3,
   ) {}
 
+  /**
+   * If accesKeyId and secretAccessKey are missing, the standard credentials provider chain will be used:
+   * https://docs.aws.amazon.com/AWSJavaSDK/latest/javadoc/com/amazonaws/auth/DefaultAWSCredentialsProviderChain.html
+   */
   private static buildCredentials(
     integration?: AwsS3Integration,
   ): Credentials | CredentialsOptions | undefined {
-    /*
-    Credentials is an optional config. 
-    If missing, the default ways of authenticating AWS SDK will be used.
-    */
     if (!integration) {
       return undefined;
     }
@@ -97,6 +96,7 @@ export class AwsS3UrlReader implements UrlReader {
     const accessKeyId = integration.config.accessKeyId;
     const secretAccessKey = integration.config.secretAccessKey;
     let explicitCredentials: Credentials | undefined;
+
     if (accessKeyId && secretAccessKey) {
       explicitCredentials = new Credentials({
         accessKeyId,

packages/integration/api-report.md

@@ -38,6 +38,7 @@ export type AwsS3IntegrationConfig = {
   host: string;
   accessKeyId?: string;
   secretAccessKey?: string;
+  roleArn?: string;
 };
 
 // Warning: (ae-missing-release-tag) "AzureIntegration" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)