mirror of
https://github.com/coder/coder.git
synced 2025-07-08 11:39:50 +00:00
docs: applications and authorization (#5477)
* docs: Applications * WIP * WIP * WIP * Fix: consume * Fix: @Description * Fix * Fix: s/none//g * Fix: godoc nice * Fix: description * Fix: It * Fix: code sample trim empty line * More fixes * Fix: br
This commit is contained in:
Marcin Tojek
GitHub
@ -25,6 +25,97 @@ const docTemplate = `{
|
||||
"host": "{{.Host}}",
|
||||
"basePath": "{{.BasePath}}",
|
||||
"paths": {
|
||||
"/applications/auth-redirect": {
|
||||
"get": {
|
||||
"security": [
|
||||
{
|
||||
"CoderSessionToken": []
|
||||
}
|
||||
],
|
||||
"tags": [
|
||||
"Applications"
|
||||
],
|
||||
"summary": "Redirect to URI with encrypted API key",
|
||||
"operationId": "redirect-to-uri-with-encrypted-api-key",
|
||||
"parameters": [
|
||||
{
|
||||
"type": "string",
|
||||
"description": "Redirect destination",
|
||||
"name": "redirect_uri",
|
||||
"in": "query"
|
||||
}
|
||||
],
|
||||
"responses": {
|
||||
"307": {
|
||||
"description": "Temporary Redirect"
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
"/applications/host": {
|
||||
"get": {
|
||||
"security": [
|
||||
{
|
||||
"CoderSessionToken": []
|
||||
}
|
||||
],
|
||||
"produces": [
|
||||
"application/json"
|
||||
],
|
||||
"tags": [
|
||||
"Applications"
|
||||
],
|
||||
"summary": "Get applications host",
|
||||
"operationId": "get-app-host",
|
||||
"responses": {
|
||||
"200": {
|
||||
"description": "OK",
|
||||
"schema": {
|
||||
"$ref": "#/definitions/codersdk.GetAppHostResponse"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
"/authcheck": {
|
||||
"post": {
|
||||
"security": [
|
||||
{
|
||||
"CoderSessionToken": []
|
||||
}
|
||||
],
|
||||
"consumes": [
|
||||
"application/json"
|
||||
],
|
||||
"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": [
|
||||
@ -32,6 +123,9 @@ const docTemplate = `{
|
||||
"CoderSessionToken": []
|
||||
}
|
||||
],
|
||||
"consumes": [
|
||||
"application/json"
|
||||
],
|
||||
"produces": [
|
||||
"application/json"
|
||||
],
|
||||
@ -427,6 +521,9 @@ const docTemplate = `{
|
||||
"CoderSessionToken": []
|
||||
}
|
||||
],
|
||||
"consumes": [
|
||||
"application/json"
|
||||
],
|
||||
"produces": [
|
||||
"application/json"
|
||||
],
|
||||
@ -468,6 +565,9 @@ const docTemplate = `{
|
||||
"CoderSessionToken": []
|
||||
}
|
||||
],
|
||||
"consumes": [
|
||||
"application/json"
|
||||
],
|
||||
"produces": [
|
||||
"application/json"
|
||||
],
|
||||
@ -509,6 +609,9 @@ const docTemplate = `{
|
||||
"CoderSessionToken": []
|
||||
}
|
||||
],
|
||||
"consumes": [
|
||||
"application/json"
|
||||
],
|
||||
"produces": [
|
||||
"application/json"
|
||||
],
|
||||
@ -553,6 +656,9 @@ const docTemplate = `{
|
||||
"CoderSessionToken": []
|
||||
}
|
||||
],
|
||||
"consumes": [
|
||||
"application/json"
|
||||
],
|
||||
"produces": [
|
||||
"application/json"
|
||||
],
|
||||
@ -624,7 +730,67 @@ const docTemplate = `{
|
||||
}
|
||||
},
|
||||
"definitions": {
|
||||
"codersdk.AuthorizationCheck": {
|
||||
"description": "AuthorizationCheck is used to check if the currently authenticated user (or the specified user) can do a given action to a given set of objects.",
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"action": {
|
||||
"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": {
|
||||
"description": "AuthorizationObject can represent a \"set\" of objects, such as: all workspaces in an organization, all workspaces owned by me, all workspaces across the entire product.",
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"organization_id": {
|
||||
"description": "OrganizationID (optional) adds the set constraint to all resources owned by a given organization.",
|
||||
"type": "string"
|
||||
},
|
||||
"owner_id": {
|
||||
"description": "OwnerID (optional) adds the set constraint to all resources owned by 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": {
|
||||
"description": "CreateParameterRequest is a structure used to create a new parameter value for a scope.",
|
||||
"type": "object",
|
||||
"required": [
|
||||
"destination_scheme",
|
||||
@ -712,6 +878,15 @@ const docTemplate = `{
|
||||
}
|
||||
}
|
||||
},
|
||||
"codersdk.GetAppHostResponse": {
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"host": {
|
||||
"description": "Host is the externally accessible URL for the Coder instance.",
|
||||
"type": "string"
|
||||
}
|
||||
}
|
||||
},
|
||||
"codersdk.Healthcheck": {
|
||||
"type": "object",
|
||||
"properties": {
|
||||
|
||||
@ -17,6 +17,85 @@
|
||||
},
|
||||
"basePath": "/api/v2",
|
||||
"paths": {
|
||||
"/applications/auth-redirect": {
|
||||
"get": {
|
||||
"security": [
|
||||
{
|
||||
"CoderSessionToken": []
|
||||
}
|
||||
],
|
||||
"tags": ["Applications"],
|
||||
"summary": "Redirect to URI with encrypted API key",
|
||||
"operationId": "redirect-to-uri-with-encrypted-api-key",
|
||||
"parameters": [
|
||||
{
|
||||
"type": "string",
|
||||
"description": "Redirect destination",
|
||||
"name": "redirect_uri",
|
||||
"in": "query"
|
||||
}
|
||||
],
|
||||
"responses": {
|
||||
"307": {
|
||||
"description": "Temporary Redirect"
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
"/applications/host": {
|
||||
"get": {
|
||||
"security": [
|
||||
{
|
||||
"CoderSessionToken": []
|
||||
}
|
||||
],
|
||||
"produces": ["application/json"],
|
||||
"tags": ["Applications"],
|
||||
"summary": "Get applications host",
|
||||
"operationId": "get-app-host",
|
||||
"responses": {
|
||||
"200": {
|
||||
"description": "OK",
|
||||
"schema": {
|
||||
"$ref": "#/definitions/codersdk.GetAppHostResponse"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
"/authcheck": {
|
||||
"post": {
|
||||
"security": [
|
||||
{
|
||||
"CoderSessionToken": []
|
||||
}
|
||||
],
|
||||
"consumes": ["application/json"],
|
||||
"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": [
|
||||
@ -24,6 +103,7 @@
|
||||
"CoderSessionToken": []
|
||||
}
|
||||
],
|
||||
"consumes": ["application/json"],
|
||||
"produces": ["application/json"],
|
||||
"tags": ["Templates"],
|
||||
"summary": "Create template by organization",
|
||||
@ -378,6 +458,7 @@
|
||||
"CoderSessionToken": []
|
||||
}
|
||||
],
|
||||
"consumes": ["application/json"],
|
||||
"produces": ["application/json"],
|
||||
"tags": ["Workspaces"],
|
||||
"summary": "Update workspace metadata by ID",
|
||||
@ -415,6 +496,7 @@
|
||||
"CoderSessionToken": []
|
||||
}
|
||||
],
|
||||
"consumes": ["application/json"],
|
||||
"produces": ["application/json"],
|
||||
"tags": ["Workspaces"],
|
||||
"summary": "Update workspace autostart schedule by ID",
|
||||
@ -452,6 +534,7 @@
|
||||
"CoderSessionToken": []
|
||||
}
|
||||
],
|
||||
"consumes": ["application/json"],
|
||||
"produces": ["application/json"],
|
||||
"tags": ["Workspaces"],
|
||||
"summary": "Extend workspace deadline by ID",
|
||||
@ -492,6 +575,7 @@
|
||||
"CoderSessionToken": []
|
||||
}
|
||||
],
|
||||
"consumes": ["application/json"],
|
||||
"produces": ["application/json"],
|
||||
"tags": ["Workspaces"],
|
||||
"summary": "Update workspace TTL by ID",
|
||||
@ -555,7 +639,62 @@
|
||||
}
|
||||
},
|
||||
"definitions": {
|
||||
"codersdk.AuthorizationCheck": {
|
||||
"description": "AuthorizationCheck is used to check if the currently authenticated user (or the specified user) can do a given action to a given set of objects.",
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"action": {
|
||||
"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": {
|
||||
"description": "AuthorizationObject can represent a \"set\" of objects, such as: all workspaces in an organization, all workspaces owned by me, all workspaces across the entire product.",
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"organization_id": {
|
||||
"description": "OrganizationID (optional) adds the set constraint to all resources owned by a given organization.",
|
||||
"type": "string"
|
||||
},
|
||||
"owner_id": {
|
||||
"description": "OwnerID (optional) adds the set constraint to all resources owned by 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": {
|
||||
"description": "CreateParameterRequest is a structure used to create a new parameter value for a scope.",
|
||||
"type": "object",
|
||||
"required": [
|
||||
"destination_scheme",
|
||||
@ -635,6 +774,15 @@
|
||||
}
|
||||
}
|
||||
},
|
||||
"codersdk.GetAppHostResponse": {
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"host": {
|
||||
"description": "Host is the externally accessible URL for the Coder instance.",
|
||||
"type": "string"
|
||||
}
|
||||
}
|
||||
},
|
||||
"codersdk.Healthcheck": {
|
||||
"type": "object",
|
||||
"properties": {
|
||||
|
||||
@ -106,6 +106,16 @@ func (h *HTTPAuthorizer) AuthorizeSQLFilter(r *http.Request, action rbac.Action,
|
||||
|
||||
// checkAuthorization returns if the current API key can use the given
|
||||
// permissions, factoring in the current user's roles and the API key scopes.
|
||||
//
|
||||
// @Summary Check authorization
|
||||
// @ID check-authorization
|
||||
// @Security CoderSessionToken
|
||||
// @Accept json
|
||||
// @Produce json
|
||||
// @Tags Authorization
|
||||
// @Param request body codersdk.AuthorizationRequest true "Authorization request"
|
||||
// @Success 200 {object} codersdk.AuthorizationResponse
|
||||
// @Router /authcheck [post]
|
||||
func (api *API) checkAuthorization(rw http.ResponseWriter, r *http.Request) {
|
||||
ctx := r.Context()
|
||||
auth := httpmw.UserAuthorization(r)
|
||||
|
||||
@ -145,7 +145,7 @@ func (api *API) deleteTemplate(rw http.ResponseWriter, r *http.Request) {
|
||||
// @Summary Create template by organization
|
||||
// @ID create-template-by-organization
|
||||
// @Security CoderSessionToken
|
||||
// @Consume json
|
||||
// @Accept json
|
||||
// @Produce json
|
||||
// @Tags Templates
|
||||
// @Param request body codersdk.CreateTemplateRequest true "Request body"
|
||||
|
||||
@ -65,6 +65,13 @@ var nonCanonicalHeaders = map[string]string{
|
||||
"Sec-Websocket-Version": "Sec-WebSocket-Version",
|
||||
}
|
||||
|
||||
// @Summary Get applications host
|
||||
// @ID get-app-host
|
||||
// @Security CoderSessionToken
|
||||
// @Produce json
|
||||
// @Tags Applications
|
||||
// @Success 200 {object} codersdk.GetAppHostResponse
|
||||
// @Router /applications/host [get]
|
||||
func (api *API) appHost(rw http.ResponseWriter, r *http.Request) {
|
||||
host := api.AppHostname
|
||||
if host != "" && api.AccessURL.Port() != "" {
|
||||
@ -607,6 +614,14 @@ func (api *API) setWorkspaceAppCookie(rw http.ResponseWriter, r *http.Request, t
|
||||
return true
|
||||
}
|
||||
|
||||
// @Summary Redirect to URI with encrypted API key
|
||||
// @ID redirect-to-uri-with-encrypted-api-key
|
||||
// @Security CoderSessionToken
|
||||
// @Tags Applications
|
||||
// @Param redirect_uri query string false "Redirect destination"
|
||||
// @Success 307
|
||||
// @Router /applications/auth-redirect [get]
|
||||
//
|
||||
// workspaceApplicationAuth is an endpoint on the main router that handles
|
||||
// redirects from the subdomain handler.
|
||||
//
|
||||
|
||||
@ -564,7 +564,7 @@ func (api *API) postWorkspacesByOrganization(rw http.ResponseWriter, r *http.Req
|
||||
// @Summary Update workspace metadata by ID
|
||||
// @ID update-workspace-metadata-by-id
|
||||
// @Security CoderSessionToken
|
||||
// @Consume json
|
||||
// @Accept json
|
||||
// @Produce json
|
||||
// @Tags Workspaces
|
||||
// @Param workspace path string true "Workspace ID" format(uuid)
|
||||
@ -654,7 +654,7 @@ func (api *API) patchWorkspace(rw http.ResponseWriter, r *http.Request) {
|
||||
// @Summary Update workspace autostart schedule by ID
|
||||
// @ID update-workspace-autostart-schedule-by-id
|
||||
// @Security CoderSessionToken
|
||||
// @Consume json
|
||||
// @Accept json
|
||||
// @Produce json
|
||||
// @Tags Workspaces
|
||||
// @Param workspace path string true "Workspace ID" format(uuid)
|
||||
@ -717,7 +717,7 @@ func (api *API) putWorkspaceAutostart(rw http.ResponseWriter, r *http.Request) {
|
||||
// @Summary Update workspace TTL by ID
|
||||
// @ID update-workspace-ttl-by-id
|
||||
// @Security CoderSessionToken
|
||||
// @Consume json
|
||||
// @Accept json
|
||||
// @Produce json
|
||||
// @Tags Workspaces
|
||||
// @Param workspace path string true "Workspace ID" format(uuid)
|
||||
@ -793,7 +793,7 @@ func (api *API) putWorkspaceTTL(rw http.ResponseWriter, r *http.Request) {
|
||||
// @Summary Extend workspace deadline by ID
|
||||
// @ID extend-workspace-deadline-by-id
|
||||
// @Security CoderSessionToken
|
||||
// @Consume json
|
||||
// @Accept json
|
||||
// @Produce json
|
||||
// @Tags Workspaces
|
||||
// @Param workspace path string true "Workspace ID" format(uuid)
|
||||
|
||||
Reference in New Issue
Block a user