diff --git a/website/content/docs/concepts/api-standards/index.mdx b/website/content/docs/concepts/api-standards/index.mdx deleted file mode 100644 index ebc28ad5ef..0000000000 --- a/website/content/docs/concepts/api-standards/index.mdx +++ /dev/null @@ -1,11 +0,0 @@ ---- -layout: docs -page_title: API Standards -sidebar_title: API Standards -description: |- - An introduction to Boundary API standards. ---- - -# Boundary API Standards - -This section covers our API standards including command line and HTTP API. diff --git a/website/content/docs/concepts/api-standards/cli-standards.mdx b/website/content/docs/concepts/api/cli-behavior.mdx similarity index 95% rename from website/content/docs/concepts/api-standards/cli-standards.mdx rename to website/content/docs/concepts/api/cli-behavior.mdx index f52e7f146b..09fddc43a7 100644 --- a/website/content/docs/concepts/api-standards/cli-standards.mdx +++ b/website/content/docs/concepts/api/cli-behavior.mdx @@ -1,14 +1,14 @@ --- layout: docs -page_title: CLI Standards -sidebar_title: CLI Standards +page_title: CLI Behavior +sidebar_title: CLI Behavior description: |- - Boundary's CLI standards + Boundary's CLI behavior --- -# CLI Standards +# CLI Behavior -Boundary's CLI has predictable behavior throughout its various commands. This page details these standards to help users make better use of the CLI. +Boundary's CLI has predictable behavior throughout its various commands. This page details the common patterns in used in order to help users make better use of the CLI. ## Parameter Handling diff --git a/website/content/docs/concepts/api-standards/http-standards.mdx b/website/content/docs/concepts/api/http-api-model.mdx similarity index 96% rename from website/content/docs/concepts/api-standards/http-standards.mdx rename to website/content/docs/concepts/api/http-api-model.mdx index f8ddb58b79..949e2d6da5 100644 --- a/website/content/docs/concepts/api-standards/http-standards.mdx +++ b/website/content/docs/concepts/api/http-api-model.mdx @@ -22,8 +22,8 @@ Boundary's current API version is 1; all API paths begin with `/v1/`. * `400`: Boundary returns `400` when a command cannot be completed due to invalid user input, except for a properly-formatted identifier that does not map to an existing resource, which will return a `404` as discussed below. * `401`: Boundary returns `401` if no authentication token is provided or if the provided token is invalid. A valid token that simply does not have permission for a resource will return a `403` instead. A token that is invalid or missing, but where the anonymous user (`u_anon`) is able to successfully perform the action, will not return a `401` but instead will return the result of the action. * `403`: Boundary returns `403` if a provided token was valid but does not have the grants required to perform the requested action. -* `404`: Boundary returns `404` if a resource cannot be found. Note that this happens _prior_ to authentication/authorization checking in nearly all cases as the resource information (such as its scope, available actions, etc.) is a required part of that check. As a result, an action against a resource that does not exist will return a `404` instead of a `401` or `403`. While this could be considered an information leak, since IDs are randomly generated and this only discloses whether an ID is valid, it's tolerable. -* `405`: Boundary returns a `405` to indicate that the method is not implemented for the given resource. +* `404`: Boundary returns `404` if a resource cannot be found. Note that this happens _prior_ to authentication/authorization checking in nearly all cases as the resource information (such as its scope, available actions, etc.) is a required part of that check. As a result, an action against a resource that does not exist will return a `404` instead of a `401` or `403`. While this could be considered an information leak, since IDs are randomly generated and this only discloses whether an ID is valid, it's tolerable as it allows for far simpler and more robust client implementation. +* `405`: Boundary returns a `405` to indicate that the method (HTTP verb or custom action) is not implemented for the given resource. * `500`: Boundary returns `500` if an error occurred that is not (directly) tied to invalid user input. If a `500` is generated, information about the error will be logged to Boundary's server log but is not generally provided to the client. ## Path Layout diff --git a/website/content/docs/concepts/api/index.mdx b/website/content/docs/concepts/api/index.mdx new file mode 100644 index 0000000000..fe43e59eae --- /dev/null +++ b/website/content/docs/concepts/api/index.mdx @@ -0,0 +1,12 @@ +--- +layout: docs +page_title: API +sidebar_title: API +description: |- + An introduction to Boundary's API. +--- + +# Boundary API + +This section covers our API, including information about its underlying model +and how the CLI implements support for the API. diff --git a/website/content/docs/concepts/security-model/index.mdx b/website/content/docs/concepts/security-model/index.mdx deleted file mode 100644 index 72057119f3..0000000000 --- a/website/content/docs/concepts/security-model/index.mdx +++ /dev/null @@ -1,11 +0,0 @@ ---- -layout: docs -page_title: Security Model -sidebar_title: Security Model -description: |- - Boundary security model overview. ---- - -# Security Model - -This section describes the security models that Boundary follows. Here you can find in-depth analysis about how permissions, identity, and target security are handled within the Boundary product. diff --git a/website/content/docs/concepts/security/index.mdx b/website/content/docs/concepts/security/index.mdx new file mode 100644 index 0000000000..6cde32b3dd --- /dev/null +++ b/website/content/docs/concepts/security/index.mdx @@ -0,0 +1,11 @@ +--- +layout: docs +page_title: Security +sidebar_title: Security +description: |- + Boundary security overview. +--- + +# Security + +This section describes Boundary's security norms. Here you can find in-depth analysis about how permissions, identity, and target security are handled within the Boundary product. diff --git a/website/content/docs/concepts/security-model/permissions-model.mdx b/website/content/docs/concepts/security/permissions-model.mdx similarity index 100% rename from website/content/docs/concepts/security-model/permissions-model.mdx rename to website/content/docs/concepts/security/permissions-model.mdx index 9221f94c28..675053a288 100644 --- a/website/content/docs/concepts/security-model/permissions-model.mdx +++ b/website/content/docs/concepts/security/permissions-model.mdx @@ -117,20 +117,6 @@ the scope, but *only the host sets belonging to host catalog hcst_1234567890*. Pinning is essentially a way to use top-level resources to create mini permission boundaries for their subordinate resources. -### Templates - -A few template possibilities exist, which will at grant evaluation time -subsitute the given value into the ID field of the grant string: - -* `{{account.id}}`: The substituted value is the account ID associated with the -token used to perform the action. As an example, -`id={{account.id}};actions=read,change-password"` is one of Boundary's default -grants to allow users that have authenticated with the Password auth method to -change their own password. - -* `{{user.id}}`: The substituted value is the user ID associated with the token -used to perform the action. - ### Wildcard ID Various wildcard possibilities are allowed: @@ -168,6 +154,20 @@ Finally, ID, type, and actions can all be wildcards: Such a grant is essentially a full administrator grant for a scope. +### Templates + +A few template possibilities exist, which will at grant evaluation time +subsitute the given value into the ID field of the grant string: + +* `{{account.id}}`: The substituted value is the account ID associated with the +token used to perform the action. As an example, +`id={{account.id}};actions=read,change-password"` is one of Boundary's default +grants to allow users that have authenticated with the Password auth method to +change their own password. + +* `{{user.id}}`: The substituted value is the user ID associated with the token +used to perform the action. + ## Resource Table The following table works as a quick cheat-sheet to help you manage your diff --git a/website/data/docs-navigation.js b/website/data/docs-navigation.js index b56c91e229..0115a231b0 100644 --- a/website/data/docs-navigation.js +++ b/website/data/docs-navigation.js @@ -2,9 +2,9 @@ // // - A string refers to the name of a file // - A "category" value refers to the name of a directory -// - All directories must have an "index.mdx" file to serve as -// the landing page for the category, or a "name" property to -// serve as the category title in the sidebar +// - All directories must have an "index.mdx" file to serve as the landing page +// for the category, or a "name" property to serve as the category title in +// the sidebar export default [ { @@ -29,12 +29,19 @@ export default [ { category: 'concepts', content: [ - { - category: 'security-model', - content: [ - 'permissions-model', - ] - }, + { + category: 'api', + content: [ + 'http-api-model', + 'cli-behavior', + ] + }, + { + category: 'security', + content: [ + 'permissions-model', + ] + }, { category: 'domain-model', content: [ @@ -56,13 +63,6 @@ export default [ 'users', ], }, - { - category: 'api-standards', - content: [ - 'http-standards', - 'cli-standards', - ] - }, ], }, '---',