@aws-cdk/cli-plugin-contract

AWS CDK CLI Library

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. 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.