From 8afb10e0903e2b34c4d8ae43e49b248ac42073d1 Mon Sep 17 00:00:00 2001
From: Vincent Vielle <vincent@coder.com>
Date: Tue, 26 Nov 2024 07:19:43 +0100
Subject: [PATCH] chore: improve validation of Security tag in swaggerparser
 (#15660)

Aims to resolve #15605

There's currently one option valid for the `@Security` tag in
swaggerparser - which fails in the CI if we try to put any other value.

At least one of our endpoints does not accept `CoderSessionToken` as an
option for the authentication and so we need to add new possibilities in
order to keep the documentation up-to-date.

In this PR , I added `ProvisionerKey` which is the way our provisioner
daemon can authenticate to the backend - also modified a bit the code to
simplify other options later.
---
 coderd/apidoc/docs.go                | 2 +-
 coderd/apidoc/swagger.json           | 2 +-
 coderd/coderdtest/swaggerparser.go   | 7 ++++++-
 docs/reference/api/enterprise.md     | 3 +--
 enterprise/coderd/provisionerkeys.go | 2 +-
 5 files changed, 10 insertions(+), 6 deletions(-)

diff --git a/coderd/apidoc/docs.go b/coderd/apidoc/docs.go
index 9db467d3a9..fe5d7c6384 100644
--- a/coderd/apidoc/docs.go
+++ b/coderd/apidoc/docs.go
@@ -3642,7 +3642,7 @@ const docTemplate = `{
             "get": {
                 "security": [
                     {
-                        "CoderSessionToken": []
+                        "CoderProvisionerKey": []
                     }
                 ],
                 "produces": [
diff --git a/coderd/apidoc/swagger.json b/coderd/apidoc/swagger.json
index af7cfd9649..04af1b4015 100644
--- a/coderd/apidoc/swagger.json
+++ b/coderd/apidoc/swagger.json
@@ -3208,7 +3208,7 @@
 			"get": {
 				"security": [
 					{
-						"CoderSessionToken": []
+						"CoderProvisionerKey": []
 					}
 				],
 				"produces": ["application/json"],
diff --git a/coderd/coderdtest/swaggerparser.go b/coderd/coderdtest/swaggerparser.go
index c0cbe54236..45907819fd 100644
--- a/coderd/coderdtest/swaggerparser.go
+++ b/coderd/coderdtest/swaggerparser.go
@@ -300,6 +300,11 @@ func assertPathParametersDefined(t *testing.T, comment SwaggerComment) {
 }
 
 func assertSecurityDefined(t *testing.T, comment SwaggerComment) {
+	authorizedSecurityTags := []string{
+		"CoderSessionToken",
+		"CoderProvisionerKey",
+	}
+
 	if comment.router == "/updatecheck" ||
 		comment.router == "/buildinfo" ||
 		comment.router == "/" ||
@@ -308,7 +313,7 @@ func assertSecurityDefined(t *testing.T, comment SwaggerComment) {
 		comment.router == "/users/otp/change-password" {
 		return // endpoints do not require authorization
 	}
-	assert.Equal(t, "CoderSessionToken", comment.security, "@Security must be equal CoderSessionToken")
+	assert.Containsf(t, authorizedSecurityTags, comment.security, "@Security must be either of these options: %v", authorizedSecurityTags)
 }
 
 func assertAccept(t *testing.T, comment SwaggerComment) {
diff --git a/docs/reference/api/enterprise.md b/docs/reference/api/enterprise.md
index f03645ea1e..8a2a5d0860 100644
--- a/docs/reference/api/enterprise.md
+++ b/docs/reference/api/enterprise.md
@@ -2032,8 +2032,7 @@ To perform this operation, you must be authenticated. [Learn more](authenticatio
 ```shell
 # Example request using curl
 curl -X GET http://coder-server:8080/api/v2/provisionerkeys/{provisionerkey} \
-  -H 'Accept: application/json' \
-  -H 'Coder-Session-Token: API_KEY'
+  -H 'Accept: application/json'
 ```
 
 `GET /provisionerkeys/{provisionerkey}`
diff --git a/enterprise/coderd/provisionerkeys.go b/enterprise/coderd/provisionerkeys.go
index a14e2c965c..279b9c567e 100644
--- a/enterprise/coderd/provisionerkeys.go
+++ b/enterprise/coderd/provisionerkeys.go
@@ -202,7 +202,7 @@ func (api *API) deleteProvisionerKey(rw http.ResponseWriter, r *http.Request) {
 
 // @Summary Fetch provisioner key details
 // @ID fetch-provisioner-key-details
-// @Security CoderSessionToken
+// @Security CoderProvisionerKey
 // @Produce json
 // @Tags Enterprise
 // @Param provisionerkey path string true "Provisioner Key"