Skip to content

Latest commit

 

History

History
92 lines (75 loc) · 5.16 KB

configuring-credential-providers.md

File metadata and controls

92 lines (75 loc) · 5.16 KB

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 = StsAssumeRoleCredentialsProvider|<arn>|<sessionName>|endpointRegion=us-east-1

This basic configuration creates an StsAssumeRoleCredentialsProvider with an ARN and session name. If endpointRegion is not specified, the provider will use the region defined in the AWS config file. If no region is found in the config file, the credentials provider will fail.

The providers generated by this config property will be AWS SDK v2 AwsCredentialsProviders. These differ from the SDK v1 AWSCredentialsProviders in a number of ways. See Credentials Provider Changes.

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 = KclStsAssumeRoleCredentialsProvider|<arn>|<sessionName>\
    |endpointRegion=us-east-1|externalId=spartacus

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

You can create a default DefaultCredentialsProvider by passing it in the config like:

AwsCredentialsProvider = DefaultCredentialsProvider

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 or .create() method (e.g., ProfileCredentialsProvider(String)). However, most of these providers require builders and will require a custom implementation similar to KclStsAssumeRoleCredentialsProvider for customization

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
    }

Leveraging nested properties, an AwsCredentialsProperty value might look like:

AwsCredentialsProvider = KclStsAssumeRoleCredentialsProvider|<arn>|<sessionName>\
    |endpointRegion=us-east-1|externalId=spartacus

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

KclStsAssumeRoleCredentialsProvider

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 = KclStsAssumeRoleCredentialsProvider|<arn>|<sessionName>|endpointRegion=us-east-1