From 7bf6e0098a9ca1bdbaefc93c79a6f26fec5e5d2c Mon Sep 17 00:00:00 2001 From: Miles Ziemer <45497130+milesziemer@users.noreply.github.com> Date: Fri, 18 Aug 2023 11:04:20 -0400 Subject: [PATCH] Add validator for services with no auth trait (#1929) Adds a validator that warns when there's a service shape that has multiple authDefinition traits applied, but no auth trait. This encourages the use of the auth trait so auth scheme priority is being modeled explicitly. It also allows for tooling to look for and use this validation event. Documentation was also updated to explain that without the auth trait, auth scheme ordering is alphabetical. A test for the auth trait (auth-trait-must-target-service-schemes) was updated to avoid getting the warning message from the new validator. --- .../source-2.0/spec/authentication-traits.rst | 5 ++ .../ServiceAuthDefinitionsValidator.java | 53 +++++++++++++++++++ ...e.amazon.smithy.model.validation.Validator | 1 + ...uth-trait-must-target-service-schemes.json | 6 ++- .../multiple-auth-schemes.errors | 1 + .../multiple-auth-schemes.smithy | 18 +++++++ .../one-auth-scheme.errors | 0 .../one-auth-scheme.smithy | 16 ++++++ 8 files changed, 99 insertions(+), 1 deletion(-) create mode 100644 smithy-model/src/main/java/software/amazon/smithy/model/validation/validators/ServiceAuthDefinitionsValidator.java create mode 100644 smithy-model/src/test/resources/software/amazon/smithy/model/errorfiles/validators/service-auth-definitions/multiple-auth-schemes.errors create mode 100644 smithy-model/src/test/resources/software/amazon/smithy/model/errorfiles/validators/service-auth-definitions/multiple-auth-schemes.smithy create mode 100644 smithy-model/src/test/resources/software/amazon/smithy/model/errorfiles/validators/service-auth-definitions/one-auth-scheme.errors create mode 100644 smithy-model/src/test/resources/software/amazon/smithy/model/errorfiles/validators/service-auth-definitions/one-auth-scheme.smithy diff --git a/docs/source-2.0/spec/authentication-traits.rst b/docs/source-2.0/spec/authentication-traits.rst index d1d0b3e1605..446560d8606 100644 --- a/docs/source-2.0/spec/authentication-traits.rst +++ b/docs/source-2.0/spec/authentication-traits.rst @@ -276,6 +276,11 @@ the ``auth`` trait, then the operation is expected to support each of the service. Each entry in the ``auth`` trait is a shape ID that MUST refer to an authentication scheme trait applied to the service in which it is bound. +.. note:: + When a service has multiple authentication scheme traits applied and no + ``auth`` trait, the ordering of authentication schemes is alphabetical + based on the absolute shape ID of each authentication scheme trait. + The following example defines all combinations in which ``auth`` can be applied to services and operations: diff --git a/smithy-model/src/main/java/software/amazon/smithy/model/validation/validators/ServiceAuthDefinitionsValidator.java b/smithy-model/src/main/java/software/amazon/smithy/model/validation/validators/ServiceAuthDefinitionsValidator.java new file mode 100644 index 00000000000..3e596571231 --- /dev/null +++ b/smithy-model/src/main/java/software/amazon/smithy/model/validation/validators/ServiceAuthDefinitionsValidator.java @@ -0,0 +1,53 @@ +/* + * Copyright 2023 Amazon.com, Inc. or its affiliates. All Rights Reserved. + * + * Licensed under the Apache License, Version 2.0 (the "License"). + * You may not use this file except in compliance with the License. + * A copy of the License is located at + * + * http://aws.amazon.com/apache2.0 + * + * or in the "license" file accompanying this file. This file is distributed + * on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either + * express or implied. See the License for the specific language governing + * permissions and limitations under the License. + */ + +package software.amazon.smithy.model.validation.validators; + +import java.util.ArrayList; +import java.util.List; +import java.util.stream.Collectors; +import software.amazon.smithy.model.Model; +import software.amazon.smithy.model.knowledge.ServiceIndex; +import software.amazon.smithy.model.shapes.ServiceShape; +import software.amazon.smithy.model.traits.AuthTrait; +import software.amazon.smithy.model.validation.AbstractValidator; +import software.amazon.smithy.model.validation.ValidationEvent; + +/** + * Validates the @authDefinition traits applied to service shapes. + */ +public class ServiceAuthDefinitionsValidator extends AbstractValidator { + + @Override + public List validate(Model model) { + List events = new ArrayList<>(); + ServiceIndex index = ServiceIndex.of(model); + + List services = model.getServiceShapes().stream() + .filter(serviceShape -> !serviceShape.hasTrait(AuthTrait.ID)) + .filter(serviceShape -> index.getAuthSchemes(serviceShape).size() > 1) + .collect(Collectors.toList()); + + for (ServiceShape service : services) { + events.add(warning(service, "This service uses multiple authentication schemes but does not have " + + "the `@auth` trait applied. The `@auth` trait defines a priority ordering " + + "of auth schemes for a client to use. Without it, the ordering of auth " + + "schemes is alphabetical based on the absolute shape ID of the auth " + + "schemes.")); + + } + return events; + } +} diff --git a/smithy-model/src/main/resources/META-INF/services/software.amazon.smithy.model.validation.Validator b/smithy-model/src/main/resources/META-INF/services/software.amazon.smithy.model.validation.Validator index 391872dd462..f278bac44bc 100644 --- a/smithy-model/src/main/resources/META-INF/services/software.amazon.smithy.model.validation.Validator +++ b/smithy-model/src/main/resources/META-INF/services/software.amazon.smithy.model.validation.Validator @@ -36,6 +36,7 @@ software.amazon.smithy.model.validation.validators.ResourceIdentifierBindingVali software.amazon.smithy.model.validation.validators.ResourceIdentifierValidator software.amazon.smithy.model.validation.validators.ResourceLifecycleValidator software.amazon.smithy.model.validation.validators.ResourceOperationInputOutputValidator +software.amazon.smithy.model.validation.validators.ServiceAuthDefinitionsValidator software.amazon.smithy.model.validation.validators.ServiceValidator software.amazon.smithy.model.validation.validators.SetValidator software.amazon.smithy.model.validation.validators.ShapeIdConflictValidator diff --git a/smithy-model/src/test/resources/software/amazon/smithy/model/errorfiles/validators/auth/auth-trait-must-target-service-schemes.json b/smithy-model/src/test/resources/software/amazon/smithy/model/errorfiles/validators/auth/auth-trait-must-target-service-schemes.json index 572a8868474..ebfd40d15a9 100644 --- a/smithy-model/src/test/resources/software/amazon/smithy/model/errorfiles/validators/auth/auth-trait-must-target-service-schemes.json +++ b/smithy-model/src/test/resources/software/amazon/smithy/model/errorfiles/validators/auth/auth-trait-must-target-service-schemes.json @@ -10,7 +10,11 @@ ], "traits": { "smithy.api#httpBasicAuth": {}, - "smithy.api#httpDigestAuth": {} + "smithy.api#httpDigestAuth": {}, + "smithy.api#auth": [ + "smithy.api#httpDigestAuth", + "smithy.api#httpBasicAuth" + ] } }, "ns.foo#ValidOperation": { diff --git a/smithy-model/src/test/resources/software/amazon/smithy/model/errorfiles/validators/service-auth-definitions/multiple-auth-schemes.errors b/smithy-model/src/test/resources/software/amazon/smithy/model/errorfiles/validators/service-auth-definitions/multiple-auth-schemes.errors new file mode 100644 index 00000000000..a4a677ed5db --- /dev/null +++ b/smithy-model/src/test/resources/software/amazon/smithy/model/errorfiles/validators/service-auth-definitions/multiple-auth-schemes.errors @@ -0,0 +1 @@ +[WARNING] smithy.example#FooService: This service uses multiple authentication schemes but does not have the `@auth` trait applied. The `@auth` trait defines a priority ordering of auth schemes for a client to use. Without it, the ordering of auth schemes is alphabetical based on the absolute shape ID of the auth schemes. | ServiceAuthDefinitions diff --git a/smithy-model/src/test/resources/software/amazon/smithy/model/errorfiles/validators/service-auth-definitions/multiple-auth-schemes.smithy b/smithy-model/src/test/resources/software/amazon/smithy/model/errorfiles/validators/service-auth-definitions/multiple-auth-schemes.smithy new file mode 100644 index 00000000000..e188ee3f3e4 --- /dev/null +++ b/smithy-model/src/test/resources/software/amazon/smithy/model/errorfiles/validators/service-auth-definitions/multiple-auth-schemes.smithy @@ -0,0 +1,18 @@ +$version: "2" + +namespace smithy.example + +// Service shape with multiple auth schemes and no auth trait should cause warning +@httpBasicAuth +@httpDigestAuth +@httpBearerAuth +service FooService { + version: "2023-08-15" + operations: [GetFoo] +} + +operation GetFoo { + output: GetFooOutput +} + +structure GetFooOutput {} diff --git a/smithy-model/src/test/resources/software/amazon/smithy/model/errorfiles/validators/service-auth-definitions/one-auth-scheme.errors b/smithy-model/src/test/resources/software/amazon/smithy/model/errorfiles/validators/service-auth-definitions/one-auth-scheme.errors new file mode 100644 index 00000000000..e69de29bb2d diff --git a/smithy-model/src/test/resources/software/amazon/smithy/model/errorfiles/validators/service-auth-definitions/one-auth-scheme.smithy b/smithy-model/src/test/resources/software/amazon/smithy/model/errorfiles/validators/service-auth-definitions/one-auth-scheme.smithy new file mode 100644 index 00000000000..5974d929bd4 --- /dev/null +++ b/smithy-model/src/test/resources/software/amazon/smithy/model/errorfiles/validators/service-auth-definitions/one-auth-scheme.smithy @@ -0,0 +1,16 @@ +$version: "2" + +namespace smithy.example + +// Service shape with one auth schemes and no auth trait should NOT cause warning +@httpBasicAuth +service FooService { + version: "2023-08-15" + operations: [GetFoo] +} + +operation GetFoo { + output: GetFooOutput +} + +structure GetFooOutput {}