Add aws.auth#cognitoUserPoolsScopes trait

API Gateway supports OAuth scopes on operations that use Cognito User
Pools authorizers. The aws.apigateway#authorizationScopes trait added
in #3084 targeted only the operations annotated with @Authorizer.
That trait pairs scopes with the generic API Gateway authorizer trait,
but scopes only apply when the authorizer is Cognito so the trait
belongs alongside @cognitoUserPools in the aws.auth namespace.

Add the `aws.auth#cognitoUserPoolsScopes` list trait, selectable only
on operations bound to a service with the @cognitoUserPools trait
applied. The new `AddCognitoUserPoolsScopes` OpenAPI mapper writes a
per-operation security requirement using the Cognito scheme name when
the trait is present.

Author: mee-aa

.changes/next-release/feature-1d0fb9d2b93784accf545d038bd5b0658cc9ca13.json

@@ -0,0 +1,7 @@
+{
+  "type": "feature",
+  "description": "Added `aws.auth#cognitoUserPoolsScopes` trait for specifying OAuth scopes on operations that use an Amazon Cognito User Pools authorizer.",
+  "pull_requests": [
+    "[#3109](https://github.com/smithy-lang/smithy/pull/3109)"
+  ]
+}

.changes/next-release/feature-cognito-user-pools-scopes-trait.json

@@ -584,72 +584,6 @@ endpoint access mode:
     This trait should be considered internal-only and not exposed to your
     customers.
 
-.. smithy-trait:: aws.apigateway#authorizationScopes
-.. _aws.apigateway#authorizationScopes-trait:
-
---------------------------------------------
-``aws.apigateway#authorizationScopes`` trait
---------------------------------------------
-
-Summary
-    Defines the list of OAuth scopes required for an API Gateway operation
-    that uses a `Cognito`_ authorizer. Applied alongside the
-    :ref:`aws.apigateway#authorizer-trait` to specify which scopes the
-    caller must have.
-Trait selector
-    ``operation[trait|aws.apigateway#authorizer]``
-
-    *An operation with the aws.apigateway#authorizer trait applied*
-Value type
-    ``list`` of ``string``
-See also
-    - `Control access using Cognito user pools`_ for more information on
-      how scopes work with Cognito authorizers
-
-.. note::
-
-    Authorization scopes are only supported with ``COGNITO_USER_POOLS``
-    authorizers. API Gateway validates the scope values at import time.
-
-The following example requires the ``email`` and ``profile`` scopes on an
-operation that uses a Cognito authorizer:
-
-.. code-block:: smithy
-
-    $version: "2"
-
-    namespace smithy.example
-
-    use aws.apigateway#authorizer
-    use aws.apigateway#authorizers
-    use aws.apigateway#authorizationScopes
-    use aws.auth#sigv4
-
-    @sigv4(name: "service")
-    @authorizer("my-cognito-auth")
-    @authorizers(
-        "my-cognito-auth": {
-            scheme: "aws.auth#sigv4"
-            type: "cognito_user_pools"
-        }
-    )
-    service MyService {
-      version: "2024-01-01"
-      operations: [GetUserProfile]
-    }
-
-    @authorizer("my-cognito-auth")
-    @authorizationScopes(["email", "profile"])
-    operation GetUserProfile {
-        input := {}
-        output := {}
-    }
-
-.. note::
-
-    This trait should be considered internal-only and not exposed to your
-    customers.
-
 .. smithy-trait:: aws.apigateway#integration
 .. _aws.apigateway#integration-trait:
 
@@ -1334,5 +1268,3 @@ integration response to two ``header`` parameters of the method response.
 .. _x-amazon-apigateway-endpoint-configuration: https://docs.aws.amazon.com/apigateway/latest/developerguide/api-gateway-swagger-extensions-endpoint-configuration.html
 .. _API endpoint types for REST APIs: https://docs.aws.amazon.com/apigateway/latest/developerguide/api-gateway-api-endpoint-types.html
 .. _endpoint IDs: https://docs.aws.amazon.com/vpc/latest/privatelink/concepts.html#concepts-vpc-endpoints
-.. _Control access using Cognito user pools: https://docs.aws.amazon.com/apigateway/latest/developerguide/apigateway-integrate-with-cognito.html
-.. _Cognito: https://docs.aws.amazon.com/cognito/latest/developerguide/cognito-user-pools.html

docs/source-2.0/aws/amazon-apigateway.rst

@@ -210,6 +210,61 @@ Trait value
     }
 
 
