Swift: Add a static credential identity resolver example (awsdocs#6979)

swift/example_code/sts/AssumeRole/Package.swift

@@ -0,0 +1,40 @@
+// swift-tools-version:5.9
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+//
+// The swift-tools-version declares the minimum version of Swift required to
+// build this package.
+
+import PackageDescription
+
+let package = Package(
+    name: "AssumeRole",
+    // Let Xcode know the minimum Apple platforms supported.
+    platforms: [
+        .macOS(.v11),
+        .iOS(.v13)
+    ],
+    dependencies: [
+        // Dependencies declare other packages that this package depends on.
+        .package(
+            url: "https://github.com/awslabs/aws-sdk-swift",
+            from: "1.0.0"
+        ),
+        .package(
+            url: "https://github.com/apple/swift-argument-parser.git",
+            branch: "main"
+        ),
+    ],
+    targets: [
+        // Targets are the basic building blocks of a package, defining a module or a test suite.
+        // Targets can depend on other targets in this package and products from dependencies.
+        .executableTarget(
+            name: "AssumeRole",
+            dependencies: [
+                .product(name: "AWSSTS", package: "aws-sdk-swift"),
+                .product(name: "AWSS3", package: "aws-sdk-swift"),
+                .product(name: "ArgumentParser", package: "swift-argument-parser"),
+            ],
+            path: "Sources"),
+    ]
+)

swift/example_code/sts/AssumeRole/Sources/entry.swift

@@ -0,0 +1,277 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+//
+/// A simple example that shows how to use the AWS SDK for Swift to
+/// authenticate using optional static credentials and an AWS IAM role ARN.
+
+// snippet-start:[swift.sts.AssumeRole.imports]
+import ArgumentParser
+import AWSClientRuntime
+import AWSS3
+import AWSSDKIdentity
+import AWSSTS
+import Foundation
+import SmithyIdentity
+// snippet-end:[swift.sts.AssumeRole.imports]
+
+struct ExampleCommand: ParsableCommand {
+    @Option(help: "AWS access key ID")
+    var accessKey: String? = nil
+    @Option(help: "AWS secret access key")
+    var secretKey: String? = nil
+    @Option(help: "Session token")
+    var sessionToken: String? = nil
+    @Argument(help: "ARN of the role to assume")
+    var roleArn: String
+
+    static var configuration = CommandConfiguration(
+        commandName: "AssumeRole",
+        abstract: """
+        Authenticate using the specified role, optionally using specified
+        access key, secret access key, and session token first.
+        """,
+        discussion: """
+        This program uses the specified access key, secret access key, and
+        optional session token, to request temporary credentials for the
+        specified role Then it uses the credentials to list the user's
+        Amazon S3 buckets. This shows a couple of ways to use a
+        StaticAWSCredentialIdentityResolver object.
+        """
+    )
+
+    /// Called by ``main()`` to do the actual running of the AWS
+    /// example.
+    // snippet-start:[swift.sts.AssumeRole.command.runasync]
+    func runAsync() async throws {
+        // If credentials are specified, create a credential identity
+        // resolver that uses them to authenticate. This identity will be used
+        // to ask for permission to use the specified role.
+
+        var identityResolver: StaticAWSCredentialIdentityResolver? = nil
+
+        if accessKey != nil && secretKey != nil {
+            do {
+                identityResolver = try getIdentityResolver(accessKey: accessKey, 
+                            secretKey: secretKey, sessionToken: sessionToken)
+            } catch {
+                print("ERROR: Unable to get identity resolver in runAsync:",
+                        dump(error))
+                throw error
+            }
+        }
+
+        // Assume the role using the credentials provided on the command line,
+        // or using the default credentials if none were specified.
+
+        do {
+            // snippet-start: [swift.sts.AssumeRole]
+            let credentials = try await assumeRole(identityResolver: identityResolver,
+                                        roleArn: roleArn)
+            do {
+                identityResolver = try getIdentityResolver(
+                    accessKey: credentials.accessKey, 
+                    secretKey: credentials.secret,
+                    sessionToken: credentials.sessionToken
+                )
+            } catch {
+                print("ERROR: Unable to authenticate using provided options:",
+                        dump(error))
+                throw error
+            }
+            // snippet-end: [swift.sts.AssumeRole]
+        } catch {
+            print("ERROR: Error assuming role in runAsync:", dump(error))
+            throw AssumeRoleExampleError.assumeRoleFailed
+        }
+
+        // Use the credential identity resolver to access AWS S3.
+
+        do {
+            let names = try await getBucketNames(identityResolver: identityResolver)
+
+            print("Found \(names.count) buckets:")
+            for name in names {
+                print("  \(name)")
+            }
+        } catch {
+            print("ERROR: Error getting bucket names in runAsync:", dump(error))
+            throw error
+        }
+    }
+    // snippet-end:[swift.sts.AssumeRole.command.runasync]
+}
+
+/// An `Error` type used to return errors from the
+/// `assumeRole(identityResolver: roleArn:)` function.
+enum AssumeRoleExampleError: Error {
+    /// An error indicating that the STS `AssumeRole` request failed.
+    case assumeRoleFailed
+    /// An error indicating that the returned credentials were missing
+    /// required information.
+    case incompleteCredentials
+    /// An error indicating that no credentials were returned by `AssumeRole`.
+    case missingCredentials
+
+    /// Return a human-readable explanation of the error.
+    var errorDescription: String? {
+        switch self {
+        case .assumeRoleFailed:
+            return "Unable to assume the specified role."
+        case .incompleteCredentials:
+            return "AWS STS returned incomplete credentials."
+        case .missingCredentials:
+            return "AWS STS did not return any credentials for the specified role."
+        }
+    }
+}
+
+// snippet-start:[swift.sts.AssumeRole.assumeRole-function]
+/// Assume the specified role. If any kind of credential identity resolver is
+/// specified, that identity is adopted before assuming the role.
+/// 
+/// - Parameters:
+///   - identityResolver: Any kind of `AWSCredentialIdentityResolver`. If
+///     provided, this identity is adopted before attempting to assume the
+///     specified role.
+///   - roleArn: The ARN of the AWS role to assume.
+///
+/// - Throws: Re-throws STS errors. Also can throw any
+///   `AssumeRoleExampleError`. 
+/// - Returns: An `AWSCredentialIdentity` containing the temporary credentials
+///   assigned.
+func assumeRole(identityResolver: (any AWSCredentialIdentityResolver)?,
+                roleArn: String) async throws -> AWSCredentialIdentity {
+    let stsConfiguration = try await STSClient.STSClientConfiguration(
+        awsCredentialIdentityResolver: identityResolver
+    )
+    let stsClient = STSClient(config: stsConfiguration)
+
+    // Assume the role and return the assigned credentials.
+
+    // snippet-start: [swift.sts.sts.AssumeRole]
+    let input = AssumeRoleInput(
+        roleArn: roleArn,
+        roleSessionName: "AssumeRole-Example"
+    )
+
+    let output = try await stsClient.assumeRole(input: input)
+
+    guard let credentials = output.credentials else {
+        throw AssumeRoleExampleError.missingCredentials
+    }
+
+    guard let accessKey = credentials.accessKeyId,
+            let secretKey = credentials.secretAccessKey,
+            let sessionToken = credentials.sessionToken else {
+        throw AssumeRoleExampleError.incompleteCredentials
+    }
+    // snippet-end: [swift.sts.sts.AssumeRole]
+
+    // Return an `AWSCredentialIdentity` object with the temporary
+    // credentials.
+
+    let awsCredentials = AWSCredentialIdentity(
+        accessKey: accessKey,
+        secret: secretKey,
+        sessionToken: sessionToken
+    )
+    return awsCredentials
+}
+// snippet-end:[swift.sts.AssumeRole.assumeRole-function]
+
+/// Return an array containing the names of all available buckets using
+/// the specified credential identity resolver to authenticate.
+///
+/// - Parameter identityResolver: Any type of `AWSCredentialIdentityResolver`,
+///   used to authenticate and authorize the user for access to the bucket
+///   names.
+///
+/// - Throws: Re-throws errors from `ListBucketsPaginated`.
+///
+/// - Returns: An array of strings listing the buckets.
+func getBucketNames(identityResolver: (any AWSCredentialIdentityResolver)?)
+                    async throws -> [String] {
+    do {
+        // Get an S3Client with which to access Amazon S3.
+        // snippet-start:[swift.sts.AssumeRole.use-resolver]
+        let configuration = try await S3Client.S3ClientConfiguration(
+            awsCredentialIdentityResolver: identityResolver
+        )
+        let client = S3Client(config: configuration)
+
+        // Use "Paginated" to get all the buckets. This lets the SDK handle
+        // the 'continuationToken' in "ListBucketsOutput".
+        let pages = client.listBucketsPaginated(
+            input: ListBucketsInput( maxBuckets: 10)
+        )
+        // snippet-end:[swift.sts.AssumeRole.use-resolver]
+
+        // Get the bucket names.
+        var bucketNames: [String] = []
+
+        do {
+            for try await page in pages {
+                guard let buckets = page.buckets else {
+                    print("Error: page is empty.")
+                    continue
+                }
+
+                for bucket in buckets {
+                    bucketNames.append(bucket.name ?? "<unknown>")
+                }
+            }
+
+            return bucketNames
+        } catch {
+            print("ERROR: listBuckets:", dump(error))
+            throw error
+        }
+    }
+}
+
+/// Create a credential identity resolver using access key and secret access
+/// key.
+///
+/// - Parameters:
+///   - accessKey: A string containing the AWS access key ID.
+///   - secretKey: A string containing the AWS secret access key.
+///   - sessionToken: An optional string containing the session token.
+/// - Throws: Re-throws errors from AWSSDKIdentity.
+/// - Returns: A `StaticAWSCredentialIdentityResolver` that can be used when
+///   configuring service clients.
+func getIdentityResolver(accessKey: String?, secretKey: String?,
+                         sessionToken: String?)
+            throws -> StaticAWSCredentialIdentityResolver? {
+
+    if accessKey == nil || secretKey == nil {
+        return nil
+    }
+
+    guard let accessKey = accessKey,
+          let secretKey = secretKey else {
+        return nil
+    }
+
+    let credentials = AWSCredentialIdentity(
+        accessKey: accessKey,
+        secret: secretKey,
+        sessionToken: sessionToken
+    )
+
+    return try StaticAWSCredentialIdentityResolver(credentials)
+}
+
+/// The program's asynchronous entry point.
+@main
+struct Main {
+    static func main() async {
+        let args = Array(CommandLine.arguments.dropFirst())
+
+        do {
+            let command = try ExampleCommand.parse(args)
+            try await command.runAsync()
+        } catch {
+            ExampleCommand.exit(withError: error)
+        }
+    }    
+}