amazon-kinesis-client/docs/multilang/configuring-credential-providers.md

Configuring Credential Providers

AwsCredentialProviders are not a one-size-fits-all. The AWS SDK provides a rich API to support various configurations for many different providers. KCL multilang does not, and is not intended to, proxy the full breadth of the AWS SDK. However, KCL now provides better extensibility to handle, and be enhanced to handle, additional configurations. This document should help multilang customers configure a suitable CredentialProvider (or contribute changes to support a new use case!).

Sample Provider Configuration

In a Properties file, an AWSCredentialsProperty configuration might look like:

AWSCredentialsProvider = STSAssumeRoleSessionCredentialsProvider|<arn>|<sessionName> 

This basic configuration creates an STSAssumeRoleSessionCredentialsProvider with an ARN and session name. While functional, this configuration is limited. For example, this configuration cannot set a regional endpoint (e.g., VPC use case).

Leveraging nested properties, an AWSCredentialsProperty value might change to:

AWSCredentialsProvider = KclSTSAssumeRoleSessionCredentialsProvider|<arn>|<sessionName>\
    |endpointRegion=us-east-1|externalId=spartacus

N.B. Backslash (\) is for multi-line legibility and is not required.

Nested Properties

KCL multilang supports "nested properties" on the AWSCredentialsProvider key in the properties file. The Backus-Naur form of the value:

<property-value> ::= <provider-class> ["|" <required-param>]* ["|" <nested-property>]*
<provider-class> ::= <fully-qualified-provider-class> | <provider-class-name>
<required-param> ::= <string> # this depends on the provider
<nested-property> ::= <nested-key> "=" <nested-value>
<nested-key> ::= <lower-camel-case-key>
<nested-value ::= <string> # this depends on the nested key

In general, required parameters are passed directly to the class' constructor (e.g., STSAssumeRoleSessionCredentialsProvider(String, String)).

Nested properties are a custom mapping provided by KCL multilang, and do not exist in the AWS SDK. See NestedPropertyKey for the supported keys, and details on their expected values.

Nested Property Processor

Nested keys are processed via NestedPropertyProcessor. Implementation is, obviously, dependent on the implementing class. Adding a new nested key should be trivial. A backwards-compatible addition might look like:

    default void acceptFoo(...) {
        // do nothing
    }

KclSTSAssumeRoleSessionCredentialsProvider

KCL multilang includes a custom nested property processor for STSAssumeRole. Multilang configurations that use STSAssumeRoleSessionCredentialsProvider need only prefix Kcl to exercise this new provider:

AWSCredentialsProvider = KclSTSAssumeRoleSessionCredentialsProvider|<arn>|<sessionName>