Merge pull request #21 from webrpc/auth_annotations

Use auth annotations to render security schema in method section

Author: LukasJenicek

README.md

@@ -25,16 +25,19 @@ webrpc-gen -schema=./proto.ridl -target=github.com/webrpc/[email protected] -ou
 ## Set custom template variables
 Change any of the following default values by passing `-option="Value"` CLI flag to webrpc-gen.
 
-| webrpc-gen -option   | Default value              | Example value                                                          |
-|----------------------|----------------------------|------------------------------------------------------------------------|
-| `-title`             | `{Services[0].Name} API`   | `"Example API"`                                                        |
-| `-apiVersion`        | `""`                       | `v22.10.25`                                                            |
-| `-serverUrl`         | `""`                       | `https://api.example.com`                                              |
-| `-serverDescription` | `""`                       | `"Staging API"`                                                        |
-| `-servers`           | `""`                       | `http://localhost:8080;description,http://localhost:8081;description`  |
+| webrpc-gen -option     | Default value            | Example value                                                                                                                        |
+|------------------------|--------------------------|--------------------------------------------------------------------------------------------------------------------------------------|
+| `-title`               | `{Services[0].Name} API` | `"Example API"`                                                                                                                      |
+| `-apiVersion`          | `""`                     | `v22.10.25`                                                                                                                          |
+| `-serverUrl`           | `""`                     | `https://api.example.com`                                                                                                            |
+| `-serverDescription`   | `""`                     | `"Staging API"`                                                                                                                      |
+| `-servers`             | `""`                     | `http://localhost:8080;description,http://localhost:8081;description`                                                                |
+| `-securityAnnotation`  | `""`                     | `@auth`                                                                                                                              |
+| `-securitySchemes`     | `""`                     | `{"ApiKeyAuth":{"type":"apiKey", "in":"header", "description":"Access key for authenticating requests", "name":"X-Access-Key"}}`     | 
+
 
 Example:
-- server url and server description will become part of the servers format in the end to keeep it backward compatible
+- server url and server description will become part of the servers format in the end to keep it backward compatible
 - means that the result will be `server="http://localhost:8080;description,http://localhost:8081;description,https://api.example.com;Production"`
 ```
 webrpc-gen \ 
@@ -48,6 +51,36 @@ webrpc-gen \
   -servers="http://localhost:8080;description,http://localhost:8081;description"
 ```
 
+- `securityAnnotation` must match the custom annotation you are using in your project to describe ACL for specific service methods
+- `securitySchemes` give you possibility to pass an openapi security schemes which are later matched by your custom `acl annotation`. In this example it's an `@auth` annotation. 
+Example with security annotation:
+```
+// proto.ridl
+service ExampleService
+  @auth:"ApiKeyAuth,ServiceAuth"
+  - GetUserV2(header: map<string,string>, userID: uint64) => (profilePicture: string)
+
+// Makefile
+SECURITY_SCHEMES="{ \
+  'ApiKeyAuth': { \
+    'type': 'apiKey', \
+    'in': 'header', \
+    'description': 'Project access key for authenticating requests', \
+    'name': 'X-Access-Key' \
+  }, \
+}"; \
+webrpc-gen \
+  -schema=./proto.ridl \
+  -target=./ \
+  -out=./openapi.gen.yaml \
+  -title="Example webrpc API" \
+  -apiVersion="v22.11.8"  \
+  -serverUrl=https://api.example.com \
+  -serverDescription="Production" \
+  -securityAnnotation="@auth" \
+  -securitySchemes="$$SECURITY_SCHEMES"
+```
+
 # Open in Swagger UI
 
 Open generated documentation in Swagger editor:

_examples/Makefile

@@ -3,7 +3,30 @@
 all: generate diff
 
 generate:
-	webrpc-gen -schema=./proto.ridl -target=../ -out=./openapi.gen.yaml -title="Example webrpc API" -apiVersion="v22.11.8" -serverUrl=https://api.example.com -serverDescription="Production"
+	SECURITY_SCHEMES="{ \
+              'ApiKeyAuth': { \
+                'type': 'apiKey', \
+                'in': 'header', \
+                'description': 'Project access key for authenticating requests', \
+                'name': 'X-Access-Key' \
+              }, \
+              'ServiceAuth': { \
+                'type': 'apiKey', \
+                'in': 'header', \
+                'description': 'Project access key for authenticating requests', \
+                'name': 'X-Access-Key' \
+              } \
+            }"; \
+	webrpc-gen \
+		-schema=./proto.ridl \
+		-target=../ \
+		-out=./openapi.gen.yaml \
+		-title="Example webrpc API" \
+		-apiVersion="v22.11.8"  \
+		-serverUrl=https://api.example.com \
+		-serverDescription="Production" \
+		-securityAnnotation="@auth" \
+		-securitySchemes="$$SECURITY_SCHEMES"
 
 diff:
 	git diff --color --ignore-all-space --ignore-blank-lines --exit-code .

