AWS CDK CLI Library

---

!cdk-constructs: Stable

---

Overview

As any piece of software that interacts with an AWS account, the CDK CLI needs
AWS credentials for authentication and authorization. When it comes to choose
which sources to get credentials from, it has
the [same behavior as the AWS CLI][cli-auth]. But this basic behavior may result
in some failure scenarios:

- The initial set of credentials to work with cannot be obtained.
- The account to which the initial credentials belong to cannot be obtained.
- The account associated to the credentials is different from the account on
which the CLI is trying to operate on.

Since these failures may happen for valid use case reasons, the CDK CLI offers
an alternative mechanism for users to provide AWS credentials: credential
provider plugins.

This package defines the types and the contract between the CLI and the plugins,
which plugin authors are expected to adhere to.

The entrypoint is communicated to the CLI via the --plugin command line
argument. The value of this argument should be a JavaScript file that, when
require'd, will return an instance of the Plugin interface.

Once the CLI gets an instance of a plugin, it first initializes plugin by
calling the Plugin.init() method, if one is defined. The CLI uses this method
to pass an instance of IPluginHost to the plugin. The
plugin, in turn, can use the repository to register one or more instances of
CredentialProviderSource, which is where the actual logic for providing
credentials is located.

If, in the authentication process, the CLI decides to use plugins, it will try
each credential provider source in the order in which they were registered. For
each source, the first thing the CLI will check is whether the source is ready
to interact at all, by calling the isAvailable()
method. If it is available, the next check is whether it can provide credentials
for the specific account the CLI is targeting at that moment. This is the
canProvideCredentials() method.

If both checks pass, the CLI asks the source for credentials by calling
getProvider(). In addition to the account ID, this method also receives the
Mode of operation, which can be ForReading or ForWriting. This information
may be useful to tailor the credentials for the use case. For example, if the
CLI needs the credentials only for reading, the plugin may return credentials
with more restricted permissions.

[cli-auth]: (https://docs.aws.amazon.com/cli/v1/userguide/cli-chap-authentication.html)