+.. smithy-trait:: aws.auth#cognitoUserPoolsScopes
+.. _aws.auth#cognitoUserPoolsScopes-trait:
+
+-----------------------------------------
+``aws.auth#cognitoUserPoolsScopes`` trait
+-----------------------------------------
+
+Trait summary
+    The ``aws.auth#cognitoUserPoolsScopes`` trait defines the list of
+    OAuth scopes required to invoke an operation that uses an
+    :ref:`aws.auth#cognitoUserPools-trait` authorizer.
+Trait selector
+    ``service[trait|aws.auth#cognitoUserPools] ~> operation``
+
+    *An operation in a service that has the ``aws.auth#cognitoUserPools``
+    trait applied.*
+Trait value
+    A list of ``string`` values.
+
+When the scopes list is non-empty, the generated OpenAPI operation emits a
+``security`` requirement that uses the ``aws.auth.cognitoUserPools`` security
+scheme name and carries the listed scopes. See :ref:`smithy-to-openapi` for
+details.
+
+.. code-block:: smithy
+
+    $version: "2"
+
+    namespace aws.fooBaz
+
+    use aws.api#service
+    use aws.auth#cognitoUserPools
+    use aws.auth#cognitoUserPoolsScopes
+    use aws.protocols#restJson1
+
+    @service(sdkId: "Some Value")
+    @cognitoUserPools(
+        providerArns: ["arn:aws:cognito-idp:us-east-1:123:userpool/123"])
+    @restJson1
+    service FooBaz {
+        version: "2018-03-17"
+        operations: [GetThing]
+    }
+
+    @cognitoUserPoolsScopes(["email", "profile"])
+    @http(method: "GET", uri: "/things/{id}")
+    operation GetThing {
+        input := {
+            @httpLabel
+            @required
+            id: String
+        }
+    }
+
+
 .. _AWS signature version 4: https://docs.aws.amazon.com/general/latest/gr/signature-version-4.html
 .. _AWS Signature Version 4 Asymmetric (SigV4A): https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_sigv.html#how-sigv4a-works
 .. _credential scope: https://docs.aws.amazon.com/general/latest/gr/sigv4-create-string-to-sign.html

docs/source-2.0/aws/aws-auth.rst

@@ -2158,6 +2158,49 @@ entry:
 In the entry, ``providerARNs`` will be populated from the ``providerArns`` list
 from the trait.
 
+Per-operation scopes can be required by applying the
+:ref:`aws.auth#cognitoUserPoolsScopes-trait` to an operation. When scopes
+are present, Smithy emits a ``security`` requirement on the generated OpenAPI
+operation that uses the ``aws.auth.cognitoUserPools`` scheme name:
+
+.. code-block:: smithy
+
+    $version: "2"
+    namespace smithy.example
+
+    use aws.auth#cognitoUserPools
+    use aws.auth#cognitoUserPoolsScopes
+    use aws.protocols#restJson1
+
+    @restJson1
+    @cognitoUserPools(
+        providerArns: ["arn:aws:cognito-idp:us-east-1:123:userpool/123"])
+    service Example {
+        version: "2019-06-17"
+        operations: [GetThing]
+    }
+
+    @cognitoUserPoolsScopes(["email", "profile"])
+    @http(method: "GET", uri: "/things")
+    operation GetThing {}
+
+The ``GetThing`` operation in the generated OpenAPI will include:
+
+.. code-block:: json
+
+    {
+        "security": [
+            {
+                "aws.auth.cognitoUserPools": [
+                    "email",
+                    "profile"
+                ]
+            }
+        ]
+    }
+
+Operations without the trait inherit the service-level security requirement.
+
 Amazon API Gateway API key usage plans
 ======================================
 
@@ -2316,73 +2359,6 @@ is converted to the following OpenAPI model:
     }
 
 