_examples/openapi.gen.yaml

@@ -1,8 +1,8 @@
-# example v0.0.1 ebe5209e9238f02a045c540943d0298b747f5f03
+# example v0.0.1 9e3db8dcce83f00fbc6c12b6a2b712b5fdd38874
 # --
 # Code generated by [email protected] with ../ generator; DO NOT EDIT
 # 
-# webrpc-gen -schema=./proto.ridl -target=../ -out=./openapi.gen.yaml -title=Example webrpc API -apiVersion=v22.11.8 -serverUrl=https://api.example.com -serverDescription=Production
+# webrpc-gen -schema=./proto.ridl -target=../ -out=./openapi.gen.yaml -title=Example webrpc API -apiVersion=v22.11.8 -serverUrl=https://api.example.com -serverDescription=Production -securityAnnotation=@auth -securitySchemes={               'ApiKeyAuth': {                 'type': 'apiKey',                 'in': 'header',                 'description': 'Project access key for authenticating requests',                 'name': 'X-Access-Key'               },               'ServiceAuth': {                 'type': 'apiKey',                 'in': 'header',                 'description': 'Project access key for authenticating requests',                 'name': 'X-Access-Key'               }             }
 openapi: 3.0.0
 info:
   title: 'Example webrpc API'
@@ -11,6 +11,7 @@ servers:
   - url: 'https://api.example.com'
     description: 'Production'
 components:
+  securitySchemes: {               'ApiKeyAuth': {                 'type': 'apiKey',                 'in': 'header',                 'description': 'Project access key for authenticating requests',                 'name': 'X-Access-Key'               },               'ServiceAuth': {                 'type': 'apiKey',                 'in': 'header',                 'description': 'Project access key for authenticating requests',                 'name': 'X-Access-Key'               }             }
   schemas:
     ErrorWebrpcEndpoint:
       type: object
@@ -537,6 +538,9 @@ paths:
   /rpc/ExampleService/GetUserV2:
     post:
       summary: GetUserV2
+      security:
+          - ApiKeyAuth: []
+          - ServiceAuth: []
       requestBody:
         content:
           application/json:

_examples/proto.ridl

@@ -47,6 +47,7 @@ struct Optional
 service ExampleService
   @deprecated:GetUserV2
   - GetUser(header: map<string,string>, userID: uint64) => (code: uint32, user: User)
+  @auth:"ApiKeyAuth,ServiceAuth"
   - GetUserV2(header: map<string,string>, userID: uint64) => (code: uint32, user: User, profilePicture: string)
   - FindUser(s: SearchFilter) => (name: string, user: User)
   - ListUsers() => (users: []User)

main.go.tmpl

@@ -7,6 +7,8 @@
 {{- set $opts "serverUrl" (default .Opts.serverUrl "") -}}
 {{- set $opts "serverDescription" (default .Opts.serverDescription "") -}}
 {{- set $opts "servers" (default .Opts.servers "") -}}
+{{- set $opts "securityAnnotation" (default .Opts.securityAnnotation "") -}}
+{{- set $opts "securitySchemes" (default .Opts.securitySchemes "") -}}
 
 {{- /* Print help on -help. */ -}}
 {{- if exists .Opts "help" -}}
@@ -88,6 +90,9 @@ servers:
 {{- end }}
 {{- end }}
 components:
+  {{- if (ne (get $opts "securitySchemes") "") }}
+  securitySchemes: {{ get $opts "securitySchemes" }}
+  {{- end }}
   schemas:
     {{- range $_, $error := $webrpcErrors }}
     {{ template "errorType" $error }}
@@ -132,6 +137,17 @@ paths:
       {{- if (index $method.Annotations "deprecated") }}
       deprecated: true
       {{- end }}
+      {{- if (index $opts "securityAnnotation") }}
+      {{- $annotation := trimPrefix (get $opts "securityAnnotation") "@" -}}
+      {{- if (index $method.Annotations $annotation) }}
+      security:
+        {{- $auth := index $method.Annotations $annotation -}}
+        {{- $authParts := split "," $auth.Value -}}
+        {{- range $authParts }}
+          - {{ . }}: []
+        {{- end }}
+      {{- end }}
+      {{- end }}
       {{- if gt (len $method.Comments) 0 }}
       description: "{{ replaceAll (join $method.Comments "\n") "\"" "'" }}"
     {{- end }}