+ Timing SDK operations +
+How to perform basic instrumentation in the AWS SDK for Go V2 to time SDK operations
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Natively-supported
+
+
+
+
+
+
+ Configuring Authentication
+Customizing service client authentication.
+ The AWS SDK for Go V2 provides the ability to configure the authentication +behavior service. In most cases, the default configuration will suffice, but +configuring custom authentication allows for additional behavior such as +working with pre-release service features.
+Definitions
+This section provides a high-level description of authentication components in +the AWS SDK for Go V2.
+AuthScheme
+An AuthScheme is the +interface that defines the workflow through which the SDK retrieves a caller +identity and attaches it to an operation request.
+An auth scheme uses the following components, described in detail further +below:
+-
+
- A unique ID which identifies the scheme +
- An identity resolver, which returns a caller identity used in the signing +process (e.g. your AWS credentials) +
- A signer, which performs the actual injection of caller identity into the
+operation’s transport request (e.g. the
AuthorizationHTTP header)
+
Each service client options includes an AuthSchemes field, which by default
+is populated with the list of auth schemes supported by that service.
AuthSchemeResolver
+Each service client options includes an AuthSchemeResolver field. This
+interface, defined per-service, is the API called by the SDK to determine the
+possible authentication options for each operation.
IMPORTANT: The auth scheme resolver does NOT dictate what auth scheme is +used. It returns a list of schemes that can be used (“options”), the final +scheme is selected through a fixed algorithm described +here.
+Option
+Returned from a call to ResolverAuthSchemes, an Option represents a possible authentication option.
An option consists of three sets of information:
+-
+
- An ID representing the possible scheme +
- An opaque set of properties to be provided to the scheme’s identity resolver +
- An opaque set of properties to be provided to the scheme’s signer +
a note on properties
+For 99% of use cases, callers need not be concerned with the opaque properties +for identity resolution and signing. The SDK will pull out the necessary +properties for each scheme and pass them to the strongly-typed interfaces +exposed in the SDK. For example, the default auth resolver for services encode +the SigV4 option to have signer properties for the signing name and region, the +values of which are passed to the client’s configured +v4.HTTPSigner implementation when SigV4 +is selected.
+Identity
+An Identity is an abstract +representation of who the SDK caller is.
+The most common type of identity used in the SDK is a set of aws.Credentials.
+For most use cases, the caller need not concern themselves with Identity as
+an abstraction and can work with the concrete types directly.
Note: to preserve backwards compatibility and prevent API confusion, the
+AWS SDK-specific identity type aws.Credentials does not directly satisfy the
+Identity interface. This mapping is handled internally.
IdentityResolver
+IdentityResolver is the
+interface through which an Identity is retrieved.
Concrete versions of IdentityResolver exist in the SDK in strongly-typed form
+(e.g. aws.CredentialsProvider), the
+SDK handles this mapping internally.
A caller will only need to directly implement the IdentityResolver interface
+when defining an external auth scheme.
Signer
+Signer is the interface
+through which a request is supplemented with the retrieved caller Identity.
Concrete versions of Signer exist in the SDK in strongly-typed form
+(e.g. v4.HTTPSigner), the SDK
+handles this mapping internally.
A caller will only need to directly implement the Signer interface
+when defining an external auth scheme.
AuthResolverParameters
+Each service takes a specific set of inputs which are passed to its resolution
+function, defined in each service package as AuthResolverParameters.
The base resolver parameters are as follows:
+| name | +type | +description | +
|---|---|---|
Operation |
+string |
+The name of the operation being invoked. | +
Region |
+string |
+The client’s AWS region. Only present for services that use SigV4[A]. | +
If you are implementing your own resolver, you should never need to construct +your own instance of its parameters. The SDK will source these values +per-request and pass them to your implementation.
+Auth scheme resolution workflow
+When you call an AWS service operation through the SDK, the following sequence +of actions occurs after the request has been serialized:
+-
+
- The SDK calls the client’s
AuthSchemeResolver.ResolveAuthSchemes()API, +sourcing the input parameters as necessary, to obtain a list of possible +Options for the operation.
+ - The SDK iterates over that list and selects the first scheme that satisfies
+the following conditions.
+
-
+
- A scheme with matching ID is present in the client’s own
AuthSchemeslist
+ - The scheme’s identity resolver exists (is non-
nil) on the client’s Options +(checked via the scheme’sGetIdentityResolvermethod, the mapping to the +concrete identity resolver types described above is handled internally) (1)
+
+ - A scheme with matching ID is present in the client’s own
- Assuming a viable scheme was selected, the SDK invokes its
+
GetIdentityResolver()API to retrieve the caller’s identity. For example, +the builtin SigV4 auth scheme will map to the client’sCredentialsprovider +internally.
+ - The SDK calls the identity resolver’s
GetIdentity()(e.g. +aws.CredentialProvider.Retrieve()for SigV4).
+ - The SDK calls the endpoint resolver’s
ResolveEndpoint()to find the +endpoint for the request. The endpoint may include additional metadata that +influences the signing process (e.g. unique signing name for S3 Object Lambda).
+ - The SDK calls the auth scheme’s
Signer()API to retrieve its signer, and +uses itsSignRequest()API to sign the request with the +previously-retrieved caller identity.
+
(1) If the SDK encounters the anonymous option (ID smithy.api#noAuth) in the
+list, it is selected automatically, as there is no corresponding identity
+resolver.
Natively-supported AuthSchemes
+The following auth schemes are natively supported by AWS SDK for Go V2.
+| Name | +Scheme ID | +Identity resolver | +Signer | +Notes | +
|---|---|---|---|---|
| SigV4 | +aws.auth#sigv4 |
+aws.CredentialsProvider | +v4.HTTPSigner | +The current default for most AWS service operations. | +
| SigV4A | +aws.auth#sigv4a |
+aws.CredentialsProvider | +n/a | +SigV4A usage is limited at this time, the signer implementation is internal. | +
| SigV4Express | +com.amazonaws.s3#sigv4express |
+s3.ExpressCredentialsProvider | +v4.HTTPSigner | +Used for Express One Zone. | +
| HTTP Bearer | +smithy.api#httpBearerAuth |
+smithybearer.TokenProvider | +smithybearer.Signer | +Used by codecatalyst. | +
| Anonymous | +smithy.api#noAuth |
+n/a | +n/a | +No authentication - no identity is required, and the request is not signed or authenticated. | +
Identity configuration
+In AWS SDK for Go V2, the identity components of an auth scheme are
+configured in SDK client Options. The SDK will automatically pick up and use
+the values for these components for the scheme it selects when an operation is
+called.
Note: For backwards compatibility reasons, the SDK implicitly allows the
+use of the anonymous auth scheme if no identity resolvers are configured.
+This can be manually achieved by setting all identity resolvers on a client’s
+Options to nil (the sigv4 identity resolver can also be set to
+aws.AnonymousCredentials{}).
Signer configuration
+In AWS SDK for Go V2, the signer components of an auth scheme are
+configured in SDK client Options. The SDK will automatically pick up and use
+the values for these components for the scheme it selects when an operation is
+called. No additional configuration is necessary.
Custom auth scheme
+In order to define a custom auth scheme and configure it for use, the caller +must do the following:
+-
+
- Define an AuthScheme +implementation +
- Register the scheme on the SDK client’s
AuthSchemeslist
+ - Instrument the SDK client’s
AuthSchemeResolverto return an authOption+with the scheme’s ID where applicable
+
+
+
+
+
+
+
+
+
+
+ The following services have unique or customized authentication behavior. We +recommend you delegate to the default implementation and wrap accordingly if +you require custom authentication behavior therein:
+| Service | +Notes | +
|---|---|
| S3 | +Conditional use of SigV4A and SigV4Express depending on operation input. | +
| EventBridge | +Conditional use of SigV4A depending on operation input. | +
| Cognito | +Certain operations are anonymous-only. | +
| SSO | +Certain operations are anonymous-only. | +
| STS | +Certain operations are anonymous-only. | +
+ Last modified December 19, 2023: Add authentication config guide (#2426) (766cb48e53)
+
+
+