-.. _apigateway-authorization-scopes:
-
-Authorization scopes
-====================
-
-When an operation uses a `Cognito`_ authorizer, OAuth scopes can be added to
-the security requirement using the
-:ref:`aws.apigateway#authorizationScopes-trait`. The trait is applied
-alongside the :ref:`aws.apigateway#authorizer-trait` on an operation and
-specifies which scopes the caller must have.
-
-The following Smithy model requires the ``email`` and ``profile`` scopes
-on the ``GetUserProfile`` operation:
-
-.. code-block:: smithy
-
-    $version: "2"
-    namespace smithy.example
-
-    use aws.apigateway#authorizer
-    use aws.apigateway#authorizers
-    use aws.apigateway#authorizationScopes
-    use aws.auth#sigv4
-    use aws.protocols#restJson1
-
-    @restJson1
-    @sigv4(name: "service")
-    @authorizer("my-cognito-auth")
-    @authorizers(
-        "my-cognito-auth": {scheme: "aws.auth#sigv4", type: "cognito_user_pools"}
-    )
-    service Example {
-      version: "2019-06-17"
-      operations: [GetUserProfile]
-    }
-
-    @authorizer("my-cognito-auth")
-    @authorizationScopes(["email", "profile"])
-    @http(uri: "/profile", method: "GET")
-    operation GetUserProfile {}
-
-The scopes are included in the OpenAPI security requirement for the
-operation:
-
-.. code-block:: json
-
-    {
-        "paths": {
-            "/profile": {
-                "get": {
-                    "operationId": "GetUserProfile",
-                    "responses": {
-                        "200": {
-                            "description": "GetUserProfile response"
-                        }
-                    },
-                    "security": [
-                        {
-                            "my-cognito-auth": ["email", "profile"]
-                        }
-                    ]
-                }
-            }
-        }
-    }
-
-
 .. _other-traits:
 
 Other traits that influence API Gateway
@@ -2489,4 +2465,3 @@ The conversion process is highly extensible through
 .. _x-amazon-apigateway-gateway-responses: https://docs.aws.amazon.com/apigateway/latest/developerguide/api-gateway-swagger-extensions-gateway-responses.html
 .. _x-amazon-apigateway-security-policy: https://docs.aws.amazon.com/apigateway/latest/developerguide/openapi-extensions-security-policy.html
 .. _x-amazon-apigateway-endpoint-access-mode: https://docs.aws.amazon.com/apigateway/latest/developerguide/openapi-extensions-endpoint-access-mode.html
-.. _Cognito: https://docs.aws.amazon.com/cognito/latest/developerguide/cognito-user-pools.html

docs/source-2.0/guides/model-translations/converting-to-openapi.rst

@@ -9,7 +9,6 @@
 import java.util.Objects;
 import java.util.Optional;
 import java.util.logging.Logger;
-import software.amazon.smithy.aws.apigateway.traits.AuthorizationScopesTrait;
 import software.amazon.smithy.aws.apigateway.traits.AuthorizerDefinition;
 import software.amazon.smithy.aws.apigateway.traits.AuthorizerIndex;
 import software.amazon.smithy.aws.apigateway.traits.AuthorizerTrait;
