feat: multi-auth

.changes/nextrelease/multi-auth.json

@@ -0,0 +1,7 @@
+[
+  {
+    "type": "feature",
+    "category": "Auth",
+    "description": "Adds support for the `auth` service trait.  This allows for auth scheme selection at both the service and operation level."
+  }
+]

.github/workflows/docs-build.yml

@@ -78,17 +78,21 @@ jobs:
                 for encoding in encodings:
                   try:
                     with open(file_path, 'r', encoding=encoding) as f:
-                      sourceCode = f.read()
+                      source_code = f.read()
                     break
                   except UnicodeDecodeError:
                     continue
                 
-                pattern = r'(function\s+\w+\([^)]*\))\s*:\s*?\??\w+\s*\n\s*\{'
-                match = re.search(pattern, sourceCode)
+                pattern = r'(function\s+\w+\([^)]*\))\s*:\s*?\??\w+(\s*\n\s*\{|;)'
+                match = re.search(pattern, source_code)
                 if match:
-                  sourceCode = re.sub(pattern, r'\1 {', sourceCode)
+                  def replace_function(match):
+                    return match.group(1) + " {\n" if '{' in match.group(2) else match.group(1) + ';'
+                  
+                  new_source_code = re.sub(pattern, replace_function, source_code)
+        
                   with open(file_path, 'w') as f:
-                    f.write(sourceCode)
+                    f.write(new_source_code)
               
               except FileNotFoundError:
                 print('php file not found : ', file_path)

phpunit.xml.dist

@@ -1,5 +1,10 @@
 <?xml version="1.0" encoding="UTF-8"?>
-<phpunit xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" bootstrap="./tests/bootstrap.php" colors="true" xsi:noNamespaceSchemaLocation="https://schema.phpunit.de/9.3/phpunit.xsd">
+<phpunit xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+         bootstrap="./tests/bootstrap.php"
+         colors="true"
+         xsi:noNamespaceSchemaLocation="https://schema.phpunit.de/9.3/phpunit.xsd"
+         convertDeprecationsToExceptions="true"
+>
   <coverage>
     <include>
       <directory suffix=".php">src</directory>

src/Auth/AuthSchemeResolver.php

@@ -0,0 +1,153 @@
+<?php
+
+namespace Aws\Auth;
+
+use Aws\Auth\Exception\UnresolvedAuthSchemeException;
+use Aws\Identity\AwsCredentialIdentity;
+use Aws\Identity\BearerTokenIdentity;
+
+/**
+ * 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
+{
+    const UNSIGNED_BODY = '-unsigned-body';
+
+    /**
+     * @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',
+        'smithy.api#httpBearerAuth' => 'bearer',
+        'smithy.auth#noAuth' => 'anonymous'
+    ];
+
+    /**
+     * @var array Mapping of auth schemes to signature versions used in
+     *            resolving a signature version.
+     */
+    private $authSchemeMap;
+    private $tokenProvider;
+    private $credentialProvider;
+
+
+    public function __construct(
+        callable $credentialProvider,
+        callable $tokenProvider = null,
+        array $authSchemeMap = []
+    ){
+        $this->credentialProvider = $credentialProvider;
+        $this->tokenProvider = $tokenProvider;
+        $this->authSchemeMap = empty($authSchemeMap)
+            ? self::$defaultAuthSchemeMap
+            : $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
+     *
+     * @return string
+     * @throws UnresolvedAuthSchemeException
+     */
+    public function selectAuthScheme(
+        array $authSchemes,
+        array $args = []
+    ): string
+    {
+        $failureReasons = [];
+
+        foreach($authSchemes as $authScheme) {
+            $normalizedAuthScheme = isset($this->authSchemeMap[$authScheme])
+                ? $this->authSchemeMap[$authScheme]
+                : $authScheme;
+
+            if ($this->isCompatibleAuthScheme($normalizedAuthScheme)) {
+                if ($normalizedAuthScheme === 'v4' && !empty($args['unsigned_payload'])) {
+                    return $normalizedAuthScheme . self::UNSIGNED_BODY;
+                }
+
+                return $normalizedAuthScheme;
+            } else {
+                $failureReasons[] = $this->getIncompatibilityMessage($authScheme);
+            }
+        }
+
+        throw new UnresolvedAuthSchemeException(
+            'Could not resolve an authentication scheme: '
+            . implode('; ', $failureReasons)
+        );
+    }
+
+    /**
+     * Determines compatibility based on either Identity or the availability
+     * of the CRT extension.
+     *
+     * @param $authScheme
+     *
+     * @return bool
+     */
+    private function isCompatibleAuthScheme($authScheme): bool
+    {
+        switch ($authScheme) {
+            case 'v4':
+            case 'anonymous':
+                return $this->hasAwsCredentialIdentity();
+            case 'v4a':
+                return extension_loaded('awscrt') && $this->hasAwsCredentialIdentity();
+            case 'bearer':
+                return $this->hasBearerTokenIdentity();
+            default:
+                return false;
+        }
+    }
+
+    /**
+     * Provides incompatibility messages in the event an incompatible auth scheme
+     * is encountered.
+     *
+     * @param $authScheme
+     *
+     * @return string
+     */
+    private function getIncompatibilityMessage($authScheme): string
+    {
+        switch ($authScheme) {
+            case 'v4a':
+                return 'The aws-crt-php extension must be installed to use Signature V4A';
+            case 'bearer':
+                return 'Bearer token credentials must be provided to use Bearer authentication';
+            default:
+                return "The service does not support `{$authScheme}` authentication.";
+        }
+    }
+
+    /**
+     * @return bool
+     */
+    private function hasAwsCredentialIdentity(): bool
+    {
+        $fn = $this->credentialProvider;
+        return $fn()->wait() instanceof AwsCredentialIdentity;
+    }
+
+    /**
+     * @return bool
+     */
+    private function hasBearerTokenIdentity(): bool
+    {
+        if ($this->tokenProvider) {
+            $fn = $this->tokenProvider;
+            return $fn()->wait() instanceof BearerTokenIdentity;
+        }
+        return false;
+    }
+}

