From 29f21a73457c92b756defcb2a69c162ed928c965 Mon Sep 17 00:00:00 2001 From: Sean O'Brien Date: Thu, 15 Feb 2024 17:23:04 -0500 Subject: [PATCH] update documentation --- src/Auth/AuthSchemeResolver.php | 22 +++++++++++++++++++++- src/Auth/AuthSchemeResolverInterface.php | 9 ++++++--- src/Auth/AuthSelectionMiddleware.php | 13 ++++++++----- src/Auth/Exception/AuthException.php | 6 +++++- src/ClientResolver.php | 2 +- src/Command.php | 6 +++--- src/Identity/IdentityInterface.php | 3 +++ 7 files changed, 47 insertions(+), 14 deletions(-) diff --git a/src/Auth/AuthSchemeResolver.php b/src/Auth/AuthSchemeResolver.php index 7e33a5ab90..8450e678bb 100644 --- a/src/Auth/AuthSchemeResolver.php +++ b/src/Auth/AuthSchemeResolver.php @@ -6,13 +6,22 @@ use Aws\Identity\BearerTokenIdentity; use Aws\Identity\IdentityInterface; +/** + * Houses logic for selecting an auth scheme modeled in a service's `auth` trait. + * The `auth` trait can be modeled either in a service's metadata, or at the operation level. + */ class AuthSchemeResolver implements AuthSchemeResolverInterface { /** - * @var array + * @var array Mapping of auth schemes to signature versions used in + * resolving a signature version. */ private $authSchemeMap; + /** + * @var string[] Default mapping of modeled auth trait auth schemes + * to the SDK's supported signature versions. + */ private static $defaultAuthSchemeMap = [ 'aws.auth#sigv4' => 'v4', 'aws.auth#sigv4a' => 'v4a', @@ -28,6 +37,11 @@ public function __construct(array $authSchemeMap = []) } /** + * Accepts a priority-ordered list of auth schemes and an Identity + * and selects the first compatible auth schemes, returning a normalized + * signature version. For example, based on the default auth scheme mapping, + * if `aws.auth#sigv4` is selected, `v4` will be returned. + * * @param array $authSchemes * @param $identity * @@ -60,6 +74,9 @@ public function selectAuthScheme( } /** + * Determines compatibility based on either Identity or the availability + * of the CRT extension. + * * @param $authScheme * @param $identity * @@ -85,6 +102,9 @@ private function isCompatibleAuthScheme($authScheme, $identity): bool } /** + * Provides incompatibility messages in the event an incompatible auth scheme + * is encountered. + * * @param $authScheme * * @return string diff --git a/src/Auth/AuthSchemeResolverInterface.php b/src/Auth/AuthSchemeResolverInterface.php index d967cd5abf..67ec20d9c6 100644 --- a/src/Auth/AuthSchemeResolverInterface.php +++ b/src/Auth/AuthSchemeResolverInterface.php @@ -5,13 +5,16 @@ use Aws\Identity\IdentityInterface; /** - * + * An AuthSchemeResolver object determines which auth scheme will be used for request signing. */ interface AuthSchemeResolverInterface { /** - * @param array $authSchemes - * @param IdentityInterface $identity + * Selects an auth scheme for request signing. + * + * @param array $authSchemes a priority-ordered list of authentication schemes. + * @param IdentityInterface $identity Credentials to be used in request signing. + * * @return string */ public function selectAuthScheme( diff --git a/src/Auth/AuthSelectionMiddleware.php b/src/Auth/AuthSelectionMiddleware.php index aa13a9619a..2e9c747c82 100644 --- a/src/Auth/AuthSelectionMiddleware.php +++ b/src/Auth/AuthSelectionMiddleware.php @@ -7,10 +7,12 @@ use GuzzleHttp\Promise\Promise; /** - * Handles auth scheme resolution. + * Handles auth scheme resolution. If a service models and auth scheme using + * the `auth` trait and the operation or metadata levels, this middleware will + * attempt to select the first compatible auth scheme it encounters and apply its + * signature version to the command's `@context` property bag. * * IMPORTANT: this middleware must be added to the "build" step. - * Specifically, it must precede the 'endpoint-v2-middleware' step. * * @internal */ @@ -19,7 +21,7 @@ class AuthSelectionMiddleware /** @var callable */ private $nextHandler; - /** @var callable | AuthResolver */ + /** @var AuthSchemeResolverInterface */ private $authResolver; /** @var callable */ @@ -82,14 +84,15 @@ public function __construct( public function __invoke(CommandInterface $command) { $nextHandler = $this->nextHandler; - $identityFn = $this->identityProvider; - $identity = $identityFn()->wait(); $serviceAuth = $this->api->getMetadata('auth') ?: []; $operation = $this->api->getOperation($command->getName()); $operationAuth = isset($operation['auth']) ? $operation['auth'] : []; $resolvableAuth = $operationAuth ?: $serviceAuth; if (!empty($resolvableAuth)) { + $identityFn = $this->identityProvider; + $identity = $identityFn()->wait(); + if (isset($command['@context']['authResolver']) && $command['@context']['authResolver'] instanceof AuthSchemeResolverInterface ){ diff --git a/src/Auth/Exception/AuthException.php b/src/Auth/Exception/AuthException.php index bca0dc8358..72e2725816 100644 --- a/src/Auth/Exception/AuthException.php +++ b/src/Auth/Exception/AuthException.php @@ -2,5 +2,9 @@ namespace Aws\Auth\Exception; +use Aws\Exception\AwsException; -class AuthException extends \RuntimeException {} +/** + * Represents an error when attempting to resolve authentication. + */ +class AuthException extends AwsException {} diff --git a/src/ClientResolver.php b/src/ClientResolver.php index 9d7dcdc181..1107b3dde6 100644 --- a/src/ClientResolver.php +++ b/src/ClientResolver.php @@ -122,7 +122,7 @@ class ClientResolver 'auth_scheme_resolver' => [ 'type' => 'value', 'valid' => [AuthSchemeResolverInterface::class], - 'doc' => 'A callable or Aws\Auth\AuthResolver object which accept a priority-ordered list of auth scheme versions and an identity and returns an auth scheme version', + 'doc' => 'An instance of Aws\Auth\AuthSchemeResolverInterface which selects a modeled auth scheme and returns a signature version', 'default' => [__CLASS__, '_default_auth_scheme_resolver'], ], 'api_provider' => [ diff --git a/src/Command.php b/src/Command.php index e9b8b86fdc..97518870a9 100644 --- a/src/Command.php +++ b/src/Command.php @@ -66,9 +66,9 @@ public function getHandlerList() * * @returns array * - * @deprecated In favor of using the @context key. - * Auth schemes are now accessible via the `signature_version` key - * in a Command's context, if applicable. + * @deprecated In favor of using the @context property bag. + * Auth schemes are now accessible via the `signature_version` key + * in a Command's context, if applicable. */ public function getAuthSchemes() { diff --git a/src/Identity/IdentityInterface.php b/src/Identity/IdentityInterface.php index e85ae7d5ee..608ec9f9aa 100644 --- a/src/Identity/IdentityInterface.php +++ b/src/Identity/IdentityInterface.php @@ -2,6 +2,9 @@ namespace Aws\Identity; +/** + * @internal + */ interface IdentityInterface { /**