@@ -107,18 +106,12 @@ public OperationObject updateOperation(
         // ...API Gateway's built-in API keys are being used. It requires the
         // security to be specified on every operation.
         // See https://docs.aws.amazon.com/apigateway/latest/developerguide/api-gateway-setup-api-key-with-console.html#api-gateway-usage-plan-configure-apikey-on-method
-        List<String> scopes = shape.getTrait(AuthorizationScopesTrait.class)
-                .map(AuthorizationScopesTrait::getValues)
-                .orElse(ListUtils.of());
-
-        if (Objects.equals(operationAuth, serviceAuth)
-                && !usesApiGatewayApiKeys(service, operationAuth)
-                && scopes.isEmpty()) {
+        if (Objects.equals(operationAuth, serviceAuth) && !usesApiGatewayApiKeys(service, operationAuth)) {
             return operation;
         }
 
         return operation.toBuilder()
-                .addSecurity(MapUtils.of(operationAuth, scopes))
+                .addSecurity(MapUtils.of(operationAuth, ListUtils.of()))
                 .build();
     }
 

smithy-aws-apigateway-openapi/src/main/java/software/amazon/smithy/aws/apigateway/openapi/AddAuthorizers.java

@@ -0,0 +1,83 @@
+/*
+ * Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+ * SPDX-License-Identifier: Apache-2.0
+ */
+package software.amazon.smithy.aws.apigateway.openapi;
+
+import java.util.List;
+import java.util.Map;
+import java.util.logging.Logger;
+import software.amazon.smithy.aws.traits.auth.CognitoUserPoolsScopesTrait;
+import software.amazon.smithy.aws.traits.auth.CognitoUserPoolsTrait;
+import software.amazon.smithy.model.knowledge.ServiceIndex;
+import software.amazon.smithy.model.shapes.OperationShape;
+import software.amazon.smithy.model.traits.Trait;
+import software.amazon.smithy.openapi.fromsmithy.Context;
+import software.amazon.smithy.openapi.model.OperationObject;
+import software.amazon.smithy.utils.ListUtils;
+import software.amazon.smithy.utils.MapUtils;
+
+/**
+ * Adds per-operation OAuth scopes to the Cognito User Pools security
+ * requirement when an operation is annotated with
+ * {@link CognitoUserPoolsScopesTrait}.
+ *
+ * <p>The mapper only applies when Cognito User Pools is an effective
+ * authentication scheme for the operation. Operations that opt out of
+ * authentication with {@code @auth([])} or use a different scheme are
+ * left unchanged. When scopes are present the mapper appends a security
+ * requirement to the operation using the Cognito scheme name, which
+ * takes precedence over the service-level security requirement.
+ *
+ * @see <a href="https://docs.aws.amazon.com/apigateway/latest/developerguide/apigateway-enable-cognito-user-pool.html">Integrate a REST API with a User Pool</a>
+ */
+final class AddCognitoUserPoolsScopes implements ApiGatewayMapper {
+
+    private static final Logger LOGGER = Logger.getLogger(AddCognitoUserPoolsScopes.class.getName());
+
+    @Override
+    public List<ApiGatewayConfig.ApiType> getApiTypes() {
+        return ListUtils.of(ApiGatewayConfig.ApiType.REST);
+    }
+
+    @Override
+    public OperationObject updateOperation(
+            Context<? extends Trait> context,
+            OperationShape shape,
+            OperationObject operation,
+            String httpMethodName,
+            String path
+    ) {
+        if (!context.getService().hasTrait(CognitoUserPoolsTrait.class)) {
+            return operation;
+        }
+
+        if (!shape.hasTrait(CognitoUserPoolsScopesTrait.ID)) {
+            return operation;
+        }
+
+        List<String> scopes = shape.expectTrait(CognitoUserPoolsScopesTrait.class).getValues();
+
+        // Only emit a scoped security requirement when Cognito is actually an
+        // effective auth scheme for this operation. This respects operations
+        // that opt out of auth via @auth([]) or that use a different scheme
+        // via @auth.
+        ServiceIndex serviceIndex = ServiceIndex.of(context.getModel());
+        if (!serviceIndex.getEffectiveAuthSchemes(context.getService(), shape)
+                .containsKey(CognitoUserPoolsTrait.ID)) {
+            return operation;
+        }
+
+        String schemeName = CognitoUserPoolsTrait.ID.toString().replace("#", ".");
+        Map<String, List<String>> requirement = MapUtils.of(schemeName, scopes);
+
+        LOGGER.fine(() -> String.format(
+                "Adding Cognito User Pools scopes %s to operation %s",
+                scopes,
+                shape.getId()));
+
+        return operation.toBuilder()
+                .addSecurity(requirement)
+                .build();
+    }
+}