src/Auth/AuthSchemeResolverInterface.php

@@ -0,0 +1,24 @@
+<?php
+
+namespace Aws\Auth;
+
+use Aws\Identity\IdentityInterface;
+
+/**
+ * An AuthSchemeResolver object determines which auth scheme will be used for request signing.
+ */
+interface AuthSchemeResolverInterface
+{
+    /**
+     * 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(
+        array $authSchemes,
+        array $args
+    ): ?string;
+}

src/Auth/AuthSelectionMiddleware.php

@@ -0,0 +1,101 @@
+<?php
+namespace Aws\Auth;
+
+use Aws\Api\Service;
+use Aws\CommandInterface;
+use Closure;
+use GuzzleHttp\Promise\Promise;
+
+/**
+ * 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.
+ *
+ * @internal
+ */
+class AuthSelectionMiddleware
+{
+    /** @var callable */
+    private $nextHandler;
+
+    /** @var AuthSchemeResolverInterface */
+    private $authResolver;
+
+    /** @var Service */
+    private $api;
+
+    /**
+     * Create a middleware wrapper function
+     *
+     * @param AuthSchemeResolverInterface $authResolver
+     * @param Service $api
+     * @return Closure
+     */
+    public static function wrap(
+        AuthSchemeResolverInterface $authResolver,
+        Service $api
+    ): Closure
+    {
+        return function (callable $handler) use ($authResolver, $api) {
+            return new self($handler, $authResolver, $api);
+        };
+    }
+
+    /**
+     * @param callable $nextHandler
+     * @param $authResolver
+     * @param callable $identityProvider
+     * @param Service $api
+     */
+    public function __construct(
+        callable $nextHandler,
+        AuthSchemeResolverInterface $authResolver,
+        Service $api
+    )
+    {
+        $this->nextHandler = $nextHandler;
+        $this->authResolver = $authResolver;
+        $this->api = $api;
+    }
+
+    /**
+     * @param CommandInterface $command
+     *
+     * @return Promise
+     */
+    public function __invoke(CommandInterface $command)
+    {
+        $nextHandler = $this->nextHandler;
+        $serviceAuth = $this->api->getMetadata('auth') ?: [];
+        $operation = $this->api->getOperation($command->getName());
+        $operationAuth = isset($operation['auth']) ? $operation['auth'] : [];
+        $unsignedPayload = isset($operation['unsignedpayload'])
+            ? $operation['unsignedpayload']
+            : false;
+        $resolvableAuth = $operationAuth ?: $serviceAuth;
+
+        if (!empty($resolvableAuth)) {
+            if (isset($command['@context']['auth_scheme_resolver'])
+                && $command['@context']['auth_scheme_resolver'] instanceof AuthSchemeResolverInterface
+            ){
+                $resolver = $command['@context']['auth_scheme_resolver'];
+            } else {
+                $resolver = $this->authResolver;
+            }
+
+            $selectedAuthScheme = $resolver->selectAuthScheme(
+                $resolvableAuth,
+                ['unsigned_payload' => $unsignedPayload]
+            );
+
+            if (!empty($selectedAuthScheme)) {
+                $command['@context']['signature_version'] = $selectedAuthScheme;
+            }
+        }
+
+        return $nextHandler($command);
+    }
+}