Is there a way to identify routes that require authentication?

[griggsca91]

Usecase: Routes require authentication and want to be able to paste in a token so we can make requests from Swagger or RapiDoc UI.

Question: Is there any way to identify that a route requires authentication?

[sudorandom]

There are several angles on this:

• Add annotations/options from protobuf into the relevant paths/requests/responses. Then post-processing using yq or jq could make sense here
• If there's a universal(-ish) protobuf for annotating methods with an authentication type then the generator could use that to add the required headers. 🤔
• Do more to merge properties from "base" to also include endpoints so you could override paths with a given security scope.

Either way, what we'd want to end up with is a way to control these settings: https://swagger.io/docs/specification/authentication/. You can already add this to the 'base' YAML:

components:
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer

But then you'd need to somehow dictate which paths uses it. We're missing this right now:

paths:
  /billing_info:
    get:
      summary: Gets the account billing info
      security:
        - BearerAuth: []

[sudorandom]

It does look like google.api/auth.proto allows you to annotate these kinds of authentication details. Maybe this is the way.

https://github.com/googleapis/googleapis/blob/master/google/api/auth.proto

[griggsca91]

I also just took a look at what GRPC Gateway does, and they specify auth as an option in the protofiles. It looks like it's not specific to auth, but it just allows you to override whatever value gets generated in the openapi output.

https://github.com/grpc-ecosystem/grpc-gateway/blob/7299a45d6b3382cd21b2f6019e0fed3ba092cab7/examples/internal/proto/examplepb/a_bit_of_everything.proto#L567

which kind of falls under option 2? The options could be the same, it would just fall under the namespace of this plugin.

gRPC in general doesn't specify any direction though in regards to authentication, and the google authentication proto looks like it's specific to google client authentication. I couldn't find a way to use for annotating.

[sudorandom]

It will be a good amount of work but I think supporting the https://github.com/grpc-ecosystem/grpc-gateway/blob/main/protoc-gen-openapiv2/options/openapiv2.proto protobuf file. This would remove the need for having a "base" openapi file.

[sudorandom]

I decided to use google/gnostic's openapiv3 protobuf annotations for this instead of grpc-gateway... but I did just add some support for these annotations:

https://github.com/google/gnostic/blob/main/cmd/protoc-gen-openapi/examples/tests/openapiv3annotations/message.proto#L46

Only the document-level and (some) method-level options are respected now. The rest can be supported in time.

I won't count this issue as complete until it's properly documented

[sudorandom]

Okay, I found some time today to work on this. I've updated the README outlining which annotations are supported. If support for more annotations are added I'll more this to a different document so that the README isn't too hard to navigate.

[griggsca91]

Awesome thanks! Didn't expect this so quickly. Appreciate it!