How can I set route level "Bearer" Security in Swagger?

[cyantarek]

This is not a bug reports. But I find it little bit awkward to implement more Swagger features by digging into the Swagger proto files included with protoc-gen-swagger, as I could not find documentation on how to use more advanced features of swagger with grpc-gateway.

Anyway, after digging, much, I could not find any way to setup route level "Bearer" security.

Here's an example swagger.json file that has route level security setup.

   "/order/{order_id}": {
      "get": {
        "security": [
          {
            "Bearer": []
          }
        ],
    ...

With this, I can define which routes are public (JWT Bearer Token not required) or protected (JWT Bearer Token required).

How can I define this in proto so that protoc-gen-swagger can generate the swagger.json with the security option?

Thanks.

[johanbrandhorst]

Hi @cyantarek, thanks for the question. I thought we had an example for this, but it turns out we don't have one specifically for bearer auth, however, I know from experience that the following file-wide configuration should work:

option (grpc.gateway.protoc_gen_swagger.options.openapiv2_swagger) = {
  security_definitions: {
    security: {
      key: "bearer"
      value: {
        type: TYPE_API_KEY
        in: IN_HEADER
        name: "Authorization"
        description: "Authentication token, prefixed by Bearer: Bearer <token>"
      }
    }
  }
  security: {
    security_requirement: {
      key: "bearer"
    }
  }
};

This enables in-header authentication on all routes, and you can overwrite it for a specific route like so (I think, untested):

  rpc CreateUser(CreateUserRequest) returns (User) {
    option (google.api.http) = {
      post: "/api/v1/user"
      body: "*"
    };
    option (grpc.gateway.protoc_gen_swagger.options.openapiv2_swagger) = {
      security: { } // Disable security key
    };
  }

I don't think there's anyway to force the user to specify the Bearer prefix with openapi 2, so this may be the closest you will get. If this helped you, would you be interested in contributing this to our documentation?

[cyantarek]

Hi,

Thanks for the info.

I'm working on the grpc gateway swagger in one of my projects. And yeah, I want to make a documentation how I'm doing. Can you please tell me where can I put the README.md file?

[johanbrandhorst]

This sort of thing could go in https://github.com/grpc-ecosystem/grpc-gateway/blob/master/docs/_docs/customizingyourgateway.md, or maybe a new file. You can see what these files look like right now here: https://grpc-ecosystem.github.io/grpc-gateway/docs/customizingyourgateway.html

[cyantarek]

After following your this recipe:

 rpc CreateUser(CreateUserRequest) returns (User) {
    option (google.api.http) = {
      post: "/api/v1/user"
      body: "*"
    };
    option (grpc.gateway.protoc_gen_swagger.options.openapiv2_swagger) = {
      security: { } // Disable security key
    };
  }

I'm getting this error
Option field "(grpc.gateway.protoc_gen_swagger.options.openapiv2_swagger)" is not a field or extension of message "MethodOptions"

May be I need to use this:

grpc.gateway.protoc_gen_swagger.options.openapiv2_operation

[johanbrandhorst]

Yeah, you're right, change grpc.gateway.protoc_gen_swagger.options.openapiv2_swagger to grpc.gateway.protoc_gen_swagger.options.openapiv2_operation. Does that work?

[cyantarek]

Yeah, that works great. Thanks!

[johanbrandhorst]

That's great! Would you be willing to add some docs around this in a PR?

[cyantarek]

Sure, I'll add very soon!

[stale]

This issue has been automatically marked as stale because it has not had recent activity. It will be closed if no further activity occurs. Thank you for your contributions.

[ganttee]

The above usage test failed, and the latest one has become:

option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_swagger) = {
    security_definitions: {
      security: {
        key: "bearer"
        value: {
          type: TYPE_API_KEY
          in: IN_HEADER
          name: "Authorization"
          description: "Authentication token, prefixed by Bearer: Bearer <token>"
        }
      }
    }
    security: {
      security_requirement: {
        key: "bearer"
      }
    }
};

rpc CreateUser(CreateUserRequest) returns (User) {
    option (google.api.http) = {
      post: "/api/v1/user"
      body: "*"
    };
    option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {
      security: { } // Disable security key
    };
  }