WIP

coder · mtojek · Dec 21, 2022 · Dec 20, 2022 · Dec 20, 2022 · Dec 20, 2022
commit d259c0542a337a9a2ea9b8bf6ad34f949e1705b9
diff --git a/coderd/apidoc/docs.go b/coderd/apidoc/docs.go
@@ -32,9 +32,6 @@ const docTemplate = `{
                         "CoderSessionToken": []
                     }
                 ],
-                "produces": [
-                    "application/json"
-                ],
                 "tags": [
                     "Applications"
                 ],
@@ -80,6 +77,42 @@ const docTemplate = `{
                 }
             }
         },
+        "/authcheck": {
+            "post": {
+                "security": [
+                    {
+                        "CoderSessionToken": []
+                    }
+                ],
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Authorization"
+                ],
+                "summary": "Check authorization",
+                "operationId": "check-authorization",
+                "parameters": [
+                    {
+                        "description": "Authorization request",
+                        "name": "request",
+                        "in": "body",
+                        "required": true,
+                        "schema": {
+                            "$ref": "#/definitions/codersdk.AuthorizationRequest"
+                        }
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/codersdk.AuthorizationResponse"
+                        }
+                    }
+                }
+            }
+        },
         "/organizations/{organization-id}/templates/": {
             "post": {
                 "security": [
@@ -679,6 +712,64 @@ const docTemplate = `{
         }
     },
     "definitions": {
+        "codersdk.AuthorizationCheck": {
+            "type": "object",
+            "properties": {
+                "action": {
+                    "description": "Action can be ` + "`" + `create` + "`" + `, ` + "`" + `read` + "`" + `, ` + "`" + `update` + "`" + `, or ` + "`" + `delete` + "`" + `",
+                    "type": "string",
+                    "enum": [
+                        "create",
+                        "read",
+                        "update",
+                        "delete"
+                    ]
+                },
+                "object": {
+                    "description": "Object can represent a \"set\" of objects, such as:\n\t- All workspaces in an organization\n\t- All workspaces owned by me\n\t- All workspaces across the entire product\nWhen defining an object, use the most specific language when possible to\nproduce the smallest set. Meaning to set as many fields on 'Object' as\nyou can. Example, if you want to check if you can update all workspaces\nowned by 'me', try to also add an 'OrganizationID' to the settings.\nOmitting the 'OrganizationID' could produce the incorrect value, as\nworkspaces have both ` + "`" + `user` + "`" + ` and ` + "`" + `organization` + "`" + ` owners.",
+                    "$ref": "#/definitions/codersdk.AuthorizationObject"
+                }
+            }
+        },
+        "codersdk.AuthorizationObject": {
+            "type": "object",
+            "properties": {
+                "organization_id": {
+                    "description": "OrganizationID (optional) is an organization_id. It adds the set constraint to\nall resources owned by a given organization.",
+                    "type": "string"
+                },
+                "owner_id": {
+                    "description": "OwnerID (optional) is a user_id. It adds the set constraint to all resources owned\nby a given user.",
+                    "type": "string"
+                },
+                "resource_id": {
+                    "description": "ResourceID (optional) reduces the set to a singular resource. This assigns\na resource ID to the resource type, eg: a single workspace.\nThe rbac library will not fetch the resource from the database, so if you\nare using this option, you should also set the 'OwnerID' and 'OrganizationID'\nif possible. Be as specific as possible using all the fields relevant.",
+                    "type": "string"
+                },
+                "resource_type": {
+                    "description": "ResourceType is the name of the resource.\n` + "`" + `./coderd/rbac/object.go` + "`" + ` has the list of valid resource types.",
+                    "type": "string"
+                }
+            }
+        },
+        "codersdk.AuthorizationRequest": {
+            "type": "object",
+            "properties": {
+                "checks": {
+                    "description": "Checks is a map keyed with an arbitrary string to a permission check.\nThe key can be any string that is helpful to the caller, and allows\nmultiple permission checks to be run in a single request.\nThe key ensures that each permission check has the same key in the\nresponse.",
+                    "type": "object",
+                    "additionalProperties": {
+                        "$ref": "#/definitions/codersdk.AuthorizationCheck"
+                    }
+                }
+            }
+        },
+        "codersdk.AuthorizationResponse": {
+            "type": "object",
+            "additionalProperties": {
+                "type": "boolean"
+            }
+        },
         "codersdk.CreateParameterRequest": {
             "type": "object",
             "required": [

diff --git a/coderd/apidoc/swagger.json b/coderd/apidoc/swagger.json
@@ -24,7 +24,6 @@
             "CoderSessionToken": []
           }
         ],
-        "produces": ["application/json"],
         "tags": ["Applications"],
         "summary": "Redirect to URI with encrypted API key",
         "operationId": "redirect-to-uri-with-encrypted-api-key",
@@ -64,6 +63,38 @@
         }
       }
     },
+    "/authcheck": {
+      "post": {
+        "security": [
+          {
+            "CoderSessionToken": []
+          }
+        ],
+        "produces": ["application/json"],
+        "tags": ["Authorization"],
+        "summary": "Check authorization",
+        "operationId": "check-authorization",
+        "parameters": [
+          {
+            "description": "Authorization request",
+            "name": "request",
+            "in": "body",
+            "required": true,
+            "schema": {
+              "$ref": "#/definitions/codersdk.AuthorizationRequest"
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "OK",
+            "schema": {
+              "$ref": "#/definitions/codersdk.AuthorizationResponse"
+            }
+          }
+        }
+      }
+    },
     "/organizations/{organization-id}/templates/": {
       "post": {
         "security": [
@@ -602,6 +633,59 @@
     }
   },
   "definitions": {
+    "codersdk.AuthorizationCheck": {
+      "type": "object",
+      "properties": {
+        "action": {
+          "description": "Action can be `create`, `read`, `update`, or `delete`",
+          "type": "string",
+          "enum": ["create", "read", "update", "delete"]
+        },
+        "object": {
+          "description": "Object can represent a \"set\" of objects, such as:\n\t- All workspaces in an organization\n\t- All workspaces owned by me\n\t- All workspaces across the entire product\nWhen defining an object, use the most specific language when possible to\nproduce the smallest set. Meaning to set as many fields on 'Object' as\nyou can. Example, if you want to check if you can update all workspaces\nowned by 'me', try to also add an 'OrganizationID' to the settings.\nOmitting the 'OrganizationID' could produce the incorrect value, as\nworkspaces have both `user` and `organization` owners.",
+          "$ref": "#/definitions/codersdk.AuthorizationObject"
+        }
+      }
+    },
+    "codersdk.AuthorizationObject": {
+      "type": "object",
+      "properties": {
+        "organization_id": {
+          "description": "OrganizationID (optional) is an organization_id. It adds the set constraint to\nall resources owned by a given organization.",
+          "type": "string"
+        },
+        "owner_id": {
+          "description": "OwnerID (optional) is a user_id. It adds the set constraint to all resources owned\nby a given user.",
+          "type": "string"
+        },
+        "resource_id": {
+          "description": "ResourceID (optional) reduces the set to a singular resource. This assigns\na resource ID to the resource type, eg: a single workspace.\nThe rbac library will not fetch the resource from the database, so if you\nare using this option, you should also set the 'OwnerID' and 'OrganizationID'\nif possible. Be as specific as possible using all the fields relevant.",
+          "type": "string"
+        },
+        "resource_type": {
+          "description": "ResourceType is the name of the resource.\n`./coderd/rbac/object.go` has the list of valid resource types.",
+          "type": "string"
+        }
+      }
+    },
+    "codersdk.AuthorizationRequest": {
+      "type": "object",
+      "properties": {
+        "checks": {
+          "description": "Checks is a map keyed with an arbitrary string to a permission check.\nThe key can be any string that is helpful to the caller, and allows\nmultiple permission checks to be run in a single request.\nThe key ensures that each permission check has the same key in the\nresponse.",
+          "type": "object",
+          "additionalProperties": {
+            "$ref": "#/definitions/codersdk.AuthorizationCheck"
+          }
+        }
+      }
+    },
+    "codersdk.AuthorizationResponse": {
+      "type": "object",
+      "additionalProperties": {
+        "type": "boolean"
+      }
+    },
     "codersdk.CreateParameterRequest": {
       "type": "object",
       "required": [

diff --git a/coderd/authorize.go b/coderd/authorize.go
@@ -104,6 +104,16 @@ func (h *HTTPAuthorizer) AuthorizeSQLFilter(r *http.Request, action rbac.Action,
 	return prepared, nil
 }
 
+// @Summary Check authorization
+// @ID check-authorization
+// @Security CoderSessionToken
+// @Consume json
+// @Produce json
+// @Tags Authorization
+// @Param request body codersdk.AuthorizationRequest true "Authorization request"
+// @Success 200 {object} codersdk.AuthorizationResponse
+// @Router /authcheck [post]
+//
 // checkAuthorization returns if the current API key can use the given
 // permissions, factoring in the current user's roles and the API key scopes.
 func (api *API) checkAuthorization(rw http.ResponseWriter, r *http.Request) {

diff --git a/coderd/workspaceapps.go b/coderd/workspaceapps.go
@@ -494,7 +494,6 @@ func (api *API) verifyWorkspaceApplicationSubdomainAuth(rw http.ResponseWriter,
 // @Summary Redirect to URI with encrypted API key
 // @ID redirect-to-uri-with-encrypted-api-key
 // @Security CoderSessionToken
-// @Produce json
 // @Tags Applications
 // @Param redirect_uri query string false "Redirect destination"
 // @Success 307

diff --git a/codersdk/authorization.go b/codersdk/authorization.go
@@ -10,7 +10,7 @@ type AuthorizationResponse map[string]bool
 
 // AuthorizationRequest is a structure instead of a map because
 // go-playground/validate can only validate structs. If you attempt to pass
-// a map into 'httpapi.Read', you will get an invalid type error.
+// a map into `httpapi.Read`, you will get an invalid type error.
 type AuthorizationRequest struct {
 	// Checks is a map keyed with an arbitrary string to a permission check.
 	// The key can be any string that is helpful to the caller, and allows
@@ -34,13 +34,13 @@ type AuthorizationCheck struct {
 	// Omitting the 'OrganizationID' could produce the incorrect value, as
 	// workspaces have both `user` and `organization` owners.
 	Object AuthorizationObject `json:"object"`
-	// Action can be 'create', 'read', 'update', or 'delete'
-	Action string `json:"action"`
+	// Action can be `create`, `read`, `update`, or `delete`
+	Action string `json:"action" enums:"create,read,update,delete"`
 }
 
 type AuthorizationObject struct {
 	// ResourceType is the name of the resource.
-	// './coderd/rbac/object.go' has the list of valid resource types.
+	// `./coderd/rbac/object.go` has the list of valid resource types.
 	ResourceType string `json:"resource_type"`
 	// OwnerID (optional) is a user_id. It adds the set constraint to all resources owned
 	// by a given user.

diff --git a/docs/api/authorization.md b/docs/api/authorization.md
@@ -0,0 +1,70 @@
+# Authorization
+
+> This page is incomplete, stay tuned.
+
+## Check authorization
+
+### Code samples
+
+```shell
+# Example request using curl
+curl -X POST http://coder-server:8080/api/v2/authcheck \
+  -H 'Content-Type: application/json' \
+  -H 'Accept: application/json' \
+  -H 'Coder-Session-Token: API_KEY'
+
+```
+
+`POST /authcheck`
+
+> Body parameter
+
+```json
+{
+  "checks": {
+    "property1": {
+      "action": "create",
+      "object": {
+        "organization_id": "string",
+        "owner_id": "string",
+        "resource_id": "string",
+        "resource_type": "string"
+      }
+    },
+    "property2": {
+      "action": "create",
+      "object": {
+        "organization_id": "string",
+        "owner_id": "string",
+        "resource_id": "string",
+        "resource_type": "string"
+      }
+    }
+  }
+}
+```
+
+### Parameters
+
+| Name | In   | Type                                                                     | Required | Description           |
+| ---- | ---- | ------------------------------------------------------------------------ | -------- | --------------------- |
+| body | body | [codersdk.AuthorizationRequest](schemas.md#codersdkauthorizationrequest) | true     | Authorization request |
+
+### Example responses
+
+> 200 Response
+
+```json
+{
+  "property1": true,
+  "property2": true
+}
+```
+
+### Responses
+
+| Status | Meaning                                                 | Description | Schema                                                                     |
+| ------ | ------------------------------------------------------- | ----------- | -------------------------------------------------------------------------- |
+| 200    | [OK](https://tools.ietf.org/html/rfc7231#section-6.3.1) | OK          | [codersdk.AuthorizationResponse](schemas.md#codersdkauthorizationresponse) |
+
+To perform this operation, you must be authenticated by means of one of the following methods: **CoderSessionToken**.