diff --git a/website/.dir-locals.el b/website/.dir-locals.el new file mode 100644 index 0000000000..387d11b742 --- /dev/null +++ b/website/.dir-locals.el @@ -0,0 +1,4 @@ +;;; Directory Local Variables +;;; For more information see (info "(emacs) Directory Variables") + +((auto-mode-alist . (("\\.mdx\\'" . markdown-mode)))) diff --git a/website/.editorconfig b/website/.editorconfig deleted file mode 100644 index 36bf83fdb5..0000000000 --- a/website/.editorconfig +++ /dev/null @@ -1,18 +0,0 @@ -# This file is for unifying the coding style for different editors and IDEs -# editorconfig.org - -root = true - -[*] -end_of_line = lf -charset = utf-8 -insert_final_newline = true -trim_trailing_whitespace = true -indent_style = space -indent_size = 2 - -[Makefile] -indent_style = tab - -[{*.md,*.json}] -max_line_length = null diff --git a/website/.env b/website/.env deleted file mode 100644 index 6ba0ec1161..0000000000 --- a/website/.env +++ /dev/null @@ -1,3 +0,0 @@ -NEXT_PUBLIC_ALGOLIA_APP_ID=YY0FFNI7MF -NEXT_PUBLIC_ALGOLIA_INDEX=product_VAULT -NEXT_PUBLIC_ALGOLIA_SEARCH_ONLY_API_KEY=9c555e8fa951c1c53e726c0ce2eb3b73 diff --git a/website/.env.production b/website/.env.production deleted file mode 100644 index 83825a896c..0000000000 --- a/website/.env.production +++ /dev/null @@ -1 +0,0 @@ -HASHI_ENV=production diff --git a/website/.eslintrc.js b/website/.eslintrc.js deleted file mode 100644 index eafa067f94..0000000000 --- a/website/.eslintrc.js +++ /dev/null @@ -1,10 +0,0 @@ -/** - * Copyright (c) HashiCorp, Inc. - * SPDX-License-Identifier: MPL-2.0 - */ - -module.exports = { - ...require('@hashicorp/platform-cli/config/.eslintrc'), - /* Specify overrides here */ - ignorePatterns: ['public/'] -} diff --git a/website/.gitignore b/website/.gitignore index adaccf90db..b2d6de3062 100644 --- a/website/.gitignore +++ b/website/.gitignore @@ -1,11 +1,20 @@ -node_modules -.DS_Store -.next -out -.mdx-data +# Dependencies +/node_modules + +# Production +/build -# As per Next.js conventions (https://nextjs.org/docs/basic-features/environment-variables#default-environment-variables) -.env*.local -!.env* +# Generated files +.docusaurus +.cache-loader + +# Misc +.DS_Store +.env.local +.env.development.local +.env.test.local +.env.production.local -website-preview +npm-debug.log* +yarn-debug.log* +yarn-error.log* diff --git a/website/.nvmrc b/website/.nvmrc deleted file mode 100644 index 958b5a36e1..0000000000 --- a/website/.nvmrc +++ /dev/null @@ -1 +0,0 @@ -v14 diff --git a/website/.stylelintrc.js b/website/.stylelintrc.js deleted file mode 100644 index 01d3cc1703..0000000000 --- a/website/.stylelintrc.js +++ /dev/null @@ -1,9 +0,0 @@ -/** - * Copyright (c) HashiCorp, Inc. - * SPDX-License-Identifier: MPL-2.0 - */ - -module.exports = { - ...require('@hashicorp/platform-cli/config/stylelint.config'), - /* Specify overrides here */ -} diff --git a/website/Dockerfile b/website/Dockerfile deleted file mode 100644 index b105794424..0000000000 --- a/website/Dockerfile +++ /dev/null @@ -1,11 +0,0 @@ -# Copyright (c) HashiCorp, Inc. -# SPDX-License-Identifier: MPL-2.0 - -FROM docker.mirror.hashicorp.services/node:14.17.0-alpine -RUN apk add --update --no-cache git make g++ automake autoconf libtool nasm libpng-dev - -COPY ./package.json /website/package.json -COPY ./package-lock.json /website/package-lock.json -WORKDIR /website -RUN npm install -g npm@latest -RUN npm install diff --git a/website/Makefile b/website/Makefile index eeaa9157f5..9724eee7d4 100644 --- a/website/Makefile +++ b/website/Makefile @@ -1,58 +1,23 @@ -###################################################### -# NOTE: This file is managed by the Digital Team's # -# Terraform configuration @ hashicorp/mktg-terraform # -###################################################### - -.DEFAULT_GOAL := website - -# Set the preview mode for the website shell to "developer" or "io" -PREVIEW_MODE ?= developer -REPO ?= vault - -# Enable setting alternate docker tool, e.g. 'make DOCKER_CMD=podman' -DOCKER_CMD ?= docker - -CURRENT_GIT_BRANCH=$$(git rev-parse --abbrev-ref HEAD) -LOCAL_CONTENT_DIR= -PWD=$$(pwd) - -DOCKER_IMAGE="hashicorp/dev-portal" -DOCKER_IMAGE_LOCAL="dev-portal-local" -DOCKER_RUN_FLAGS=-it \ - --publish "3000:3000" \ - --rm \ - --tty \ - --volume "$(PWD)/content:/app/content" \ - --volume "$(PWD)/public:/app/public" \ - --volume "$(PWD)/data:/app/data" \ - --volume "$(PWD)/redirects.js:/app/redirects.js" \ - --volume "next-dir:/app/website-preview/.next" \ - --volume "$(PWD)/.env:/app/.env" \ - -e "REPO=$(REPO)" \ - -e "PREVIEW_FROM_REPO=$(REPO)" \ - -e "IS_CONTENT_PREVIEW=true" \ - -e "LOCAL_CONTENT_DIR=$(LOCAL_CONTENT_DIR)" \ - -e "CURRENT_GIT_BRANCH=$(CURRENT_GIT_BRANCH)" \ - -e "PREVIEW_MODE=$(PREVIEW_MODE)" - -# Default: run this if working on the website locally to run in watch mode. -.PHONY: website -website: - @echo "==> Downloading latest Docker image..." - @$(DOCKER_CMD) pull $(DOCKER_IMAGE) - @echo "==> Starting website..." - @$(DOCKER_CMD) run $(DOCKER_RUN_FLAGS) $(DOCKER_IMAGE) - -# Use this if you have run `website/build-local` to use the locally built image. -.PHONY: website/local -website/local: - @echo "==> Starting website from local image..." - @$(DOCKER_CMD) run $(DOCKER_RUN_FLAGS) $(DOCKER_IMAGE_LOCAL) - -# Run this to generate a new local Docker image. -.PHONY: website/build-local -website/build-local: - @echo "==> Building local Docker image" - @$(DOCKER_CMD) build https://github.com/hashicorp/dev-portal.git\#main \ - -t $(DOCKER_IMAGE_LOCAL) +NPM := $(shell which npm) +.PHONY: start, clean, deploy, serve, install + +start: node_modules + @$(NPM) run start + +build: node_modules $(wildcard content/**/*.mdx) sidebars.ts sidebarsApi.ts + @$(NPM) run build + +serve: build + @$(NPM) run serve + +deploy: node_modules + @$(NPM) run deploy + +clean: node_modules + @$(NPM) run clear + +node_modules: package.json + @$(NPM) install + +install: node_modules diff --git a/website/README.md b/website/README.md index e18ee8cc38..39e420110b 100644 --- a/website/README.md +++ b/website/README.md @@ -1,15 +1,8 @@ -# Vault Website +# OpenBao Website -This subdirectory contains the content for the [Vault Website](https://vaultproject.io/). - - +This subdirectory contains the content for the [OpenBao +Website](https://openbao.github.io/openbao/). It is built using +[Docusaurus](https://docusaurus.io), a modern static site generator. ## Table of Contents @@ -17,60 +10,38 @@ This subdirectory contains the content for the [Vault Website](https://vaultproj - [Running the Site Locally](#running-the-site-locally) - [Editing Markdown Content](#editing-markdown-content) - [Editing Navigation Sidebars](#editing-navigation-sidebars) -- [Changing the Release Version](#changing-the-release-version) -- [Redirects](#redirects) -- [Browser Support](#browser-support) - [Deployment](#deployment) - - - ## Contributions Welcome! -If you find a typo or you feel like you can improve the HTML, CSS, or JavaScript, we welcome contributions. Feel free to open issues or pull requests like any normal GitHub project, and we'll merge it in 🚀 - - - - - +If you find a typo or you feel like you can improve the HTML, CSS, or +JavaScript, we welcome contributions. Feel free to open issues or pull requests +like any normal GitHub project, and we'll merge it in 🚀 ## Running the Site Locally -The website can be run locally through node.js or [Docker](https://www.docker.com/get-started). If you choose to run through Docker, everything will be a little bit slower due to the additional overhead, so for frequent contributors it may be worth it to use node. - -> **Note:** If you are using a text editor that uses a "safe write" save style such as **vim** or **goland**, this can cause issues with the live reload in development. If you turn off safe write, this should solve the problem. In vim, this can be done by running `:set backupcopy=yes`. In goland, search the settings for "safe write" and turn that setting off. - -### With Docker - -Running the site locally is simple. Provided you have Docker installed, clone this repo, run `make`, and then visit `http://localhost:3000`. - -The docker image is pre-built with all the website dependencies installed, which is what makes it so quick and simple, but also means if you need to change dependencies and test the changes within Docker, you'll need a new image. If this is something you need to do, you can run `make build-image` to generate a local Docker image with updated dependencies, then `make website-local` to use that image and preview. - -### With Node +The website can be run locally through node.js. If your local development +environment has a supported version (v18.0.0+) of [node +installed](https://nodejs.org/en/) you can run: -If your local development environment has a supported version (v10.0.0+) of [node installed](https://nodejs.org/en/) you can run: +- `make` -- `npm install` -- `npm start` - -...and then visit `http://localhost:3000`. - -If you pull down new code from github, you should run `npm install` again. Otherwise, there's no need to re-run `npm install` each time the site is run, you can just run `npm start` to get it going. - - - - - +...and then visit `http://localhost:3000/openbao`. ## Editing Markdown Content -Documentation content is written in [Markdown](https://www.markdownguide.org/cheat-sheet/) and you'll find all files listed under the `/content` directory. - -To create a new page with Markdown, create a file ending in `.mdx` in a `content/`. The path in the content directory will be the URL route. For example, `content/docs/hello.mdx` will be served from the `/docs/hello` URL. +Documentation content is written in +[Markdown](https://www.markdownguide.org/cheat-sheet/) and you'll find all files +listed under the `/content` directory. -> **Important**: Files and directories will only be rendered and published to the website if they are [included in sidebar data](#editing-navigation-sidebars). Any file not included in sidebar data will not be rendered or published. +To create a new page with Markdown, create a file ending in `.mdx` in a +`content/`. The path in the content directory will be the URL +route. For example, `content/docs/hello.mdx` will be served from the +`/docs/hello` URL. -This file can be standard Markdown and also supports [YAML frontmatter](https://middlemanapp.com/basics/frontmatter/). YAML frontmatter is optional, there are defaults for all keys. +This file can be standard Markdown and also supports [YAML +frontmatter](https://middlemanapp.com/basics/frontmatter/). YAML frontmatter is +optional, there are defaults for all keys. ```yaml --- @@ -81,178 +52,42 @@ description: "A thorough, yet succinct description of the page's contents" The significant keys in the YAML frontmatter are: -- `title` `(string)` - This is the title of the page that will be set in the HTML title. -- `description` `(string)` - This is a description of the page that will be set in the HTML description. - -> ⚠️ If there is a need for a `/api/*` url on this website, the url will be changed to `/api-docs/*`, as the `api` folder is reserved by next.js. - -### Validating Content - -Content changes are automatically validated against a set of rules as part of the pull request process. If you want to run these checks locally to validate your content before comitting your changes, you can run the following command: - -``` -npm run content-check -``` - -If the validation fails, actionable error messages will be displayed to help you address detected issues. - -### Creating New Pages - -There is currently a small bug with new page creation - if you create a new page and link it up via subnav data while the server is running, it will report an error saying the page was not found. This can be resolved by restarting the server. +- `title` `(string)` - This is the title of the page that will be set in the + HTML title. +- `description` `(string)` - This is a description of the page that will be set + in the HTML description. ### Markdown Enhancements -There are several custom markdown plugins that are available by default that enhance [standard markdown](https://commonmark.org/) to fit our use cases. This set of plugins introduces a couple instances of custom syntax, and a couple specific pitfalls that are not present by default with markdown, detailed below: - -- > **Warning**: We are deprecating the current [paragraph alerts](https://github.com/hashicorp/remark-plugins/tree/master/plugins/paragraph-custom-alerts#paragraph-custom-alerts), in favor of the newer [MDX Inline Alert](#inline-alerts) components. The legacy paragraph alerts are represented by the symbols `~>`, `->`, `=>`, or `!>`. -- If you see `@include '/some/path.mdx'`, this is a [markdown include](https://github.com/hashicorp/remark-plugins/tree/master/plugins/include-markdown#include-markdown-plugin). It's worth noting as well that all includes resolve from `website/content/partials` by default, and that changes to partials will not live-reload the website. -- If you see `# Headline ((#slug))`, this is an example of an [anchor link alias](https://github.com/hashicorp/remark-plugins/tree/je.anchor-link-adjustments/plugins/anchor-links#anchor-link-aliases). It adds an extra permalink to a headline for compatibility and is removed from the output. -- Due to [automatically generated permalinks](https://github.com/hashicorp/remark-plugins/tree/je.anchor-link-adjustments/plugins/anchor-links#anchor-links), any text changes to _headlines_ or _list items that begin with inline code_ can and will break existing permalinks. Be very cautious when changing either of these two text items. - - Headlines are fairly self-explanatory, but here's an example of how to list items that begin with inline code look. - - ```markdown - - this is a normal list item - - `this` is a list item that begins with inline code - ``` - - Its worth noting that _only the inline code at the beginning of the list item_ will cause problems if changed. So if you changed the above markup to... - - ```markdown - - lsdhfhksdjf - - `this` jsdhfkdsjhkdsfjh - ``` - - ...while it perhaps would not be an improved user experience, no links would break because of it. The best approach is to **avoid changing headlines and inline code at the start of a list item**. If you must change one of these items, make sure to tag someone from the digital marketing development team on your pull request, they will help to ensure as much compatibility as possible. +There are several custom markdown plugins that are available by default that +enhance [standard markdown](https://commonmark.org/) to fit our use cases. This +set of plugins introduces a couple instances of custom syntax, and a couple +specific pitfalls that are not present by default with markdown, detailed below: + +- If you see `@include '/some/path.mdx'`, this is a [markdown + include](https://github.com/hashicorp/remark-plugins/tree/master/plugins/include-markdown#include-markdown-plugin). + It's worth noting as well that all includes resolve from + `website/content/partials` by default, and that changes to partials will not + live-reload the website. +- If you see `# Headline {#slug}`, this is an example of a [heading + ID](https://docusaurus.io/docs/markdown-features/toc#heading-ids). It adds an + extra permalink to a headline for compatibility and is removed from the + output. +- Due to automatically generated headline IDs, any text changes to _headlines_ + can and will break existing permalinks. Be very cautious when changing either + of these. ### Custom Components -A number of custom [mdx components](https://mdxjs.com/) are available for use within any `.mdx` file. Each one is documented below: - -#### Inline Alerts - -There are custom MDX components available to author alert data. [See the full documentation here](https://developer.hashicorp.com/swingset/components/mdxinlinealert). They render as colored boxes to draw the user's attention to some type of aside. - -```mdx -## Alert types - -### Tip - - - To provide general information to the user regarding the current context or - relevant actions. - - -### Highlight - - - To provide general or promotional information to the user prominently. - - -### Note - - - To help users avoid an issue. Provide guidance and actions if possible. - - -### Warning - - - To indicate critical issues that need immediate action or help users - understand something critical. - - -## Title override prop - -To provide general information. -``` - -#### Tabs - -The `Tabs` component creates tabbed content of any type, but is often used for code examples given in different languages. Here's an example of how it looks from the Vagrant documentation website: - -![Tabs Component](https://p176.p0.n0.cdn.getcloudapp.com/items/WnubALZ4/Screen%20Recording%202020-06-11%20at%2006.03%20PM.gif?v=1de81ea720a8cc8ade83ca64fb0b9edd) - -> Please refer to the [Swingset](https://react-components.vercel.app/?component=Tabs) documentation for the latest examples and API reference. - -It can be used as such within a markdown file: - -````mdx -Normal **markdown** content. - - - - -```shell-session -$ command ... -``` - - - - -```shell-session -$ curl ... -``` - - - - -Continued normal markdown content -```` - -The intentionally skipped line is a limitation of the mdx parser which is being actively worked on. All tabs must have a heading, and there is no limit to the number of tabs, though it is recommended to go for a maximum of three or four. - -#### Enterprise Alert - -This component provides a standard way to call out functionality as being present only in the enterprise version of the software. It can be presented in two contexts, inline or standalone. Here's an example of standalone usage from the Consul docs website: - -![Enterprise Alert Component - Standalone](https://p176.p0.n0.cdn.getcloudapp.com/items/WnubALp8/Screen%20Shot%202020-06-11%20at%206.06.03%20PM.png?v=d1505b90bdcbde6ed664831a885ea5fb) - -The standalone component can be used as such in markdown files: - -```mdx -# Page Headline - - - -Continued markdown content... -``` - -It can also receive custom text contents if you need to change the messaging but wish to retain the style. This will replace the text `This feature is available in all versions of Consul Enterprise.` with whatever you add. For example: - -```mdx -# Page Headline - - - My custom text here, and a link! - - -Continued markdown content... -``` - -It's important to note that once you are adding custom content, it must be html and can not be markdown, as demonstrated above with the link. - -Now let's look at inline usage, here's an example: - -![Enterprise Alert Component - Inline](https://p176.p0.n0.cdn.getcloudapp.com/items/L1upYLEJ/Screen%20Shot%202020-06-11%20at%206.07.50%20PM.png?v=013ba439263de8292befbc851d31dd78) - -And here's how it could be used in your markdown document: - -```mdx -### Some Enterprise Feature - -Continued markdown content... -``` - -It's also worth noting that this component will automatically adjust to the correct product colors depending on the context. - -#### Other Components - -Other custom components can be made available on a per-site basis, the above are the standards. If you have questions about custom components that are not documented here, or have a request for a new custom component, please reach out to @hashicorp/digital-marketing. +A number of custom [mdx components](https://mdxjs.com/) are available for use +within any `.mdx` file. Please consult the [Docusaurus +documentation](https://docusaurus.io/docs/markdown-features) for more +information about them. ### Syntax Highlighting -When using fenced code blocks, the recommendation is to tag the code block with a language so that it can be syntax highlighted. For example: +When using fenced code blocks, the recommendation is to tag the code block with +a language so that it can be syntax highlighted. For example: ```` ``` @@ -264,11 +99,16 @@ When using fenced code blocks, the recommendation is to tag the code block with ``` ```` -Check out the [supported languages list](https://prismjs.com/#supported-languages) for the syntax highlighter we use if you want to double check the language name. +Check out the [supported languages +list](https://prismjs.com/#supported-languages) for the syntax highlighter we +use if you want to double check the language name. -It is also worth noting specifically that if you are using a code block that is an example of a terminal command, the correct language tag is `shell-session`. For example: +It is also worth noting specifically that if you are using a code block that is +an example of a terminal command, the correct language tag is `shell-session`. +For example: -🚫**BAD**: Using `shell`, `sh`, `bash`, or `plaintext` to represent a terminal command +🚫**BAD**: Using `shell`, `sh`, `bash`, or `plaintext` to represent a terminal +command ```` ```shell @@ -284,252 +124,20 @@ $ terraform apply ``` ```` - - - - - ## Editing Navigation Sidebars -The structure of the sidebars are controlled by files in the [`/data` directory](data). For example, [data/docs-nav-data.json](data/docs-nav-data.json) controls the **docs** sidebar. Within the `data` folder, any file with `-nav-data` after it controls the navigation for the given section. - -The sidebar uses a simple recursive data structure to represent _files_ and _directories_. The sidebar is meant to reflect the structure of the docs within the filesystem while also allowing custom ordering. Let's look at an example. First, here's our example folder structure: - -```text -. -├── docs -│   └── directory -│   ├── index.mdx -│   ├── file.mdx -│   ├── another-file.mdx -│   └── nested-directory -│   ├── index.mdx -│   └── nested-file.mdx -``` - -Here's how this folder structure could be represented as a sidebar navigation, in this example it would be the file `website/data/docs-nav-data.json`: - -```json -[ - { - "title": "Directory", - "routes": [ - { - "title": "Overview", - "path": "directory" - }, - { - "title": "File", - "path": "directory/file" - }, - { - "title": "Another File", - "path": "directory/another-file" - }, - { - "title": "Nested Directory", - "routes": [ - { - "title": "Overview", - "path": "directory/nested-directory" - }, - { - "title": "Nested File", - "path": "directory/nested-directory/nested-file" - } - ] - } - ] - } -] -``` - -A couple more important notes: - -- Within this data structure, ordering is flexible, but hierarchy is not. The structure of the sidebar must correspond to the structure of the content directory. So while you could put `file` and `another-file` in any order in the sidebar, or even leave one or both of them out, you could not decide to un-nest the `nested-directory` object without also un-nesting it in the filesystem. -- The `title` property on each node in the `nav-data` tree is the human-readable name in the navigation. -- The `path` property on each leaf node in the `nav-data` tree is the URL path where the `.mdx` document will be rendered, and the -- Note that "index" files must be explicitly added. These will be automatically resolved, so the `path` value should be, as above, `directory` rather than `directory/index`. A common convention is to set the `title` of an "index" node to be `"Overview"`. - -Below we will discuss a couple of more unusual but still helpful patterns. - -### Index-less Categories - -Sometimes you may want to include a category but not have a need for an index page for the category. This can be accomplished, but as with other branch and leaf nodes, a human-readable `title` needs to be set manually. Here's an example of how an index-less category might look: - -```text -. -├── docs -│   └── indexless-category -│   └── file.mdx -``` - -```json -// website/data/docs-nav-data.json -[ - { - "title": "Indexless Category", - "routes": [ - { - "title": "File", - "path": "indexless-category/file" - } - ] - } -] -``` - -### Custom or External Links - -Sometimes you may have a need to include a link that is not directly to a file within the docs hierarchy. This can also be supported using a different pattern. For example: - -```json -[ - { - "name": "Directory", - "routes": [ - { - "title": "File", - "path": "directory/file" - }, - { - "title": "Another File", - "path": "directory/another-file" - }, - { - "title": "Tao of HashiCorp", - "href": "https://www.hashicorp.com/tao-of-hashicorp" - } - ] - } -] -``` - -If the link provided in the `href` property is external, it will display a small icon indicating this. If it's internal, it will appear the same way as any other direct file link. - - - - - - -## Changing the Release Version - -To change the version displayed for download on the website, head over to `data/version.js` and change the number there. It's important to note that the version number must match a version that has been released and is live on `releases.hashicorp.com` -- if it does not, the website will be unable to fetch links to the binaries and will not compile. So this version number should be changed _only after a release_. - -### Displaying a Prerelease - -If there is a prerelease of any type that should be displayed on the downloads page, this can be done by editing `pages/downloads/index.jsx`. By default, the download component might look something like this: - -```jsx - -``` +The structure of the sidebars are controlled by the `sidebar.ts` and +`sidebarApi.ts` files. For example, [sidebar.ts](sidebar.ts) controls the +**docs** sidebar. Please consult the [Docusaurus +documentation](https://docusaurus.io/docs/sidebar/items) on how to edit the +sidebars. -To add a prerelease, an extra `prerelease` property can be added to the component as such: - -```jsx - -``` - -This configuration would display something like the following text on the website, emphasis added to the configurable parameters: - -``` -A {{ release candidate }} for {{ v1.0.0 }} is available! The release can be downloaded here. -``` - -You may customize the parameters in any way you'd like. To remove a prerelease from the website, simply delete the `prerelease` parameter from the above component. - - - - - - -## Redirects - -This website structures URLs based on the filesystem layout. This means that if a file is moved, removed, or a folder is re-organized, links will break. If a path change is necessary, it can be mitigated using redirects. It's important to note that redirects should only be used to cover for external links -- if you are moving a path which internal links point to, the internal links should also be adjusted to point to the correct page, rather than relying on a redirect. - -To add a redirect, head over to the `redirects.js` file - the format is fairly simple - there's a `source` and a `destination` - fill them both in, indicate that it's a permanent redirect or not using the `permanent` key, and that's it. Let's look at an example: - -``` -{ - source: '/foo', - destination: '/bar', - permanent: true -} -``` - -This redirect rule will send all incoming links to `/foo` to `/bar`. For more details on the redirects file format, [check out the docs on vercel](https://vercel.com/docs/configuration#project/redirects). All redirects will work both locally and in production exactly the same way, so feel free to test and verify your redirects locally. In the past testing redirects has required a preview deployment -- this is no longer the case. Please note however that if you add a redirect while the local server is running, you will need to restart it in order to see the effects of the redirect. - -There is still one caveat though: redirects do not apply to client-side navigation. By default, all links in the navigation and docs sidebar will navigate purely on the client side, which makes navigation through the docs significantly faster, especially for those with low-end devices and/or weak internet connections. In the future, we plan to convert all internal links within docs pages to behave this way as well. This means that if there is a link on this website to a given piece of content that has changed locations in some way, we need to also _directly change existing links to the content_. This way, if a user clicks a link that navigates on the client side, or if they hit the url directly and the page renders from the server side, either one will work perfectly. - -Let's look at an example. Say you have a page called `/docs/foo` which needs to be moved to `/docs/nested/foo`. Additionally, this is a page that has been around for a while and we know there are links into `/docs/foo.html` left over from our previous website structure. First, we move the page, then adjust the docs sidenav, in `data/docs-navigation.js`. Find the category the page is in, and move it into the appropriate subcategory. Next, we add to `_redirects` as such. The `.html` version is covered automatically. - -```js -{ source: '/foo', destination: '/nested/foo', permanent: true } -``` - -Next, we run a global search for internal links to `/foo`, and make sure to adjust them to be `/nested/foo` - this is to ensure that client-side navigation still works correctly. _Adding a redirect alone is not enough_. +## Deployment -One more example - let's say that content is being moved to an external website. A common example is guides moving to `learn.hashicorp.com`. In this case, we take all the same steps, except that we need to make a different type of change to the `docs-navigation` file. If previously the structure looked like: +This website is hosted on GitHub Pages and configured to automatically deploy +anytime you push code to the `gh-pages` branch. To perform a manual deployment +run the following command: -```js -{ - category: 'docs', - content: [ - 'foo' - ] -} ``` - -If we no longer want the link to be in the side nav, we can simply remove it. If we do still want the link in the side nav, but pointing to an external destination, we need to slightly change the structure as such: - -```js -{ - category: 'docs', - content: [ - { title: 'Foo Title', href: 'https://learn.hashicorp.com//foo' } - ] -} +$ GIT_USER= yarn deploy ``` - -As the majority of items in the side nav are internal links, the structure makes it as easy as possible to represent these links. This alternate syntax is the most concise manner than an external link can be represented. External links can be used anywhere within the docs sidenav. - -It's also worth noting that it is possible to do glob-based redirects, for example matching `/docs/*`, and you may see this pattern in the redirects file. This type of redirect is much higher risk and the behavior is a bit more nuanced, so if you need to add a glob redirect, please reach out to the website maintainers and ask about it first. - - - - - - -## Browser Support - -We support the following browsers targeting roughly the versions specified. - -| ![Chrome](https://raw.githubusercontent.com/alrra/browser-logos/main/src/chrome/chrome.svg) | ![Edge](https://raw.githubusercontent.com/alrra/browser-logos/main/src/edge/edge.svg) | ![Opera](https://raw.githubusercontent.com/alrra/browser-logos/main/src/opera/opera.svg) | ![Firefox](https://raw.githubusercontent.com/alrra/browser-logos/main/src/firefox/firefox.svg) | ![Safari](https://raw.githubusercontent.com/alrra/browser-logos/main/src/safari/safari.svg) | -| ------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- | -| **Latest** | **Latest** | **Latest** | **Latest** | **Latest** | - - - - - - -## Deployment - -This website is hosted on Vercel and configured to automatically deploy anytime you push code to the `stable-website` branch. Any time a pull request is submitted that changes files within the `website` folder, a deployment preview will appear in the github checks which can be used to validate the way docs changes will look live. Deployments from `stable-website` will look and behave the same way as deployment previews. - - diff --git a/website/babel.config.js b/website/babel.config.js new file mode 100644 index 0000000000..e00595dae7 --- /dev/null +++ b/website/babel.config.js @@ -0,0 +1,3 @@ +module.exports = { + presets: [require.resolve('@docusaurus/core/lib/babel/preset')], +}; diff --git a/website/content/api-docs/auth/approle.mdx b/website/content/api-docs/auth/approle.mdx index 9d630effb3..c3f5591d33 100644 --- a/website/content/api-docs/auth/approle.mdx +++ b/website/content/api-docs/auth/approle.mdx @@ -1,6 +1,5 @@ --- -layout: api -page_title: AppRole - Auth Methods - HTTP API +sidebar_label: AppRole description: This is the API documentation for the OpenBao AppRole auth method. --- @@ -8,7 +7,7 @@ description: This is the API documentation for the OpenBao AppRole auth method. This is the API documentation for the OpenBao AppRole auth method. For general information about the usage and operation of the AppRole method, please -see the [OpenBao AppRole method documentation](/vault/docs/auth/approle). +see the [OpenBao AppRole method documentation](/docs/auth/approle). This documentation assumes the AppRole method is mounted at the `/auth/approle` path in OpenBao. Since it is possible to enable auth methods at any location, diff --git a/website/content/api-docs/auth/cert.mdx b/website/content/api-docs/auth/cert.mdx index d0804f5e2b..02f152d6d3 100644 --- a/website/content/api-docs/auth/cert.mdx +++ b/website/content/api-docs/auth/cert.mdx @@ -1,6 +1,5 @@ --- -layout: api -page_title: TLS Certificate - Auth Methods - HTTP API +sidebar_label: TLS Certificates description: |- This is the API documentation for the OpenBao TLS Certificate authentication method. @@ -8,11 +7,19 @@ description: |- # TLS certificate auth method (API) -@include 'x509-sha1-deprecation.mdx' +:::warning + +**Note**: This engine can use external X.509 certificates as part of TLS or signature validation. + Verifying signatures against X.509 certificates that use SHA-1 is deprecated and is no longer + usable without a workaround. See the + [deprecation FAQ](/docs/deprecation/faq#q-what-is-the-impact-of-removing-support-for-x-509-certificates-with-signatures-that-use-sha-1) + for more information. + +::: This is the API documentation for the OpenBao TLS Certificate authentication method. For general information about the usage and operation of the TLS -Certificate method, please see the [OpenBao TLS Certificate method documentation](/vault/docs/auth/cert). +Certificate method, please see the [OpenBao TLS Certificate method documentation](/docs/auth/cert). This documentation assumes the TLS Certificate method is mounted at the `/auth/cert` path in OpenBao. Since it is possible to enable auth methods at any @@ -404,11 +411,15 @@ https://tools.ietf.org/html/rfc6125#section-2.3) ### Sample request -~> **NOTE** The `--cacert` value used here is for the OpenBao TLS Listener CA +:::warning + +**NOTE** The `--cacert` value used here is for the OpenBao TLS Listener CA certificate, not the CA that issued the client authentication certificate. This can be omitted if the CA used to issue the OpenBao server certificate is trusted by the local system executing this command. +::: + ```shell-session $ curl \ --request POST \ diff --git a/website/content/api-docs/auth/index.mdx b/website/content/api-docs/auth/index.mdx index 2cc48c1d92..953f34a187 100644 --- a/website/content/api-docs/auth/index.mdx +++ b/website/content/api-docs/auth/index.mdx @@ -1,6 +1,5 @@ --- -layout: api -page_title: Auth Methods - HTTP API +sidebar_label: Overview description: |- Each auth method publishes its own set of API paths and methods. These endpoints are documented in this section. diff --git a/website/content/api-docs/auth/jwt.mdx b/website/content/api-docs/auth/jwt.mdx index 82445b4b25..63cdf9d2c9 100644 --- a/website/content/api-docs/auth/jwt.mdx +++ b/website/content/api-docs/auth/jwt.mdx @@ -1,6 +1,5 @@ --- -layout: api -page_title: JWT/OIDC - Auth Methods - HTTP API +sidebar_label: JWT/OIDC description: |- This is the API documentation for the OpenBao JWT/OIDC authentication method plugin. @@ -8,11 +7,19 @@ description: |- # JWT/OIDC auth method (API) -@include 'x509-sha1-deprecation.mdx' +:::warning + +**Note**: This engine can use external X.509 certificates as part of TLS or signature validation. + Verifying signatures against X.509 certificates that use SHA-1 is deprecated and is no longer + usable without a workaround. See the + [deprecation FAQ](/docs/deprecation/faq#q-what-is-the-impact-of-removing-support-for-x-509-certificates-with-signatures-that-use-sha-1) + for more information. + +::: This is the API documentation for the OpenBao JWT/OIDC auth method plugin. To learn more about the usage and operation, see the -[OpenBao JWT/OIDC method documentation](/vault/docs/auth/jwt). +[OpenBao JWT/OIDC method documentation](/docs/auth/jwt). This documentation assumes the plugin method is mounted at the `/auth/jwt` path in OpenBao. Since it is possible to enable auth methods @@ -43,7 +50,7 @@ set. - `bound_issuer` `(string: )` - The value against which to match the `iss` claim in a JWT. - `jwt_supported_algs` `(comma-separated string, or array of strings: )` - A list of supported signing algorithms. Defaults to [RS256] for OIDC roles. Defaults to all [available algorithms](https://github.com/hashicorp/cap/blob/main/jwt/algs.go) for JWT roles. - `default_role` `(string: )` - The default role to use if none is provided during login. -- `provider_config` `(map: )` - Configuration options for provider-specific handling. Providers with specific handling include: Azure, Google, SecureAuth, IBM ISAM. The options are described in each provider's section in [OIDC Provider Setup](/vault/docs/auth/jwt/oidc-providers). +- `provider_config` `(map: )` - Configuration options for provider-specific handling. Providers with specific handling include: Azure, Google, SecureAuth, IBM ISAM. The options are described in each provider's section in [OIDC Provider Setup](/docs/auth/jwt/oidc-providers). - `namespace_in_state` `(bool: true)` - Pass namespace in the OIDC state parameter instead of as a separate query parameter. With this setting, the allowed redirect URL(s) in OpenBao and on the provider side should not contain a namespace query parameter. This means only one redirect URL entry needs to be maintained on the provider side for all vault namespaces that will be authenticating against it. Defaults to true for new configs. ### Sample payload @@ -117,7 +124,7 @@ entities attempting to login. At least one of the bound values must be set. the user; this will be used as the name for the Identity entity alias created due to a successful login. The claim value must be a string. - `user_claim_json_pointer` `(bool: false)` - Specifies if the `user_claim` value uses - [JSON pointer](/vault/docs/auth/jwt#claim-specifications-and-json-pointer) syntax for + [JSON pointer](/docs/auth/jwt#claim-specifications-and-json-pointer) syntax for referencing claims. By default, the `user_claim` value will not use JSON pointer. - `clock_skew_leeway` `(int or string: )` - The amount of leeway to add to all claims to account for clock skew, in seconds. Defaults to `60` seconds if set to `0` and can be disabled @@ -135,7 +142,7 @@ entities attempting to login. At least one of the bound values must be set. claim matches this value. - `bound_claims` `(map: )` - If set, a map of claims (keys) to match against respective claim values (values). The expected value may be a single string or a list of strings. The interpretation of the bound - claim values is configured with `bound_claims_type`. Keys support [JSON pointer](/vault/docs/auth/jwt#claim-specifications-and-json-pointer) + claim values is configured with `bound_claims_type`. Keys support [JSON pointer](/docs/auth/jwt#claim-specifications-and-json-pointer) syntax for referencing claims. - `bound_claims_type` `(string: "string")` - Configures the interpretation of the bound_claims values. If `"string"` (the default), the values will treated as string literals and must match exactly. @@ -144,10 +151,10 @@ entities attempting to login. At least one of the bound values must be set. - `groups_claim` `(string: )` - The claim to use to uniquely identify the set of groups to which the user belongs; this will be used as the names for the Identity group aliases created due to a successful login. The claim - value must be a list of strings. Supports [JSON pointer](/vault/docs/auth/jwt#claim-specifications-and-json-pointer) + value must be a list of strings. Supports [JSON pointer](/docs/auth/jwt#claim-specifications-and-json-pointer) syntax for referencing claims. - `claim_mappings` `(map: )` - If set, a map of claims (keys) to be copied to - specified metadata fields (values). Keys support [JSON pointer](/vault/docs/auth/jwt#claim-specifications-and-json-pointer) + specified metadata fields (values). Keys support [JSON pointer](/docs/auth/jwt#claim-specifications-and-json-pointer) syntax for referencing claims. - `oidc_scopes` `(list: )` - If set, a list of OIDC scopes to be used with an OIDC role. The standard scope "openid" is automatically included and need not be specified. @@ -306,10 +313,10 @@ Obtain an authorization URL from OpenBao to start an OIDC login flow. - `redirect_uri` `(string: )` - Path to the callback to complete the login. This will be of the form, "https://.../oidc/callback" where the leading portion is dependent on your OpenBao server location, port, and the mount of the JWT plugin. This must be configured with OpenBao and the - provider. See [Redirect URIs](/vault/docs/auth/jwt#redirect-uris) for more information. + provider. See [Redirect URIs](/docs/auth/jwt#redirect-uris) for more information. - `client_nonce` `(string: )` - Optional client-provided nonce that must match the `client_nonce` value provided during a subsequent request to the - [callback](/vault/api-docs/auth/jwt#oidc-callback) API. + [callback](/api-docs/auth/jwt#oidc-callback) API. ### Sample payload @@ -360,7 +367,7 @@ against any bound claims, and if valid an OpenBao token will be returned. an ID token. - `client_nonce` `(string: )` - Optional client-provided nonce that must match the `client_nonce` value provided during the prior request to the - [auth_url](/vault/api-docs/auth/jwt#oidc-authorization-url-request) API. + [auth_url](/api-docs/auth/jwt#oidc-authorization-url-request) API. ### Sample request diff --git a/website/content/api-docs/auth/kerberos.mdx b/website/content/api-docs/auth/kerberos.mdx index 3d007ed4d7..5ecc42e2ac 100644 --- a/website/content/api-docs/auth/kerberos.mdx +++ b/website/content/api-docs/auth/kerberos.mdx @@ -1,16 +1,23 @@ --- -layout: api -page_title: Kerberos - Auth Methods - HTTP API +sidebar_label: Kerberos description: This is the API documentation for the OpenBao Kerberos auth method plugin. --- # Kerberos auth method (API) -@include 'x509-sha1-deprecation.mdx' +:::warning + +**Note**: This engine can use external X.509 certificates as part of TLS or signature validation. + Verifying signatures against X.509 certificates that use SHA-1 is deprecated and is no longer + usable without a workaround. See the + [deprecation FAQ](/docs/deprecation/faq#q-what-is-the-impact-of-removing-support-for-x-509-certificates-with-signatures-that-use-sha-1) + for more information. + +::: This is the API documentation for the OpenBao Kerberos auth method plugin. To learn more about the usage and operation, see the -[OpenBao Kerberos auth method](/vault/docs/auth/kerberos). +[OpenBao Kerberos auth method](/docs/auth/kerberos). This documentation assumes the Kerberos auth method is mounted at the `auth/kerberos` path in OpenBao. Since it is possible to enable auth methods at diff --git a/website/content/api-docs/auth/kubernetes.mdx b/website/content/api-docs/auth/kubernetes.mdx index 33959181ac..9cd33b3430 100644 --- a/website/content/api-docs/auth/kubernetes.mdx +++ b/website/content/api-docs/auth/kubernetes.mdx @@ -1,16 +1,22 @@ --- -layout: api -page_title: Kubernetes - Auth Methods - HTTP API description: This is the API documentation for the OpenBao Kubernetes auth method plugin. --- # Kubernetes auth method (API) -@include 'x509-sha1-deprecation.mdx' +:::warning + +**Note**: This engine can use external X.509 certificates as part of TLS or signature validation. + Verifying signatures against X.509 certificates that use SHA-1 is deprecated and is no longer + usable without a workaround. See the + [deprecation FAQ](/docs/deprecation/faq#q-what-is-the-impact-of-removing-support-for-x-509-certificates-with-signatures-that-use-sha-1) + for more information. + +::: This is the API documentation for the OpenBao Kubernetes auth method plugin. To learn more about the usage and operation, see the -[OpenBao Kubernetes auth method](/vault/docs/auth/kubernetes). +[OpenBao Kubernetes auth method](/docs/auth/kubernetes). This documentation assumes the Kubernetes method is mounted at the `/auth/kubernetes` path in OpenBao. Since it is possible to enable auth methods at @@ -45,12 +51,16 @@ access the Kubernetes API. ### Deprecated parameters --> The following fields have been deprecated and will be removed in a future release: +:::info + +The following fields have been deprecated and will be removed in a future release: + +::: - `disable_iss_validation` `(bool: true)` **Deprecated** Disable JWT issuer validation. Allows to skip ISS validation. - `issuer` `(string: "")` **Deprecated** Optional JWT issuer. If no issuer is specified, then this plugin will use `kubernetes/serviceaccount` as the default issuer. -See [these instructions](/vault/docs/auth/kubernetes#discovering-the-service-account-issuer) for looking up the issuer for a given Kubernetes cluster. +See [these instructions](/docs/auth/kubernetes#discovering-the-service-account-issuer) for looking up the issuer for a given Kubernetes cluster. ### Caveats @@ -138,7 +148,7 @@ entities attempting to login. While it is strongly advised that you use `serviceaccount_uid`, you may also use `serviceaccount_name` in cases where you want to set the alias ahead of time, and the risks are mitigated or otherwise acceptable given your use case. It is very important to limit who is able to delete/create service accounts within a given cluster. - See the [Create an Entity Alias](/vault/api-docs/secret/identity/entity-alias#create-an-entity-alias) document + See the [Create an Entity Alias](/api-docs/secret/identity/entity-alias#create-an-entity-alias) document which further expands on the potential security implications mentioned above. @include 'tokenfields.mdx' diff --git a/website/content/api-docs/auth/ldap.mdx b/website/content/api-docs/auth/ldap.mdx index 1c8858751d..c680586635 100644 --- a/website/content/api-docs/auth/ldap.mdx +++ b/website/content/api-docs/auth/ldap.mdx @@ -1,16 +1,23 @@ --- -layout: api -page_title: LDAP - Auth Methods - HTTP API +sidebar_label: LDAP description: This is the API documentation for the OpenBao LDAP auth method. --- # LDAP auth method (API) -@include 'x509-sha1-deprecation.mdx' +:::warning + +**Note**: This engine can use external X.509 certificates as part of TLS or signature validation. + Verifying signatures against X.509 certificates that use SHA-1 is deprecated and is no longer + usable without a workaround. See the + [deprecation FAQ](/docs/deprecation/faq#q-what-is-the-impact-of-removing-support-for-x-509-certificates-with-signatures-that-use-sha-1) + for more information. + +::: This is the API documentation for the OpenBao LDAP auth method. For general information about the usage and operation of the LDAP method, please -see the [OpenBao LDAP method documentation](/vault/docs/auth/ldap). +see the [OpenBao LDAP method documentation](/docs/auth/ldap). This documentation assumes the LDAP method is mounted at the `/auth/ldap` path in OpenBao. Since it is possible to enable auth methods at any location, @@ -107,7 +114,14 @@ This endpoint configures the LDAP auth method. @include 'tokenfields.mdx' -@include 'ldap-auth-userfilter-warning.mdx' +:::warning + +When specifying a `userfilter`, either the templated value `{{.UserAttr}}` or +the literal value that matches `userattr` should be present in the filter to +ensure that the search returns a unique result that takes `userattr` into +consideration for entity alias mapping purposes and avoid possible collisions on login. + +::: ### Sample request diff --git a/website/content/api-docs/auth/radius.mdx b/website/content/api-docs/auth/radius.mdx index 0c2824261a..f814e78fe7 100644 --- a/website/content/api-docs/auth/radius.mdx +++ b/website/content/api-docs/auth/radius.mdx @@ -1,6 +1,5 @@ --- -layout: api -page_title: RADIUS - Auth Methods - HTTP API +sidebar_label: RADIUS description: This is the API documentation for the OpenBao RADIUS auth method. --- @@ -8,7 +7,7 @@ description: This is the API documentation for the OpenBao RADIUS auth method. This is the API documentation for the OpenBao RADIUS auth method. For general information about the usage and operation of the RADIUS method, please -see the [OpenBao RADIUS method documentation](/vault/docs/auth/radius). +see the [OpenBao RADIUS method documentation](/docs/auth/radius). This documentation assumes the RADIUS method is mounted at the `/auth/radius` path in OpenBao. Since it is possible to enable auth methods at any location, diff --git a/website/content/api-docs/auth/token.mdx b/website/content/api-docs/auth/token.mdx index 2b70b5abe1..9c6c19fae5 100644 --- a/website/content/api-docs/auth/token.mdx +++ b/website/content/api-docs/auth/token.mdx @@ -1,6 +1,5 @@ --- -layout: api -page_title: Token - Auth Methods - HTTP API +sidebar_label: Tokens description: This is the API documentation for the OpenBao token auth method. --- @@ -8,7 +7,7 @@ description: This is the API documentation for the OpenBao token auth method. This is the API documentation for the OpenBao token auth method. For general information about the usage and operation of the token method, please -see the [OpenBao Token method documentation](/vault/docs/auth/token). +see the [OpenBao Token method documentation](/docs/auth/token). ## List accessors @@ -88,7 +87,7 @@ during this call. - `lease` `(string: "")` - DEPRECATED; use `ttl` instead - `ttl` `(string: "")` - The TTL period of the token, provided as "1h", where hour is the largest suffix. If not provided, the token is valid for the - [default lease TTL](/vault/docs/configuration), or indefinitely if the + [default lease TTL](/docs/configuration), or indefinitely if the root policy is used. - `type` `(string: "")` - The token type. Can be "batch" or "service". Defaults to the type specified by the role configuration named by `role_name`. @@ -799,7 +798,7 @@ be cached. Listing the `/auth/token/accessors` endpoint is a good way to get some sense of the potential impact: tidy does this and more, so if this call creates problems for your cluster, it would be wise to give OpenBao more resources before attempting tidy. Note that the request may time out depending on -[max duration](/vault/docs/configuration#default_max_request_duration) +[max duration](/docs/configuration#default_max_request_duration) and your client's timeout configuration, make sure to allow it run to completion to properly judge the impact. diff --git a/website/content/api-docs/auth/userpass.mdx b/website/content/api-docs/auth/userpass.mdx index f3d345b21a..e86086cd35 100644 --- a/website/content/api-docs/auth/userpass.mdx +++ b/website/content/api-docs/auth/userpass.mdx @@ -1,6 +1,5 @@ --- -layout: api -page_title: Userpass - Auth Methods - HTTP API +sidebar_label: Username and Password description: |- This is the API documentation for the OpenBao username and password auth method. @@ -10,7 +9,7 @@ description: |- This is the API documentation for the OpenBao Username & Password auth method. For general information about the usage and operation of the Username and Password method, please -see the [OpenBao Userpass method documentation](/vault/docs/auth/userpass). +see the [OpenBao Userpass method documentation](/docs/auth/userpass). This documentation assumes the Username & Password method is mounted at the `/auth/userpass` path in OpenBao. Since it is possible to enable auth methods at any location, diff --git a/website/content/api-docs/index.mdx b/website/content/api-docs/index.mdx index d4a8b21fc0..6102518dca 100644 --- a/website/content/api-docs/index.mdx +++ b/website/content/api-docs/index.mdx @@ -1,7 +1,6 @@ --- -layout: api -page_title: HTTP API description: OpenBao has an HTTP API that can be used to control every aspect of OpenBao. +displayed_sidebar: api --- # HTTP API @@ -14,13 +13,17 @@ All API routes are prefixed with `/v1/`. This documentation is only for the v1 API, which is currently the only version. -~> **Backwards compatibility:** At the current version, OpenBao does not yet +:::warning + +**Backwards compatibility:** At the current version, OpenBao does not yet promise backwards compatibility even with the v1 prefix. We'll remove this warning when this policy changes. At this point in time the core API (that is, `sys/` routes) change very infrequently, but various secrets engines/auth methods/etc. sometimes have minor changes to accommodate new features as they're developed. +::: + ## Transport The API is expected to be accessed over a TLS connection at all times, with a @@ -36,7 +39,7 @@ either the `X-Vault-Token` HTTP Header or as `Authorization` HTTP Header using the `Bearer ` scheme. Otherwise, a client token can be retrieved using an [authentication -engine](/vault/docs/auth). +engine](/docs/auth). Each auth method has one or more unauthenticated login endpoints. These endpoints can be reached without any authentication, and are used for @@ -58,8 +61,8 @@ Typically the request data, body and response data to and from OpenBao is in JSO OpenBao sets the `Content-Type` header appropriately with its response and does not require it from the clients request. -The demonstration below uses the [`KVv1` secrets engine](/vault/api-docs/secret/kv/kv-v1), which is a -simple Key/Value store. Please read [the API documentation of KV secret engines](/vault/api-docs/secret/kv) +The demonstration below uses the [`KVv1` secrets engine](/api-docs/secret/kv/kv-v1), which is a +simple Key/Value store. Please read [the API documentation of KV secret engines](/api-docs/secret/kv) for details of `KVv1` compared to `KVv2` and how they differ in their URI paths as well as the features available in version 2 of the KV secrets engine. @@ -132,7 +135,7 @@ discover whether an operation is actually a create or update operation based on the data already stored within OpenBao. This makes permission management via ACLs more flexible. -A [KVv2 example](/vault/api-docs/secret/kv/kv-v2#sample-request-3) for the engine path of `secret` requires that URI is +A [KVv2 example](/api-docs/secret/kv/kv-v2#sample-request-3) for the engine path of `secret` requires that URI is appended with ***`data/`*** prior to the secret name (`baz`) such as: ```shell-session @@ -173,7 +176,7 @@ methods, etc. then append `?help=1` to any URL. If you have valid permission to access the path, then the help text will be returned as a markdown-formatted block in the `help` attribute of the response. -Additionally, with the [OpenAPI generation](/vault/api-docs/system/internal-specs-openapi) in OpenBao, you will get back a small +Additionally, with the [OpenAPI generation](/api-docs/system/internal-specs-openapi) in OpenBao, you will get back a small OpenAPI document in the `openapi` attribute. This document is relevant for the path you're looking up and any paths under it - also note paths in the OpenAPI document are relative to the initial path queried. @@ -246,11 +249,15 @@ The following HTTP status codes are used throughout the API. OpenBao tries to adhere to these whenever possible, but in case it doesn't -- then feel free to [raise a bug](https://github.com/openbao/openbao/issues) for our attention! -~> _Note_: Applications should be prepared to accept both `200` and `204` as +:::warning + +_Note_: Applications should be prepared to accept both `200` and `204` as success. `204` is simply an indication that there is no response body to parse, but API endpoints that indicate that they return a `204` may return a `200` if warnings are generated during the operation. +::: + - `200` - Success with data. - `204` - Success, no data returned. - `400` - Invalid request, missing or invalid data. @@ -278,4 +285,4 @@ A maximum request size of 32MB is imposed to prevent a denial of service attack with arbitrarily large requests; this can be tuned per `listener` block in OpenBao's server configuration file. -[proxy]: /vault/docs/agent-and-proxy/proxy#listener-stanza +[proxy]: /docs/agent-and-proxy/proxy#listener-stanza diff --git a/website/content/api-docs/libraries.mdx b/website/content/api-docs/libraries.mdx index 5581eb073f..e075d4f05e 100644 --- a/website/content/api-docs/libraries.mdx +++ b/website/content/api-docs/libraries.mdx @@ -1,6 +1,5 @@ --- -layout: api -page_title: 'HTTP API: Libraries' +sidebar_label: Client Libraries description: >- List of official and community contributed libraries for interacting with the OpenBao HTTP API. @@ -11,13 +10,17 @@ description: >- The programming libraries listed on this page can be used to consume the API more conveniently. Some are officially maintained while others are provided by the community. -For a step-by-step walkthrough on using these client libraries, see the [developer quickstart](/vault/docs/get-started/developer-qs). +For a step-by-step walkthrough on using these client libraries, see the [developer quickstart](/docs/get-started/developer-qs). -~> **Note**: OpenBao intends to remain API compatible with HashiCorp Vault. This +:::warning + +**Note**: OpenBao intends to remain API compatible with HashiCorp Vault. This means that most of the existing [libraries for Vault](https://developer.hashicorp.com/vault/api-docs/libraries) should also work with OpenBao. +::: + ## Official These libraries are officially maintained by OpenBao. diff --git a/website/content/api-docs/relatedtools.mdx b/website/content/api-docs/relatedtools.mdx index 5ed6fcbfc2..4853d8eb03 100644 --- a/website/content/api-docs/relatedtools.mdx +++ b/website/content/api-docs/relatedtools.mdx @@ -1,17 +1,19 @@ --- -layout: api -page_title: Related Tools description: Short list of third-party tools that work with or are related to OpenBao. --- # Related tools -~> **Note**: OpenBao intends to remain API compatible with HashiCorp Vault. This +:::warning + +**Note**: OpenBao intends to remain API compatible with HashiCorp Vault. This means that most of the existing [tooling for Vault](https://developer.hashicorp.com/vault/api-docs/relatedtools) should also work with OpenBao. -- [OpenBao Agent](/vault/docs/agent-and-proxy/agent) can render OpenBao secrets either to files or directly into a child process as environment variables using `consul-template` templating syntax -- [OpenBao Proxy](/vault/docs/agent-and-proxy/proxy) acts as an API Proxy for OpenBao, and can optionally allow or force interacting clients to use its automatically authenticated token +::: + +- [OpenBao Agent](/docs/agent-and-proxy/agent) can render OpenBao secrets either to files or directly into a child process as environment variables using `consul-template` templating syntax +- [OpenBao Proxy](/docs/agent-and-proxy/proxy) acts as an API Proxy for OpenBao, and can optionally allow or force interacting clients to use its automatically authenticated token Want to add your own project, or one that you use? Additions are welcome via [pull requests](https://github.com/openbao/openbao/blob/main/website/content/api-docs/relatedtools.mdx). diff --git a/website/content/api-docs/secret/cubbyhole.mdx b/website/content/api-docs/secret/cubbyhole.mdx index d7a93785b7..5e58ad9e73 100644 --- a/website/content/api-docs/secret/cubbyhole.mdx +++ b/website/content/api-docs/secret/cubbyhole.mdx @@ -1,6 +1,5 @@ --- -layout: api -page_title: Cubbyhole - Secrets Engines - HTTP API +sidebar_label: Cubbyhole description: This is the API documentation for the OpenBao Cubbyhole secrets engine. --- @@ -9,7 +8,7 @@ description: This is the API documentation for the OpenBao Cubbyhole secrets eng This is the API documentation for the OpenBao Cubbyhole secrets engine. For general information about the usage and operation of the Cubbyhole secrets engine, please see the -[OpenBao Cubbyhole documentation](/vault/docs/secrets/cubbyhole). +[OpenBao Cubbyhole documentation](/docs/secrets/cubbyhole). This documentation assumes the Cubbyhole secrets engine is enabled at the `/cubbyhole` path in OpenBao. Since it is possible to enable secrets engines at diff --git a/website/content/api-docs/secret/databases/cassandra.mdx b/website/content/api-docs/secret/databases/cassandra.mdx index 77f90204ca..cf038a8086 100644 --- a/website/content/api-docs/secret/databases/cassandra.mdx +++ b/website/content/api-docs/secret/databases/cassandra.mdx @@ -1,6 +1,5 @@ --- -layout: api -page_title: Cassandra - Database - Secrets Engines - HTTP API +sidebar_label: Cassandra description: >- The Cassandra plugin for OpenBao's database secrets engine generates database credentials to access Cassandra servers. @@ -8,7 +7,15 @@ description: >- # Cassandra database plugin HTTP API -@include 'x509-sha1-deprecation.mdx' +:::warning + +**Note**: This engine can use external X.509 certificates as part of TLS or signature validation. + Verifying signatures against X.509 certificates that use SHA-1 is deprecated and is no longer + usable without a workaround. See the + [deprecation FAQ](/docs/deprecation/faq#q-what-is-the-impact-of-removing-support-for-x-509-certificates-with-signatures-that-use-sha-1) + for more information. + +::: The Cassandra database plugin is one of the supported plugins for the database secrets engine. This plugin generates database credentials dynamically based on @@ -17,7 +24,7 @@ configured roles for the Cassandra database. ## Configure connection In addition to the parameters defined by the [Database -Secrets Engine](/vault/api-docs/secret/databases#configure-connection), this plugin +Secrets Engine](/api-docs/secret/databases#configure-connection), this plugin has a number of parameters to further configure a connection. | Method | Path | @@ -55,7 +62,7 @@ has a number of parameters to further configure a connection. private key; a certificate, private key, and issuing CA certificate; or just a CA certificate. The value in this field must be an encoded JSON object. For convenience format is the same as the output of the `issue` command from the `pki` secrets engine; see - [the pki documentation](/vault/docs/secrets/pki). Only one of `pem_bundle` or `pem_json` can be specified. + [the pki documentation](/docs/secrets/pki). Only one of `pem_bundle` or `pem_json` can be specified.
pem_json example @@ -97,7 +104,7 @@ openbao write database/config/cassandra-example <...other fields> pem_json=@/pat definition](https://github.com/gocql/gocql/blob/master/frame.go#L188) for valid options. -- `username_template` `(string)` - [Template](/vault/docs/concepts/username-templating) describing how +- `username_template` `(string)` - [Template](/docs/concepts/username-templating) describing how dynamic usernames are generated.
@@ -173,7 +180,7 @@ $ curl \ Statements are configured during role creation and are used by the plugin to determine what is sent to the database on user creation, renewing, and revocation. For more information on configuring roles see the [Role -API](/vault/api-docs/secret/databases#create-role) in the database secrets engine docs. +API](/api-docs/secret/databases#create-role) in the database secrets engine docs. ### Parameters diff --git a/website/content/api-docs/secret/databases/index.mdx b/website/content/api-docs/secret/databases/index.mdx index 02587d2788..a970db9655 100644 --- a/website/content/api-docs/secret/databases/index.mdx +++ b/website/content/api-docs/secret/databases/index.mdx @@ -1,6 +1,5 @@ --- -layout: api -page_title: Database - Secrets Engines - HTTP API +sidebar_label: Overview description: Top page for database secrets engine information --- @@ -9,7 +8,7 @@ description: Top page for database secrets engine information This is the API documentation for the OpenBao Database secrets engine. For general information about the usage and operation of the database secrets engine, please see the -[OpenBao database secrets engine documentation](/vault/docs/secrets/databases). +[OpenBao database secrets engine documentation](/docs/secrets/databases). This documentation assumes the database secrets engine is enabled at the `/database` path in OpenBao. Since it is possible to enable secrets engines at any @@ -23,7 +22,11 @@ plugin has additional, database plugin specific, parameters for this endpoint. Please read the HTTP API for the plugin you'd wish to configure to see the full list of additional parameters. -~> This endpoint distinguishes between `create` and `update` ACL capabilities. +:::warning + +This endpoint distinguishes between `create` and `update` ACL capabilities. + +::: | Method | Path | | :----- | :----------------------- | @@ -51,11 +54,13 @@ list of additional parameters. information on support and formatting for this parameter. - `password_policy` `(string: "")` - The name of the - [password policy](/vault/docs/concepts/password-policies) to use when generating passwords + [password policy](/docs/concepts/password-policies) to use when generating passwords for this database. If not specified, this will use a default policy defined as: 20 characters with at least 1 uppercase, 1 lowercase, 1 number, and 1 dash character. -~> We highly recommended that you use an OpenBao-specific user rather than the admin user +:::warning + +We highly recommended that you use an OpenBao-specific user rather than the admin user in your database when configuring the plugin. This user will be used to create/update/delete users within the database so it will need to have the appropriate permissions to do so. If the plugin supports @@ -63,6 +68,8 @@ permissions to do so. If the plugin supports you perform that action after configuring the plugin. This will change the password of the user configured in this step. The new password will **not** be viewable by users. +::: + ### Common fields There are several common fields that you will see across many of the database plugins. @@ -90,7 +97,7 @@ are supported and any additional details about them. - `disable_escaping` `(boolean: false)` - Determines whether special characters in the username and password fields will be escaped. Useful for alternate connection string formats like ADO. More information regarding this parameter can be found on the - [databases secrets engine docs.](/vault/docs/secrets/databases#disable-character-escaping) + [databases secrets engine docs.](/docs/secrets/databases#disable-character-escaping) Defaults to `false`. ### Sample payload @@ -260,9 +267,13 @@ password. | :----- | :---------------------------- | | `POST` | `/database/rotate-root/:name` | -!> **Use caution:** the root user's password will not be accessible once rotated so it is highly +:::danger + +**Use caution:** the root user's password will not be accessible once rotated so it is highly recommended that you create a user for OpenBao to utilize rather than using the actual root user. +::: + ### Parameters - `name` `(string: )` – Specifies the name of the connection to rotate. @@ -281,7 +292,11 @@ $ curl \ This endpoint creates or updates a role definition. -~> This endpoint distinguishes between `create` and `update` ACL capabilities. +:::warning + +This endpoint distinguishes between `create` and `update` ACL capabilities. + +::: | Method | Path | | :----- | :---------------------- | @@ -301,7 +316,7 @@ This endpoint creates or updates a role definition. - `max_ttl` `(string/int: 0)` - Specifies the maximum TTL for the leases associated with this role. Accepts time suffixed strings (`1h`) or an integer - number of seconds. Defaults to `sys/mounts`'s default TTL time; this value is allowed to be less than the mount max TTL (or, if not set, the system max TTL), but it is not allowed to be longer. See also [The TTL General Case](/vault/docs/concepts/tokens#the-general-case). + number of seconds. Defaults to `sys/mounts`'s default TTL time; this value is allowed to be less than the mount max TTL (or, if not set, the system max TTL), but it is not allowed to be longer. See also [The TTL General Case](/docs/concepts/tokens#the-general-case). - `creation_statements` `(list: )` – Specifies the database statements executed to create and configure a user. See the plugin's API page @@ -481,11 +496,19 @@ This endpoint creates or updates a static role definition. Static Roles are a 1-to-1 mapping of an OpenBao Role to a user in a database which are automatically rotated based on the configured `rotation_period`. -~> This endpoint distinguishes between `create` and `update` ACL capabilities. +:::warning + +This endpoint distinguishes between `create` and `update` ACL capabilities. -~> OpenBao will rotate the password when creating a static role. OpenBao must do +::: + +:::warning + +OpenBao will rotate the password when creating a static role. OpenBao must do this in order to know the password. +::: + | Method | Path | | :----- | :----------------------------- | | `POST` | `/database/static-roles/:name` | diff --git a/website/content/api-docs/secret/databases/influxdb.mdx b/website/content/api-docs/secret/databases/influxdb.mdx index 9fd52d58ac..5894067e73 100644 --- a/website/content/api-docs/secret/databases/influxdb.mdx +++ b/website/content/api-docs/secret/databases/influxdb.mdx @@ -1,6 +1,5 @@ --- -layout: api -page_title: Influxdb - Database - Secrets Engines - HTTP API +sidebar_label: InfluxDB description: >- The Influxdb plugin for OpenBao's database secrets engine generates database credentials to access Influxdb servers. @@ -8,7 +7,15 @@ description: >- # Influxdb database plugin HTTP API -@include 'x509-sha1-deprecation.mdx' +:::warning + +**Note**: This engine can use external X.509 certificates as part of TLS or signature validation. + Verifying signatures against X.509 certificates that use SHA-1 is deprecated and is no longer + usable without a workaround. See the + [deprecation FAQ](/docs/deprecation/faq#q-what-is-the-impact-of-removing-support-for-x-509-certificates-with-signatures-that-use-sha-1) + for more information. + +::: The Influxdb database plugin is one of the supported plugins for the database secrets engine. This plugin generates database credentials dynamically based on @@ -17,7 +24,7 @@ configured roles for the Influxdb database. ## Configure connection In addition to the parameters defined by the [Database -Secrets Engine](/vault/api-docs/secret/databases#configure-connection), this plugin +Secrets Engine](/api-docs/secret/databases#configure-connection), this plugin has a number of parameters to further configure a connection. | Method | Path | @@ -52,11 +59,11 @@ has a number of parameters to further configure a connection. private key; a certificate, private key, and issuing CA certificate; or just a CA certificate. For convenience format is the same as the output of the `issue` command from the `pki` secrets engine; see - [the pki documentation](/vault/docs/secrets/pki). + [the pki documentation](/docs/secrets/pki). - `connect_timeout` `(string: "5s")` – Specifies the connection timeout to use. -- `username_template` `(string)` - [Template](/vault/docs/concepts/username-templating) describing how +- `username_template` `(string)` - [Template](/docs/concepts/username-templating) describing how dynamic usernames are generated. TLS works as follows: @@ -107,7 +114,7 @@ $ curl \ Statements are configured during role creation and are used by the plugin to determine what is sent to the database on user creation, renewing, and revocation. For more information on configuring roles see the [Role -API](/vault/api-docs/secret/databases#create-role) in the database secrets engine docs. +API](/api-docs/secret/databases#create-role) in the database secrets engine docs. ### Parameters diff --git a/website/content/api-docs/secret/databases/mysql-maria.mdx b/website/content/api-docs/secret/databases/mysql-maria.mdx index 0cec5ec633..477c5e2d88 100644 --- a/website/content/api-docs/secret/databases/mysql-maria.mdx +++ b/website/content/api-docs/secret/databases/mysql-maria.mdx @@ -1,6 +1,5 @@ --- -layout: api -page_title: MySQL/MariaDB - Database - Secrets Engines - HTTP API +sidebar_label: MySQL/MariaDB description: >- The MySQL/MariaDB plugin for OpenBao's database secrets engine generates database credentials to access MySQL and MariaDB servers. @@ -8,7 +7,15 @@ description: >- # MySQL/MariaDB database plugin HTTP API -@include 'x509-sha1-deprecation.mdx' +:::warning + +**Note**: This engine can use external X.509 certificates as part of TLS or signature validation. + Verifying signatures against X.509 certificates that use SHA-1 is deprecated and is no longer + usable without a workaround. See the + [deprecation FAQ](/docs/deprecation/faq#q-what-is-the-impact-of-removing-support-for-x-509-certificates-with-signatures-that-use-sha-1) + for more information. + +::: The MySQL database plugin is one of the supported plugins for the database secrets engine. This plugin generates database credentials dynamically based on @@ -17,7 +24,7 @@ configured roles for the MySQL database. ## Configure connection In addition to the parameters defined by the [Database -Backend](/vault/api-docs/secret/databases#configure-connection), this plugin +Backend](/api-docs/secret/databases#configure-connection), this plugin has a number of parameters to further configure a connection. | Method | Path | @@ -58,11 +65,11 @@ has a number of parameters to further configure a connection. - `tls_skip_verify` `(boolean: false)` - When set to true, disables the server certificate verification. Setting this to true is not recommended for production. -- `username_template` `(string)` - [Template](/vault/docs/concepts/username-templating) describing how +- `username_template` `(string)` - [Template](/docs/concepts/username-templating) describing how dynamic usernames are generated. - `disable_escaping` `(boolean: false)` - Turns off the escaping of special characters inside of the username - and password fields. See the [databases secrets engine docs](/vault/docs/secrets/databases#disable-character-escaping) + and password fields. See the [databases secrets engine docs](/docs/secrets/databases#disable-character-escaping) for more information. Defaults to `false`. **Default Username Templates:** @@ -150,7 +157,7 @@ $ curl \ Statements are configured during role creation and are used by the plugin to determine what is sent to the database on user creation, renewing, and revocation. For more information on configuring roles see the [Role -API](/vault/api-docs/secret/databases#create-role) in the database secrets engine docs. +API](/api-docs/secret/databases#create-role) in the database secrets engine docs. ### Parameters diff --git a/website/content/api-docs/secret/databases/postgresql.mdx b/website/content/api-docs/secret/databases/postgresql.mdx index 747c850603..45bc481801 100644 --- a/website/content/api-docs/secret/databases/postgresql.mdx +++ b/website/content/api-docs/secret/databases/postgresql.mdx @@ -1,6 +1,5 @@ --- -layout: api -page_title: PostgreSQL - Database - Secrets Engines - HTTP API +sidebar_label: PostgreSQL description: >- The PostgreSQL plugin for OpenBao's database secrets engine generates database credentials to access PostgreSQL servers. @@ -15,7 +14,7 @@ configured roles for the PostgreSQL database. ## Configure connection In addition to the parameters defined by the [Database -Backend](/vault/api-docs/secret/databases#configure-connection), this plugin +Backend](/api-docs/secret/databases#configure-connection), this plugin has a number of parameters to further configure a connection. | Method | Path | @@ -45,17 +44,17 @@ has a number of parameters to further configure a connection. `max_open_connections` it will be reduced to be equal. - `max_connection_lifetime` `(string: "0s")` - Specifies the maximum amount of - time a connection may be reused. If <= `0s`, connections are reused forever. + time a connection may be reused. If \<= `0s`, connections are reused forever. - `username` `(string: "")` - The root credential username used in the connection URL. - `password` `(string: "")` - The root credential password used in the connection URL. -- `username_template` `(string)` - [Template](/vault/docs/concepts/username-templating) describing how +- `username_template` `(string)` - [Template](/docs/concepts/username-templating) describing how dynamic usernames are generated. - `disable_escaping` `(boolean: false)` - Turns off the escaping of special characters inside of the username - and password fields. See the [databases secrets engine docs](/vault/docs/secrets/databases#disable-character-escaping) + and password fields. See the [databases secrets engine docs](/docs/secrets/databases#disable-character-escaping) for more information. Defaults to `false`. - `password_authentication` `(string: "password")` - When set to "scram-sha-256", passwords will be hashed by OpenBao and stored as-is by PostgreSQL. @@ -156,7 +155,7 @@ for more information. Below are two small examples. Statements are configured during role creation and are used by the plugin to determine what is sent to the database on user creation, renewing, and revocation. For more information on configuring roles see the [Role -API](/vault/api-docs/secret/databases#create-role) in the database secrets engine docs. +API](/api-docs/secret/databases#create-role) in the database secrets engine docs. ### Parameters diff --git a/website/content/api-docs/secret/databases/redis.mdx b/website/content/api-docs/secret/databases/redis.mdx index 87a95fe6f7..b30deb084c 100644 --- a/website/content/api-docs/secret/databases/redis.mdx +++ b/website/content/api-docs/secret/databases/redis.mdx @@ -1,6 +1,5 @@ --- -layout: api -page_title: Redis - Database - Secrets Engines - HTTP API +sidebar_label: Redis description: >- The Redis plugin for OpenBao's database secrets engine generates [ACL credentials](https://redis.io/docs/manual/security/acl/) to access Redis servers. @@ -15,7 +14,7 @@ configured roles for the Redis database. ## Configure connection In addition to the parameters defined by the [Database -Secrets Engine](/vault/api-docs/secret/databases#configure-connection), this plugin +Secrets Engine](/api-docs/secret/databases#configure-connection), this plugin has a number of parameters to further configure a connection. | Method | Path | @@ -64,7 +63,7 @@ $ curl \ Statements are configured during role creation and are used by the plugin to determine what is sent to the database on user creation, renewing, and revocation. For more information on configuring roles see the [Role -API](/vault/api-docs/secret/databases#create-role) in the database secrets engine docs. +API](/api-docs/secret/databases#create-role) in the database secrets engine docs. ### Parameters diff --git a/website/content/api-docs/secret/identity/entity-alias.mdx b/website/content/api-docs/secret/identity/entity-alias.mdx index 13d71355e4..379c25903f 100644 --- a/website/content/api-docs/secret/identity/entity-alias.mdx +++ b/website/content/api-docs/secret/identity/entity-alias.mdx @@ -1,24 +1,31 @@ --- -layout: api -page_title: 'Identity Secret Backend: Entity Alias - HTTP API' +sidebar_label: Entity Alias description: >- This is the API documentation for managing entity aliases in the identity store. --- -~> **NOTE:** Be careful in granting permissions to non-readonly identity endpoints. +:::warning + +**NOTE:** Be careful in granting permissions to non-readonly identity endpoints. If a user can modify an entity, they can grant it additional privileges through policies. If a user can modify an alias they can login with, they can bind it to an entity with higher privileges. +::: + ## Create an entity alias -~> **IMPORTANT NOTE:** Prior to creating any alias it is important to consider the cardinality of the alias' name, +:::warning + +**IMPORTANT NOTE:** Prior to creating any alias it is important to consider the cardinality of the alias' name, since there are potential security issues to be aware of. The main one revolves around alias reuse. It is possible for multiple authenticated entities to be bound to the same alias, and therefore gain access to all of its privileges. It is recommended, whenever possible, to create a unique alias for each entity. This is especially true in the case of machine generated entities. +::: + This endpoint creates a new alias for an entity. | Method | Path | diff --git a/website/content/api-docs/secret/identity/entity.mdx b/website/content/api-docs/secret/identity/entity.mdx index 714b01fa66..3f7c2a0d27 100644 --- a/website/content/api-docs/secret/identity/entity.mdx +++ b/website/content/api-docs/secret/identity/entity.mdx @@ -1,6 +1,5 @@ --- -layout: api -page_title: 'Identity Secret Backend: Entity - HTTP API' +sidebar_label: Entity description: This is the API documentation for managing entities in the identity store. --- @@ -398,7 +397,7 @@ $ curl \ This endpoint merges many entities into one entity. Additionally, all groups associated with `from_entity_ids` are merged with those of `to_entity_id`. Note that if these entities contain aliases sharing the same mount accessor, the merge will fail unless `conflicting_alias_ids_to_keep` is present, and entities must be merged one at a time. This is because each entity can only have one alias with each mount accessor - for more -information, see the [identity concepts page](/vault/docs/concepts/identity). +information, see the [identity concepts page](/docs/concepts/identity). | Method | Path | | :----- | :----------------------- | diff --git a/website/content/api-docs/secret/identity/group-alias.mdx b/website/content/api-docs/secret/identity/group-alias.mdx index b4592eef47..1010ba3986 100644 --- a/website/content/api-docs/secret/identity/group-alias.mdx +++ b/website/content/api-docs/secret/identity/group-alias.mdx @@ -1,6 +1,5 @@ --- -layout: api -page_title: 'Identity Secret Backend: Group Alias - HTTP API' +sidebar_label: Group Alias description: >- This is the API documentation for managing the group aliases in the identity store. diff --git a/website/content/api-docs/secret/identity/group.mdx b/website/content/api-docs/secret/identity/group.mdx index abcd419059..b0d7e2436e 100644 --- a/website/content/api-docs/secret/identity/group.mdx +++ b/website/content/api-docs/secret/identity/group.mdx @@ -1,13 +1,16 @@ --- -layout: api -page_title: 'Identity Secret Backend: Group - HTTP API' +sidebar_label: Group description: This is the API documentation for managing groups in the identity store. --- -~> **NOTE:** Be careful in granting permissions to non-readonly identity group +:::warning + +**NOTE:** Be careful in granting permissions to non-readonly identity group endpoints. If a user can modify group membership, they can add their entity to a group with higher privileges. +::: + ## Create a group This endpoint creates or updates a Group. diff --git a/website/content/api-docs/secret/identity/index.mdx b/website/content/api-docs/secret/identity/index.mdx index 58b6a3c06d..f81433bb94 100644 --- a/website/content/api-docs/secret/identity/index.mdx +++ b/website/content/api-docs/secret/identity/index.mdx @@ -1,6 +1,5 @@ --- -layout: api -page_title: Identity - Secrets Engines - HTTP API +sidebar_label: Overview description: This is the API documentation for the OpenBao Identity secrets engine. --- @@ -8,15 +7,15 @@ description: This is the API documentation for the OpenBao Identity secrets engi This is the API documentation for the OpenBao Identity secrets engine. For general information about the usage and operation of the Identity secrets engine, please -see the [OpenBao Identity documentation](/vault/docs/secrets/identity). +see the [OpenBao Identity documentation](/docs/secrets/identity). ## API sections -- [Entity](/vault/api-docs/secret/identity/entity) -- [Entity Alias](/vault/api-docs/secret/identity/entity-alias) -- [Group](/vault/api-docs/secret/identity/group) -- [Group Alias](/vault/api-docs/secret/identity/group-alias) -- [Identity Tokens](/vault/api-docs/secret/identity/tokens) -- [Lookup](/vault/api-docs/secret/identity/lookup) -- [OIDC Provider](/vault/api-docs/secret/identity/oidc-provider) -- [MFA](/vault/api-docs/secret/identity/mfa) +- [Entity](/api-docs/secret/identity/entity) +- [Entity Alias](/api-docs/secret/identity/entity-alias) +- [Group](/api-docs/secret/identity/group) +- [Group Alias](/api-docs/secret/identity/group-alias) +- [Identity Tokens](/api-docs/secret/identity/tokens) +- [Lookup](/api-docs/secret/identity/lookup) +- [OIDC Provider](/api-docs/secret/identity/oidc-provider) +- [MFA](/api-docs/secret/identity/mfa) diff --git a/website/content/api-docs/secret/identity/lookup.mdx b/website/content/api-docs/secret/identity/lookup.mdx index 5bcb00efe8..04d6b07488 100644 --- a/website/content/api-docs/secret/identity/lookup.mdx +++ b/website/content/api-docs/secret/identity/lookup.mdx @@ -1,6 +1,5 @@ --- -layout: api -page_title: 'Identity Secret Backend: Lookup - HTTP API' +sidebar_label: Lookup description: |- This is the API documentation for entity and group lookups from identity store. diff --git a/website/content/api-docs/secret/identity/mfa/duo.mdx b/website/content/api-docs/secret/identity/mfa/duo.mdx index eb8cfd2912..7f04708bf2 100644 --- a/website/content/api-docs/secret/identity/mfa/duo.mdx +++ b/website/content/api-docs/secret/identity/mfa/duo.mdx @@ -1,6 +1,5 @@ --- -layout: api -page_title: /identity/mfa/method/duo - HTTP API +sidebar_label: Duo description: >- The '/identity/mfa/method/duo' endpoint focuses on managing Duo MFA behaviors in OpenBao. --- @@ -103,7 +102,7 @@ $ curl \ ## Delete Duo MFA method This endpoint deletes a Duo MFA method. MFA methods can only be deleted if they're not currently in use -by a [login enforcement](/vault/api-docs/secret/identity/mfa/login-enforcement). +by a [login enforcement](/api-docs/secret/identity/mfa/login-enforcement). | Method | Path | | :------- | :----------------------------- | diff --git a/website/content/api-docs/secret/identity/mfa/index.mdx b/website/content/api-docs/secret/identity/mfa/index.mdx index f6a0a90793..7f1ebcc760 100644 --- a/website/content/api-docs/secret/identity/mfa/index.mdx +++ b/website/content/api-docs/secret/identity/mfa/index.mdx @@ -1,6 +1,5 @@ --- -layout: api -page_title: /identity/mfa - HTTP API +sidebar_label: Overview description: >- The '/identity/mfa' endpoint focuses on managing login MFA behaviors in OpenBao. --- @@ -9,15 +8,15 @@ description: >- ## Supported MFA types. -- [TOTP](/vault/api-docs/secret/identity/mfa/totp) +- [TOTP](/api-docs/secret/identity/mfa/totp) -- [Okta](/vault/api-docs/secret/identity/mfa/okta) +- [Okta](/api-docs/secret/identity/mfa/okta) -- [Duo](/vault/api-docs/secret/identity/mfa/duo) +- [Duo](/api-docs/secret/identity/mfa/duo) -- [PingID](/vault/api-docs/secret/identity/mfa/pingid) +- [PingID](/api-docs/secret/identity/mfa/pingid) ## Other -- [Login Enforcement](/vault/api-docs/secret/identity/mfa/login-enforcement) -- [MFA Validate](/vault/api-docs/system/mfa/validate) +- [Login Enforcement](/api-docs/secret/identity/mfa/login-enforcement) +- [MFA Validate](/api-docs/system/mfa-validate) diff --git a/website/content/api-docs/secret/identity/mfa/login-enforcement.mdx b/website/content/api-docs/secret/identity/mfa/login-enforcement.mdx index 1885605e69..bd17af6a94 100644 --- a/website/content/api-docs/secret/identity/mfa/login-enforcement.mdx +++ b/website/content/api-docs/secret/identity/mfa/login-enforcement.mdx @@ -1,6 +1,5 @@ --- -layout: api -page_title: /identity/mfa/login-enforcement - HTTP API +sidebar_label: Login Enforcement description: >- The '/identity/mfa/login-enforcement' endpoint focuses on specifying which MFA methods should be used when logging in. diff --git a/website/content/api-docs/secret/identity/mfa/okta.mdx b/website/content/api-docs/secret/identity/mfa/okta.mdx index d93ec0a63c..f1dd1ae498 100644 --- a/website/content/api-docs/secret/identity/mfa/okta.mdx +++ b/website/content/api-docs/secret/identity/mfa/okta.mdx @@ -1,6 +1,5 @@ --- -layout: api -page_title: /identity/mfa/method/okta - HTTP API +sidebar_label: Okta description: >- The '/identity/mfa/method/okta' endpoint focuses on managing Okta MFA behaviors in OpenBao. --- @@ -97,7 +96,7 @@ $ curl \ ## Delete okta MFA method This endpoint deletes a Okta MFA method. The MFA methods can only be deleted if they're not currently in use -by a [login enforcement](/vault/api-docs/secret/identity/mfa/login-enforcement). +by a [login enforcement](/api-docs/secret/identity/mfa/login-enforcement). | Method | Path | | :------- | :------------------------------ | diff --git a/website/content/api-docs/secret/identity/mfa/pingid.mdx b/website/content/api-docs/secret/identity/mfa/pingid.mdx index 379f6acc39..f2c56df41d 100644 --- a/website/content/api-docs/secret/identity/mfa/pingid.mdx +++ b/website/content/api-docs/secret/identity/mfa/pingid.mdx @@ -1,6 +1,5 @@ --- -layout: api -page_title: /identity/mfa/method/pingid - HTTP API +sidebar_label: PingID description: >- The '/identity/mfa/method/pingid' endpoint focuses on managing PingID MFA behaviors in OpenBao. --- @@ -91,7 +90,7 @@ $ curl \ ## Delete PingID MFA method This endpoint deletes a PingID MFA method. MFA methods can only be deleted if they're not currently in use -by a [login enforcement](/vault/api-docs/secret/identity/mfa/login-enforcement). +by a [login enforcement](/api-docs/secret/identity/mfa/login-enforcement). | Method | Path | | :------- | :-------------------------------- | diff --git a/website/content/api-docs/secret/identity/mfa/totp.mdx b/website/content/api-docs/secret/identity/mfa/totp.mdx index 23e90d861d..793fc07070 100644 --- a/website/content/api-docs/secret/identity/mfa/totp.mdx +++ b/website/content/api-docs/secret/identity/mfa/totp.mdx @@ -1,6 +1,5 @@ --- -layout: api -page_title: /identity/mfa/method/totp - HTTP API +sidebar_label: TOTP description: >- The '/identity/mfa/method/totp' endpoint focuses on managing TOTP MFA behaviors in OpenBao. --- @@ -105,7 +104,7 @@ $ curl \ ## Delete TOTP MFA method This endpoint deletes a TOTP MFA method. MFA methods can only be deleted if they're not currently in use -by a [login enforcement](/vault/api-docs/secret/identity/mfa/login-enforcement). +by a [login enforcement](/api-docs/secret/identity/mfa/login-enforcement). | Method | Path | | :------- | :------------------------------ | diff --git a/website/content/api-docs/secret/identity/oidc-provider.mdx b/website/content/api-docs/secret/identity/oidc-provider.mdx index 999cdd10ca..d5ad5ccf21 100644 --- a/website/content/api-docs/secret/identity/oidc-provider.mdx +++ b/website/content/api-docs/secret/identity/oidc-provider.mdx @@ -1,6 +1,5 @@ --- -layout: api -page_title: 'OIDC Identity Provider' +sidebar_label: OIDC Provider description: >- This is the API documentation for configuring and managing OIDC providers with OpenBao. --- @@ -87,7 +86,7 @@ This endpoint returns a list of all OIDC providers. ### Query parameters - `allowed_client_id` `(string: )` – Filters the list of OIDC providers to those - that allow the given client ID in their set of [allowed_client_ids](/vault/api-docs/secret/identity/oidc-provider#allowed_client_ids). + that allow the given client ID in their set of [allowed_client_ids](/api-docs/secret/identity/oidc-provider#allowed_client_ids). ### Sample request @@ -152,7 +151,7 @@ This endpoint creates or updates a scope. - `name` `(string: )` – The name of the scope. This parameter is specified as part of the URL. The `openid` scope name is reserved. -- `template` `(string: )` - The [JSON template](/vault/docs/concepts/oidc-provider#scopes) +- `template` `(string: )` - The [JSON template](/docs/concepts/oidc-provider#scopes) string for the scope. This may be provided as escaped JSON or base64 encoded JSON. - `description` `(string: )` – A description of the scope. @@ -269,9 +268,9 @@ This endpoint creates or updates a client. - `name` `(string: )` – The name of the client. This parameter is specified as part of the URL. -- `key` `(string: "default")` – A reference to a [named key](/vault/api-docs/secret/identity/tokens#create-a-named-key) +- `key` `(string: "default")` – A reference to a [named key](/api-docs/secret/identity/tokens#create-a-named-key) resource. This key will be used to sign ID tokens for the client. This cannot be modified - after creation. If not supplied, defaults to the built-in [default key](/vault/docs/concepts/oidc-provider#keys). + after creation. If not supplied, defaults to the built-in [default key](/docs/concepts/oidc-provider#keys). - `redirect_uris` `([]string: )` - Redirection URI values used by the client. One of these values must exactly match the `redirect_uri` parameter value used in each [authentication request](https://openid.net/specs/openid-connect-core-1_0.html#AuthRequest). @@ -280,7 +279,7 @@ This endpoint creates or updates a client. the client. Client assignments limit the OpenBao entities and groups that are allowed to authenticate through the client. By default, no OpenBao entities are allowed. To allow all OpenBao entities to authenticate through the client, supply the built-in - [allow_all](/vault/docs/concepts/oidc-provider#assignments) assignment. + [allow_all](/docs/concepts/oidc-provider#assignments) assignment. - `client_type` `(string: "confidential")` – The [client type](https://datatracker.ietf.org/doc/html/rfc6749#section-2.1) based on its ability to maintain confidentiality of credentials. This cannot be modified @@ -300,11 +299,11 @@ This endpoint creates or updates a client. for the authorization code flow - `id_token_ttl` `(int or duration: "24h")` – The time-to-live for ID tokens obtained by the client. - Accepts [duration format strings](/vault/docs/concepts/duration-format). The value should be less than the `verification_ttl` + Accepts [duration format strings](/docs/concepts/duration-format). The value should be less than the `verification_ttl` on the key. - `access_token_ttl` `(int or duration: "24h")` – The time-to-live for access tokens obtained by the client. - Accepts [duration format strings](/vault/docs/concepts/duration-format). + Accepts [duration format strings](/docs/concepts/duration-format). ### Sample payload @@ -440,9 +439,9 @@ This endpoint creates or updates an assignment. - `name` `(string: )` – The name of the assignment. This parameter is specified as part of the URL. -- `entity_ids` `([]string: )` - A list of OpenBao [entity](/vault/docs/secrets/identity#entities-and-aliases) IDs. +- `entity_ids` `([]string: )` - A list of OpenBao [entity](/docs/secrets/identity#entities-and-aliases) IDs. -- `group_ids` `([]string: )` – A list of OpenBao [group](/vault/docs/secrets/identity#identity-groups) IDs. +- `group_ids` `([]string: )` – A list of OpenBao [group](/docs/secrets/identity#identity-groups) IDs. ### Sample payload @@ -575,7 +574,7 @@ $ curl \ { "issuer": "http://127.0.0.1:8200/v1/identity/oidc/provider/test-provider", "jwks_uri": "http://127.0.0.1:8200/v1/identity/oidc/provider/test-provider/.well-known/keys", - "authorization_endpoint": "http://127.0.0.1:8200/ui/vault/identity/oidc/provider/test-provider/authorize", + "authorization_endpoint": "http://127.0.0.1:8200/ui/identity/oidc/provider/test-provider/authorize", "token_endpoint": "http://127.0.0.1:8200/v1/identity/oidc/provider/test-provider/token", "userinfo_endpoint": "http://127.0.0.1:8200/v1/identity/oidc/provider/test-provider/userinfo", "request_parameter_supported": false, diff --git a/website/content/api-docs/secret/identity/tokens.mdx b/website/content/api-docs/secret/identity/tokens.mdx index 8d7bdb583b..4b08442a73 100644 --- a/website/content/api-docs/secret/identity/tokens.mdx +++ b/website/content/api-docs/secret/identity/tokens.mdx @@ -1,6 +1,5 @@ --- -layout: api -page_title: 'Identity Secret Backend: Identity Tokens - HTTP API' +sidebar_label: Identity Tokens description: >- This is the API documentation for configuring, acquiring, and validating openbao issued identity tokens. @@ -86,9 +85,9 @@ This endpoint creates or updates a named key which is used by a role to sign tok - `name` `(string)` – Name of the named key. -- `rotation_period` `(int or time string: "24h")` - How often to generate a new signing key. Uses [duration format strings](/vault/docs/concepts/duration-format). +- `rotation_period` `(int or time string: "24h")` - How often to generate a new signing key. Uses [duration format strings](/docs/concepts/duration-format). -- `verification_ttl` `(int or time string: "24h")` - Controls how long the public portion of a signing key will be available for verification after being rotated. Uses [duration format strings](/vault/docs/concepts/duration-format). +- `verification_ttl` `(int or time string: "24h")` - Controls how long the public portion of a signing key will be available for verification after being rotated. Uses [duration format strings](/docs/concepts/duration-format). - `allowed_client_ids` `(list: [])` - Array of role client ids allowed to use this key for signing. If empty, no roles are allowed. If "\*", all roles are allowed. @@ -244,7 +243,7 @@ Create or update a role. ID tokens are generated against a role and signed again - `client_id` `(string: )` - Optional client ID. A random ID will be generated if left unset. -- `ttl` `(int or time string: "24h")` - TTL of the tokens generated against the role. Uses [duration format strings](/vault/docs/concepts/duration-format). +- `ttl` `(int or time string: "24h")` - TTL of the tokens generated against the role. Uses [duration format strings](/docs/concepts/duration-format). ### Sample payload diff --git a/website/content/api-docs/secret/index.mdx b/website/content/api-docs/secret/index.mdx index efe63dc780..8b990c8cac 100644 --- a/website/content/api-docs/secret/index.mdx +++ b/website/content/api-docs/secret/index.mdx @@ -1,6 +1,5 @@ --- -layout: api -page_title: Secrets Engines - HTTP API +sidebar_label: Overview description: |- Each secrets engine publishes its own set of API paths and methods. These endpoints are documented in this section. diff --git a/website/content/api-docs/secret/kubernetes.mdx b/website/content/api-docs/secret/kubernetes.mdx index 0f136808ec..4e44720677 100644 --- a/website/content/api-docs/secret/kubernetes.mdx +++ b/website/content/api-docs/secret/kubernetes.mdx @@ -1,16 +1,23 @@ --- -layout: api -page_title: Kubernetes - Secrets Engines - HTTP API +sidebar_label: Kubernetes description: This is the API documentation for the OpenBao Kubernetes secrets engine. --- # Kubernetes secrets engine (API) -@include 'x509-sha1-deprecation.mdx' +:::warning + +**Note**: This engine can use external X.509 certificates as part of TLS or signature validation. + Verifying signatures against X.509 certificates that use SHA-1 is deprecated and is no longer + usable without a workaround. See the + [deprecation FAQ](/docs/deprecation/faq#q-what-is-the-impact-of-removing-support-for-x-509-certificates-with-signatures-that-use-sha-1) + for more information. + +::: This is the API documentation for the OpenBao Kubernetes secrets engine. To learn more about the usage and operation, see the -[Kubernetes secrets engine documentation](/vault/docs/secrets/kubernetes). +[Kubernetes secrets engine documentation](/docs/secrets/kubernetes). This documentation assumes the Kubernetes secrets engine is mounted at the `/kubernetes` path in OpenBao. Since it is possible to enable secrets engines at @@ -136,15 +143,15 @@ Only one of `service_account_name`, `kubernetes_role_name` or namespaces in which credentials can be generated. Accepts either a JSON or YAML object. The value should be of type [LabelSelector](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.24/#labelselector-v1-meta) - as illustrated in [Sample Payload 4](/vault/api-docs/secret/kubernetes#sample-payload-4) and - [Sample Payload 5](/vault/api-docs/secret/kubernetes#sample-payload-5) below. + as illustrated in [Sample Payload 4](/api-docs/secret/kubernetes#sample-payload-4) and + [Sample Payload 5](/api-docs/secret/kubernetes#sample-payload-5) below. If set with `allowed_kubernetes_namespaces`, the conditions are `OR`ed. - `token_max_ttl` `(string: "")` - The maximum TTL for generated Kubernetes tokens, specified in seconds or as a Go duration format string, e.g. `"1h"`. - If not set or set to 0, the [system default](/vault/docs/configuration#max_lease_ttl) will be used. + If not set or set to 0, the [system default](/docs/configuration#max_lease_ttl) will be used. - `token_default_ttl` `(string: "")` - The default TTL for generated Kubernetes tokens, specified in seconds or as a Go duration format string, e.g. `"1h"`. - If not set or set to 0, the [system default](/vault/docs/configuration#default_lease_ttl) will be used. + If not set or set to 0, the [system default](/docs/configuration#default_lease_ttl) will be used. - `token_default_audiences` `(string: "")` - The default intended audiences for generated Kubernetes tokens, specified by a comma separated string. e.g `"custom-audience-0,custom-audience-1"`. If not set or set to `""`, the Kubernetes cluster default for audiences of service account tokens will be used. @@ -167,10 +174,10 @@ Only one of `service_account_name`, `kubernetes_role_name` or [PolicyRule](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.23/#policyrule-v1-rbac-authorization-k8s-io) objects, as illustrated in the [Kubernetes RBAC documentation](https://kubernetes.io/docs/reference/access-authn-authz/rbac/) - and [Sample Payload 3](/vault/api-docs/secret/kubernetes#sample-payload-3) below. + and [Sample Payload 3](/api-docs/secret/kubernetes#sample-payload-3) below. - `name_template` `(string: "")` - The name template to use when generating service accounts, roles and role bindings. If unset, a default template is - used. See [username templating](/vault/docs/concepts/username-templating) + used. See [username templating](/docs/concepts/username-templating) for details on how to write a custom template. - `extra_annotations` `(map: nil)` - Additional annotations to apply to all generated Kubernetes objects. See the @@ -385,7 +392,7 @@ Generate a service account token. - `audiences` `(string: "")` - A comma separated string containing the intended audiences of the generated Kubernetes service account the token, e.g. `"custom-audience-0,custom-audience-1"`. If not set or set to `""`, - the [token_default_audiences](/vault/api-docs/secret/kubernetes#token_default_audiences) will be used. + the [token_default_audiences](/api-docs/secret/kubernetes#token_default_audiences) will be used. ### Sample payload diff --git a/website/content/api-docs/secret/kv/index.mdx b/website/content/api-docs/secret/kv/index.mdx index 169e2d7048..3b922c3769 100644 --- a/website/content/api-docs/secret/kv/index.mdx +++ b/website/content/api-docs/secret/kv/index.mdx @@ -1,6 +1,5 @@ --- -layout: api -page_title: KV - Secrets Engines - HTTP API +sidebar_label: Overview description: This is the API documentation for the OpenBao KV secrets engine. --- @@ -8,8 +7,8 @@ description: This is the API documentation for the OpenBao KV secrets engine. This backend can be run in one of two versions. Each of which have a distinct API. Choose the version below you are running. For more information on the KV secrets -engine see the [OpenBao kv documentation](/vault/docs/secrets/kv). +engine see the [OpenBao kv documentation](/docs/secrets/kv). -- [KV Version 1 API](/vault/api-docs/secret/kv/kv-v1) +- [KV Version 1 API](/api-docs/secret/kv/kv-v1) -- [KV Version 2 API](/vault/api-docs/secret/kv/kv-v2) +- [KV Version 2 API](/api-docs/secret/kv/kv-v2) diff --git a/website/content/api-docs/secret/kv/kv-v1.mdx b/website/content/api-docs/secret/kv/kv-v1.mdx index 0d85441f61..efebc3b4e4 100644 --- a/website/content/api-docs/secret/kv/kv-v1.mdx +++ b/website/content/api-docs/secret/kv/kv-v1.mdx @@ -1,6 +1,5 @@ --- -layout: api -page_title: KV - Secrets Engines - HTTP API +sidebar_label: K/V Version 1 description: This is the API documentation for the OpenBao KV secrets engine, version 1. --- @@ -8,14 +7,18 @@ description: This is the API documentation for the OpenBao KV secrets engine, ve This is the API documentation for the OpenBao KV secrets engine. For general information about the usage and operation of the version 1 KV secrets engine, please -see the [OpenBao KV documentation](/vault/docs/secrets/kv/kv-v1). For information +see the [OpenBao KV documentation](/docs/secrets/kv/kv-v1). For information about the differences between KV version 1 and version 2, please [see the KV overview -documentation](/vault/docs/secrets/kv). +documentation](/docs/secrets/kv). -~> Note: This documentation assumes the kv secrets engine is enabled at the +:::warning + +Note: This documentation assumes the kv secrets engine is enabled at the `/secret` path in OpenBao. Since it is possible to enable secrets engines at any location, please update your API calls accordingly. +::: + ## Read secret This endpoint retrieves the secret at the specified location. @@ -55,7 +58,7 @@ $ curl \ _Note_: the `lease_duration` field, which will be populated if a "ttl" field was included in the data, is advisory. No lease is created. This is a way for writers to indicate how often a given value should be re-read by the client. -See the [OpenBao KV secrets engine documentation](/vault/docs/secrets/kv/kv-v1#ttls) +See the [OpenBao KV secrets engine documentation](/docs/secrets/kv/kv-v1#ttls) for more details. ## List secrets @@ -122,7 +125,7 @@ policy granting the `update` capability. be held at the given location. Multiple key/value pairs can be specified, and all will be returned on a read operation. A key called `ttl` will trigger some special behavior. See the [OpenBao KV secrets engine - documentation](/vault/docs/secrets/kv/kv-v1#ttls) for details. + documentation](/docs/secrets/kv/kv-v1#ttls) for details. ### Sample payload diff --git a/website/content/api-docs/secret/kv/kv-v2.mdx b/website/content/api-docs/secret/kv/kv-v2.mdx index 43782c9b7e..1eb065addd 100644 --- a/website/content/api-docs/secret/kv/kv-v2.mdx +++ b/website/content/api-docs/secret/kv/kv-v2.mdx @@ -1,6 +1,5 @@ --- -layout: api -page_title: KV - Secrets Engines - HTTP API +sidebar_label: K/V Version 2 description: This is the API documentation for the OpenBao KV secrets engine, version 2. --- @@ -8,9 +7,9 @@ description: This is the API documentation for the OpenBao KV secrets engine, ve This is the API documentation for the OpenBao KV secrets engine while running in versioned mode. For general information about the usage and operation of the version 2 -KV secrets engine, please see the [OpenBao KV documentation](/vault/docs/secrets/kv/kv-v2). +KV secrets engine, please see the [OpenBao KV documentation](/docs/secrets/kv/kv-v2). For information about the differences between KV version 1 and version 2, please [see the KV overview -documentation](/vault/docs/secrets/kv). +documentation](/docs/secrets/kv). ## Configure the KV engine @@ -37,7 +36,7 @@ key-value store. - `delete_version_after` `(string:"0s")` – If set, specifies the length of time before a version is deleted. - Accepts [duration format strings](/vault/docs/concepts/duration-format). + Accepts [duration format strings](/docs/concepts/duration-format). ### Sample payload @@ -99,7 +98,7 @@ This endpoint retrieves the secret at the specified location. The metadata fields `created_time`, `deletion_time`, `destroyed`, and `version` are version specific. The `custom_metadata` field is part of the secret's key metadata and is included in the response whether or not the calling token has `read` access to -the associated [metadata endpoint](/vault/api-docs/secret/kv/kv-v2#read-secret-metadata). +the associated [metadata endpoint](/api-docs/secret/kv/kv-v2#read-secret-metadata). | Method | Path | |:-------|:---------------------------------------------------------| @@ -638,7 +637,7 @@ It does not create a new version. written to this key. If not set, the backend's `delete_version_after` will be used. If the value is greater than the backend's `delete_version_after`, the backend's `delete_version_after` will be used. Accepts [duration format - strings](/vault/docs/concepts/duration-format). + strings](/docs/concepts/duration-format). - `custom_metadata` `(map: nil)` - A map of arbitrary string to string valued user-provided metadata meant to describe the secret. @@ -702,7 +701,7 @@ not create a new version. written to this key. If not set, the backend's `delete_version_after` will be used. If the value is greater than the backend's `delete_version_after`, the backend's `delete_version_after` will be used. Accepts [duration format - strings](/vault/docs/concepts/duration-format). + strings](/docs/concepts/duration-format). - `custom_metadata` `(map: nil)` - A map of arbitrary string to string valued user-provided metadata meant to describe the secret. diff --git a/website/content/api-docs/secret/ldap.mdx b/website/content/api-docs/secret/ldap.mdx index d59ade3bcb..8fe7b39d42 100644 --- a/website/content/api-docs/secret/ldap.mdx +++ b/website/content/api-docs/secret/ldap.mdx @@ -1,16 +1,23 @@ --- -layout: api -page_title: LDAP - Secrets Engines - HTTP API +sidebar_label: LDAP description: This is the API documentation for the OpenBao LDAP secrets engine. --- # LDAP secrets engine (API) -@include 'x509-sha1-deprecation.mdx' +:::warning + +**Note**: This engine can use external X.509 certificates as part of TLS or signature validation. + Verifying signatures against X.509 certificates that use SHA-1 is deprecated and is no longer + usable without a workaround. See the + [deprecation FAQ](/docs/deprecation/faq#q-what-is-the-impact-of-removing-support-for-x-509-certificates-with-signatures-that-use-sha-1) + for more information. + +::: This is the API documentation for the OpenBao LDAP secrets engine. For general information about the usage and operation of the LDAP secrets engine, -please see the [LDAP secrets engine docs](/vault/docs/secrets/ldap). +please see the [LDAP secrets engine docs](/docs/secrets/ldap). This documentation assumes the LDAP secrets engine is enabled at the `/ldap` path in OpenBao. Since it is possible to mount secrets engines at any path, please @@ -26,9 +33,13 @@ This endpoint configures the LDAP secret engine to manage user entries. | `GET` | `/ldap/config` | | `DELETE` | `/ldap/config` | --> **Note**: The LDAP entry used by `config` should have the necessary privileges +:::info + +**Note**: The LDAP entry used by `config` should have the necessary privileges to search and change entry passwords in LDAP. +::: + ### Parameters - `binddn` `(string: )` - Distinguished name (DN) of object to bind for managing user entries. @@ -38,15 +49,15 @@ to search and change entry passwords in LDAP. `ldaps://ldap.myorg.com:636`. This can also be a comma-delineated list of URLs, e.g. `ldaps://ldap.myorg.com, ldaps://ldap.myorg.com:636`, in which case the servers will be tried in-order if there are errors during the connection process.`. -- `password_policy` `(string: )` - The name of the [password policy](/vault/docs/concepts/password-policies) +- `password_policy` `(string: )` - The name of the [password policy](/docs/concepts/password-policies) to use to generate passwords. Note that this accepts the name of the policy, not the policy itself. - `schema` `(string: "openldap")` - The LDAP schema to use when storing entry passwords. Valid schemas include `openldap`, `ad`, and `racf`. - `userdn` `(string: )` - The base DN under which to perform user search in - [library management](/vault/api-docs/secret/ldap#library-management) and [static roles](/vault/api-docs/secret/ldap#static-roles). + [library management](/api-docs/secret/ldap#library-management) and [static roles](/api-docs/secret/ldap#static-roles). For example, `ou=Users,dc=openbao,dc=com`. - `userattr` `(string: )` – The attribute field name used to perform user search - in [library management](/vault/api-docs/secret/ldap#library-management) and [static roles](/vault/api-docs/secret/ldap#static-roles). + in [library management](/api-docs/secret/ldap#library-management) and [static roles](/api-docs/secret/ldap#static-roles). Defaults to `cn` for the `openldap` schema, `userPrincipalName` for the `ad` schema, and `racfid` for the `racf` schema. - `upndomain` (string: `optional`) - The domain (userPrincipalDomain) used to construct a UPN @@ -81,11 +92,11 @@ configuration if both are specified. prior to the introduction of password policies). - If `length` is set, the same algorithm is used, but with the length specified instead of the default length. - If `password_policy` is set, the password will be generated from the associated - [password policy](/vault/docs/concepts/password-policies). The policy is not exercised prior to saving the configuration. + [password policy](/docs/concepts/password-policies). The policy is not exercised prior to saving the configuration. The policy will need to exist prior to passwords needing to be generated by this engine, but does not need to exist prior to saving the configuration. -See [LDAP secrets engine docs](/vault/docs/secrets/ldap) for additional information. +See [LDAP secrets engine docs](/docs/secrets/ldap) for additional information. ### Sample payload @@ -167,9 +178,9 @@ The `static-role` endpoint configures OpenBao to manage the passwords of existin ### Parameters - `username` `(string: )` - The username of the existing LDAP entry to manage - password rotation for. LDAP search for the username will be rooted at the [userdn](/vault/api-docs/secret/ldap#userdn) + password rotation for. LDAP search for the username will be rooted at the [userdn](/api-docs/secret/ldap#userdn) configuration value. The attribute to use when searching for the user can be configured - with the [userattr](/vault/api-docs/secret/ldap#userattr) configuration value. This is useful + with the [userattr](/api-docs/secret/ldap#userattr) configuration value. This is useful when `dn` isn't used for login purposes (such as SSH). Cannot be modified after creation.
**Example:** `"bob"` - `dn` `(string: )` - Distinguished name (DN) of the existing LDAP entry to manage @@ -177,7 +188,7 @@ The `static-role` endpoint configures OpenBao to manage the passwords of existin search performed during password rotation. Cannot be modified after creation.
**Example:** `cn=bob,ou=Users,dc=openbao,dc=com` - `rotation_period` `(string: )` - How often OpenBao should rotate the password of the user entry. Accepts - [duration format strings](/vault/docs/concepts/duration-format). The minimum rotation period is 5 seconds.
+ [duration format strings](/docs/concepts/duration-format). The minimum rotation period is 5 seconds.
**Example:** `"3600", "5s", "1h"` ### Sample payload @@ -341,14 +352,14 @@ v_{{.DisplayName}}_{{.RoleName}}_{{random 10}}_{{unix_time}}
- `default_ttl` `(string/int)` - Specifies the TTL for the leases associated with this role. Accepts - [duration format strings](/vault/docs/concepts/duration-format). Defaults to system/engine default TTL time. + [duration format strings](/docs/concepts/duration-format). Defaults to system/engine default TTL time. - `max_ttl` `(string/int)` - Specifies the maximum TTL for the leases associated with this role. Accepts - [duration format strings](/vault/docs/concepts/duration-format). Defaults to system/mount default TTL time; + [duration format strings](/docs/concepts/duration-format). Defaults to system/mount default TTL time; this value is allowed to be less than the mount max TTL (or, if not set, the system max TTL), but it is not allowed to be longer. The `creation_ldif`, `deletion_ldif`, `rollback_ldif`, and `username_template` fields are all templated fields. See -[Username Templating](/vault/docs/concepts/username-templating) for details on how to use templating. Also see +[Username Templating](/docs/concepts/username-templating) for details on how to use templating. Also see [Templates](#templates) for specifics on what data is available for each template. #### Sample payload @@ -387,9 +398,13 @@ Full Payload: } ``` --> Note: The LDIF statements may optionally be base64 encoded. If they are base64 encoded when creating/updating the +:::info + +Note: The LDIF statements may optionally be base64 encoded. If they are base64 encoded when creating/updating the role configuration, the decoded version will be returned from the `GET` endpoint. +::: + #### Sample POST request ```shell-session @@ -446,7 +461,7 @@ The following parameters are available within the LDIF templates: **Default pattern:** `v___<10 random chars>_` `.Password` - The generated password (optionally from -[password policies](/vault/docs/concepts/password-policies)) +[password policies](/docs/concepts/password-policies)) `.RoleName` - The name of the role that credentials are being generated for. @@ -600,10 +615,10 @@ When adding a service account to the library, OpenBao verifies it already exists service accounts must already exist in the LDAP directory. - `ttl` `(duration: "24h", optional)` - The maximum amount of time a single check-out lasts before OpenBao automatically checks it back in. Defaults to 24 hours. Setting it to zero reflects an unlimited lending period. - Uses [duration format strings](/vault/docs/concepts/duration-format). + Uses [duration format strings](/docs/concepts/duration-format). - `max_ttl` `(duration: "24h", optional)` - The maximum amount of time a check-out last with renewal before OpenBao automatically checks it back in. Defaults to 24 hours. Setting it to zero reflects an unlimited lending period. - Uses [duration format strings](/vault/docs/concepts/duration-format). + Uses [duration format strings](/docs/concepts/duration-format). - `disable_check_in_enforcement` `(bool: false, optional)` - Disable enforcing that service accounts must be checked in by the entity or client token that checked them out. Defaults to false. @@ -704,7 +719,7 @@ Returns a `200` if a credential is available, and a `400` if no credential is av - `ttl` `(duration: "", optional)` - The maximum amount of time a check-out lasts before OpenBao automatically checks it back in. Setting it to zero reflects an unlimited lending period. Defaults to the set's `ttl`. If the requested `ttl` is higher than the set's, the set's will be used. - Uses [duration format strings](/vault/docs/concepts/duration-format). + Uses [duration format strings](/docs/concepts/duration-format). ### Sample POST request diff --git a/website/content/api-docs/secret/pki.mdx b/website/content/api-docs/secret/pki.mdx index 65f07aca23..51d55b0429 100644 --- a/website/content/api-docs/secret/pki.mdx +++ b/website/content/api-docs/secret/pki.mdx @@ -1,16 +1,23 @@ --- -layout: api -page_title: PKI - Secrets Engines - HTTP API +sidebar_label: PKI description: This is the API documentation for the OpenBao PKI secrets engine. --- # PKI secrets engine (API) -@include 'x509-sha1-deprecation.mdx' +:::warning + +**Note**: This engine can use external X.509 certificates as part of TLS or signature validation. + Verifying signatures against X.509 certificates that use SHA-1 is deprecated and is no longer + usable without a workaround. See the + [deprecation FAQ](/docs/deprecation/faq#q-what-is-the-impact-of-removing-support-for-x-509-certificates-with-signatures-that-use-sha-1) + for more information. + +::: This is the API documentation for the OpenBao PKI secrets engine. For general information about the usage and operation of the PKI secrets engine, please see -the [PKI documentation](/vault/docs/secrets/pki). +the [PKI documentation](/docs/secrets/pki). This documentation assumes the PKI secrets engine is enabled at the `/pki` path in OpenBao. Since it is possible to enable secrets engines at any location, please @@ -107,9 +114,13 @@ issuers may have different CRLs. It is _strongly_ encouraged to limit the scope of CAs within a mount and not to mix different types of CAs (roots and intermediates). -~> **Note**: Some functionality will not work if a default issuer is not - configured. OpenBao automatically selects the default issuer from the - current issuing certificate on migration from an older OpenBao version. +:::warning + +**Note**: Some functionality will not work if a default issuer is not +configured. OpenBao automatically selects the default issuer from the +current issuing certificate on migration from an older OpenBao version. + +::: ## ACME certificate issuance @@ -191,14 +202,19 @@ fetch an EAB token and pass it to the ACME client for use on the initial registration: this binds the ACME client's registration to an authenticated OpenBao endpoint, but not further to the client's entity or other information. -~> Note: Enabling EAB is strongly recommended for public-facing OpenBao - deployments. Use of the `VAULT_DISABLE_PUBLIC_ACME` environment variable - can be used to enforce all ACME instances have EAB enabled. +:::warning + +Note: Enabling EAB is strongly recommended for public-facing OpenBao +deployments. Use of the `VAULT_DISABLE_PUBLIC_ACME` environment variable +can be used to enforce all ACME instances have EAB enabled. + +::: + #### ACME required headers ACME requires the following response headers (`allowed_response_headers`) -to be specified by [mount tuning](/vault/api-docs/system/mounts#tune-mount-configuration): +to be specified by [mount tuning](/api-docs/system/mounts#tune-mount-configuration): - `Replay-Nonce` - `Link` @@ -555,8 +571,12 @@ store. Choice of issuing CA is determined first by the role (when using the It is suggested to limit access to the path-overridden issue endpoint (on `/pki/issuer/:issuer_ref/issue/:name`). -~> **Note**: The private key is _not_ stored. If you do not save the private - key from the response, you will need to request a new certificate. +:::warning + +**Note**: The private key is _not_ stored. If you do not save the private +key from the response, you will need to request a new certificate. + +::: | Method | Path | Issuer | | :----- | :------------------------------------ | :------------ | @@ -573,15 +593,23 @@ It is suggested to limit access to the path-overridden issue endpoint (on refer to the currently configured default issuer, or the name assigned to an issuer. This parameter is part of the request URL. -~> Note: This parameter is not present on the `/pki/issue/:name` path and - takes its value from the role's `issuer_ref` field. +:::warning + +Note: This parameter is not present on the `/pki/issue/:name` path and +takes its value from the role's `issuer_ref` field. + +::: - `common_name` `(string: "")` - Specifies the requested CN for the certificate. If the CN is allowed by role policy, it will be issued. If more than one `common_name` is desired, specify the alternative names in the `alt_names` list. -~> Note: A value for `common_name` is required when [require_cn](#require_cn) is set to `true` +:::warning + +Note: A value for `common_name` is required when [require_cn](#require_cn) is set to `true` + +::: - `alt_names` `(string: "")` - Specifies requested Subject Alternative Names, in a comma-delimited list. These can be host names or email addresses; they will @@ -621,8 +649,12 @@ It is suggested to limit access to the path-overridden issue endpoint (on `format`. The other option is `pkcs8` which will return the key marshalled as PEM-encoded PKCS8. -~> **Note** that this does not apply to the private key within the certificate - field if `format=pem_bundle` parameter is specified. +:::warning + +**Note** that this does not apply to the private key within the certificate +field if `format=pem_bundle` parameter is specified. + +::: - `exclude_cn_from_sans` `(bool: false)` - If true, the given `common_name` will not be included in DNS or Email Subject Alternate Names (as appropriate). @@ -708,8 +740,12 @@ It is suggested to limit access to the path-overridden sign endpoint (on refer to the currently configured default issuer, or the name assigned to an issuer. This parameter is part of the request URL. -~> Note: This parameter is not present on the `/pki/sign/:name` path and - takes its value from the role's `issuer_ref` field. +:::warning + +Note: This parameter is not present on the `/pki/sign/:name` path and +takes its value from the role's `issuer_ref` field. + +::: - `csr` `(string: )` - Specifies the PEM-encoded CSR. @@ -808,10 +844,14 @@ verbatim. This endpoint can be used both when signing an OpenBao-backed intermediate or when signing an externally-owned intermediate. -~> **Note**: This is a privileged endpoint, as callers are granted a new - intermediate certificate, with which they can issue for arbitrary names. - Access to this endpoint should be restricted by policy to only trusted - operators. +:::warning + +**Note**: This is a privileged endpoint, as callers are granted a new +intermediate certificate, with which they can issue for arbitrary names. +Access to this endpoint should be restricted by policy to only trusted +operators. + +::: | Method | Path | Issuer | | :----- | :------------------------------------------ | :------- | @@ -825,8 +865,12 @@ when signing an externally-owned intermediate. refer to the currently configured default issuer, or the name assigned to an issuer. This parameter is part of the request URL. -~> Note: This parameter is not present on the `/pki/root/sign-intermediate` - path and takes the value `default`. +:::warning + +Note: This parameter is not present on the `/pki/root/sign-intermediate` +path and takes the value `default`. + +::: - `csr` `(string: )` - Specifies the PEM-encoded CSR to be signed. @@ -925,7 +969,7 @@ when signing an externally-owned intermediate. - `not_before_duration` `(duration: "30s")` - Specifies the duration by which to backdate the NotBefore property. This value has no impact in the validity period of the requested certificate, specified in the `ttl` field. - Uses [duration format strings](/vault/docs/concepts/duration-format). + Uses [duration format strings](/docs/concepts/duration-format). - `not_after` `(string)` - Set the Not After field of the certificate with specified date value. The value format should be given in UTC format @@ -938,19 +982,27 @@ when signing an externally-owned intermediate. on issuer's key length (SHA-2-256 for RSA keys, and matching the curve size for NIST P-Curves). -~> **Note**: ECDSA and Ed25519 issuers do not follow configuration of the - `signature_bits` value; only RSA issuers will change signature types - based on this parameter. +:::warning + +**Note**: ECDSA and Ed25519 issuers do not follow configuration of the +`signature_bits` value; only RSA issuers will change signature types +based on this parameter. + +::: - `skid` `(string: "")` - Value for the Subject Key Identifier field (RFC 5280 Section 4.2.1.2). Specified as a string in hex format. Default is empty, allowing OpenBao to automatically calculate the SKID according to method one in the above RFC section. -~> **Note**: This value should ONLY be used when cross-signing to mimic - the existing certificate's SKID value; this is necessary to allow - certain TLS implementations (such as OpenSSL) which use SKID/AKID - matches in chain building to restrict possible valid chains. +:::warning + +**Note**: This value should ONLY be used when cross-signing to mimic +the existing certificate's SKID value; this is necessary to allow +certain TLS implementations (such as OpenSSL) which use SKID/AKID +matches in chain building to restrict possible valid chains. + +::: - `use_pss` `(bool: false)` - Specifies whether or not to use PSS signatures over PKCS#1v1.5 signatures when a RSA-type issuer is used. Ignored for @@ -1023,11 +1075,15 @@ $ curl \ This endpoint uses the configured CA certificate to sign a self-issued certificate (which will usually be a self-signed certificate as well). -~> **_This is an extremely privileged endpoint_**. The given certificate will be - signed as-is with only minimal validation performed (is it a CA cert, and is it - actually self-issued). The only values that will be changed will be the - authority key ID, the issuer DN, and, if set, any distribution points.

- It is recommended to limit this endpoint to only trusted operators. +:::warning + +**_This is an extremely privileged endpoint_**. The given certificate will be +signed as-is with only minimal validation performed (is it a CA cert, and is it +actually self-issued). The only values that will be changed will be the +authority key ID, the issuer DN, and, if set, any distribution points.

+It is recommended to limit this endpoint to only trusted operators. + +::: This is generally only needed for root certificate rolling in cases where you don't want/can't get access to a CSR (such as if it's a root stored in OpenBao @@ -1047,8 +1103,12 @@ endpoint, you most likely should be using a different endpoint (such as refer to the currently configured default issuer, or the name assigned to an issuer. This parameter is part of the request URL. -~> Note: This parameter is not present on the `/pki/root/sign-self-issued` - path and takes the value `default`. +:::warning + +Note: This parameter is not present on the `/pki/root/sign-self-issued` +path and takes the value `default`. + +::: - `certificate` `(string: )` - Specifies the PEM-encoded self-issued certificate. @@ -1110,8 +1170,12 @@ have access.** refer to the currently configured default issuer, or the name assigned to an issuer. This parameter is part of the request URL. -~> Note: This parameter is not present on the `/pki/root/sign-self-issued` - path and takes the value `default`. +:::warning + +Note: This parameter is not present on the `/pki/root/sign-self-issued` +path and takes the value `default`. + +::: - `name` `(string: "")` - Specifies a role. If set, the following parameters from the role will have effect: `ttl`, `max_ttl`, `generate_lease`, `no_store` and `not_before_duration`. @@ -1124,9 +1188,13 @@ have access.** drop the `KeyUsage` part of the value. Values are not case-sensitive. To specify no default key usage constraints, set this to an empty list. -~> Note: previous versions of this document incorrectly called this a constraint; - this value is only used as a default when the `KeyUsage` extension is missing - from the CSR. +:::warning + +Note: previous versions of this document incorrectly called this a constraint; +this value is only used as a default when the `KeyUsage` extension is missing +from the CSR. + +::: - `ext_key_usage` `(list: [])` - Specifies the default extended key usage constraint on the issued certificate. Valid @@ -1134,14 +1202,22 @@ have access.** drop the `ExtKeyUsage` part of the value. Values are not case-sensitive. To specify no key default usage constraints, set this to an empty list. -~> Note: previous versions of this document incorrectly called this a constraint; - this value is only used as a default when the `ExtendedKeyUsage` extension is - missing from the CSR. +:::warning + +Note: previous versions of this document incorrectly called this a constraint; +this value is only used as a default when the `ExtendedKeyUsage` extension is +missing from the CSR. + +::: - `ext_key_usage_oids` `(string: "")` - A comma-separated string or list of extended key usage oids. -~> Note: This value is only used as a default when the `ExtendedKeyUsage` - extension is missing from the CSR. +:::warning + +Note: This value is only used as a default when the `ExtendedKeyUsage` +extension is missing from the CSR. + +::: - `ttl` `(string: "")` - Specifies the requested Time To Live. Cannot be greater than the engine's `max_ttl` value. If not provided, the engine's `ttl` value @@ -1166,9 +1242,13 @@ have access.** on issuer's key length (SHA-2-256 for RSA keys, and matching the curve size for NIST P-Curves). -~> **Note**: ECDSA and Ed25519 issuers do not follow configuration of the - `signature_bits` value; only RSA issuers will change signature types - based on this parameter. +:::warning + +**Note**: ECDSA and Ed25519 issuers do not follow configuration of the +`signature_bits` value; only RSA issuers will change signature types +based on this parameter. + +::: - `use_pss` `(bool: false)` - Specifies whether or not to use PSS signatures over PKCS#1v1.5 signatures when a RSA-type issuer is used. Ignored for @@ -1225,11 +1305,15 @@ This endpoint revokes a certificate using its serial number. This is an alternative option to the standard method of revoking using OpenBao lease IDs. A successful revocation will rotate the CRL. -~> **Note**: This operation is privileged as it allows revocation of arbitrary - certificates based purely on their serial number. It does not validate that - the requesting user issued the certificate or has possession of the private - key.

- It is not possible to revoke issuers using this path. +:::warning + +**Note**: This operation is privileged as it allows revocation of arbitrary +certificates based purely on their serial number. It does not validate that +the requesting user issued the certificate or has possession of the private +key.

+It is not possible to revoke issuers using this path. + +::: | Method | Path | | :----- | :------------ | @@ -1237,8 +1321,12 @@ successful revocation will rotate the CRL. #### Parameters -~> Note: either `serial_number` or `certificate` (but not both) must be - specified on requests to this endpoint. +:::warning + +Note: either `serial_number` or `certificate` (but not both) must be +specified on requests to this endpoint. + +::: - `serial_number` `(string: )` - Specifies the serial number of the certificate to revoke, in hyphen-separated or colon-separated hexadecimal. @@ -1286,11 +1374,15 @@ rotate the CRL. It is not possible to revoke issuers using this path. -~> **Note**: This operation is **NOT** privileged, as it validates revocation - has a private key corresponding to a certificate signed by OpenBao. However, - to avoid third parties performing a denial-of-service (DOS) against OpenBao, - we've made this endpoint authenticated. Thus it is strongly encouraged to - generally allow all access to this path via ACLs. +:::warning + +**Note**: This operation is **NOT** privileged, as it validates revocation +has a private key corresponding to a certificate signed by OpenBao. However, +to avoid third parties performing a denial-of-service (DOS) against OpenBao, +we've made this endpoint authenticated. Thus it is strongly encouraged to +generally allow all access to this path via ACLs. + +::: | Method | Path | | :----- | :--------------------- | @@ -1298,8 +1390,12 @@ It is not possible to revoke issuers using this path. #### Parameters -~> Note: either `serial_number` or `certificate` (but not both) must be - specified on requests to this endpoint. +:::warning + +Note: either `serial_number` or `certificate` (but not both) must be +specified on requests to this endpoint. + +::: - `serial_number` `(string: )` - Specifies the serial number of the certificate to revoke, in hyphen-separated or colon-separated hexadecimal. @@ -1477,12 +1573,16 @@ endpoint. These are unauthenticated endpoints. -~> Note: this endpoint accepts the `If-Modified-Since` header, to respond with - 304 Not Modified when the requested resource has not changed. This header - needs to be allowed on the PKI mount by tuning the `passthrough_request_headers` - option. In order for clients to know the last modified time, the response - header `Last-Modified` needs to be added to the mount tunable - `allowed_response_headers`. +:::warning + +Note: this endpoint accepts the `If-Modified-Since` header, to respond with +304 Not Modified when the requested resource has not changed. This header +needs to be allowed on the PKI mount by tuning the `passthrough_request_headers` +option. In order for clients to know the last modified time, the response +header `Last-Modified` needs to be added to the mount tunable +`allowed_response_headers`. + +::: | Method | Path | Issuer | Format | | :----- | :----------------------------- | :-------- |:----------------------------------------------------------------------------------| @@ -1500,8 +1600,12 @@ These are unauthenticated endpoints. refer to the currently configured default issuer, or the name assigned to an issuer. This parameter is part of the request URL. -~> Note: This parameter is not present on the `/pki/cert/ca` and - `/pki/ca(/pem)?` paths and takes the implicit value `default`. +:::warning + +Note: This parameter is not present on the `/pki/cert/ca` and +`/pki/ca(/pem)?` paths and takes the implicit value `default`. + +::: #### Sample request @@ -1542,9 +1646,13 @@ These are unauthenticated endpoints. | `GET` | `/pki/ca_chain` | `default` | PEM [\[1\]](#openbao-cli-with-der-pem-responses "OpenBao CLI With DER/PEM Responses") | | `GET` | `/pki/cert/ca_chain` | `default` | JSON | -~> **Note**: These endpoints return the full chain (including the default - issuer's certificate and all parent issuers known to OpenBao) in these - responses. +:::warning + +**Note**: These endpoints return the full chain (including the default +issuer's certificate and all parent issuers known to OpenBao) in these +responses. + +::: #### Sample request @@ -1585,14 +1693,22 @@ Endpoints with source `local` only include cluster-local revocations. These are unauthenticated endpoints. -~> **Note**: These endpoints now serve a [version 2](https://datatracker.ietf.org/doc/html/rfc5280#section-5.1.2.1) CRL response. +:::warning + +**Note**: These endpoints now serve a [version 2](https://datatracker.ietf.org/doc/html/rfc5280#section-5.1.2.1) CRL response. -~> Note: this endpoint accepts the `If-Modified-Since` header, to respond with - 304 Not Modified when the requested resource has not changed. This header - needs to be allowed on the PKI mount by tuning the `passthrough_request_headers` - option. In order for clients to know the last modified time, the response - header `Last-Modified` needs to be added to the mount tunable - `allowed_response_headers`. +::: + +:::warning + +Note: this endpoint accepts the `If-Modified-Since` header, to respond with +304 Not Modified when the requested resource has not changed. This header +needs to be allowed on the PKI mount by tuning the `passthrough_request_headers` +option. In order for clients to know the last modified time, the response +header `Last-Modified` needs to be added to the mount tunable +`allowed_response_headers`. + +::: | Method | Path | Issuer | Format | Type | Source | | :----- | :---------------------------------------------- | :-------- | :-------------------------------------------------------------------------------- | :------- | :------ | @@ -1616,8 +1732,12 @@ These are unauthenticated endpoints. refer to the currently configured default issuer, or the name assigned to an issuer. This parameter is part of the request URL. -~> Note: This parameter is not present on the `/pki/cert/crl` and - `/pki/crl(/pem)?` paths and takes the implicit value `default`. +:::warning + +Note: This parameter is not present on the `/pki/cert/crl` and +`/pki/crl(/pem)?` paths and takes the implicit value `default`. + +::: #### Sample request @@ -1679,14 +1799,18 @@ While root generation does create entries here, importing certificates (including both roots and intermediates) will not cause the imported certificate's serial number to appear in this list. -~> Note: The endpoint to list all certificates is authenticated. This is to - prevent automated enumeration of issued certificates for internal services; - however, this information should generally be considered non-sensitive and - the certificates themselves are exposed without authentication (provided - their serial number is known).

- Many Public CAs participate in the Certificate Transparency initiative, - where all issued certificates are publicly disclosed in the interest - of third-party verification of CA integrity. +:::warning + +Note: The endpoint to list all certificates is authenticated. This is to +prevent automated enumeration of issued certificates for internal services; +however, this information should generally be considered non-sensitive and +the certificates themselves are exposed without authentication (provided +their serial number is known).

+Many Public CAs participate in the Certificate Transparency initiative, +where all issued certificates are publicly disclosed in the interest +of third-party verification of CA integrity. + +::: | Method | Path | | :----- | :----------- | @@ -1741,10 +1865,14 @@ These are unauthenticated endpoints. - `crl` for the _default_ issuer's CRL - `ca_chain` for the _default_ issuer's CA trust chain. -~> **Note**: These endpoints return the full chain - (including this certificate and all parent issuers known to OpenBao) in - the `ca_chain` response, for both the `certificate` and newer `ca_chain` - fields. +:::warning + +**Note**: These endpoints return the full chain +(including this certificate and all parent issuers known to OpenBao) in +the `ca_chain` response, for both the `certificate` and newer `ca_chain` +fields. + +::: #### Sample request @@ -1845,8 +1973,12 @@ be retrieved later_. - `key_type` `(string: "rsa")` - Specifies the desired key type; must be `rsa`, `ed25519` or `ec`. -~> **Note**: In FIPS 140-2 mode, the following algorithms are not certified - and thus should not be used: `ed25519`. +:::warning + +**Note**: In FIPS 140-2 mode, the following algorithms are not certified +and thus should not be used: `ed25519`. + +::: - `key_bits` `(int: 0)` - Specifies the number of bits to use for the generated keys. Allowed values are 0 (universal default); with @@ -1902,12 +2034,16 @@ be reused for this root. This generated root will sign its own CRL. Authority Access distribution points use the values set via `config/urls`. -~> **Note**: The PKI Secrets Engine supports multiple issuers under a single - mount. Use the management operations in this section to [list](#list-issuers) - and [modify issuers](#update-issuer) within this mount. No issuers will be - overridden by calling this operation. Deleting individual keys and issuers - should be preferred to calling `DELETE /pki/root`, [which deletes - everything](#delete-all-issuers-and-keys). +:::warning + +**Note**: The PKI Secrets Engine supports multiple issuers under a single +mount. Use the management operations in this section to [list](#list-issuers) +and [modify issuers](#update-issuer) within this mount. No issuers will be +overridden by calling this operation. Deleting individual keys and issuers +should be preferred to calling `DELETE /pki/root`, [which deletes +everything](#delete-all-issuers-and-keys). + +::: | Method | Path | | :----- | :--------------------------------- | @@ -1975,14 +2111,22 @@ use the values set via `config/urls`. `format`. The other option is `pkcs8` which will return the key marshalled as PEM-encoded PKCS8. -~> **Note** that this does not apply to the private key within the certificate - field if `format=pem_bundle` parameter is specified. +:::warning + +**Note** that this does not apply to the private key within the certificate +field if `format=pem_bundle` parameter is specified. + +::: - `key_type` `(string: "rsa")` - Specifies the desired key type; must be `rsa`, `ed25519` or `ec`. -~> **Note**: In FIPS 140-2 mode, the following algorithms are not certified - and thus should not be used: `ed25519`. +:::warning + +**Note**: In FIPS 140-2 mode, the following algorithms are not certified +and thus should not be used: `ed25519`. + +::: - `key_bits` `(int: 0)` - Specifies the number of bits to use for the generated keys. Allowed values are 0 (universal default); with @@ -2044,7 +2188,7 @@ use the values set via `config/urls`. - `not_before_duration` `(duration: "30s")` - Specifies the duration by which to backdate the NotBefore property. This value has no impact in the validity period of the requested certificate, specified in the `ttl` field. - Uses [duration format strings](/vault/docs/concepts/duration-format). + Uses [duration format strings](/docs/concepts/duration-format). - `not_after` `(string)` - Set the Not After field of the certificate with specified date value. The value format should be given in UTC format @@ -2056,9 +2200,13 @@ use the values set via `config/urls`. values can be found at https://golang.org/pkg/crypto/x509/#KeyUsage - simply drop the `KeyUsage` part of the value. Values are not case-sensitive. -~> Note: previous versions of this document incorrectly called this a constraint; +:::warning + + Note: previous versions of this document incorrectly called this a constraint; this value is only used as a default when the `KeyUsage` extension is missing from the CSR. + +::: - `ext_key_usage` `(list: [])` - Specifies the default extended key usage constraint on the issued certificate. Valid @@ -2066,16 +2214,28 @@ use the values set via `config/urls`. drop the `ExtKeyUsage` part of the value. Values are not case-sensitive. To specify no key default usage constraints, set this to an empty list. -~> Note: previous versions of this document incorrectly called this a constraint; +:::warning + + Note: previous versions of this document incorrectly called this a constraint; this value is only used as a default when the `ExtendedKeyUsage` extension is missing from the CSR. +::: + - `ext_key_usage_oids` `(string: "")` - A comma-separated string or list of extended key usage oids. -~> Note: This value is only used as a default when the `ExtendedKeyUsage` +:::warning + + Note: This value is only used as a default when the `ExtendedKeyUsage` extension is missing from the CSR. -* ~> Note: Keys of type `rsa` currently only support PKCS#1 v1.5 signatures. +::: + +:::warning + + Note: Keys of type `rsa` currently only support PKCS#1 v1.5 signatures. + +::: #### Sample payload @@ -2131,11 +2291,15 @@ parameters that can be set in a CSR are supported in this request. No new issuer is yet created by this call; note that a new key may be generated depending on the `type` request parameter. -~> **Note**: In order to complete the intermediate generation, the CSR must be - signed and the resulting certificate imported. This may involve working with - external systems (such as an external or offline root CA) to transmit the - CSR and complete the signing before the signed intermediate certificate is - [imported](#import-ca-certificate-and-keys) into this mount. +:::warning + +**Note**: In order to complete the intermediate generation, the CSR must be +signed and the resulting certificate imported. This may involve working with +external systems (such as an external or offline root CA) to transmit the +CSR and complete the signing before the signed intermediate certificate is +[imported](#import-ca-certificate-and-keys) into this mount. + +::: | Method | Path | Private key source (`type`) | | :----- |:-------------------------------------------| :-------------------------- | @@ -2183,16 +2347,28 @@ generated depending on the `type` request parameter. `format`. The other option is `pkcs8` which will return the key marshalled as PEM-encoded PKCS8. -~> **Note** that this does not apply to the private key within the certificate - field if `format=pem_bundle` parameter is specified. +:::warning + +**Note** that this does not apply to the private key within the certificate +field if `format=pem_bundle` parameter is specified. + +::: - `key_type` `(string: "rsa")` - Specifies the desired key type; must be `rsa`, `ed25519` or `ec`. Not suitable for `type=existing` requests. -~> **Note**: In FIPS 140-2 mode, the following algorithms are not certified - and thus should not be used: `ed25519`. +:::warning + +**Note**: In FIPS 140-2 mode, the following algorithms are not certified +and thus should not be used: `ed25519`. + +::: + +:::warning -~> **Note**: Keys of type `rsa` currently only support PKCS#1 v1.5 signatures. +**Note**: Keys of type `rsa` currently only support PKCS#1 v1.5 signatures. + +::: - `key_bits` `(int: 0)` - Specifies the number of bits to use for the generated keys. Allowed values are 0 (universal default); with @@ -2215,10 +2391,14 @@ generated depending on the `type` request parameter. on issuer's key length (SHA-2-256 for RSA keys, and matching the curve size for NIST P-Curves). -~> **Note**: ECDSA and Ed25519 issuers do not follow configuration of the +:::warning + +**Note**: ECDSA and Ed25519 issuers do not follow configuration of the `signature_bits` value; only RSA issuers will change signature types based on this parameter. +::: + - `exclude_cn_from_sans` `(bool: false)` - If true, the given `common_name` will not be included in DNS or Email Subject Alternate Names (as appropriate). Useful if the CN is not a hostname or email address, but is instead some @@ -2324,35 +2504,59 @@ key IDs of any entries in the bundle that already existed within this mount. | `POST` | `/pki/issuers/import/cert` | no | `pem_bundle` | | `POST` | `/pki/intermediate/set-signed` | no | `certificate` | -~> **Note**: endpoints which allow importing private keys _should_ be considered - highly privileged and restricted appropriately. Endpoints which allow - importing issuers should also be restricted, but note that issuers without - keys are unable to issue certificates or CRLs. +:::warning + +**Note**: endpoints which allow importing private keys _should_ be considered +highly privileged and restricted appropriately. Endpoints which allow +importing issuers should also be restricted, but note that issuers without +keys are unable to issue certificates or CRLs. + +::: + +:::warning + +Note: OpenBao will deduplicate differently-encoded but same-valued keys and +issuers. This means the returned certificate _may_ differ in encoding from +the one provided on subsequent re-imports of the same issuer or key. + +::: + +:::warning -~> Note: OpenBao will deduplicate differently-encoded but same-valued keys and - issuers. This means the returned certificate _may_ differ in encoding from - the one provided on subsequent re-imports of the same issuer or key. +Note: This import may fail due to CRL rebuilding issues or other potential +issues; this may impact long-term use of these issuers, but some issuers or +keys may still be imported as a result of this process. -~> Note: This import may fail due to CRL rebuilding issues or other potential - issues; this may impact long-term use of these issuers, but some issuers or - keys may still be imported as a result of this process. +::: -~> Warning: See the [note](/vault/docs/secrets/pki/considerations#issuer-subjects-and-crls) - regarding Subject naming on externally created CA certificates and - shortcomings with CRL building. +:::warning + +Warning: See the [note](/docs/secrets/pki/considerations#issuer-subjects-and-crls) +regarding Subject naming on externally created CA certificates and +shortcomings with CRL building. + +::: #### Parameters - `pem_bundle` `(string: )` - Specifies the unencrypted private key and certificate, concatenated in PEM format. -~> Note: this parameter is on the `/pki/config/ca` and `/pki/issuers/import/*` - paths; it is not on the `/pki/intermediate/set-signed` path. +:::warning + +Note: this parameter is on the `/pki/config/ca` and `/pki/issuers/import/*` +paths; it is not on the `/pki/intermediate/set-signed` path. + +::: - `certificate` `(string: )` - Specifies the certificates to import, concatenated in PEM format. -~> Note: this parameter is **only** on the `/pki/intermediate/set-signed` path. +:::warning + +Note: this parameter is **only** on the `/pki/intermediate/set-signed` path. + +::: #### Sample request @@ -2452,12 +2656,16 @@ do so, import a new issuer and a new `issuer_id` will be assigned. | `POST` | `/pki/issuer/:issuer_ref` | | `PATCH` | `/pki/issuer/:issuer_ref` | -~> **Note** `POST`ing to this endpoint causes OpenBao to overwrite the previous - contents of the issuer, using the provided request data (and any defaults - for elided parameters). It does not update only the provided fields.

- OpenBao supports the PATCH operation to this endpoint, using the [JSON patch - format](https://datatracker.ietf.org/doc/html/rfc6902) supported by KVv2, - allowing update of specific fields. Note that `bao write` uses `POST`. +:::warning + +**Note** `POST`ing to this endpoint causes OpenBao to overwrite the previous +contents of the issuer, using the provided request data (and any defaults +for elided parameters). It does not update only the provided fields.

+OpenBao supports the PATCH operation to this endpoint, using the [JSON patch +format](https://datatracker.ietf.org/doc/html/rfc6902) supported by KVv2, +allowing update of specific fields. Note that `bao write` uses `POST`. + +::: #### Parameters @@ -2479,32 +2687,40 @@ do so, import a new issuer and a new `issuer_id` will be assigned. - `permit` to allow this issuance to succeed with a `NotAfter` value exceeding that of this issuer. -~> Note: Not all values result in leaf certificates that can be validated - through the entire validity period. It is suggested to use `truncate` for - intermediate CAs and `permit` only for root CAs. This is because - (root) certificates in browsers' trust stores typically aren't checked - for validity, whereas intermediate CA certificates sent in TLS connections - are checked for validity at the time of use. This means that a leaf - certificate permitted to be issued for longer than the intermediate likely - won't continue to validate after the intermediate has expired. +:::warning + +Note: Not all values result in leaf certificates that can be validated +through the entire validity period. It is suggested to use `truncate` for +intermediate CAs and `permit` only for root CAs. This is because +(root) certificates in browsers' trust stores typically aren't checked +for validity, whereas intermediate CA certificates sent in TLS connections +are checked for validity at the time of use. This means that a leaf +certificate permitted to be issued for longer than the intermediate likely +won't continue to validate after the intermediate has expired. + +::: - `manual_chain` `([]string: nil)` - Chain of issuer references to build this issuer's computed CAChain field from, when non-empty. -~> Note: the `manual_chain` field is an advanced field useful when automatic - chain building isn't desired. The first element _must_ be the present - issuer's reference. Subsequent references _should_ validate previous - entries, terminating with a root certificate. _Ideally_ a single linear - chain would come first (from this issuer to a single root certificate) - before any parallel, alternate chains appear.

- This field is especially useful for cross-signed intermediates within - OpenBao. Because each cross-signed intermediate will only know of the - one root, but issuance should serve both, update the issuers' entries - with the desired `manual_chain` value.

- The CA Chain returned by a GET to the issuer configuration is the same - chain presented during signing and (if this issuer is the default) on - the `/ca_chain` path. Setting `manual_chain` thus allows controlling - the presented chain as desired. +:::warning + +Note: the `manual_chain` field is an advanced field useful when automatic +chain building isn't desired. The first element _must_ be the present +issuer's reference. Subsequent references _should_ validate previous +entries, terminating with a root certificate. _Ideally_ a single linear +chain would come first (from this issuer to a single root certificate) +before any parallel, alternate chains appear.

+This field is especially useful for cross-signed intermediates within +OpenBao. Because each cross-signed intermediate will only know of the +one root, but issuance should serve both, update the issuers' entries +with the desired `manual_chain` value.

+The CA Chain returned by a GET to the issuer configuration is the same +chain presented during signing and (if this issuer is the default) on +the `/ca_chain` path. Setting `manual_chain` thus allows controlling +the presented chain as desired. + +::: - `usage` `([]string: read-only,issuing-certificates,crl-signing,ocsp-signing)` - Allowed usages for this issuer. Valid options are: @@ -2517,14 +2733,18 @@ do so, import a new issuer and a new `issuer_id` will be assigned. cannot be set unless that KeyUsage is allowed on the x509 certificate. - `ocsp-signing`, to allow this issuer to be used for signing OCSP responses -~> Note: The `usage` field allows for a soft-delete capability on the issuer, - or to prevent use of the issuer prior to it being enabled. For example, - as issuance is rotated to a new issuer, the old issuer could be marked - `usage=read-only,crl-signing,ocsp-signing`, allowing existing certificates to be revoked - (and the CRL updated), but preventing new certificate issuance. After all - certificates issued under this certificate have expired, this certificate - could be marked `usage=read-only`, freezing the CRL. Finally, after a grace - period, the issuer could be deleted. +:::warning + +Note: The `usage` field allows for a soft-delete capability on the issuer, +or to prevent use of the issuer prior to it being enabled. For example, +as issuance is rotated to a new issuer, the old issuer could be marked +`usage=read-only,crl-signing,ocsp-signing`, allowing existing certificates to be revoked +(and the CRL updated), but preventing new certificate issuance. After all +certificates issued under this certificate have expired, this certificate +could be marked `usage=read-only`, freezing the CRL. Finally, after a grace +period, the issuer could be deleted. + +::: - `revocation_signature_algorithm` `(string: "")` - Which signature algorithm to use when building CRLs. See Go's [`x509.SignatureAlgorithm`](https://pkg.go.dev/crypto/x509#SignatureAlgorithm) @@ -2533,8 +2753,12 @@ do so, import a new issuer and a new `issuer_id` will be assigned. is for Go to select the signature algorithm automatically, which may not always work. -~> Note: This can fail if the underlying key does not support the requested - signature algorithm; this may not always be known at modification time. +:::warning + +Note: This can fail if the underlying key does not support the requested +signature algorithm; this may not always be known at modification time. + +::: - `issuing_certificates` `(array: nil)` - Specifies the URL values for the Issuing Certificate field. This can be an array or a comma-separated @@ -2546,11 +2770,15 @@ do so, import a new issuer and a new `issuer_id` will be assigned. comma-separated string list. See also [RFC 5280 Section 4.2.1.13](https://datatracker.ietf.org/doc/html/rfc5280#section-4.2.1.13) for information about the CRL Distribution Points field. -~> Note: When multiple issuers are in use under a single mount, each issuer will - have its own CRL distribution point. These separate CRLs should either be - aggregated into a single CRL (externally; as OpenBao does not support this - functionality) or multiple `crl_distribution_points` should be specified - here, pointing to each cluster and issuer. +:::warning + +Note: When multiple issuers are in use under a single mount, each issuer will +have its own CRL distribution point. These separate CRLs should either be +aggregated into a single CRL (externally; as OpenBao does not support this +functionality) or multiple `crl_distribution_points` should be specified +here, pointing to each cluster and issuer. + +::: - `ocsp_servers` `(array: nil)` - Specifies the URL values for the OCSP Servers field. This can be an array or a comma-separated string list. See also @@ -2566,8 +2794,12 @@ do so, import a new issuer and a new `issuer_id` will be assigned. literal value `{{cluster_aia_path}}` with the value of `aia_path` from the cluster-local configuration endpoint `/config/cluster`. -~> **Note**: If no cluster-local address is present and templating is used, - issuance will fail. +:::warning + +**Note**: If no cluster-local address is present and templating is used, +issuance will fail. + +::: #### Sample payload @@ -2620,15 +2852,23 @@ have signed this issuer's certificate. This will cause all CRLs to be rebuilt. This is mostly provided for book-keeping and as a soft-delete feature, to ensure this issuer is not accidentally reused in the future. -~> **Warning**: This operation cannot be undone! +:::warning -~> Note: This operation **does not** have any impact on other clusters or - mounts and **may not** have any impact on whether clients consider these - issuers revoked. Revoked issuers will not appear on their own CRLs. Revoked - issuers may not appear on other CRLs if a suitable parent is not present in - the same mount point. Revoked issuers will still need to be revoked in any - other mounts they appear in, both as issuers, in the event of issuer reuse, - and as issued certificates, in the event of an external parent mount. +**Warning**: This operation cannot be undone! + +::: + +:::warning + +Note: This operation **does not** have any impact on other clusters or +mounts and **may not** have any impact on whether clients consider these +issuers revoked. Revoked issuers will not appear on their own CRLs. Revoked +issuers may not appear on other CRLs if a suitable parent is not present in +the same mount point. Revoked issuers will still need to be revoked in any +other mounts they appear in, both as issuers, in the event of issuer reuse, +and as issued certificates, in the event of an external parent mount. + +::: | Method | Path | | :------ | :------------------------------- | @@ -2673,10 +2913,14 @@ $ curl \ This endpoint deletes the specified issuer. A warning is emitted and the default is cleared if this issuer is the default issuer. -~> **Note**: If an issuer is incorrectly deleted, but its key material - remains, it is possible to re-import just the issuer certificate. The - `issuer_id` will change, but the name can be re-assigned to the new - issuer. +:::warning + +**Note**: If an issuer is incorrectly deleted, but its key material +remains, it is possible to re-import just the issuer certificate. The +`issuer_id` will change, but the name can be re-assigned to the new +issuer. + +::: | Method | Path | | :------- | :------------------------ | @@ -2696,8 +2940,12 @@ $ curl \ This endpoint allows an operator to import a single pem encoded `rsa`, `ec`, or `ed25519` key. -~> **Note**: This API does not protect against importing keys using insecure combinations of - algorithm and key length. +:::warning + +**Note**: This API does not protect against importing keys using insecure combinations of +algorithm and key length. + +::: | Method | Path | |:-------|:-------------------| @@ -2746,8 +2994,12 @@ $ curl \ This endpoint allows an operator to fetch information about an existing key. -~> **Note**: OpenBao does not allow reading the value of the private key after - it has been created. +:::warning + +**Note**: OpenBao does not allow reading the value of the private key after +it has been created. + +::: | Method | Path | | :----- | :------------------ | @@ -2792,9 +3044,13 @@ do so, import a new key and a new `key_id` will be assigned. | :----- | :------------------ | | `POST` | `/pki/key/:key_ref` | -~> **Note** `POST`ing to this endpoint causes OpenBao to overwrite the previous - contents of the key, using the provided request data (and any defaults - for elided parameters). It does not update only the provided fields. +:::warning + +**Note** `POST`ing to this endpoint causes OpenBao to overwrite the previous +contents of the key, using the provided request data (and any defaults +for elided parameters). It does not update only the provided fields. + +::: #### Parameters @@ -2842,14 +3098,18 @@ $ curl \ This endpoint deletes the specified key. A warning is emitted and the default is cleared if this key is the default key. -~> **Note**: Because OpenBao does not allow exporting the private key - after it is initially generated, deletion of keys is a sensitive - operation. Additionally, one key may be used by more than one issuer. - As a result, OpenBao prohibits deletion of keys until **all** issuers - using this key have also been deleted. If these issuers are still - necessary for chain building, re-import them without the corresponding - keys after the key has been deleted or use the soft-delete feature - of issuers. +:::warning + +**Note**: Because OpenBao does not allow exporting the private key +after it is initially generated, deletion of keys is a sensitive +operation. Additionally, one key may be used by more than one issuer. +As a result, OpenBao prohibits deletion of keys until **all** issuers +using this key have also been deleted. If these issuers are still +necessary for chain building, re-import them without the corresponding +keys after the key has been deleted or use the soft-delete feature +of issuers. + +::: | Method | Path | | :------- | :------------------ | @@ -2913,13 +3173,17 @@ request is denied. | `POST` | `/pki/roles/:name` | | `PATCH` | `/pki/roles/:name` | -~> **Note** `POST`ing to this endpoint when the role already exists causes - OpenBao to overwrite the contents of the role, using the provided request - data (and any defaults for elided parameters). It does not update only - the provided fields.

- OpenBao supports the PATCH operation to this endpoint, using the [JSON patch - format](https://datatracker.ietf.org/doc/html/rfc6902) supported by KVv2, - allowing update of specific fields. Note that `bao write` uses `POST`. +:::warning + +**Note** `POST`ing to this endpoint when the role already exists causes +OpenBao to overwrite the contents of the role, using the provided request +data (and any defaults for elided parameters). It does not update only +the provided fields.

+OpenBao supports the PATCH operation to this endpoint, using the [JSON patch +format](https://datatracker.ietf.org/doc/html/rfc6902) supported by KVv2, +allowing update of specific fields. Note that `bao write` uses `POST`. + +::: #### Parameters @@ -2931,12 +3195,20 @@ request is denied. prevent access to the `/pki/issuer/:issuer_ref/{issue,sign}/:name` paths to prevent users overriding the role's `issuer_ref` value. -~> Note: This parameter is stored as-is; if the reference is to a name, it - is **not** resolve to an identifier. Deletion of issuers (or updating their - names) **may** result in issuance failing or using an unexpected issuer. +:::warning + +Note: This parameter is stored as-is; if the reference is to a name, it +is **not** resolve to an identifier. Deletion of issuers (or updating their +names) **may** result in issuance failing or using an unexpected issuer. + +::: -~> **Note**: existing roles from previous OpenBao versions are migrated to use - the `issuer_ref=default`. +:::warning + +**Note**: existing roles from previous OpenBao versions are migrated to use +the `issuer_ref=default`. + +::: - `ttl` `(string: "")` - Specifies the Time To Live value to be used for the validity period of the requested certificate, provided as a string duration @@ -2953,10 +3225,14 @@ request is denied. certificates for `localhost` as one of the requested common names. This is useful for testing and to allow clients on a single host to talk securely. -~> **Note**: This strictly applies to `localhost` and `localdomain` when this - option is enabled. Additionally, even if this option is disabled, if either - name is included in `allowed_domains`, the match rules for that option - could permit issuance of a certificate for `localhost`. +:::warning + +**Note**: This strictly applies to `localhost` and `localdomain` when this +option is enabled. Additionally, even if this option is disabled, if either +name is included in `allowed_domains`, the match rules for that option +could permit issuance of a certificate for `localhost`. + +::: - `allowed_domains` `(list: [])` - Specifies the domains this role is allowed to issue certificates for. This is used with the `allow_bare_domains`, @@ -2965,17 +3241,21 @@ request is denied. SAN entries, and Email-typed SAN entries. When `allow_any_name` is used, this attribute has no effect. -~> **Note**: The three options `allow_bare_domains`, `allow_subdomains`, and - `allow_glob_domains` are each independent of each other. That is, at least - one type of allowed matching must describe the relationship between the - `allowed_domains` list and the names on the issued certificate. For example, - given `allowed_domain=foo.*.example.com` and `allow_subdomains=true` and - `allow_glob_domains=true`, a request for `bar.foo.baz.example.com` won't - be permitted, even though it `foo.baz.example.com` matches the glob - `foo.*.example.com` and `bar` is a subdomain of that. +:::warning + +**Note**: The three options `allow_bare_domains`, `allow_subdomains`, and +`allow_glob_domains` are each independent of each other. That is, at least +one type of allowed matching must describe the relationship between the +`allowed_domains` list and the names on the issued certificate. For example, +given `allowed_domain=foo.*.example.com` and `allow_subdomains=true` and +`allow_glob_domains=true`, a request for `bar.foo.baz.example.com` won't +be permitted, even though it `foo.baz.example.com` matches the glob +`foo.*.example.com` and `bar` is a subdomain of that. + +::: - `allowed_domains_template` `(bool: false)` - When set, `allowed_domains` - may contain templates, as with [ACL Path Templating](/vault/docs/concepts/policies). + may contain templates, as with [ACL Path Templating](/docs/concepts/policies). Non-templated domains are also still permitted. - `allow_bare_domains` `(bool: false)` - Specifies if clients can request @@ -3001,16 +3281,24 @@ request is denied. will be allowed to request certificates with names matching the glob patterns. -~> **Note**: These globs behave like shell-style globs and can match - across multiple domain parts. For example, `allowed_domains=*.example.com` - with `allow_glob_domains` enabled will match not only `foo.example.com` but - also `baz.bar.foo.example.com`. +:::warning -~> **Warning**: Glob patterns will match wildcard domains and permit their - issuance unless otherwise restricted by `allow_wildcard_certificates`. For - instance, with `allowed_domains=*.*.example.com` and both `allow_glob_domains` - and `allow_wildcard_certificates` enabled, we will permit the issuance of - a wildcard certificate for `*.foo.example.com`. +**Note**: These globs behave like shell-style globs and can match +across multiple domain parts. For example, `allowed_domains=*.example.com` +with `allow_glob_domains` enabled will match not only `foo.example.com` but +also `baz.bar.foo.example.com`. + +::: + +:::warning + +**Warning**: Glob patterns will match wildcard domains and permit their +issuance unless otherwise restricted by `allow_wildcard_certificates`. For +instance, with `allowed_domains=*.*.example.com` and both `allow_glob_domains` +and `allow_wildcard_certificates` enabled, we will permit the issuance of +a wildcard certificate for `*.foo.example.com`. + +::: - `allow_wildcard_certificates` `(bool: true)` - Allows the issuance of certificates with [RFC 6125](https://tools.ietf.org/html/rfc6125) wildcards @@ -3043,7 +3331,7 @@ request is denied. `spiffe://hostname/*`). - `allowed_uri_sans_template` `(bool: false)` - When set, `allowed_uri_sans` - may contain templates, as with [ACL Path Templating](/vault/docs/concepts/policies). + may contain templates, as with [ACL Path Templating](/docs/concepts/policies). Non-templated domains are also still permitted. - `allowed_other_sans` `(string: "")` - Defines allowed custom OID/UTF8-string @@ -3083,8 +3371,12 @@ request is denied. When `any` is used, this role cannot generate certificates and can only be used to sign CSRs. -~> **Note**: In FIPS 140-2 mode, the following algorithms are not certified - and thus should not be used: `ed25519`. +:::warning + +**Note**: In FIPS 140-2 mode, the following algorithms are not certified +and thus should not be used: `ed25519`. + +::: - `key_bits` `(int: 0)` - Specifies the number of bits to use for the generated keys. Allowed values are 0 (universal default); with @@ -3099,9 +3391,13 @@ request is denied. on issuer's key length (SHA-2-256 for RSA keys, and matching the curve size for NIST P-Curves). -~> **Note**: ECDSA and Ed25519 issuers do not follow configuration of the - `signature_bits` value; only RSA issuers will change signature types - based on this parameter. +:::warning + +**Note**: ECDSA and Ed25519 issuers do not follow configuration of the +`signature_bits` value; only RSA issuers will change signature types +based on this parameter. + +::: - `use_pss` `(bool: false)` - Specifies whether or not to use PSS signatures over PKCS#1v1.5 signatures when a RSA-type issuer is used. Ignored for @@ -3310,13 +3606,17 @@ parameter. | :----- | :----------------- | | `POST` | `/pki/config/urls` | -~> **Note**: When using multiple issuers within the same mount, it is strongly - suggested to use the per-issuer AIA information instead of the global - AIA information. If any of the per-issuer AIA fields are set, the entire - issuer's preferences will be used instead. Otherwise, these fields are used - as a fallback.

- This can be achieved by using _templated_ global AIA values, but setting - the cluster-local address in configuration. +:::warning + +**Note**: When using multiple issuers within the same mount, it is strongly +suggested to use the per-issuer AIA information instead of the global +AIA information. If any of the per-issuer AIA fields are set, the entire +issuer's preferences will be used instead. Otherwise, these fields are used +as a fallback.

+This can be achieved by using _templated_ global AIA values, but setting +the cluster-local address in configuration. + +::: #### Parameters @@ -3330,11 +3630,15 @@ parameter. comma-separated string list. See also [RFC 5280 Section 4.2.1.13](https://datatracker.ietf.org/doc/html/rfc5280#section-4.2.1.13) for information about the CRL Distribution Points field. -~> Note: When multiple issuers are in use under a single mount, each issuer will - have its own CRL distribution point. These separate CRLs should either be - aggregated into a single CRL (externally; as OpenBao does not support this - functionality) or multiple `crl_distribution_points` should be specified - here, pointing to each cluster and issuer. +:::warning + +Note: When multiple issuers are in use under a single mount, each issuer will +have its own CRL distribution point. These separate CRLs should either be +aggregated into a single CRL (externally; as OpenBao does not support this +functionality) or multiple `crl_distribution_points` should be specified +here, pointing to each cluster and issuer. + +::: - `ocsp_servers` `(array: nil)` - Specifies the URL values for the OCSP Servers field. This can be an array or a comma-separated string list. See also @@ -3359,8 +3663,12 @@ parameter. - `crl_distribution_points={{cluster_aia_path}}/issuer/{{issuer_id}}/crl/der` - `ocsp_servers={{cluster_aia_path}}/ocsp` -~> **Note**: If no cluster-local address is present and templating is used, - issuance will fail. +:::warning + +**Note**: If no cluster-local address is present and templating is used, +issuance will fail. + +::: #### Sample payload @@ -3440,10 +3748,14 @@ This endpoint allows setting the value of the default issuer. generation) will become the default and it will look (to anyone strictly using old APIs) that it is the only issuer in the mount. However, it is encouraged for applications to update to the newer, safer semantics - associated with [multi-issuer rotation](/vault/docs/secrets/pki/rotation-primitives). + associated with [multi-issuer rotation](/docs/secrets/pki/rotation-primitives). + +:::warning + +Note: When an import creates more than one new issuer with key material +known to this mount, no default update will occur. -~> Note: When an import creates more than one new issuer with key material - known to this mount, no default update will occur. +::: #### Sample payload @@ -3682,27 +3994,43 @@ CRL for any request. If enabled, it will re-build the CRL. If the `ocsp_disable` key is set to `true`, the OCSP responder will always respond with an Unauthorized OCSP response to any request. -~> **Note**: This parameter is global, across all clusters and issuers. Use - the per-issuer `usage` field to disable CRL building for a specific - issuer, while leaving the global CRL building enabled. +:::warning -~> Note: Disabling the CRL does not affect whether revoked certificates are +**Note**: This parameter is global, across all clusters and issuers. Use +the per-issuer `usage` field to disable CRL building for a specific +issuer, while leaving the global CRL building enabled. + +::: + +:::warning + +Note: Disabling the CRL does not affect whether revoked certificates are stored internally. Certificates that have been revoked when a role's certificate storage is enabled will continue to be marked and stored as revoked until `tidy` has been run with the desired safety buffer. Re-enabling CRL generation will then result in all such certificates becoming a part of the CRL. -~> Note: Enabling automatic rebuilding of CRLs disables immediate regeneration - on revocation. This is in line with the behavior of other CAs which only - rebuild CRLs periodically. We suggest manually hitting the rotate if a - fresh CRL is necessary after a revocation. For the most part though, CRLs - should not be relied upon for the latest certificate status information, - and OCSP should be used instead. +::: + +:::warning + +Note: Enabling automatic rebuilding of CRLs disables immediate regeneration +on revocation. This is in line with the behavior of other CAs which only +rebuild CRLs periodically. We suggest manually hitting the rotate if a +fresh CRL is necessary after a revocation. For the most part though, CRLs +should not be relied upon for the latest certificate status information, +and OCSP should be used instead. + +::: -~> Note: The periodic function which controls automatic rebuilding of CRLs - and delta CRLs only executes once a minute; this prevents high system load - but limits the granularity of the temporal options below. +:::warning + +Note: The periodic function which controls automatic rebuilding of CRLs +and delta CRLs only executes once a minute; this prevents high system load +but limits the granularity of the temporal options below. + +::: | Method | Path | | :----- | :---------------- | @@ -3773,19 +4101,27 @@ has expired or is close to expiring, administrators **must** hit this endpoint to manually rotate the CRL. This rotates all CRLs on the present cluster, and **must** be called on every cluster. -~> **Note**: Mirroring the behavior of earlier OpenBao versions, we add - certificates revoked by an unknown issuer to the default issuer's CRL. - To fully purge old revoked, unexpired certificates, it is not sufficient - to delete their issuer and is instead necessary to **remove** the mount - completely. +:::warning + +**Note**: Mirroring the behavior of earlier OpenBao versions, we add +certificates revoked by an unknown issuer to the default issuer's CRL. +To fully purge old revoked, unexpired certificates, it is not sufficient +to delete their issuer and is instead necessary to **remove** the mount +completely. + +::: + +:::warning + +**Note**: It is suggested to switch to enabling the CRL's `auto_rebuild` +functionality to avoid having to manually hit the Rotate endpoint when the +CRL expires. This ensures a valid CRL is always maintained, at the expense of +potentially not being up-to-date. If a revocation occurs that must be +immediately propagated, this endpoint can be used to regenerate the CRL, +though distribution must still occur outside of OpenBao (either manually or +via AIA where supported). -~> **Note**: It is suggested to switch to enabling the CRL's `auto_rebuild` - functionality to avoid having to manually hit the Rotate endpoint when the - CRL expires. This ensures a valid CRL is always maintained, at the expense of - potentially not being up-to-date. If a revocation occurs that must be - immediately propagated, this endpoint can be used to regenerate the CRL, - though distribution must still occur outside of OpenBao (either manually or - via AIA where supported). +::: | Method | Path | | :----- | :---------------- | @@ -3944,10 +4280,14 @@ source and signed by the specified issuer. Values are taken verbatim from the pa - `critical` `(type: bool)` - should the extension be marked critical - `value` `(type: string)` - base64 encoded bytes for extension value -~> **Note**:: The following extension ids are not allowed to be provided and can be influenced by other parameters - - `2.5.29.20`: CRL Number - - `2.5.29.27`: Delta CRL - - `2.5.29.35`: Authority Key Identifier +:::warning + +**Note**: The following extension ids are not allowed to be provided and can be influenced by other parameters +- `2.5.29.20`: CRL Number +- `2.5.29.27`: Delta CRL +- `2.5.29.35`: Authority Key Identifier + +::: #### Sample payload @@ -3999,8 +4339,12 @@ expiration time. | :----- | :---------- | | `POST` | `/pki/tidy` | -~> Note: it is encouraged to use the [automatic tidy capabilities](#configure-automatic-tidy) - to ensure this gets run periodically. +:::warning + +Note: it is encouraged to use the [automatic tidy capabilities](#configure-automatic-tidy) +to ensure this gets run periodically. + +::: #### Parameters @@ -4018,23 +4362,31 @@ expiration time. performance of OCSP and CRL building, by shifting work to a tidy operation instead. -~> Note: With multiple issuers, a CA which issued a particular revoked - certificate may be removed and re-added, resulting in a different issuer - ID value. When building CRLs, these links are automatically updated for any - missing or added issuers, but during OCSP this value is computed and then - discarded, potentially causing a performance penalty on each request. - During regular CA operations, it is not necessary to run this operation. -

- It is suggested to run this tidy when removing or importing new issuers but - otherwise not to run it during automatic tidy operations. +:::warning + +Note: With multiple issuers, a CA which issued a particular revoked +certificate may be removed and re-added, resulting in a different issuer +ID value. When building CRLs, these links are automatically updated for any +missing or added issuers, but during OCSP this value is computed and then +discarded, potentially causing a performance penalty on each request. +During regular CA operations, it is not necessary to run this operation. +

+It is suggested to run this tidy when removing or importing new issuers but +otherwise not to run it during automatic tidy operations. + +::: - `tidy_expired_issuers` `(bool: false)` - Set to true to automatically remove expired issuers after the `issuer_safety_buffer` duration has elapsed. We log the issuer certificate on removal to allow recovery; no keys are removed during this process. -~> Note: The default issuer will not be removed even if it has expired and is - past the `issuer_safety_buffer` specified. +:::warning + +Note: The default issuer will not be removed even if it has expired and is +past the `issuer_safety_buffer` specified. + +::: - `tidy_move_legacy_ca_bundle` `(bool: false)` - Set to true to backup any legacy CA/issuers bundle to `config/ca_bundle.bak`. This can be restored with @@ -4043,7 +4395,7 @@ expiration time. issuers if present). Migration will only occur after `issuer_safety_buffer` has passed since the last successful migration. -- `safety_buffer` `(string: "")` - Specifies a duration using [duration format strings](/vault/docs/concepts/duration-format) +- `safety_buffer` `(string: "")` - Specifies a duration using [duration format strings](/docs/concepts/duration-format) used as a safety buffer to ensure certificates are not expunged prematurely; as an example, this can keep certificates from being removed from the CRL that, due to clock skew, might still be considered valid on other hosts. For a certificate to be expunged, @@ -4064,10 +4416,14 @@ expiration time. Does not affect `tidy_expired_issuers`. -~> Note: Using too long of a `pause_duration` can result in tidy operations - not concluding during this lifetime! Using too short of a pause duration - (but non-zero) can lead to lock contention. Use [tidy's cancellation](#cancel-tidy) - to stop a running operation after the sleep period is over. +:::warning + +Note: Using too long of a `pause_duration` can result in tidy operations +not concluding during this lifetime! Using too short of a pause duration +(but non-zero) can lead to lock contention. Use [tidy's cancellation](#cancel-tidy) +to stop a running operation after the sleep period is over. + +::: - `revocation_queue_safety_buffer` `(string: "")` - Specifies a duration after which cross-cluster revocation requests will be removed as expired. @@ -4189,10 +4545,14 @@ The below parameters are in addition to the regular parameters accepted by the throughout operations like issuance, revocation, and subsequent tidies, the figure is updated. -~> *Note*: It is strongly recommend to not enable this value if 50k or more - certificates are stored in the mount or if many PKI mounts are in use in - this cluster. Instead, use audit logs and aggregate this data externally - to OpenBao so as not to impact OpenBao performance. +:::warning + +*Note*: It is strongly recommend to not enable this value if 50k or more +certificates are stored in the mount or if many PKI mounts are in use in +this cluster. Instead, use audit logs and aggregate this data externally +to OpenBao so as not to impact OpenBao performance. + +::: - `publish_stored_certificate_count_metrics` `(bool: false)` - When enabled, publishes the value computed by `maintain_stored_certificate_counts` to @@ -4324,7 +4684,7 @@ $ curl \ ## Cluster scalability -See [PKI Cluster Scalability](/vault/docs/secrets/pki/considerations#cluster-scalability) in the considerations page. +See [PKI Cluster Scalability](/docs/secrets/pki/considerations#cluster-scalability) in the considerations page. ## OpenBao CLI with DER/PEM responses diff --git a/website/content/api-docs/secret/rabbitmq.mdx b/website/content/api-docs/secret/rabbitmq.mdx index 2a8030ec57..a4e4e4b1e9 100644 --- a/website/content/api-docs/secret/rabbitmq.mdx +++ b/website/content/api-docs/secret/rabbitmq.mdx @@ -1,14 +1,15 @@ --- -layout: api -page_title: RabbitMQ - Secrets Engines - HTTP API +sidebar_label: RabbitMQ description: This is the API documentation for the OpenBao RabbitMQ secrets engine. --- +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; # RabbitMQ secrets engine (API) This is the API documentation for the OpenBao RabbitMQ secrets engine. For general information about the usage and operation of the RabbitMQ secrets engine, please -see the [RabbitMQ documentation](/vault/docs/secrets/rabbitmq). +see the [RabbitMQ documentation](/docs/secrets/rabbitmq). This documentation assumes the RabbitMQ secrets engine is enabled at the `/rabbitmq` path in OpenBao. Since it is possible to enable secrets engines at any @@ -33,10 +34,10 @@ RabbitMQ. - `verify_connection` `(bool: true)` – Specifies whether to verify connection URI, username, and password. -- `password_policy` `(string: "")` - Specifies a [password policy](/vault/docs/concepts/password-policies) to +- `password_policy` `(string: "")` - Specifies a [password policy](/docs/concepts/password-policies) to use when creating dynamic credentials. Defaults to generating an alphanumeric password if not set. -- `username_template` `(string)` - [Template](/vault/docs/concepts/username-templating) describing how +- `username_template` `(string)` - [Template](/docs/concepts/username-templating) describing how dynamic usernames are generated. ### Sample payload @@ -53,7 +54,7 @@ RabbitMQ. ### Sample request - + ```shell-session $ curl \ @@ -63,8 +64,8 @@ $ curl \ http://127.0.0.1:8200/v1/rabbitmq/config/connection ``` - - + + ```shell-session $ openbao write rabbitmq/config/connection \ @@ -74,7 +75,7 @@ $ openbao write rabbitmq/config/connection \ password_policy="rabbitmq_policy" ``` - + ## Configure lease @@ -103,7 +104,7 @@ This endpoint configures the lease settings for generated credentials. ### Sample request - + ```shell-session $ curl \ @@ -113,8 +114,8 @@ $ curl \ http://127.0.0.1:8200/v1/rabbitmq/config/lease ``` - - + + ```shell-session $ openbao write rabbitmq/config/lease \ @@ -122,7 +123,7 @@ $ openbao write rabbitmq/config/lease \ max_ttl=3600 ``` - + ## Create role @@ -159,7 +160,7 @@ This endpoint creates or updates the role definition. ### Sample request - + ```shell-session $ curl \ @@ -169,8 +170,8 @@ $ curl \ http://127.0.0.1:8200/v1/rabbitmq/roles/my-role ``` - - + + ```shell-session $ openbao write rabbitmq/roles/my-role \ @@ -179,7 +180,7 @@ $ openbao write rabbitmq/roles/my-role \ vhost_topics="..." ``` - + ## Read role @@ -198,7 +199,7 @@ This endpoint queries the role definition. ### Sample request - + ```shell-session $ curl \ @@ -206,14 +207,14 @@ $ curl \ http://127.0.0.1:8200/v1/rabbitmq/roles/my-role ``` - - + + ```shell-session $ openbao read rabbitmq/roles/my-role ``` - + ### Sample response @@ -244,7 +245,7 @@ This endpoint deletes the role definition. ### Sample request - + ```shell-session $ curl \ @@ -253,14 +254,14 @@ $ curl \ http://127.0.0.1:8200/v1/rabbitmq/roles/my-role ``` - - + + ```shell-session openbao delete rabbitmq/roles/my-role ``` - + ## Generate credentials @@ -280,7 +281,7 @@ role. ### Sample request - + ```shell-session $ curl \ @@ -288,14 +289,14 @@ $ curl \ http://127.0.0.1:8200/v1/rabbitmq/creds/my-role ``` - - + + ```shell-session $ openbao read rabbitmq/creds/my-role ``` - + ### Sample response diff --git a/website/content/api-docs/secret/ssh.mdx b/website/content/api-docs/secret/ssh.mdx index f035a0dca6..e73d2983b3 100644 --- a/website/content/api-docs/secret/ssh.mdx +++ b/website/content/api-docs/secret/ssh.mdx @@ -1,6 +1,5 @@ --- -layout: api -page_title: SSH - Secrets Engines - HTTP API +sidebar_label: SSH description: This is the API documentation for the OpenBao SSH secrets engine. --- @@ -8,7 +7,7 @@ description: This is the API documentation for the OpenBao SSH secrets engine. This is the API documentation for the OpenBao SSH secrets engine. For general information about the usage and operation of the SSH secrets engine, please see -the [SSH documentation](/vault/docs/secrets/ssh). +the [SSH documentation](/docs/secrets/ssh). This documentation assumes the SSH secrets engine is enabled at the `/ssh` path in OpenBao. Since it is possible to enable secrets engines at any location, please @@ -141,10 +140,10 @@ This endpoint creates or updates a named role. - `key_id_format` `(string: "")` – When supplied, this value specifies a custom format for the key id of a signed certificate. The following variables are - available for use: '{{token_display_name}}' - The display name of the token used - to make the request. '{{role_name}}' - The name of the role signing the request. - '{{public_key_hash}}' - A SHA256 checksum of the public key that is being signed. - e.g. "custom-keyid-{{token_display_name}}" + available for use: '\{\{token_display_name}}' - The display name of the token used + to make the request. '\{\{role_name}}' - The name of the role signing the request. + '\{\{public_key_hash}}' - A SHA256 checksum of the public key that is being signed. + e.g. "custom-keyid-\{\{token_display_name}}" - `allowed_user_key_lengths` `(map: "")` – Specifies a map of ssh key types and their expected sizes which are allowed to be signed by @@ -165,27 +164,39 @@ This endpoint creates or updates a named role. with `ecdsa-sha2-nistp256` or `ed25519`), the value of the length is ignored (and can be zero). - ~> **Note**: In FIPS 140-2 mode, the following algorithms are not certified +:::warning + + **Note**: In FIPS 140-2 mode, the following algorithms are not certified and thus should not be used: `ed25519`. +::: + - `algorithm_signer` `(string: "default")` - Algorithm to sign keys with. Valid values are `ssh-rsa`, `rsa-sha2-256`, `rsa-sha2-512`, or `default`. This value may also be left blank to use the signer's default algorithm, and must be left blank or have value `default` for CA key types other than RSA. - ~> **Note**: The value of `default` may change over time as vulnerabilities +:::warning + + **Note**: The value of `default` may change over time as vulnerabilities in algorithms are discovered. The present value for RSA keys is equivalent to `rsa-sha2-256`. - ~> **Warning**: The `algorithm_signer` value `ssh-rsa` uses the SHA-1 hash +::: + +:::warning + + **Warning**: The `algorithm_signer` value `ssh-rsa` uses the SHA-1 hash algorithm. This algorithm is now considered insecure and is not supported by current OpenSSH versions. As a result, OpenBao has made the new default `rsa-sha2-256` for RSA CA keys. It is strongly encouraged for all users to migrate to `rsa-sha2-256` or `default` if the role was created with an explicit `algorithm_signer=rsa-sha` parameter or has been migrated to such. +::: + - `not_before_duration` `(duration: "30s")` – Specifies the duration by which to - backdate the `ValidAfter` property. Uses [duration format strings](/vault/docs/concepts/duration-format). + backdate the `ValidAfter` property. Uses [duration format strings](/docs/concepts/duration-format). ### Sample payload @@ -582,9 +593,13 @@ overridden._ `ecdsa-sha2-nistp384`, `ecdsa-sha2-nistp521`, or `ssh-ed25519`) or an algorithm (`rsa`, `ec`, or `ed25519`). - ~> **Note**: In FIPS 140-2 mode, the following algorithms are not certified +:::warning + + **Note**: In FIPS 140-2 mode, the following algorithms are not certified and thus should not be used: `ed25519`. +::: + - `key_bits` `(int: 0)` - Specifies the desired key bits for the generated SSH CA key when `generate_signing_key` is set to `true`. This is only used for variable length keys (such as `ssh-rsa`, where the value of `key_bits` @@ -652,10 +667,14 @@ $ curl \ This endpoint returns the configured/generated public key. This is an unauthenticated endpoint. -~> Note: this is a raw response endpoint without JSON encoding; use +:::warning + +Note: this is a raw response endpoint without JSON encoding; use `openbao read -format=raw` or an external tool (e.g., `curl`) to fetch this value. +::: + | Method | Path | Content-Type | | :----- | :---------------- | ---------------- | | `GET` | `/ssh/public_key` | `200 text/plain` | @@ -719,10 +738,14 @@ The issued certificate uses the defaults specified in the role named in this endpoint. Where not restricted by the parameters of this role, the parameters of the issued certificate can be further customized in this API call. -~> **Note**: The issued certificate is returned but _not_ stored by OpenBao. +:::warning + +**Note**: The issued certificate is returned but _not_ stored by OpenBao. If you do not save it from the response, request it again by repeating this request. +::: + | Method | Path | | :----- | :---------------- | | `POST` | `/ssh/sign/:name` | @@ -799,10 +822,14 @@ The issued certificate uses the defaults specified in the role named in this endpoint. Where not restricted by the parameters of this role, the parameters of the issued certificate can be further customized in this API call. -~> **Note**: The issued credentials are returned but _not_ stored by OpenBao. +:::warning + +**Note**: The issued credentials are returned but _not_ stored by OpenBao. If you do not save them from the response, issue new credentials by using this request again. +::: + | Method | Path | | :----- | :---------------- | | `POST` | `/ssh/issue/:name` | @@ -886,12 +913,16 @@ This endpoint removes all existing host keys from OpenBao, if any are present. These keys were used with the Dynamic Keys functionality, which were removed from this engine. -~> Note: This does not clean up any pending dynamic key leases and will not +:::warning + +Note: This does not clean up any pending dynamic key leases and will not remove these keys from systems with authorized hosts entries created by OpenBao. That must be done manually by an operator, potentially before the removal of these host keys if they are necessary to access these systems. +::: + | Method | Path | | :------- | :----------------------- | | `DELETE` | `/ssh/tidy/dynamic-keys` | diff --git a/website/content/api-docs/secret/totp.mdx b/website/content/api-docs/secret/totp.mdx index 96aef64b50..181ae8c378 100644 --- a/website/content/api-docs/secret/totp.mdx +++ b/website/content/api-docs/secret/totp.mdx @@ -1,6 +1,5 @@ --- -layout: api -page_title: TOTP - Secrets Engines - HTTP API +sidebar_label: TOTP description: This is the API documentation for the OpenBao TOTP secrets engine. --- @@ -8,7 +7,7 @@ description: This is the API documentation for the OpenBao TOTP secrets engine. This is the API documentation for the OpenBao TOTP secrets engine. For general information about the usage and operation of the TOTP secrets engine, please see -the [TOTP documentation](/vault/docs/secrets/totp). +the [TOTP documentation](/docs/secrets/totp). This documentation assumes the TOTP secrets engine is enabled at the `/totp` path in OpenBao. Since it is possible to enable secrets engines at any location, diff --git a/website/content/api-docs/secret/transit.mdx b/website/content/api-docs/secret/transit.mdx index e69d291040..765c8a86e6 100644 --- a/website/content/api-docs/secret/transit.mdx +++ b/website/content/api-docs/secret/transit.mdx @@ -1,6 +1,5 @@ --- -layout: api -page_title: Transit - Secrets Engines - HTTP API +sidebar_label: Transit description: This is the API documentation for the OpenBao Transit secrets engine. --- @@ -8,7 +7,7 @@ description: This is the API documentation for the OpenBao Transit secrets engin This is the API documentation for the OpenBao Transit secrets engine. For general information about the usage and operation of the Transit secrets engine, please -see the [transit documentation](/vault/docs/secrets/transit). +see the [transit documentation](/docs/secrets/transit). This documentation assumes the transit secrets engine is enabled at the `/transit` path in OpenBao. Since it is possible to enable secrets engines at any @@ -74,7 +73,7 @@ values set here cannot be changed after key creation. - `auto_rotate_period` `(duration: "0", optional)` – The period at which this key should be rotated automatically. Setting this to "0" (the default) will disable automatic key rotation. This value cannot be shorter than one - hour. Uses [duration format strings](/vault/docs/concepts/duration-format). + hour. Uses [duration format strings](/docs/concepts/duration-format). ### Sample payload @@ -125,7 +124,7 @@ two values: an ephemeral 256-bit AES key wrapped using the wrapping key returned by OpenBao and the encryption of the import key material under the provided AES key. The wrapped AES key should be the first 512 bytes of the ciphertext, and the encrypted key material should be the remaining bytes. -See the BYOK section of the [Transit secrets engine documentation](/vault/docs/secrets/transit#bring-your-own-key-byok) +See the BYOK section of the [Transit secrets engine documentation](/docs/secrets/transit#bring-your-own-key-byok) for more information on constructing the ciphertext. If `public_key` is set, this field is not required. @@ -163,9 +162,13 @@ is available. - `allow_rotation` `(bool: false)` - If set, the imported key can be rotated within OpenBao by using the `rotate` endpoint. -~> **NOTE**: Once an imported key is rotated within OpenBao, it will no longer +:::warning + +**NOTE**: Once an imported key is rotated within OpenBao, it will no longer support importing key material with the `import_version` endpoint. +::: + - `derived` `(bool: false)` – Specifies if key derivation is to be used. If enabled, all encrypt/decrypt requests to this named key must provide a context which is used for key derivation. @@ -218,10 +221,14 @@ imported at a later date. | :----- | :----------------------------------- | | `POST` | `/transit/keys/:name/import_version` | -~> **Note**: Keys whose material was generated by OpenBao do not support +:::warning + +**Note**: Keys whose material was generated by OpenBao do not support importing key material. Only keys that were previously imported into OpenBao can import new key material from an external source. +::: + ### Parameters - `name` `(string: )` – Specifies the name of the encryption key to @@ -232,7 +239,7 @@ two values: an ephemeral 256-bit AES key wrapped using the wrapping key returned by OpenBao and the encryption of the import key material under the provided AES key. The wrapped AES key should be the first 512 bytes of the ciphertext, and the encrypted key material should be the remaining bytes. -See the BYOK section of the [Transit secrets engine documentation](/vault/docs/secrets/transit#bring-your-own-key-byok) +See the BYOK section of the [Transit secrets engine documentation](/docs/secrets/transit#bring-your-own-key-byok) for more information on constructing the ciphertext. - `hash_function` `(string: "SHA256")` - The hash function used for the @@ -443,7 +450,7 @@ are returned during a read operation on the named key.) - `auto_rotate_period` `(duration: "", optional)` – The period at which this key should be rotated automatically. Setting this to "0" will disable automatic key rotation. This value cannot be shorter than one hour. When no value is - provided, the period remains unchanged. Uses [duration format strings](/vault/docs/concepts/duration-format). + provided, the period remains unchanged. Uses [duration format strings](/docs/concepts/duration-format). ### Sample payload @@ -474,10 +481,14 @@ decryption operations. For algorithms with a configurable key size, the rotated key will use the same key size as the previous version. -~> **Note**: For imported keys, rotation is only supported if the +:::warning + +**Note**: For imported keys, rotation is only supported if the `allow_rotation` field was set to `true` on import. Once an imported key is rotated within OpenBao, it will not support further import operations. +::: + | Method | Path | | :----- | :--------------------------- | | `POST` | `/transit/keys/:name/rotate` | @@ -487,9 +498,13 @@ rotated within OpenBao, it will not support further import operations. - `managed_key_name` `(string: "")` - The name of the managed key to use for this transit key. - `managed_key_id` `(string: "")` - The UUID of the managed key to use for this transit key. -~> **Note**: If the key to be rotated is of type `managed_key`, either the `managed_key_name` or +:::warning + +**Note**: If the key to be rotated is of type `managed_key`, either the `managed_key_name` or the `managed_key_id` for the new key must be provided. +::: + ### Sample request ```shell-session @@ -519,7 +534,11 @@ CLI helper utility. wrapping key (from `/transit/wrapping_key`). This is specified as part of the URL. -~> Note: This destination key type must be an RSA key type. +:::warning + +Note: This destination key type must be an RSA key type. + +::: - `source` `(string: )` - Specifies the source key to encrypt, to copy (encrypted) to another cluster. This is specified as part of the URL. @@ -685,9 +704,13 @@ requires derivation depends on whether the context parameter is empty or not). If the user only has `update` capability and the key does not exist, an error will be returned. -~> Note: If upsert is disallowed by global keys configuration, `create` +:::warning + +Note: If upsert is disallowed by global keys configuration, `create` requests will behave like `update` requests. +::: + | Method | Path | | :----- | :----------------------- | | `POST` | `/transit/encrypt/:name` | @@ -765,11 +788,15 @@ will be returned. decrypt) could be indicative of a security breach and should not be ignored. -~>**NOTE:** All plaintext data **must be base64-encoded**. The reason for this +:::warning + +**NOTE:** All plaintext data **must be base64-encoded**. The reason for this requirement is that OpenBao does not require that the plaintext is "text". It could be a binary file such as a PDF or image. The easiest safe transport mechanism for this data as part of a JSON payload is to base64-encode it. +::: + ### Sample payload Fist, encode the plaintext with base64: @@ -787,7 +814,11 @@ Use the base64-encoded plaintext in the payload: } ``` -!> OpenBao HTTP API imposes a maximum request size of 32MB to prevent a denial of service attack. This can be tuned per [`listener` block](/vault/docs/configuration/listener/tcp) in the OpenBao server configuration. +:::danger + +OpenBao HTTP API imposes a maximum request size of 32MB to prevent a denial of service attack. This can be tuned per [`listener` block](/docs/configuration/listener/tcp) in the OpenBao server configuration. + +::: ### Sample request @@ -1109,10 +1140,14 @@ algorithm. - `sha3-384` - `sha3-512` - ~> **Note**: In FIPS 140-2 mode, the following algorithms are not certified +:::warning + + **Note**: In FIPS 140-2 mode, the following algorithms are not certified and thus should not be used: `sha3-224`, `sha3-256`, `sha3-384`, and `sha3-512`. +::: + - `input` `(string: )` – Specifies the **base64 encoded** input data. - `format` `(string: "hex")` – Specifies the output encoding. This can be either @@ -1179,10 +1214,14 @@ be used. - `sha3-384` - `sha3-512` - ~> **Note**: In FIPS 140-2 mode, the following algorithms are not certified +:::warning + + **Note**: In FIPS 140-2 mode, the following algorithms are not certified and thus should not be used: `sha3-224`, `sha3-256`, `sha3-384`, and `sha3-512`. +::: + - `input` `(string: "")` – Specifies the **base64 encoded** input data. One of `input` or `batch_input` must be supplied. @@ -1318,25 +1357,37 @@ supports signing. - `sha3-512` - `none` - ~> **Note**: In FIPS 140-2 mode, the following algorithms are not certified +:::warning + + **Note**: In FIPS 140-2 mode, the following algorithms are not certified and thus should not be used: `sha3-224`, `sha3-256`, `sha3-384`, and `sha3-512`. - ~> ** Warning:** `sha1` should be considered a compromised algorithm and used +::: + +:::warning + + ** Warning:** `sha1` should be considered a compromised algorithm and used only for legacy applications. Signing using SHA-1 can be blocked by operators by assigning the following policy corresponding to a named key: +::: + ```hcl path "/transit/sign/:name/sha1" { capabilities = ["deny"] } ``` - ~> **Note**: using `hash_algorithm=none` requires setting `prehashed=true` +:::warning + + **Note**: using `hash_algorithm=none` requires setting `prehashed=true` and `signature_algorithm=pkcs1v15`. This generates a `PKCSv1_5_NoOID` signature rather than the `PKCSv1_5_DERnull` signature type usually created. See [RFC 3447 Section 9.2](https://www.rfc-editor.org/rfc/rfc3447#section-9.2). +::: + - `input` `(string: "")` – Specifies the **base64 encoded** input data. One of `input` or `batch_input` must be supplied. @@ -1499,26 +1550,38 @@ data. - `sha3-512` - `none` - ~> **Note**: In FIPS 140-2 mode, the following algorithms are not certified +:::warning + + **Note**: In FIPS 140-2 mode, the following algorithms are not certified and thus should not be used: `sha3-224`, `sha3-256`, `sha3-384`, and `sha3-512`. - ~> ** Warning:** `sha1` should be considered a compromised algorithm. Signatures +::: + +:::warning + + ** Warning:** `sha1` should be considered a compromised algorithm. Signatures verified using the algorithm could be forgeries. Verification using SHA-1 can be blocked by operators by assigning the following policy corresponding to a named key: +::: + ```hcl path "/transit/verify/:name/sha1" { capabilities = ["deny"] } ``` - ~> **Note**: using `hash_algorithm=none` requires setting `prehashed=true` +:::warning + + **Note**: using `hash_algorithm=none` requires setting `prehashed=true` and `signature_algorithm=pkcs1v15`. This verifies a `PKCSv1_5_NoOID` signature rather than the `PKCSv1_5_DERnull` signature type usually verified. See [RFC 3447 Section 9.2](https://www.rfc-editor.org/rfc/rfc3447#section-9.2). +::: + - `input` `(string: "")` – Specifies the **base64 encoded** input data. One of `input` or `batch_input` must be supplied. @@ -1702,11 +1765,15 @@ This endpoint restores the backup as a named key. This will restore the key configurations and all the versions of the named key along with HMAC keys. The input to this endpoint should be the output of `/backup` endpoint. -~> For safety, by default the backend will refuse to restore to an existing +:::warning + +For safety, by default the backend will refuse to restore to an existing key. If you want to reuse a key name, it is recommended you delete the key before restoring. It is a good idea to attempt restoring to a different key name first to verify that the operation successfully completes. +::: + | Method | Path | | :----- | :------------------------- | | `POST` | `/transit/restore(/:name)` | diff --git a/website/content/api-docs/system/audit-hash.mdx b/website/content/api-docs/system/audit-hash.mdx index df9b803c7a..28b116e4f7 100644 --- a/website/content/api-docs/system/audit-hash.mdx +++ b/website/content/api-docs/system/audit-hash.mdx @@ -1,6 +1,4 @@ --- -layout: api -page_title: /sys/audit-hash - HTTP API description: |- The `/sys/audit-hash` endpoint is used to hash data using an audit device's hash function and salt. diff --git a/website/content/api-docs/system/audit.mdx b/website/content/api-docs/system/audit.mdx index 64812f2d4b..2d33aa2aaa 100644 --- a/website/content/api-docs/system/audit.mdx +++ b/website/content/api-docs/system/audit.mdx @@ -1,6 +1,4 @@ --- -layout: api -page_title: /sys/audit - HTTP API description: The `/sys/audit` endpoint is used to enable and disable audit devices. --- @@ -65,7 +63,7 @@ single word name or a more complex, nested path. audit device. - `options` `(map: nil)` – Specifies configuration options to pass to the audit device itself. - For more details, please see the relevant page for an audit device `type`, under [Audit Devices docs](/vault/docs/audit). + For more details, please see the relevant page for an audit device `type`, under [Audit Devices docs](/docs/audit). - `type` `(string: )` – Specifies the type of the audit device. Valid types are `file`, `socket` and `syslog`. @@ -95,10 +93,14 @@ $ curl \ This endpoint disables the audit device at the given path. -~> Note: Once an audit device is disabled, you will no longer be able to HMAC values +:::warning + +Note: Once an audit device is disabled, you will no longer be able to HMAC values for comparison with entries in the audit logs. This is true even if you re-enable the audit device at the same path, as a new salt will be created for hashing. +::: + - **`sudo` required** – This endpoint requires `sudo` capability in addition to any path-specific capabilities. diff --git a/website/content/api-docs/system/auth.mdx b/website/content/api-docs/system/auth.mdx index 30ef4df704..e7bda8ef60 100644 --- a/website/content/api-docs/system/auth.mdx +++ b/website/content/api-docs/system/auth.mdx @@ -1,6 +1,4 @@ --- -layout: api -page_title: /sys/auth - HTTP API description: The `/sys/auth` endpoint is used to manage auth methods in OpenBao. --- @@ -101,7 +99,11 @@ For example, enable the "foo" auth method will make it accessible at - `path` `(string: )` – Specifies the path in which to enable the auth method. This is part of the request URL. - !> **NOTE:** Use ASCII printable characters to specify the desired path. +:::danger + + **NOTE:** Use ASCII printable characters to specify the desired path. + +::: - `description` `(string: "")` – Specifies a human-friendly description of the auth method. diff --git a/website/content/api-docs/system/capabilities-accessor.mdx b/website/content/api-docs/system/capabilities-accessor.mdx index ed53ebec28..9140337b0e 100644 --- a/website/content/api-docs/system/capabilities-accessor.mdx +++ b/website/content/api-docs/system/capabilities-accessor.mdx @@ -1,6 +1,4 @@ --- -layout: api -page_title: /sys/capabilities-accessor - HTTP API description: |- The `/sys/capabilities-accessor` endpoint is used to fetch the capabilities of the token associated with an accessor, on the given paths. diff --git a/website/content/api-docs/system/capabilities-self.mdx b/website/content/api-docs/system/capabilities-self.mdx index a53f984ee9..f50699e64f 100644 --- a/website/content/api-docs/system/capabilities-self.mdx +++ b/website/content/api-docs/system/capabilities-self.mdx @@ -1,6 +1,4 @@ --- -layout: api -page_title: /sys/capabilities-self - HTTP API description: |- The `/sys/capabilities-self` endpoint is used to fetch the capabilities of client token on the given paths. diff --git a/website/content/api-docs/system/capabilities.mdx b/website/content/api-docs/system/capabilities.mdx index db06f11810..467766ae90 100644 --- a/website/content/api-docs/system/capabilities.mdx +++ b/website/content/api-docs/system/capabilities.mdx @@ -1,6 +1,4 @@ --- -layout: api -page_title: /sys/capabilities - HTTP API description: |- The `/sys/capabilities` endpoint is used to fetch the capabilities of a token on the given paths. diff --git a/website/content/api-docs/system/config-auditing.mdx b/website/content/api-docs/system/config-auditing.mdx index 5e27ac3c8d..2deeefe5b3 100644 --- a/website/content/api-docs/system/config-auditing.mdx +++ b/website/content/api-docs/system/config-auditing.mdx @@ -1,6 +1,4 @@ --- -layout: api -page_title: /sys/config/auditing - HTTP API description: The `/sys/config/auditing` endpoint is used to configure auditing settings. --- diff --git a/website/content/api-docs/system/config-cors.mdx b/website/content/api-docs/system/config-cors.mdx index 9fd6fd9085..abca333fef 100644 --- a/website/content/api-docs/system/config-cors.mdx +++ b/website/content/api-docs/system/config-cors.mdx @@ -1,6 +1,4 @@ --- -layout: api -page_title: /sys/config/cors - HTTP API description: >- The '/sys/config/cors' endpoint configures how the OpenBao server responds to cross-origin requests. diff --git a/website/content/api-docs/system/config-state.mdx b/website/content/api-docs/system/config-state.mdx index ffbdd9784f..5e837d1d59 100644 --- a/website/content/api-docs/system/config-state.mdx +++ b/website/content/api-docs/system/config-state.mdx @@ -1,6 +1,4 @@ --- -layout: api -page_title: /sys/config/state - HTTP API description: The '/sys/config/state' endpoint is used to retrieve the configuration state. --- diff --git a/website/content/api-docs/system/config-ui.mdx b/website/content/api-docs/system/config-ui.mdx index 9f655443ad..8f38e18c07 100644 --- a/website/content/api-docs/system/config-ui.mdx +++ b/website/content/api-docs/system/config-ui.mdx @@ -1,6 +1,4 @@ --- -layout: api -page_title: /sys/config/ui - HTTP API description: The '/sys/config/ui' endpoint configures the UI. --- diff --git a/website/content/api-docs/system/decode-token.mdx b/website/content/api-docs/system/decode-token.mdx index ae0e3cb71a..36780df915 100644 --- a/website/content/api-docs/system/decode-token.mdx +++ b/website/content/api-docs/system/decode-token.mdx @@ -1,12 +1,10 @@ --- -layout: api -page_title: /sys/decode-token - HTTP API description: The `/sys/decode-token` endpoint is used to decode the encoded token which is the result of /sys/generate-root. --- # `/sys/decode-token` -The `/sys/decode-token` endpoint is used to decode the encoded token which is the result of the [/sys/generate-root](/vault/api-docs/system/generate-root) API. +The `/sys/decode-token` endpoint is used to decode the encoded token which is the result of the [/sys/generate-root](/api-docs/system/generate-root) API. ## Parameters diff --git a/website/content/api-docs/system/experiments.mdx b/website/content/api-docs/system/experiments.mdx index ba75a235e7..ffc11d3ae3 100644 --- a/website/content/api-docs/system/experiments.mdx +++ b/website/content/api-docs/system/experiments.mdx @@ -1,6 +1,4 @@ --- -layout: api -page_title: /sys/experiments - HTTP API description: The `/sys/experiments` endpoint returns information about experiments on the OpenBao node. --- @@ -12,8 +10,8 @@ The `/sys/experiments` endpoint returns information about experiments on the Ope This endpoint returns the experiments available and enabled on the OpenBao node. Experiments are per-node and cannot be changed while the node is running. See -the [`-experiment`](/vault/docs/commands/server#experiment) flag and the -[`experiments`](/vault/docs/configuration#experiments) config key documentation for +the [`-experiment`](/docs/commands/server#experiment) flag and the +[`experiments`](/docs/configuration#experiments) config key documentation for details on enabling experiments. | Method | Path | diff --git a/website/content/api-docs/system/generate-recovery-token.mdx b/website/content/api-docs/system/generate-recovery-token.mdx index a608290780..aeb0e5cdd4 100644 --- a/website/content/api-docs/system/generate-recovery-token.mdx +++ b/website/content/api-docs/system/generate-recovery-token.mdx @@ -1,6 +1,4 @@ --- -layout: api -page_title: /sys/generate-recovery-token - HTTP API description: |- The `/sys/generate-recovery-token/` endpoints are used to create a new recovery token for OpenBao. They are only active in recovery mode. diff --git a/website/content/api-docs/system/generate-root.mdx b/website/content/api-docs/system/generate-root.mdx index b472fafc10..0fb6f9c484 100644 --- a/website/content/api-docs/system/generate-root.mdx +++ b/website/content/api-docs/system/generate-root.mdx @@ -1,6 +1,4 @@ --- -layout: api -page_title: /sys/generate-root - HTTP API description: |- The `/sys/generate-root/` endpoints are used to create a new root key for OpenBao. diff --git a/website/content/api-docs/system/ha-status.mdx b/website/content/api-docs/system/ha-status.mdx index ad0425e557..28768ecc03 100644 --- a/website/content/api-docs/system/ha-status.mdx +++ b/website/content/api-docs/system/ha-status.mdx @@ -1,6 +1,4 @@ --- -layout: api -page_title: /sys/ha-status - HTTP API description: The `/sys/ha-status` endpoint is used to check the HA status of an OpenBao cluster. --- diff --git a/website/content/api-docs/system/health.mdx b/website/content/api-docs/system/health.mdx index e24511d7bb..87cb9084e4 100644 --- a/website/content/api-docs/system/health.mdx +++ b/website/content/api-docs/system/health.mdx @@ -1,6 +1,4 @@ --- -layout: api -page_title: /sys/health - HTTP API description: The `/sys/health` endpoint is used to check the health status of OpenBao. --- diff --git a/website/content/api-docs/system/host-info.mdx b/website/content/api-docs/system/host-info.mdx index 05d3722510..0c7c9bb991 100644 --- a/website/content/api-docs/system/host-info.mdx +++ b/website/content/api-docs/system/host-info.mdx @@ -1,6 +1,4 @@ --- -layout: api -page_title: /sys/host-info - HTTP API description: The '/sys/host-info' endpoint is used to retrieve host information --- diff --git a/website/content/api-docs/system/in-flight-req.mdx b/website/content/api-docs/system/in-flight-req.mdx index efbbc5f83d..f3f1d0db97 100644 --- a/website/content/api-docs/system/in-flight-req.mdx +++ b/website/content/api-docs/system/in-flight-req.mdx @@ -1,6 +1,4 @@ --- -layout: api -page_title: /sys/in-flight-req - HTTP API description: The `/sys/in-flight-req` endpoint is used to get information on in-flight requests. --- diff --git a/website/content/api-docs/system/index.mdx b/website/content/api-docs/system/index.mdx index 628f05dfab..277518340d 100644 --- a/website/content/api-docs/system/index.mdx +++ b/website/content/api-docs/system/index.mdx @@ -1,6 +1,5 @@ --- -layout: api -page_title: System Backend - HTTP API +sidebar_label: Overview description: |- The system backend is a default backend in OpenBao that is mounted at the `/sys` endpoint. This endpoint cannot be disabled or moved, and is used to configure diff --git a/website/content/api-docs/system/init.mdx b/website/content/api-docs/system/init.mdx index a80d4c7adb..5b13548809 100644 --- a/website/content/api-docs/system/init.mdx +++ b/website/content/api-docs/system/init.mdx @@ -1,6 +1,4 @@ --- -layout: api -page_title: /sys/init - HTTP API description: The `/sys/init` endpoint is used to initialize a new OpenBao. --- @@ -35,7 +33,7 @@ $ curl \ This endpoint initializes a new OpenBao. The OpenBao must not have been previously initialized. The recovery options, as well as the stored shares option, are only -available when using [Auto Unseal](/vault/docs/concepts/seal#auto-unseal). +available when using [Auto Unseal](/docs/concepts/seal#auto-unseal). | Method | Path | | :----- | :---------- | @@ -108,8 +106,8 @@ provided) root keys, base 64 encoded root keys and initial root token: } ``` --> **Warning:** Please be reminded that recovery keys are used as an +**Warning:** Please be reminded that recovery keys are used as an authentication flow for rekeying and regeneration of root credentials and cannot be used to unseal OpenBao in the case of the unavailability of the seal mechanism. Refer to the full warning in the documentation for -[Auto Unseal](/vault/docs/concepts/seal#auto-unseal). +[Auto Unseal](/docs/concepts/seal#auto-unseal). diff --git a/website/content/api-docs/system/inspect/index.mdx b/website/content/api-docs/system/inspect/index.mdx index d16e697e6b..cc9d0a8c9a 100644 --- a/website/content/api-docs/system/inspect/index.mdx +++ b/website/content/api-docs/system/inspect/index.mdx @@ -1,6 +1,5 @@ --- -layout: api -page_title: /sys/internal/inspect - HTTP API +sidebar_label: Overview description: >- This endpoint is intended to inspect a specific internal subsystem for debugging purposes, and turned off by default. Once turned on, it can be accessed with a root token or sudo privileges @@ -10,12 +9,16 @@ description: >- The `/sys/internal/inspect` family of endpoints is intended to inspect a specific internal subsystem for debugging purposes. This endpoint is off by default. See the -[OpenBao configuration documentation](/vault/docs/configuration) to +[OpenBao configuration documentation](/docs/configuration) to enable. Once the endpoint is turned on, it can be accessed with a root token or sudo privileges. -~> **NOTE**: These endpoints are subject to change or may disappear without notice. +:::warning + +**NOTE**: These endpoints are subject to change or may disappear without notice. + +::: ## Supported inspection paths -- [Router](/vault/api-docs/system/inspect/router) +- [Router](/api-docs/system/inspect/router) diff --git a/website/content/api-docs/system/inspect/router.mdx b/website/content/api-docs/system/inspect/router.mdx index 8e5a0e5387..9ad625d80d 100644 --- a/website/content/api-docs/system/inspect/router.mdx +++ b/website/content/api-docs/system/inspect/router.mdx @@ -1,6 +1,4 @@ --- -layout: api -page_title: /sys/internal/inspect/router - HTTP API description: >- The '/sys/internal/inspect/router' endpoint focuses on viewing the contents of specific structures in the internal router subsystem. --- diff --git a/website/content/api-docs/system/internal-counters.mdx b/website/content/api-docs/system/internal-counters.mdx index 87735602a0..1342e27fdd 100644 --- a/website/content/api-docs/system/internal-counters.mdx +++ b/website/content/api-docs/system/internal-counters.mdx @@ -1,6 +1,4 @@ --- -layout: api -page_title: /sys/internal/counters - HTTP API description: >- The `/sys/internal/counters` endpoints are used to return data about OpenBao usage. --- @@ -304,7 +302,7 @@ That is to say, the response will appear as follows. ``` -Please visit the [client count](/vault/docs/concepts/client-count) concepts page for +Please visit the [client count](/docs/concepts/client-count) concepts page for more information on how clients map to these client IDs and how they are counted, or for more information about how the new clients for the current month are estimated in a billing period. @@ -929,7 +927,11 @@ provided start and end times. The returned set of client information will be deduplicated over the time window and will show the earliest activity logged for each client. The output will be ordered chronologically by month of activity. -~> **NOTE**: This endpoint is currently in tech preview status. +:::warning + +**NOTE**: This endpoint is currently in tech preview status. + +::: There are a few things to keep in mind while using this API. diff --git a/website/content/api-docs/system/internal-specs-openapi.mdx b/website/content/api-docs/system/internal-specs-openapi.mdx index cee4c459ed..596ace5cb7 100644 --- a/website/content/api-docs/system/internal-specs-openapi.mdx +++ b/website/content/api-docs/system/internal-specs-openapi.mdx @@ -1,6 +1,4 @@ --- -layout: api -page_title: /sys/internal/specs/openapi - HTTP API description: >- The `/sys/internal/specs/openapi` endpoint is used to generate an OpenAPI document of the mounted backends. @@ -15,7 +13,7 @@ The set of included paths is based on the permissions of the request token. The response may include OpenBao-specific [extensions](https://github.com/oai/openapi-specification/blob/master/versions/3.0.2.md#specification-extensions). Three are currently defined: -- `x-vault-sudo` - Endpoint requires [sudo](/vault/docs/concepts/policies#sudo) privileges. +- `x-vault-sudo` - Endpoint requires [sudo](/docs/concepts/policies#sudo) privileges. - `x-vault-unauthenticated` - Endpoint is unauthenticated. - `x-vault-create-supported` - Endpoint allows creation of new items, in addition to updating existing items. diff --git a/website/content/api-docs/system/internal-ui-feature.mdx b/website/content/api-docs/system/internal-ui-feature.mdx index 138a807e0d..3cea62f1e3 100644 --- a/website/content/api-docs/system/internal-ui-feature.mdx +++ b/website/content/api-docs/system/internal-ui-feature.mdx @@ -1,6 +1,4 @@ --- -layout: api -page_title: /sys/internal/ui/feature-flags - HTTP API description: >- The `/sys/internal/ui/feature-flags` endpoint exposes feature flags to the UI. --- diff --git a/website/content/api-docs/system/internal-ui-mounts.mdx b/website/content/api-docs/system/internal-ui-mounts.mdx index c3815a2c32..3f5d653ed3 100644 --- a/website/content/api-docs/system/internal-ui-mounts.mdx +++ b/website/content/api-docs/system/internal-ui-mounts.mdx @@ -1,6 +1,4 @@ --- -layout: api -page_title: /sys/internal/ui/mounts - HTTP API description: >- The `/sys/internal/ui/mounts` endpoint is used to manage mount listing visibility. diff --git a/website/content/api-docs/system/internal-ui-namespaces.mdx b/website/content/api-docs/system/internal-ui-namespaces.mdx index d6019ccefe..459f29bc3c 100644 --- a/website/content/api-docs/system/internal-ui-namespaces.mdx +++ b/website/content/api-docs/system/internal-ui-namespaces.mdx @@ -1,6 +1,4 @@ --- -layout: api -page_title: /sys/internal/ui/namespaces - HTTP API description: >- The `/sys/internal/ui/namespaces` endpoint exposes namespaces to the UI. --- diff --git a/website/content/api-docs/system/internal-ui-resultant-acl.mdx b/website/content/api-docs/system/internal-ui-resultant-acl.mdx index d2990a9cef..0575cbd364 100644 --- a/website/content/api-docs/system/internal-ui-resultant-acl.mdx +++ b/website/content/api-docs/system/internal-ui-resultant-acl.mdx @@ -1,6 +1,4 @@ --- -layout: api -page_title: /sys/internal/ui/resultant-acl - HTTP API description: >- The `/sys/internal/ui/resultant-acl` endpoint exposes resultant-acl to the UI. --- diff --git a/website/content/api-docs/system/key-status.mdx b/website/content/api-docs/system/key-status.mdx index cd8516f7ed..dc89814b00 100644 --- a/website/content/api-docs/system/key-status.mdx +++ b/website/content/api-docs/system/key-status.mdx @@ -1,6 +1,4 @@ --- -layout: api -page_title: /sys/key-status - HTTP API description: |- The `/sys/key-status` endpoint is used to query info about the current encryption key of OpenBao. diff --git a/website/content/api-docs/system/leader.mdx b/website/content/api-docs/system/leader.mdx index 7d2b66823e..7bff48b98c 100644 --- a/website/content/api-docs/system/leader.mdx +++ b/website/content/api-docs/system/leader.mdx @@ -1,6 +1,4 @@ --- -layout: api -page_title: /sys/leader - HTTP API description: |- The `/sys/leader` endpoint is used to check the high availability status and current leader of OpenBao. diff --git a/website/content/api-docs/system/leases.mdx b/website/content/api-docs/system/leases.mdx index b5d9be4599..b955ad3bc1 100644 --- a/website/content/api-docs/system/leases.mdx +++ b/website/content/api-docs/system/leases.mdx @@ -1,6 +1,4 @@ --- -layout: api -page_title: /sys/leases - HTTP API description: The `/sys/leases` endpoints are used to view and manage leases. --- diff --git a/website/content/api-docs/system/loggers.mdx b/website/content/api-docs/system/loggers.mdx index 95c46a1cb4..d5d177b742 100644 --- a/website/content/api-docs/system/loggers.mdx +++ b/website/content/api-docs/system/loggers.mdx @@ -1,6 +1,4 @@ --- -layout: api -page_title: /sys/loggers - HTTP API description: The `/sys/loggers` endpoint is used modify the verbosity level of logging. --- @@ -8,10 +6,14 @@ description: The `/sys/loggers` endpoint is used modify the verbosity level of l The `/sys/loggers` endpoint is used modify the verbosity level of logging. -!> **NOTE:** Changes made to the log level using this endpoint are not persisted and will be restored +:::danger + +**NOTE:** Changes made to the log level using this endpoint are not persisted and will be restored to either the default log level (info) or the level specified using `log_level` in openbao.hcl or the `VAULT_LOG_LEVEL` environment variable once the OpenBao service is reloaded or restarted. +::: + ## Modify verbosity level of all loggers | Method | Path | diff --git a/website/content/api-docs/system/metrics.mdx b/website/content/api-docs/system/metrics.mdx index eb1813f799..fcdf1f9eae 100644 --- a/website/content/api-docs/system/metrics.mdx +++ b/website/content/api-docs/system/metrics.mdx @@ -1,6 +1,4 @@ --- -layout: api -page_title: /sys/metrics - HTTP API description: The `/sys/metrics` endpoint is used to get telemetry metrics for OpenBao. --- diff --git a/website/content/api-docs/system/mfa-validate.mdx b/website/content/api-docs/system/mfa-validate.mdx index cb46fb6a30..c821cb8fb0 100644 --- a/website/content/api-docs/system/mfa-validate.mdx +++ b/website/content/api-docs/system/mfa-validate.mdx @@ -1,6 +1,4 @@ --- -layout: api -page_title: /sys/mfa/validate - HTTP API description: >- The '/sys/mfa/validate' endpoint focuses on validating login MFA requests. If validation succeeds, it returns an auth response which includes a client token. diff --git a/website/content/api-docs/system/monitor.mdx b/website/content/api-docs/system/monitor.mdx index 8b5ed76475..c5088d6ac9 100644 --- a/website/content/api-docs/system/monitor.mdx +++ b/website/content/api-docs/system/monitor.mdx @@ -1,6 +1,4 @@ --- -layout: api -page_title: /sys/monitor - HTTP API description: The `/sys/monitor` endpoint is used to receive streaming logs from the OpenBao server. --- diff --git a/website/content/api-docs/system/mounts.mdx b/website/content/api-docs/system/mounts.mdx index b740c91e5a..78f3f5682d 100644 --- a/website/content/api-docs/system/mounts.mdx +++ b/website/content/api-docs/system/mounts.mdx @@ -1,6 +1,4 @@ --- -layout: api -page_title: /sys/mounts - HTTP API description: The `/sys/mounts` endpoint is used to manage secrets engines in OpenBao. --- @@ -130,7 +128,11 @@ This endpoint enables a new secrets engine at the given path. - `path` `(string: )` – Specifies the path where the secrets engine will be mounted. This is specified as part of the URL. - !> **NOTE:** Use ASCII printable characters to specify the desired path. +:::danger + + **NOTE:** Use ASCII printable characters to specify the desired path. + +::: - `type` `(string: )` – Specifies the type of the backend, such as "kv". @@ -230,7 +232,7 @@ simple as increasing the timeout (in the event of timeout errors). For recovery situations where the secret was manually removed from the secrets backing service, one can force a secrets engine disable in OpenBao by -performing a [force revoke](/vault/api-docs/system/leases) +performing a [force revoke](/api-docs/system/leases) on the mount prefix, followed by a secrets disable when that completes. If the underlying secrets were not manually cleaned up, this method might result in dangling credentials. This is meant for extreme circumstances. diff --git a/website/content/api-docs/system/namespaces.mdx b/website/content/api-docs/system/namespaces.mdx index 00d4d24233..459d935753 100644 --- a/website/content/api-docs/system/namespaces.mdx +++ b/website/content/api-docs/system/namespaces.mdx @@ -1,6 +1,4 @@ --- -layout: api -page_title: /sys/namespaces - HTTP API description: The `/sys/namespaces` endpoint is used manage namespaces in OpenBao. --- @@ -168,117 +166,3 @@ $ curl \ } ``` -## Lock namespace - -This endpoint locks the API for the current namespace path or optional subpath. -The behavior when interacting with OpenBao from a locked namespace is described in -[API Locked Response](/vault/docs/concepts/namespace-api-lock#api-locked-response). - -| Method | Path | -| :----- | :---------------------- | -| `POST` | `/sys/namespaces/api-lock/lock/:subpath` | - -### Sample request - current namespace - -```shell-session -$ curl \ - --header "X-Vault-Token: ..." \ - --request POST \ - http://127.0.0.1:8200/v1/sys/namespaces/api-lock/lock -``` - -### Sample response - current namespace - -```json -{ - "unlock_key": "" -} -``` - -### Sample request - X-Vault-Namespace - -```shell-session -$ curl \ - --header "X-Vault-Token: ..." \ - --header "X-Vault-Namespace: some/path - --request POST \ - http://127.0.0.1:8200/v1/sys/namespaces/api-lock/lock -``` - -### Sample response - X-Vault-Namespace - -```json -{ - "unlock_key": "" -} -``` - -### Sample request - descendant of current namespace - -```shell-session -$ curl \ - --header "X-Vault-Token: ..." \ - --request POST \ - http://127.0.0.1:8200/v1/sys/namespaces/api-lock/lock/some/descendant/subpath -``` - -### Sample response - descendant of current namespace - -```json -{ - "unlock_key": "" -} -``` - -## Unlock namespace - -This endpoint unlocks the api for the current namespace path or optional subpath. - -| Method | Path | -| :----- | :---------------------- | -| `POST` | `/sys/namespaces/api-lock/unlock/:subpath` | - -### Sample payload - current namespace Non-Root - -```json -{ - "unlock_key": "" -} -``` - -### Sample request - current namespace Non-Root - -```shell-session -$ curl \ - --header "X-Vault-Token: ..." \ - --request POST \ - --data @payload.json \ - http://127.0.0.1:8200/v1/sys/namespaces/api-lock/unlock -``` - -### Sample request - current namespace root - -```shell-session -$ curl \ - --header "X-Vault-Token: " \ - --request POST \ - http://127.0.0.1:8200/v1/sys/namespaces/api-lock/unlock -``` - -### Sample payload - descendant namespace Non-Root - -```json -{ - "unlock_key": "" -} -``` - -### Sample request - descendant namespace Non-Root - -```shell-session -$ curl \ - --header "X-Vault-Token: ..." \ - --request POST \ - --data @payload.json \ - http://127.0.0.1:8200/v1/sys/namespaces/api-lock/unlock/some/descendant/path -``` diff --git a/website/content/api-docs/system/plugins-catalog.mdx b/website/content/api-docs/system/plugins-catalog.mdx index 98fe0a8ac8..63b7226eaf 100644 --- a/website/content/api-docs/system/plugins-catalog.mdx +++ b/website/content/api-docs/system/plugins-catalog.mdx @@ -1,6 +1,4 @@ --- -layout: api -page_title: /sys/plugins/catalog - HTTP API description: The `/sys/plugins/catalog` endpoint is used to manage plugins. --- diff --git a/website/content/api-docs/system/plugins-reload-backend.mdx b/website/content/api-docs/system/plugins-reload-backend.mdx index 12f27a711a..a1f6a23029 100644 --- a/website/content/api-docs/system/plugins-reload-backend.mdx +++ b/website/content/api-docs/system/plugins-reload-backend.mdx @@ -1,6 +1,4 @@ --- -layout: api -page_title: /sys/plugins/reload/backend - HTTP API description: The `/sys/plugins/reload/backend` endpoint is used to reload plugin backends. --- diff --git a/website/content/api-docs/system/policies-password.mdx b/website/content/api-docs/system/policies-password.mdx index ad775319a3..2a3d3cc412 100644 --- a/website/content/api-docs/system/policies-password.mdx +++ b/website/content/api-docs/system/policies-password.mdx @@ -1,6 +1,4 @@ --- -layout: api -page_title: /sys/policies/password - HTTP API description: >- The `/sys/policies/password` endpoints are used to manage password generation policies in OpenBao. --- @@ -11,7 +9,7 @@ The `/sys/policies/password/` endpoints are used to manage password generation p Not all secret engines utilize password policies, so check the documentation for the engine you are using for compatibility. -See [Password Policies](/vault/docs/concepts/password-policies) for details of how password policies work +See [Password Policies](/docs/concepts/password-policies) for details of how password policies work as well as the syntax of the policies themselves. ## Create/Update password policy @@ -35,7 +33,7 @@ generation times. This is specified as part of the request URL. - `policy` `(string: )` - Specifies the password policy document. This can be - base64-encoded to avoid string escaping. See [Password Policy Syntax](/vault/docs/concepts/password-policies#password-policy-syntax) + base64-encoded to avoid string escaping. See [Password Policy Syntax](/docs/concepts/password-policies#password-policy-syntax) for details on password policy definitions. ### Sample payload diff --git a/website/content/api-docs/system/policies.mdx b/website/content/api-docs/system/policies.mdx index 5d682503f3..3bbe69e444 100644 --- a/website/content/api-docs/system/policies.mdx +++ b/website/content/api-docs/system/policies.mdx @@ -1,6 +1,4 @@ --- -layout: api -page_title: /sys/policies/ - HTTP API description: >- The `/sys/policies/` endpoints are used to manage ACL policies in OpenBao. diff --git a/website/content/api-docs/system/policy.mdx b/website/content/api-docs/system/policy.mdx index 6e5487a999..089c8ff071 100644 --- a/website/content/api-docs/system/policy.mdx +++ b/website/content/api-docs/system/policy.mdx @@ -1,6 +1,4 @@ --- -layout: api -page_title: /sys/policy - HTTP API description: The `/sys/policy` endpoint is used to manage ACL policies in OpenBao. --- diff --git a/website/content/api-docs/system/pprof.mdx b/website/content/api-docs/system/pprof.mdx index f7a21231b4..eedede0ecd 100644 --- a/website/content/api-docs/system/pprof.mdx +++ b/website/content/api-docs/system/pprof.mdx @@ -1,6 +1,4 @@ --- -layout: api -page_title: /sys/pprof - HTTP API description: The `/sys/pprof` endpoint is used to query profiling information. --- diff --git a/website/content/api-docs/system/quotas-config.mdx b/website/content/api-docs/system/quotas-config.mdx index 1ec09b1fda..694907dd33 100644 --- a/website/content/api-docs/system/quotas-config.mdx +++ b/website/content/api-docs/system/quotas-config.mdx @@ -1,6 +1,4 @@ --- -layout: api -page_title: /sys/quotas/config - HTTP API description: The `/sys/quotas/config` endpoint is used to configure rate limit quotas. --- diff --git a/website/content/api-docs/system/rate-limit-quotas.mdx b/website/content/api-docs/system/rate-limit-quotas.mdx index 011c6c58e6..6d3ce98853 100644 --- a/website/content/api-docs/system/rate-limit-quotas.mdx +++ b/website/content/api-docs/system/rate-limit-quotas.mdx @@ -1,6 +1,4 @@ --- -layout: api -page_title: /sys/quotas/rate-limit - HTTP API description: The `/sys/quotas/rate-limit` endpoint is used to create, edit and delete rate limit quotas. --- diff --git a/website/content/api-docs/system/raw.mdx b/website/content/api-docs/system/raw.mdx index e888c6b4c2..265f33ea55 100644 --- a/website/content/api-docs/system/raw.mdx +++ b/website/content/api-docs/system/raw.mdx @@ -1,6 +1,4 @@ --- -layout: api -page_title: /sys/raw - HTTP API description: The `/sys/raw` endpoint is used to access the raw underlying store in OpenBao. --- @@ -9,7 +7,7 @@ description: The `/sys/raw` endpoint is used to access the raw underlying store The `/sys/raw` endpoint is used to access the raw underlying store in OpenBao. This endpoint is off by default. See the -[OpenBao configuration documentation](/vault/docs/configuration) to +[OpenBao configuration documentation](/docs/configuration) to enable. ## Read raw diff --git a/website/content/api-docs/system/rekey-recovery-key.mdx b/website/content/api-docs/system/rekey-recovery-key.mdx index 50c4c63162..abebff94dc 100644 --- a/website/content/api-docs/system/rekey-recovery-key.mdx +++ b/website/content/api-docs/system/rekey-recovery-key.mdx @@ -1,6 +1,4 @@ --- -layout: api -page_title: /sys/rekey-recovery-key - HTTP API description: >- The `/sys/rekey-recovery-key` endpoints are used to rekey the recovery keys for OpenBao. diff --git a/website/content/api-docs/system/rekey.mdx b/website/content/api-docs/system/rekey.mdx index 7bb8757dc0..83e7dde8ba 100644 --- a/website/content/api-docs/system/rekey.mdx +++ b/website/content/api-docs/system/rekey.mdx @@ -1,6 +1,4 @@ --- -layout: api -page_title: /sys/rekey - HTTP API description: The `/sys/rekey` endpoints are used to rekey the unseal keys for OpenBao. --- diff --git a/website/content/api-docs/system/remount.mdx b/website/content/api-docs/system/remount.mdx index b1692423d3..b29996868d 100644 --- a/website/content/api-docs/system/remount.mdx +++ b/website/content/api-docs/system/remount.mdx @@ -1,6 +1,4 @@ --- -layout: api -page_title: /sys/remount - HTTP API description: >- The '/sys/remount' endpoint is used remount a mounted backend to a new endpoint. @@ -18,13 +16,21 @@ engines and auth methods. OpenBao returns a migration ID when the remount operation completes. You can use the migration ID to look up the status of the mount migration. More details about the remount operation are described in -[Mount Migration](/vault/docs/concepts/mount-migration). +[Mount Migration](/docs/concepts/mount-migration). -~> Note: This endpoint requires a policy with both `sudo` and `update` capabilities to `sys/remount` +:::warning -~> Note: A mount migration will revoke all leases for the secrets of a secrets backend or tokens of an auth backend, +Note: This endpoint requires a policy with both `sudo` and `update` capabilities to `sys/remount` + +::: + +:::warning + +Note: A mount migration will revoke all leases for the secrets of a secrets backend or tokens of an auth backend, depending on which type of backend is being moved. +::: + | Method | Path | | :----- | :------------- | diff --git a/website/content/api-docs/system/rotate-config.mdx b/website/content/api-docs/system/rotate-config.mdx index f9abecfb84..078f30bba0 100644 --- a/website/content/api-docs/system/rotate-config.mdx +++ b/website/content/api-docs/system/rotate-config.mdx @@ -1,6 +1,4 @@ --- -layout: api -page_title: /sys/rotate/config - HTTP API description: The `/sys/rotate/config` endpoint is used to configure automatic key rotation. --- diff --git a/website/content/api-docs/system/rotate.mdx b/website/content/api-docs/system/rotate.mdx index f096a8005d..4dac6f7b5b 100644 --- a/website/content/api-docs/system/rotate.mdx +++ b/website/content/api-docs/system/rotate.mdx @@ -1,6 +1,4 @@ --- -layout: api -page_title: /sys/rotate - HTTP API description: The `/sys/rotate` endpoint is used to rotate the encryption key. --- diff --git a/website/content/api-docs/system/seal-status.mdx b/website/content/api-docs/system/seal-status.mdx index 589bdbfc39..8f4cd36294 100644 --- a/website/content/api-docs/system/seal-status.mdx +++ b/website/content/api-docs/system/seal-status.mdx @@ -1,6 +1,4 @@ --- -layout: api -page_title: /sys/seal-status - HTTP API description: The `/sys/seal-status` endpoint is used to check the seal status of an OpenBao. --- diff --git a/website/content/api-docs/system/seal.mdx b/website/content/api-docs/system/seal.mdx index 01ddbcff05..d2f76cd6da 100644 --- a/website/content/api-docs/system/seal.mdx +++ b/website/content/api-docs/system/seal.mdx @@ -1,6 +1,4 @@ --- -layout: api -page_title: /sys/seal - HTTP API description: The `/sys/seal` endpoint seals the OpenBao. --- diff --git a/website/content/api-docs/system/step-down.mdx b/website/content/api-docs/system/step-down.mdx index 363acf0bd7..cbab3d978a 100644 --- a/website/content/api-docs/system/step-down.mdx +++ b/website/content/api-docs/system/step-down.mdx @@ -1,6 +1,4 @@ --- -layout: api -page_title: /sys/step-down - HTTP API description: The `/sys/step-down` endpoint causes the node to give up active status. --- diff --git a/website/content/api-docs/system/storage/index.mdx b/website/content/api-docs/system/storage/index.mdx index 053fc661d2..0c7a387383 100644 --- a/website/content/api-docs/system/storage/index.mdx +++ b/website/content/api-docs/system/storage/index.mdx @@ -1,6 +1,5 @@ --- -layout: api -page_title: /sys/storage - HTTP API +sidebar_label: Overview description: |- The '/sys/storage' endpoints are used to manage OpenBao's storage backends. @@ -8,4 +7,4 @@ description: |- # `/sys/storage` -This API sub-section is currently only used to manage [Raft](/vault/api-docs/system/storage/raft) storage backend. +This API sub-section is currently only used to manage [Raft](/api-docs/system/storage/raft) storage backend. diff --git a/website/content/api-docs/system/storage/raft.mdx b/website/content/api-docs/system/storage/raft.mdx index 6c89f08e65..da3676dd3c 100644 --- a/website/content/api-docs/system/storage/raft.mdx +++ b/website/content/api-docs/system/storage/raft.mdx @@ -1,6 +1,4 @@ --- -layout: api -page_title: /sys/storage/raft - HTTP API description: |- The `/sys/storage/raft` endpoints are used to manage OpenBao's Raft storage diff --git a/website/content/api-docs/system/storage/raftautopilot.mdx b/website/content/api-docs/system/storage/raftautopilot.mdx index b2ad5c9b2e..c3b016d7f7 100644 --- a/website/content/api-docs/system/storage/raftautopilot.mdx +++ b/website/content/api-docs/system/storage/raftautopilot.mdx @@ -1,6 +1,4 @@ --- -layout: api -page_title: /sys/storage/raft/autopilot - HTTP API description: |- The `/sys/storage/raft/autopilot` endpoints are used to manage raft clusters using autopilot with OpenBao's Integrated Storage backend. @@ -10,12 +8,12 @@ description: |- # `/sys/storage/raft/autopilot` The `/sys/storage/raft/autopilot` endpoints are used to manage raft clusters using autopilot -with OpenBao's [Integrated Storage backend](/vault/docs/internals/integrated-storage). -Refer to the [Integrated Storage Autopilot](/vault/tutorials/raft/raft-autopilot) tutorial to learn how to manage raft clusters using autopilot. +with OpenBao's [Integrated Storage backend](/docs/internals/integrated-storage). +Refer to the [Integrated Storage Autopilot](/tutorials/raft/raft-autopilot) tutorial to learn how to manage raft clusters using autopilot. ## Get cluster state -This endpoint is used to retrieve the raft cluster state. See the [docs page](/vault/docs/commands/operator/raft#autopilot-state) for a description of the output. +This endpoint is used to retrieve the raft cluster state. See the [docs page](/docs/commands/operator/raft#autopilot-state) for a description of the output. | Method | Path | | :----- | :---------------------------------- | diff --git a/website/content/api-docs/system/tools.mdx b/website/content/api-docs/system/tools.mdx index c82d701837..cdd846774d 100644 --- a/website/content/api-docs/system/tools.mdx +++ b/website/content/api-docs/system/tools.mdx @@ -1,6 +1,4 @@ --- -layout: api -page_title: /sys/tools - HTTP API description: This is the API documentation for a general set of crypto tools. --- @@ -80,10 +78,14 @@ algorithm. - `sha3-384` - `sha3-512` - ~> **Note**: In FIPS 140-2 mode, the following algorithms are not certified +:::warning + + **Note**: In FIPS 140-2 mode, the following algorithms are not certified and thus should not be used: `sha3-224`, `sha3-256`, `sha3-384`, and `sha3-512`. +::: + - `input` `(string: )` – Specifies the **base64 encoded** input data. - `format` `(string: "hex")` – Specifies the output encoding. This can be either diff --git a/website/content/api-docs/system/unseal.mdx b/website/content/api-docs/system/unseal.mdx index bf7dda4ff1..076aa7f8bb 100644 --- a/website/content/api-docs/system/unseal.mdx +++ b/website/content/api-docs/system/unseal.mdx @@ -1,6 +1,4 @@ --- -layout: api -page_title: /sys/unseal - HTTP API description: The `/sys/unseal` endpoint is used to unseal the OpenBao. --- diff --git a/website/content/api-docs/system/user-lockout.mdx b/website/content/api-docs/system/user-lockout.mdx index 3bc97591e9..8ad35c55f0 100644 --- a/website/content/api-docs/system/user-lockout.mdx +++ b/website/content/api-docs/system/user-lockout.mdx @@ -1,6 +1,4 @@ --- -layout: api -page_title: /sys/locked-users - HTTP API description: The `/sys/locked-users` endpoint is used to manage locked users in OpenBao. --- @@ -8,7 +6,7 @@ description: The `/sys/locked-users` endpoint is used to manage locked users in The `/sys/locked-users` endpoint is used to list and unlock locked users in OpenBao. -Refer to the [user lockout](/vault/docs/concepts/user-lockout) overview for more details about how OpenBao handles lockouts. +Refer to the [user lockout](/docs/concepts/user-lockout) overview for more details about how OpenBao handles lockouts. ## List locked users diff --git a/website/content/api-docs/system/version-history.mdx b/website/content/api-docs/system/version-history.mdx index e48eb9cedb..525059ce46 100644 --- a/website/content/api-docs/system/version-history.mdx +++ b/website/content/api-docs/system/version-history.mdx @@ -1,6 +1,4 @@ --- -layout: api -page_title: /sys/version-history - HTTP API description: The `/sys/version-history` endpoint is used to retrieve the version history of an OpenBao. --- diff --git a/website/content/api-docs/system/wrapping-lookup.mdx b/website/content/api-docs/system/wrapping-lookup.mdx index 146c3770dd..a88137d664 100644 --- a/website/content/api-docs/system/wrapping-lookup.mdx +++ b/website/content/api-docs/system/wrapping-lookup.mdx @@ -1,6 +1,4 @@ --- -layout: api -page_title: /sys/wrapping/lookup - HTTP API description: The `/sys/wrapping/lookup` endpoint returns wrapping token properties. --- diff --git a/website/content/api-docs/system/wrapping-rewrap.mdx b/website/content/api-docs/system/wrapping-rewrap.mdx index 6da9f02e20..2a7abe4130 100644 --- a/website/content/api-docs/system/wrapping-rewrap.mdx +++ b/website/content/api-docs/system/wrapping-rewrap.mdx @@ -1,6 +1,4 @@ --- -layout: api -page_title: /sys/wrapping/rewrap - HTTP API description: >- The `/sys/wrapping/rewrap` endpoint can be used to rotate a wrapping token and refresh its TTL. diff --git a/website/content/api-docs/system/wrapping-unwrap.mdx b/website/content/api-docs/system/wrapping-unwrap.mdx index 15784d47c3..17672fc2be 100644 --- a/website/content/api-docs/system/wrapping-unwrap.mdx +++ b/website/content/api-docs/system/wrapping-unwrap.mdx @@ -1,6 +1,4 @@ --- -layout: api -page_title: /sys/wrapping/unwrap - HTTP API description: The `/sys/wrapping/unwrap` endpoint unwraps a wrapped response. --- diff --git a/website/content/api-docs/system/wrapping-wrap.mdx b/website/content/api-docs/system/wrapping-wrap.mdx index 8071097fe8..17d95fd6ba 100644 --- a/website/content/api-docs/system/wrapping-wrap.mdx +++ b/website/content/api-docs/system/wrapping-wrap.mdx @@ -1,6 +1,4 @@ --- -layout: api -page_title: /sys/wrapping/wrap - HTTP API description: |- The `/sys/wrapping/wrap` endpoint wraps the given values in a response-wrapped token. diff --git a/website/content/docs/agent-and-proxy/agent/apiproxy.mdx b/website/content/docs/agent-and-proxy/agent/apiproxy.mdx index 68052cc80d..34143e5a43 100644 --- a/website/content/docs/agent-and-proxy/agent/apiproxy.mdx +++ b/website/content/docs/agent-and-proxy/agent/apiproxy.mdx @@ -1,6 +1,5 @@ --- -layout: docs -page_title: OpenBao Agent API Proxy +sidebar_label: API proxy description: >- OpenBao Agent's API Proxy functionality allows you to use OpenBao Agent's API as a proxy for OpenBao's API. @@ -11,25 +10,29 @@ description: >- OpenBao Agent's API Proxy functionality allows you to use OpenBao Agent's API as a proxy for OpenBao's API. -~> Note: This functionality will be deprecated in a future release. Please -switch to using [OpenBao Proxy](/vault/docs/agent-and-proxy/proxy) for API proxying purposes, instead. +:::warning + +Note: This functionality will be deprecated in a future release. Please +switch to using [OpenBao Proxy](/docs/agent-and-proxy/proxy) for API proxying purposes, instead. + +::: ## Functionality -The [`listener` stanza](/vault/docs/agent-and-proxy/agent#listener-stanza) for OpenBao Agent configures a listener for OpenBao Agent. If +The [`listener` stanza](/docs/agent-and-proxy/agent#listener-stanza) for OpenBao Agent configures a listener for OpenBao Agent. If its `role` is not set to `metrics_only`, it will act as a proxy for the OpenBao server that -has been configured in the [`vault` stanza](/vault/docs/agent-and-proxy/agent#vault-stanza) of OpenBao Agent. This enables access to the OpenBao +has been configured in the [`vault` stanza](/docs/agent-and-proxy/agent#vault-stanza) of OpenBao Agent. This enables access to the OpenBao API from the Agent API, and can be configured to optionally allow or force the automatic use of the Auto-Auth token for these requests, as described below. If a `listener` has been configured alongside a `cache` stanza, the API Proxy will first attempt to utilize the cache subsystem for qualifying requests, before forwarding the -request to OpenBao. See the [caching docs](/vault/docs/agent-and-proxy/agent/caching) for more information on caching. +request to OpenBao. See the [caching docs](/docs/agent-and-proxy/agent/caching) for more information on caching. ## Using Auto-Auth token OpenBao Agent allows for easy authentication to OpenBao in a wide variety of -environments using [Auto-Auth](/vault/docs/agent-and-proxy/autoauth). By setting the +environments using [Auto-Auth](/docs/agent-and-proxy/autoauth). By setting the `use_auto_auth_token` (see below) configuration, clients will not be required to provide an OpenBao token to the requests made to the Agent. When this configuration is set, if the request doesn't already bear a token, then the @@ -43,7 +46,7 @@ request to the OpenBao server. OpenBao Agent can be configured to force the use of the auto-auth token by using the value `force` for the `use_auto_auth_token` option. This configuration overrides the default behavior described above in [Using Auto-Auth -Token](/vault/docs/agent-and-proxy/agent/apiproxy#using-auto-auth-token), and instead ignores any +Token](/docs/agent-and-proxy/agent/apiproxy#using-auto-auth-token), and instead ignores any existing OpenBao token in the request and instead uses the auto-auth token. diff --git a/website/content/docs/agent-and-proxy/agent/caching/index.mdx b/website/content/docs/agent-and-proxy/agent/caching/index.mdx index 33e25a5da9..c63b3f5640 100644 --- a/website/content/docs/agent-and-proxy/agent/caching/index.mdx +++ b/website/content/docs/agent-and-proxy/agent/caching/index.mdx @@ -1,6 +1,5 @@ --- -layout: docs -page_title: OpenBao Agent Caching +sidebar_label: Overview description: |- OpenBao Agent Caching allows client-side caching of responses containing newly created tokens and responses containing leased secrets generated off of these @@ -37,7 +36,7 @@ OpenBao Agent can restore tokens and leases from a persistent cache file created by a previous OpenBao Agent process. Refer to the [OpenBao Agent Persistent -Caching](/vault/docs/agent-and-proxy/agent/caching/persistent-caches) page for more information on +Caching](/docs/agent-and-proxy/agent/caching/persistent-caches) page for more information on this functionality. ## Cache evictions @@ -157,17 +156,21 @@ The top level `cache` block has the following configuration entry: The `cache` block also supports the `use_auto_auth_token`, `enforce_consistency`, and `when_inconsistent` configuration values of the `api_proxy` block -[described in the API Proxy documentation](/vault/docs/agent-and-proxy/agent/apiproxy#configuration-api_proxy) only to +[described in the API Proxy documentation](/docs/agent-and-proxy/agent/apiproxy#configuration-api_proxy) only to maintain backwards compatibility. This configuration **cannot** be specified alongside `api_proxy` equivalents, should not be preferred over configuring these values in the `api_proxy` block, and `api_proxy` should be the preferred place to configure these values. --> **Note:** When the `cache` block is defined, at least one +:::info + +**Note:** When the `cache` block is defined, at least one [template][agent-template] or [listener][agent-listener] must also be defined in the config, otherwise there is no way to utilize the cache. -[agent-template]: /vault/docs/agent-and-proxy/agent/template -[agent-listener]: /vault/docs/agent-and-proxy/agent#listener-stanza +::: + +[agent-template]: /docs/agent-and-proxy/agent/template +[agent-listener]: /docs/agent-and-proxy/agent#listener-stanza ### Configuration (Persist) @@ -196,9 +199,9 @@ Defaults to `/var/run/secrets/kubernetes.io/serviceaccount/token`. - `listener` `(array of objects: required)` - Configuration for the listeners. There can be one or more `listener` blocks at the top level. Adding a listener enables -the [API Proxy](/vault/docs/agent-and-proxy/agent/apiproxy) and enables the API proxy to use the cache, if configured. +the [API Proxy](/docs/agent-and-proxy/agent/apiproxy) and enables the API proxy to use the cache, if configured. These configuration values are common to both `tcp` and `unix` listener blocks. Blocks of type -`tcp` support the standard `tcp` [listener](/vault/docs/configuration/listener/tcp) +`tcp` support the standard `tcp` [listener](/docs/configuration/listener/tcp) options. Additionally, the `role` string option is available as part of the top level of the `listener` block, which can be configured to `metrics_only` to serve only metrics, or the default role, `default`, which serves everything (including metrics). @@ -255,5 +258,5 @@ listener "tcp" { ## Tutorial Refer to the [OpenBao Agent -Caching](/vault/tutorials/vault-agent/agent-caching) +Caching](/tutorials/vault-agent/agent-caching) tutorial to learn how to use the OpenBao Agent to increase the availability of tokens and secrets to clients using its Caching function. diff --git a/website/content/docs/agent-and-proxy/agent/caching/persistent-caches/index.mdx b/website/content/docs/agent-and-proxy/agent/caching/persistent-caches/index.mdx index e2fadcd2ea..666d9cf23b 100644 --- a/website/content/docs/agent-and-proxy/agent/caching/persistent-caches/index.mdx +++ b/website/content/docs/agent-and-proxy/agent/caching/persistent-caches/index.mdx @@ -1,6 +1,5 @@ --- -layout: docs -page_title: OpenBao Agent Persistent Caching +sidebar_label: Overview description: OpenBao Agent Caching --- @@ -12,9 +11,13 @@ includes tuples encrypted by a generated encryption key. The encrypted tuples include the OpenBao token used to retrieve secrets, leases for tokens/secrets, and secret values. --> **Note:** OpenBao Agent Persistent Caching will only restore _leased_ +:::info + +**Note:** OpenBao Agent Persistent Caching will only restore _leased_ secrets. Secrets that are not renewable, such as KV v2, will not be persisted. +::: + In order to use OpenBao Agent persistent cache, auto-auth must be used. If the auto-auth token has expired by the time the cache is restored, the cache will be invalidated and secrets will need to be re-fetched from OpenBao. @@ -23,9 +26,13 @@ If OpenBao Agent templating is enabled alongside of the persistent cache, OpenBa Agent will automatically route templating requests through the cache. This ensures template requests are cached and restored properly. --> **Note** OpenBao Agent persistent cache is currently supported only in a +:::info + +**Note** OpenBao Agent persistent cache is currently supported only in a Kubernetes environment. +::: + ## OpenBao agent persistent cache types Please see the sidebar for available types and their usage/configuration. diff --git a/website/content/docs/agent-and-proxy/agent/caching/persistent-caches/kubernetes.mdx b/website/content/docs/agent-and-proxy/agent/caching/persistent-caches/kubernetes.mdx index df8292046a..14f36a1921 100644 --- a/website/content/docs/agent-and-proxy/agent/caching/persistent-caches/kubernetes.mdx +++ b/website/content/docs/agent-and-proxy/agent/caching/persistent-caches/kubernetes.mdx @@ -1,6 +1,5 @@ --- -layout: docs -page_title: Kubernetes - OpenBao Agent Persistent Cache +sidebar_label: Kubernetes description: Kubernetes Persistent Cache for OpenBao Agent Caching --- @@ -16,7 +15,7 @@ and leases between initialization and sidecar OpenBao Agent containers. This cac using a memory volume between the OpenBao Agent containers. If the OpenBao Agent Injector for Kubernetes is being used, the persistent cache is automatically configured -and used if the annotation [`vault.hashicorp.com/agent-cache-enable: true`](/vault/docs/platform/k8s/injector/annotations#vault-hashicorp-com-agent-cache-enable) is set. +and used if the annotation [`vault.hashicorp.com/agent-cache-enable: true`](/docs/platform/k8s/injector/annotations#vault-hashicorp-com-agent-cache-enable) is set. ## Configuration diff --git a/website/content/docs/agent-and-proxy/agent/generate-config/index.mdx b/website/content/docs/agent-and-proxy/agent/generate-config/index.mdx index 67cb228834..942d706431 100644 --- a/website/content/docs/agent-and-proxy/agent/generate-config/index.mdx +++ b/website/content/docs/agent-and-proxy/agent/generate-config/index.mdx @@ -1,6 +1,5 @@ --- -layout: docs -page_title: agent generate-config - Command +sidebar_label: generate-config description: |- Generates a simple OpenBao Agent configuration file from the given parameters. --- @@ -12,7 +11,7 @@ Generates a simple OpenBao Agent configuration file from the given parameters. Currently, the only supported configuration type is `env-template`, which helps you generate a configuration file with environment variable templates for running OpenBao Agent in -[process supervisor](/vault/docs/agent-and-proxy/agent/process-supervisor) +[process supervisor](/docs/agent-and-proxy/agent/process-supervisor) mode. For every specified secret `-path`, the command will attempt to generate one or @@ -20,8 +19,8 @@ multiple `env_template` entries based on the `JSON` key(s) stored in the specified secret. If the secret `-path` ends with `/*`, the command will attempt to recurse through the secrets tree rooted at the given path, generating `env_template` entries for each encountered secret. Currently, -only [kv-v1](/vault/docs/secrets/kv/kv-v1) and -[kv-v2](/vault/docs/secrets/kv/kv-v2) paths are supported. +only [kv-v1](/docs/secrets/kv/kv-v1) and +[kv-v2](/docs/secrets/kv/kv-v2) paths are supported. The command specified in the `-exec` option will be used to generate an `exec` entry, which will tell OpenBao Agent which child process to run. @@ -30,7 +29,7 @@ In addition to the `env_template` entries, the command generates an `auto_auth` section with `token_file` authentication method. While this method is very convenient for local testing, it should **NOT** be used in production. In a production environment, please use any other -[Auto-Auth method](/vault/docs/agent-and-proxy/autoauth/methods) instead. +[Auto-Auth method](/docs/agent-and-proxy/autoauth/methods) instead. By default, the file will be generated in the local directory as `agent.hcl` unless a path is specified as an argument. @@ -56,15 +55,11 @@ $ bao agent generate-config \ **Expected output:** - - ```plaintext Successfully generated "my-config.hcl" configuration file! Warning: the generated file uses 'token_file' authentication method, which is not suitable for production environments. ``` - - This will produce `my-config.hcl` file in the current directory with contents similar to the following: @@ -108,7 +103,7 @@ exec { ## Usage The following flags are available in addition to the [standard set of -flags](/vault/docs/commands) included in all commands. +flags](/docs/commands) included in all commands. - `type` `(string: )` - The type of configuration file to generate; currently, only `env-template` is supported. @@ -124,5 +119,5 @@ flags](/vault/docs/commands) included in all commands. ## Tutorial Refer to the [OpenBao Agent - secrets as environment -variables](/vault/tutorials/vault-agent/agent-env-vars) tutorial for an +variables](/tutorials/vault-agent/agent-env-vars) tutorial for an end-to-end example. diff --git a/website/content/docs/agent-and-proxy/agent/index.mdx b/website/content/docs/agent-and-proxy/agent/index.mdx index 540a09d212..fdd2ccbd99 100644 --- a/website/content/docs/agent-and-proxy/agent/index.mdx +++ b/website/content/docs/agent-and-proxy/agent/index.mdx @@ -1,6 +1,5 @@ --- -layout: docs -page_title: OpenBao Agent +sidebar_label: Overview description: |- OpenBao Agent is a client-side daemon that can be used to perform some OpenBao functionality automatically. @@ -47,7 +46,7 @@ the Auto-Auth token for these requests. Please see the [API Proxy docs][apiproxy for more information. API Proxy functionality takes place within a defined `listener`, and its behaviour can be configured with an -[`api_proxy` stanza](/vault/docs/agent-and-proxy/agent/apiproxy#configuration-api_proxy). +[`api_proxy` stanza](/docs/agent-and-proxy/agent/apiproxy#configuration-api_proxy). ## Caching @@ -69,21 +68,21 @@ to only enable this on trusted interfaces, as it does not require any authorizat ### Cache -See the [caching](/vault/docs/agent-and-proxy/agent/caching#api) page for details on the cache API. +See the [caching](/docs/agent-and-proxy/agent/caching#api) page for details on the cache API. ## Configuration ### Command options -- `-log-level` ((#\_log_level)) `(string: "info")` - Log verbosity level. Supported values (in +- `-log-level` `(string: "info")` - Log verbosity level. Supported values (in order of descending detail) are `trace`, `debug`, `info`, `warn`, and `error`. This can also be specified via the `VAULT_LOG_LEVEL` environment variable. -- `-log-format` ((#\_log_format)) `(string: "standard")` - Log format. Supported values +- `-log-format` `(string: "standard")` - Log format. Supported values are `standard` and `json`. This can also be specified via the `VAULT_LOG_FORMAT` environment variable. -- `-log-file` ((#\_log_file)) - the absolute path where OpenBao Agent should save +- `-log-file` - the absolute path where OpenBao Agent should save log messages. Paths that end with a path separator use the default file name, `agent.log`. Paths that do not end with a file extension use the default `.log` extension. If the log file rotates, OpenBao Agent appends the current @@ -95,15 +94,15 @@ See the [caching](/vault/docs/agent-and-proxy/agent/caching#api) page for detail `/var/log/my-diary` | `/var/log/my-diary.log` | `/var/log/my-diary-{timestamp}.log` `/var/log/my-diary.txt` | `/var/log/my-diary.txt` | `/var/log/my-diary-{timestamp}.txt` -- `-log-rotate-bytes` ((#\_log_rotate_bytes)) - to specify the number of +- `-log-rotate-bytes` - to specify the number of bytes that should be written to a log before it needs to be rotated. Unless specified, there is no limit to the number of bytes that can be written to a log file. -- `-log-rotate-duration` ((#\_log_rotate_duration)) - to specify the maximum +- `-log-rotate-duration` - to specify the maximum duration a log should be written to before it needs to be rotated. Must be a duration value such as 30s. Defaults to 24h. -- `-log-rotate-max-files` ((#\_log_rotate_max_files)) - to specify the maximum +- `-log-rotate-max-files` - to specify the maximum number of older log file archives to keep. Defaults to `0` (no files are ever deleted). Set to `-1` to discard old log files when a new one is created. @@ -111,19 +110,23 @@ See the [caching](/vault/docs/agent-and-proxy/agent/caching#api) page for detail These are the currently-available general configuration options: -- `vault` ([vault][vault]: ) - Specifies the remote OpenBao server the Agent connects to. +- `vault` ([vault][vault]: \) - Specifies the remote OpenBao server the Agent connects to. -- `auto_auth` ([auto_auth][autoauth]: ) - Specifies the method and other options used for Auto-Auth functionality. +- `auto_auth` ([auto_auth][autoauth]: \) - Specifies the method and other options used for Auto-Auth functionality. -- `api_proxy` ([api_proxy][apiproxy]: ) - Specifies options used for API Proxy functionality. +- `api_proxy` ([api_proxy][apiproxy]: \) - Specifies options used for API Proxy functionality. -- `cache` ([cache][caching]: ) - Specifies options used for Caching functionality. +- `cache` ([cache][caching]: \) - Specifies options used for Caching functionality. -- `listener` ([listener][listener]: ) - Specifies the addresses and ports on which the Agent will respond to requests. +- `listener` ([listener][listener]: \) - Specifies the addresses and ports on which the Agent will respond to requests. - ~> **Note:** On `SIGHUP` (`kill -SIGHUP $(pidof bao)`), OpenBao Agent will attempt to reload listener TLS configuration. +:::warning + + **Note:** On `SIGHUP` (`kill -SIGHUP $(pidof bao)`), OpenBao Agent will attempt to reload listener TLS configuration. This method can be used to refresh certificates used by OpenBao Agent without having to restart its process. +::: + - `pid_file` `(string: "")` - Path to the file in which the agent's Process ID (PID) should be stored @@ -141,26 +144,30 @@ These are the currently-available general configuration options: identical in function to `caching` for historical reasons. Can also be configured by setting the `VAULT_AGENT_DISABLE_KEEP_ALIVES` environment variable as a comma separated string. This environment variable will override any values found in a configuration file. -- `template` ([template][template]: ) - Specifies options used for templating OpenBao secrets to files. +- `template` ([template][template]: \) - Specifies options used for templating OpenBao secrets to files. -- `template_config` ([template_config][template-config]: ) - Specifies templating engine behavior. +- `template_config` ([template_config][template-config]: \) - Specifies templating engine behavior. -- `exec` ([exec][process-supervisor]: ) - Specifies options for OpenBao agent to run a child process +- `exec` ([exec][process-supervisor]: \) - Specifies options for OpenBao agent to run a child process that injects secrets (via `env_template` stanzas) as environment variables. -- `env_template` ([env_template][template]: ) - Multiple blocks accepted. Each block contains +- `env_template` ([env_template][template]: \) - Multiple blocks accepted. Each block contains the options used for templating OpenBao secrets as environment variables via the - [process supervisor mode](/vault/docs/agent-and-proxy/agent/process-supervisor). + [process supervisor mode](/docs/agent-and-proxy/agent/process-supervisor). -- `telemetry` ([telemetry][telemetry]: ) – Specifies the telemetry - reporting system. See the [telemetry Stanza](/vault/docs/agent-and-proxy/agent#telemetry-stanza) section below +- `telemetry` ([telemetry][telemetry]: \) – Specifies the telemetry + reporting system. See the [telemetry Stanza](/docs/agent-and-proxy/agent#telemetry-stanza) section below for a list of metrics specific to Agent. - `log_level` - Equivalent to the [`-log-level` command-line flag](#_log_level). - ~> **Note:** On `SIGHUP` (`kill -SIGHUP $(pidof bao)`), OpenBao Agent will update the log level to the value +:::warning + + **Note:** On `SIGHUP` (`kill -SIGHUP $(pidof bao)`), OpenBao Agent will update the log level to the value specified by configuration file (including overriding values set using CLI or environment variable parameters). +::: + - `log_format` - Equivalent to the [`-log-format` command-line flag](#_log_format). - `log_file` - Equivalent to the [`-log-file` command-line flag](#_log_file). @@ -176,36 +183,36 @@ These are the currently-available general configuration options: There can at most be one top level `vault` block, and it has the following configuration entries: -- `address` `(string: )` - The address of the OpenBao server to +- `address` `(string: \)` - The address of the OpenBao server to connect to. This should be a Fully Qualified Domain Name (FQDN) or IP such as `https://openbao-fqdn:8200` or `https://172.16.9.8:8200`. This value can be overridden by setting the `VAULT_ADDR` environment variable. -- `ca_cert` `(string: )` - Path on the local disk to a single PEM-encoded +- `ca_cert` `(string: \)` - Path on the local disk to a single PEM-encoded CA certificate to verify the OpenBao server's SSL certificate. This value can be overridden by setting the `VAULT_CACERT` environment variable. -- `ca_path` `(string: )` - Path on the local disk to a directory of +- `ca_path` `(string: \)` - Path on the local disk to a directory of PEM-encoded CA certificates to verify the OpenBao server's SSL certificate. This value can be overridden by setting the `VAULT_CAPATH` environment variable. -- `client_cert` `(string: )` - Path on the local disk to a single +- `client_cert` `(string: \)` - Path on the local disk to a single PEM-encoded CA certificate to use for TLS authentication to the OpenBao server. This value can be overridden by setting the `VAULT_CLIENT_CERT` environment variable. -- `client_key` `(string: )` - Path on the local disk to a single +- `client_key` `(string: \)` - Path on the local disk to a single PEM-encoded private key matching the client certificate from `client_cert`. This value can be overridden by setting the `VAULT_CLIENT_KEY` environment variable. -- `tls_skip_verify` `(string: )` - Disable verification of TLS +- `tls_skip_verify` `(string: \)` - Disable verification of TLS certificates. Using this option is highly discouraged as it decreases the security of data transmissions to and from the OpenBao server. This value can be overridden by setting the `VAULT_SKIP_VERIFY` environment variable. -- `tls_server_name` `(string: )` - Name to use as the SNI host when +- `tls_server_name` `(string: \)` - Name to use as the SNI host when connecting via TLS. This value can be overridden by setting the `VAULT_TLS_SERVER_NAME` environment variable. @@ -262,11 +269,11 @@ listener configuration, an Agent's listener configuration also supports the foll which serves everything (including metrics). The `require_request_header` does not apply to `metrics_only` listeners. -- `agent_api` ([agent_api][agent-api]: ) - Manages optional Agent API endpoints. +- `agent_api` ([agent_api][agent-api]: \) - Manages optional Agent API endpoints. #### agent_api stanza -- `enable_quit` `(bool: false)` - If set to `true`, the agent will enable the [quit](/vault/docs/agent-and-proxy/agent#quit) API. +- `enable_quit` `(bool: false)` - If set to `true`, the agent will enable the [quit](/docs/agent-and-proxy/agent#quit) API. ### telemetry stanza @@ -287,7 +294,7 @@ runtime metrics about its performance, the auto-auth and the cache status: To run OpenBao Agent: -1. [Download](/vault/downloads) the OpenBao binary where the client application runs +1. [Download](/downloads) the OpenBao binary where the client application runs (virtual machine, Kubernetes pod, etc.) 1. Create an OpenBao Agent configuration file. (See the [Example @@ -384,16 +391,16 @@ template { } ``` -[vault]: /vault/docs/agent-and-proxy/agent#vault-stanza -[autoauth]: /vault/docs/agent-and-proxy/autoauth -[caching]: /vault/docs/agent-and-proxy/agent/caching -[apiproxy]: /vault/docs/agent-and-proxy/agent/apiproxy -[persistent-cache]: /vault/docs/agent-and-proxy/agent/caching/persistent-caches -[template]: /vault/docs/agent-and-proxy/agent/template -[process-supervisor]: /vault/docs/agent-and-proxy/agent/process-supervisor -[template-config]: /vault/docs/agent-and-proxy/agent/template#template-configurations -[agent-api]: /vault/docs/agent-and-proxy/agent/#agent_api-stanza -[listener]: /vault/docs/agent-and-proxy/agent#listener-stanza -[listener_main]: /vault/docs/configuration/listener/tcp -[winsvc]: /vault/docs/agent-and-proxy/agent/winsvc -[telemetry]: /vault/docs/configuration/telemetry +[vault]: /docs/agent-and-proxy/agent#vault-stanza +[autoauth]: /docs/agent-and-proxy/autoauth +[caching]: /docs/agent-and-proxy/agent/caching +[apiproxy]: /docs/agent-and-proxy/agent/apiproxy +[persistent-cache]: /docs/agent-and-proxy/agent/caching/persistent-caches +[template]: /docs/agent-and-proxy/agent/template +[process-supervisor]: /docs/agent-and-proxy/agent/process-supervisor +[template-config]: /docs/agent-and-proxy/agent/template#template-configurations +[agent-api]: /docs/agent-and-proxy/agent/#agent_api-stanza +[listener]: /docs/agent-and-proxy/agent#listener-stanza +[listener_main]: /docs/configuration/listener/tcp +[winsvc]: /docs/agent-and-proxy/agent/winsvc +[telemetry]: /docs/configuration/telemetry diff --git a/website/content/docs/agent-and-proxy/agent/process-supervisor.mdx b/website/content/docs/agent-and-proxy/agent/process-supervisor.mdx index fed2397009..9810ff65fd 100644 --- a/website/content/docs/agent-and-proxy/agent/process-supervisor.mdx +++ b/website/content/docs/agent-and-proxy/agent/process-supervisor.mdx @@ -1,6 +1,5 @@ --- -layout: docs -page_title: OpenBao Agent's Process Supervisor Mode +sidebar_label: Process Supervisor Mode description: >- OpenBao Agent's Process Supervisor Mode allows OpenBao secrets to be injected into a process via environment variables using Consul Template markup. @@ -12,13 +11,21 @@ OpenBao Agent's Process Supervisor Mode allows OpenBao secrets to be injected in a process via environment variables using [Consul Template markup][consul-templating-language]. --> If you are running your applications in a Kubernetes cluster, we recommend - evaluating the [OpenBao Secrets Operator](/vault/docs/platform/k8s/vso) and - the [OpenBao Agent Sidecar Injector](/vault/docs/platform/k8s/injector). +:::info -!> OpenBao Agent's Process Supervisor Mode is in public beta. Please provide your +If you are running your applications in a Kubernetes cluster, we recommend + evaluating the [OpenBao Secrets Operator](/docs/platform/k8s/vso) and + the [OpenBao Agent Sidecar Injector](/docs/platform/k8s/injector). + +::: + +:::danger + +OpenBao Agent's Process Supervisor Mode is in public beta. Please provide your feedback by opening a GitHub issue [here](https://github.com/openbao/openbao/issues). +::: + ## Functionality OpenBao Agent will inject secrets referenced in the `env_template` configuration @@ -29,7 +36,7 @@ environment variable template has rendered at least once before starting the process. If `restart_on_secret_changes` is set to `always` (default), Agent will restart the process whenever an update to an injected secret is detected. This could be either a static secret update (done on -[`static_secret_render_interval`](/vault/docs/agent-and-proxy/agent/template#static_secret_render_interval)) +[`static_secret_render_interval`](/docs/agent-and-proxy/agent/template#static_secret_render_interval)) or dynamic secret being close to its expiration. In many ways, OpenBao Agent will mirror the child process. Standard intput and @@ -39,10 +46,14 @@ its own with the same exit code. ## Configuration --> Agent's [generate-config](/vault/docs/agent-and-proxy/agent/generate-config) +:::info + +Agent's [generate-config](/docs/agent-and-proxy/agent/generate-config) tool will help you get started by generating a valid agent configuration file from the given inputs. +::: + The process supervisor mode requires at least one `env_template` block and exactly one top level `exec` block. It is incompatible with regular file `template` entries. @@ -52,9 +63,9 @@ exactly one top level `exec` block. It is incompatible with regular file `env_template` stanza maps the template specified in the `contents` field or referenced in the `source` field to the environment variable name in the title of the stanza. It uses the same -[templating language](/vault/docs/agent-and-proxy/agent/template#templating-language) +[templating language](/docs/agent-and-proxy/agent/template#templating-language) as file templates but permits only a subset of -[its configuration parameters](/vault/docs/agent-and-proxy/agent/template#template_configurations): +[its configuration parameters](/docs/agent-and-proxy/agent/template#template_configurations): - environment variable name `(string: )` - the name of the environment variable to which the contents of the template should map. @@ -71,10 +82,10 @@ as file templates but permits only a subset of a struct or map field/key that does notexist. The default behavior will print `` when accessing a field that does not exist. It is highly recommended you set this to "true". Also see - [`exit_on_retry_failure` in global OpenBao Agent Template Config](/vault/docs/agent-and-proxy/agent/template#interaction-between-exit_on_retry_failure-and-error_on_missing_key). + [`exit_on_retry_failure` in global OpenBao Agent Template Config](/docs/agent-and-proxy/agent/template#interaction-between-exit_on_retry_failure-and-error_on_missing_key). -- `left_delimiter` `(string: "{{")` - Delimiter to use in the template. The - default is "{{" but for some templates, it may be easier to use a different +- `left_delimiter` `(string: "\{\{")` - Delimiter to use in the template. The + default is "\{\{" but for some templates, it may be easier to use a different delimiter that does not conflict with the output file itself. - `right_delimiter` `(string: "}}")` - Delimiter to use in the template. The @@ -92,7 +103,7 @@ The top level `exec` block has the following configuration entries. - `restart_on_secret_changes` `(string: "always")` - Controls whether agent will restart the child process on secret changes. There are two types of secret changes relevant to this configuration: a static secret update (on - [static_secret_render_interval`](/vault/docs/agent-and-proxy/agent/template#static_secret_render_interval)) + [static_secret_render_interval`](/docs/agent-and-proxy/agent/template#static_secret_render_interval)) and dynamic secret being close to its expiration. The configuration supports two options: `always` and `never`. @@ -105,7 +116,7 @@ The top level `exec` block has the following configuration entries. ## Configuration example The following example was generated using -[`bao agent generate-config`](/vault/docs/agent-and-proxy/agent/generate-config), +[`bao agent generate-config`](/docs/agent-and-proxy/agent/generate-config), a configuration helper tool. Given this configuration, OpenBao Agent will run the child process (`./my-app arg1 arg2`) with two additional environment variables (`FOO_USER` and `FOO_PASSWORD`) populated with secrets from OpenBao. @@ -148,11 +159,11 @@ exec { ``` [consul-templating-language]: https://github.com/hashicorp/consul-template/blob/v0.28.1/docs/templating-language.md -[template-config]: /vault/docs/agent-and-proxy/agent/template#template-configurations +[template-config]: /docs/agent-and-proxy/agent/template#template-configurations ## Tutorial Refer to the [OpenBao Agent - secrets as environment -variables](/vault/tutorials/vault-agent/agent-env-vars) tutorial for an +variables](/tutorials/vault-agent/agent-env-vars) tutorial for an end-to-end example. diff --git a/website/content/docs/agent-and-proxy/agent/template.mdx b/website/content/docs/agent-and-proxy/agent/template.mdx index 895923a462..eaa9223cb8 100644 --- a/website/content/docs/agent-and-proxy/agent/template.mdx +++ b/website/content/docs/agent-and-proxy/agent/template.mdx @@ -1,6 +1,5 @@ --- -layout: docs -page_title: OpenBao Agent Template +sidebar_label: Templates description: >- OpenBao Agent's Template functionality allows OpenBao secrets to be rendered to files using Consul Template markup. @@ -9,7 +8,7 @@ description: >- # OpenBao agent templates OpenBao Agent's Template functionality allows OpenBao secrets to be rendered to files -or environment variables (via the [Process Supervisor Mode](/vault/docs/agent-and-proxy/agent/process-supervisor)) +or environment variables (via the [Process Supervisor Mode](/docs/agent-and-proxy/agent/process-supervisor)) using [Consul Template markup][consul-templating-language]. ## Functionality @@ -52,7 +51,7 @@ of secret that's being rendered by this function, template will have different renewal behavior as detailed in the [Renewals section](#renewals-and-updating-secrets). The `pkiCert` function is intended to work specifically for certificates issued by the [PKI Secrets -Engine](/vault/docs/secrets/pki). Refer to the [Certificates](#certificates) section +Engine](/docs/secrets/pki). Refer to the [Certificates](#certificates) section for differences in certificate renewal behavior between `secret` and `pkiCert`. The following links contain additional resources for the templating language used by OpenBao Agent templating. @@ -105,7 +104,7 @@ failures. - `static_secret_render_interval` `(string or integer: 5m)` - If specified, configures how often OpenBao Agent Template should render non-leased secrets such as KV v2. This setting will not change how often OpenBao Agent Templating renders leased - secrets. Uses [duration format strings](/vault/docs/concepts/duration-format). + secrets. Uses [duration format strings](/docs/concepts/duration-format). ### `template_config` stanza example @@ -116,7 +115,7 @@ template_config { } ``` -In another example `template_config` with [`error_on_missing_key` parameter in the template stanza](/vault/docs/agent-and-proxy/agent/template#error_on_missing_key) +In another example `template_config` with [`error_on_missing_key` parameter in the template stanza](/docs/agent-and-proxy/agent/template#error_on_missing_key) as well as `exit_on_retry_failure` result in the agent exiting in case of no key / value issues instead of the default retry behavior. @@ -136,7 +135,7 @@ template { ### Interaction between `exit_on_retry_failure` and `error_on_missing_key` The parameter -[`error_on_missing_key`](/vault/docs/agent-and-proxy/agent/template#error_on_missing_key) can be +[`error_on_missing_key`](/docs/agent-and-proxy/agent/template#error_on_missing_key) can be specified within the `template` stanza which determines if a template should error when a key is missing in the secret. When `error_on_missing_key` is not specified or set to `false` and the key to render is not in the secret's @@ -163,12 +162,12 @@ parameters found in the template configuration section in the consul-template page](https://github.com/hashicorp/consul-template/blob/main/docs/configuration.md#templates) can be used here: - +:::tip The parameters marked with `Δ` below are only applicable to file templates and cannot be used with `env_template` entries in process supervisor mode. - +::: - `source` `(string: "")` - Path on disk to use as the input template. This option is required if not using the `contents` option. @@ -192,7 +191,7 @@ cannot be used with `env_template` entries in process supervisor mode. - `error_on_missing_key` `(bool: false)` - Exit with an error when accessing a struct or map field/key that does notexist. The default behavior will print `` when accessing a field that does not exist. It is highly recommended you set this - to "true". Also see [`exit_on_retry_failure` in global OpenBao Agent Template Config](/vault/docs/agent-and-proxy/agent/template#interaction-between-exit_on_retry_failure-and-error_on_missing_key). + to "true". Also see [`exit_on_retry_failure` in global OpenBao Agent Template Config](/docs/agent-and-proxy/agent/template#interaction-between-exit_on_retry_failure-and-error_on_missing_key). - `exec`Δ `(object: optional)` - The exec block executes a command when the template is rendered and the output has changed. The block parameters are `command` `(string or array: required)` and `timeout` `(string: optional, defaults @@ -209,8 +208,8 @@ cannot be used with `env_template` entries in process supervisor mode. at the destination path before writing a new one. It keeps exactly one backup. This option is useful for preventing accidental changes to the data without having a rollback strategy. -- `left_delimiter` `(string: "{{")` - Delimiter to use in the template. The - default is "{{" but for some templates, it may be easier to use a different +- `left_delimiter` `(string: "\{\{")` - Delimiter to use in the template. The + default is "\{\{" but for some templates, it may be easier to use a different delimiter that does not conflict with the output file itself. - `right_delimiter` `(string: "}}")` - Delimiter to use in the template. The default is "}}" but for some templates, it may be easier to use a different @@ -239,7 +238,7 @@ the `auto_auth` stanza in the agent configuration. ## Renewals and updating secrets The OpenBao Agent templating automatically renews and fetches secrets/tokens. -Unlike [OpenBao Agent caching](/vault/docs/agent-and-proxy/agent/caching), the behavior of how OpenBao Agent +Unlike [OpenBao Agent caching](/docs/agent-and-proxy/agent/caching), the behavior of how OpenBao Agent templating does this depends on the type of secret or token. The following is a high level overview of different behaviors. @@ -251,18 +250,18 @@ of the secret's lease duration has elapsed. ### Non-Renewable secrets If a secret or token isn't renewable or leased, OpenBao Agent will fetch the secret every 5 minutes. -This can be configured using Template config [static_secret_render_interval](/vault/docs/agent-and-proxy/agent/template#static_secret_render_interval). -Non-renewable secrets include (but not limited to) [KV Version 2](/vault/docs/secrets/kv/kv-v2). +This can be configured using Template config [static_secret_render_interval](/docs/agent-and-proxy/agent/template#static_secret_render_interval). +Non-renewable secrets include (but not limited to) [KV Version 2](/docs/secrets/kv/kv-v2). ### Non-Renewable leased secrets If a secret or token is non-renewable but leased, OpenBao Agent will fetch the secret when 85% of the secrets time-to-live (TTL) is reached. Leased, non-renewable secrets include (but not limited -to) dynamic secrets such as [database credentials](/vault/docs/secrets/databases) and [KV Version 1](/vault/docs/secrets/kv/kv-v1). +to) dynamic secrets such as [database credentials](/docs/secrets/databases) and [KV Version 1](/docs/secrets/kv/kv-v1). ### Static roles -If a secret has a `rotation_period`, such as a [database static role](/vault/docs/secrets/databases#static-roles), +If a secret has a `rotation_period`, such as a [database static role](/docs/secrets/databases#static-roles), OpenBao Agent template will fetch the new secret as it changes in OpenBao. It does this by inspecting the secret's time-to-live (TTL). @@ -275,7 +274,7 @@ re-authenticates. #### Rendering using the `pkiCert` template function -If a [certificate](/vault/docs/secrets/pki) is rendered using the `pkiCert` template +If a [certificate](/docs/secrets/pki) is rendered using the `pkiCert` template function, OpenBao Agent template will have the following fetching and re-rendering behaviors on certificates: @@ -286,7 +285,7 @@ skip fetching unless the current rendered one has expired. #### Rendering using the `secret` template function -If a [certificate](/vault/docs/secrets/pki) is rendered using the `secret` template +If a [certificate](/docs/secrets/pki) is rendered using the `secret` template function, OpenBao Agent template will have the following fetching and re-rendering behaviors on certificates: @@ -325,7 +324,7 @@ template { ``` And the following demonstrates how the templates look when using `env_template` with -[Process Supervisor Mode](/vault/docs/agent-and-proxy/agent/process-supervisor) +[Process Supervisor Mode](/docs/agent-and-proxy/agent/process-supervisor) ```hcl @@ -347,4 +346,4 @@ env_template "ENV_VAR_FROM_FILE" { ``` [consul-templating-language]: https://github.com/hashicorp/consul-template/blob/v0.28.1/docs/templating-language.md -[process-supervisor]: /vault/docs/agent-and-proxy/agent/process-supervisor +[process-supervisor]: /docs/agent-and-proxy/agent/process-supervisor diff --git a/website/content/docs/agent-and-proxy/agent/versions.mdx b/website/content/docs/agent-and-proxy/agent/versions.mdx index 463a06a883..b7e64313a1 100644 --- a/website/content/docs/agent-and-proxy/agent/versions.mdx +++ b/website/content/docs/agent-and-proxy/agent/versions.mdx @@ -1,6 +1,5 @@ --- -layout: docs -page_title: OpenBao Agent Version Compatibility +sidebar_label: Version compatibility description: |- Guidelines for running different versions of Agent and Server --- @@ -42,5 +41,5 @@ Proxy: - since Agent simply mirrors the incoming requests, it is unlikely that incompatibilities would surface in proxying, but new functionality may not be available Templating: -- we don't anticipate a scenario where changes to Agent's templating itself gives rise to an incompatibility with older OpenBao Servers, though of course with any Agent version it's possible to write templates that issue requests which make use of functionality not yet present in the upstream OpenBao server, e.g. {{ with secret "secret/my-secret?some-new-option" }} +- we don't anticipate a scenario where changes to Agent's templating itself gives rise to an incompatibility with older OpenBao Servers, though of course with any Agent version it's possible to write templates that issue requests which make use of functionality not yet present in the upstream OpenBao server, e.g. \{\{ with secret "secret/my-secret?some-new-option" }} - we would not deliberately make a change to templating that breaks existing deployments diff --git a/website/content/docs/agent-and-proxy/agent/winsvc.mdx b/website/content/docs/agent-and-proxy/agent/winsvc.mdx index 3b5ad460d6..b149f7fac1 100644 --- a/website/content/docs/agent-and-proxy/agent/winsvc.mdx +++ b/website/content/docs/agent-and-proxy/agent/winsvc.mdx @@ -1,6 +1,5 @@ --- -layout: docs -page_title: OpenBao Agent Windows Service +sidebar_label: Windows service description: >- OpenBao Agent can be run as a Windows service. --- @@ -27,9 +26,13 @@ both will be shown below. ### Using sc.exe -~> **Important Note:** Ensure the executable path of the service is quoted, especially when it contains spaces, to avoid +:::warning + +**Important Note:** Ensure the executable path of the service is quoted, especially when it contains spaces, to avoid potential privilege escalation risks. +::: + If you use `sc.exe`, make sure you specify `sc.exe` explicitly, and not just `sc`. The command below shows the creation of OpenBao Agent as a service, using "OpenBao Agent" as the display name, and starting automatically when Windows starts. The `binPath` argument should include the fully qualified path to the OpenBao executable, as well as any arguments required. diff --git a/website/content/docs/agent-and-proxy/autoauth/index.mdx b/website/content/docs/agent-and-proxy/autoauth/index.mdx index 1f7af59f97..e293cfc565 100644 --- a/website/content/docs/agent-and-proxy/autoauth/index.mdx +++ b/website/content/docs/agent-and-proxy/autoauth/index.mdx @@ -1,6 +1,5 @@ --- -layout: docs -page_title: OpenBao Agent and OpenBao Proxy Auto-Auth +sidebar_label: Overview description: |- OpenBao Agent and OpenBao Proxy's Auto-Auth functionality allows easy and automatic authentication to OpenBao in a variety of environments. @@ -31,7 +30,7 @@ configured Sinks, subject to their configuration. Sinks support some advanced features, including the ability for the written values to be encrypted or -[response-wrapped](/vault/docs/concepts/response-wrapping). +[response-wrapped](/docs/concepts/response-wrapping). Both mechanisms can be used concurrently; in this case, the value will be response-wrapped, then encrypted. @@ -58,9 +57,13 @@ There are two ways that tokens can be response-wrapped: ### Encrypting tokens -~> Support for encrypted tokens is experimental; if input/output formats +:::warning + +Support for encrypted tokens is experimental; if input/output formats change, we will make every effort to provide backwards compatibility. +::: + Tokens can be encrypted, using a Diffie-Hellman exchange to generate an ephemeral key. In this mechanism, the client receiving the token writes a generated public key to a file. The sink responsible for writing the token to @@ -69,12 +72,16 @@ key, which is then used to encrypt the token via AES-GCM. The nonce, encrypted payload, and the sink's public key are then written to the output file, where the client can compute the shared secret and decrypt the token value. -~> NOTE: Token encryption is not a protection against MITM attacks! The purpose +:::warning + +NOTE: Token encryption is not a protection against MITM attacks! The purpose of this feature is for forward-secrecy and coverage against bare token values being persisted. A MITM that can write to the sink's output and/or client public-key input files could attack this exchange. Using TLS to protect the transit of tokens is highly recommended. +::: + To help mitigate MITM attacks, additional authenticated data (AAD) can be provided to Agent and Proxy. This data is written as part of the AES-GCM tag and must match on both Agent and Proxy and the client. This of course means that protecting @@ -106,11 +113,15 @@ The top level `auto_auth` block has two configuration entries: ### Configuration (Method) -~> Auto-auth does not support using tokens with a limited number of uses. Auto-auth +:::warning + +Auto-auth does not support using tokens with a limited number of uses. Auto-auth does not track the number of uses remaining, and may allow the token to expire before attempting to renew it. For example, if using AppRole auto-auth, you must use 0 (meaning unlimited) as the value for -[`token_num_uses`](/vault/api-docs/auth/approle#token_num_uses). +[`token_num_uses`](/api-docs/auth/approle#token_num_uses). + +::: These are common configuration values that live within the `method` block: @@ -135,14 +146,14 @@ These are common configuration values that live within the `method` block: automatically reauthenticate when it expires. Rather than a simple string, the written value will be a JSON-encoded [SecretWrapInfo](https://godoc.org/github.com/openbao/openbao/api#SecretWrapInfo) - structure. Uses [duration format strings](/vault/docs/concepts/duration-format). + structure. Uses [duration format strings](/docs/concepts/duration-format). - `min_backoff` `(string or integer: "1s")` - The minimum backoff time auto-auth will delay before retrying after a failed auth attempt. The backoff will start at the configured value and double (with some randomness) after successive failures, capped by `max_backoff.` If Agent templating is being used, this value is also used as the min backoff time for the templating server. - Uses [duration format strings](/vault/docs/concepts/duration-format). + Uses [duration format strings](/docs/concepts/duration-format). - `max_backoff` `(string or integer: "5m")` - The maximum time Agent will delay before retrying after a failed auth attempt. The backoff will start at @@ -150,7 +161,7 @@ These are common configuration values that live within the `method` block: capped by `max_backoff.` If Agent templating is being used, this value is also used as the max backoff time for the templating server. `max_backoff` is the duration between retries, and **not** the duration that retries will be - performed before giving up. Uses [duration format strings](/vault/docs/concepts/duration-format). + performed before giving up. Uses [duration format strings](/docs/concepts/duration-format). - `exit_on_err` `(bool: false)` - When set to true, OpenBao Agent and OpenBao Proxy will exit if any errors occur during authentication. This configurable only affects login @@ -173,7 +184,7 @@ These configuration values are common to all Sinks: reauthenticate when it expires. Rather than a simple string, the written value will be a JSON-encoded [SecretWrapInfo](https://godoc.org/github.com/openbao/openbao/api#SecretWrapInfo) - structure. Uses [duration format strings](/vault/docs/concepts/duration-format). + structure. Uses [duration format strings](/docs/concepts/duration-format). - `dh_type` `(string: optional)` - If specified, the type of Diffie-Hellman exchange to perform, meaning, which ciphers and/or curves. Currently only `curve25519` is @@ -209,9 +220,13 @@ the two formats. The HCL format may define any number of sink objects with an optional wrapping `sinks {...}` object. -~> Note: The [corresponding JSON format](#sinks-json-format) _must_ specify a +:::warning + +Note: The [corresponding JSON format](#sinks-json-format) _must_ specify a `"sinks" : [...]` array to encapsulate all `sink` JSON objects. +::: + ```hcl // Other OpenBao Agent or OpenBao Proxy configuration blocks // ... diff --git a/website/content/docs/agent-and-proxy/autoauth/methods/approle.mdx b/website/content/docs/agent-and-proxy/autoauth/methods/approle.mdx index 76ae38c8b6..80a6ab4a92 100644 --- a/website/content/docs/agent-and-proxy/autoauth/methods/approle.mdx +++ b/website/content/docs/agent-and-proxy/autoauth/methods/approle.mdx @@ -1,6 +1,5 @@ --- -layout: docs -page_title: OpenBao Auto-Auth AppRole Method +sidebar_label: AppRole description: AppRole Method for OpenBao Auto-Auth --- @@ -8,7 +7,7 @@ description: AppRole Method for OpenBao Auto-Auth The `approle` method reads in a role ID and a secret ID from files and sends the values to the [AppRole Auth -method](/vault/docs/auth/approle). +method](/docs/auth/approle). The method caches values and it is safe to delete the role ID/secret ID files after they have been read. In fact, by default, after reading the secret ID, @@ -32,15 +31,15 @@ cached. - `secret_id_response_wrapping_path` `(string: optional)` - If set, the value at `secret_id_file_path` will be expected to be a [Response-Wrapping - Token](/vault/docs/concepts/response-wrapping) + Token](/docs/concepts/response-wrapping) containing the output of the secret ID retrieval endpoint for the role (e.g. `auth/approle/role/webservers/secret-id`) and the creation path for the response-wrapping token must match the value set here. ## Example configuration -An example configuration, using approle to enable [auto-auth](/vault/docs/agent-and-proxy/autoauth) -and creating both a plaintext token sink and a [response-wrapped token sink file](/vault/docs/agent-and-proxy/autoauth#wrap_ttl), follows: +An example configuration, using approle to enable [auto-auth](/docs/agent-and-proxy/autoauth) +and creating both a plaintext token sink and a [response-wrapped token sink file](/docs/agent-and-proxy/autoauth#wrap_ttl), follows: ```hcl pid_file = "./pidfile" diff --git a/website/content/docs/agent-and-proxy/autoauth/methods/cert.mdx b/website/content/docs/agent-and-proxy/autoauth/methods/cert.mdx index 92845969d7..736eaf4ba0 100644 --- a/website/content/docs/agent-and-proxy/autoauth/methods/cert.mdx +++ b/website/content/docs/agent-and-proxy/autoauth/methods/cert.mdx @@ -1,6 +1,5 @@ --- -layout: docs -page_title: OpenBao Auto-Auth Cert Method +sidebar_label: Cert description: Cert Method for OpenBao Auto-Auth --- @@ -14,13 +13,13 @@ It is strongly advised to provide TLS settings in the configuration stanza within the auth method to avoid agent cache, if also enabled, from using the same TLS settings when proxying requests. If TLS settings are not present in the config stanza, Agent and Proxy will fall back to using TLS settings from their respective -[`vault` Stanzas](/vault/docs/agent#vault-stanza). +[`vault` Stanzas](/docs/agent#vault-stanza). ## Configuration - `name` `(string: optional)` - The trusted certificate role which should be used when authenticating with TLS. If a `name` is not specified, the auth method will - try to authenticate against [all trusted certificates](/vault/docs/auth/cert#authentication). + try to authenticate against [all trusted certificates](/docs/auth/cert#authentication). - `ca_cert` `(string: optional)` - Path on the local disk to a single PEM-encoded CA certificate to verify the OpenBao server's SSL certificate. diff --git a/website/content/docs/agent-and-proxy/autoauth/methods/index.mdx b/website/content/docs/agent-and-proxy/autoauth/methods/index.mdx index a4d3c616dd..dea41b5f27 100644 --- a/website/content/docs/agent-and-proxy/autoauth/methods/index.mdx +++ b/website/content/docs/agent-and-proxy/autoauth/methods/index.mdx @@ -1,6 +1,5 @@ --- -layout: docs -page_title: OpenBao Auto-Auth Methods +sidebar_label: Overview description: Methods for OpenBao Auto-Auth --- diff --git a/website/content/docs/agent-and-proxy/autoauth/methods/jwt.mdx b/website/content/docs/agent-and-proxy/autoauth/methods/jwt.mdx index 4496beec99..7ec18d72cd 100644 --- a/website/content/docs/agent-and-proxy/autoauth/methods/jwt.mdx +++ b/website/content/docs/agent-and-proxy/autoauth/methods/jwt.mdx @@ -1,13 +1,12 @@ --- -layout: docs -page_title: OpenBao Auto-Auth JWT Method +sidebar_label: JWT description: JWT Method for OpenBao Auto-Auth --- # OpenBao Auto-Auth JWT method The `jwt` method reads in a JWT from a file and sends it to the [JWT Auth -method](/vault/docs/auth/jwt). +method](/docs/auth/jwt). ## Configuration @@ -27,4 +26,4 @@ the symlink, not the JWT. Does nothing if `remove_jwt_after_reading` is false. - `jwt_read_period` `(duration: "0.5s", optional)` - The duration after which Agent will attempt to read the JWT stored at `path`. Defaults to `1m` if `remove_jwt_after_reading` is set to `true`, or `0.5s` otherwise. -Uses [duration format strings](/vault/docs/concepts/duration-format). +Uses [duration format strings](/docs/concepts/duration-format). diff --git a/website/content/docs/agent-and-proxy/autoauth/methods/kerberos.mdx b/website/content/docs/agent-and-proxy/autoauth/methods/kerberos.mdx index 2917cdec35..a51cceb566 100644 --- a/website/content/docs/agent-and-proxy/autoauth/methods/kerberos.mdx +++ b/website/content/docs/agent-and-proxy/autoauth/methods/kerberos.mdx @@ -1,6 +1,5 @@ --- -layout: 'docs' -page_title: 'OpenBao Auto-Auth Kerberos Method' +sidebar_label: Kerberos sidebar_current: 'docs-agent-and-proxy-autoauth-methods-kerberos' description: |- Kerberos Method for OpenBao Auto-Auth @@ -13,7 +12,7 @@ an OpenBao token for Kerberos entities. It reads in configuration and identification information from the surrounding environment, and uses it to authenticate to OpenBao. -For more on this auth method, see the [Kerberos auth method](/vault/docs/auth/kerberos). +For more on this auth method, see the [Kerberos auth method](/docs/auth/kerberos). ## Configuration diff --git a/website/content/docs/agent-and-proxy/autoauth/methods/kubernetes.mdx b/website/content/docs/agent-and-proxy/autoauth/methods/kubernetes.mdx index c811a5ddbb..3df8c1e059 100644 --- a/website/content/docs/agent-and-proxy/autoauth/methods/kubernetes.mdx +++ b/website/content/docs/agent-and-proxy/autoauth/methods/kubernetes.mdx @@ -1,6 +1,5 @@ --- -layout: docs -page_title: OpenBao Auto-Auth Kubernetes Method +sidebar_label: Kubernetes description: Kubernetes Method for OpenBao Auto-Auth --- @@ -9,7 +8,7 @@ description: Kubernetes Method for OpenBao Auto-Auth The `kubernetes` method reads in a Kubernetes service account token from the running pod (via `/var/run/secrets/kubernetes.io/serviceaccount/token`) and sends it to the [Kubernetes Auth -method](/vault/docs/auth/kubernetes/). +method](/docs/auth/kubernetes/). ## Configuration @@ -20,5 +19,5 @@ method](/vault/docs/auth/kubernetes/). ## Tutorial Refer to the [OpenBao Agent with -Kubernetes](/vault/tutorials/kubernetes/agent-kubernetes) +Kubernetes](/tutorials/kubernetes/agent-kubernetes) tutorial to learn how to authenticate the clients using a Kubernetes Service Account Token and manage the tokens lifecycle. diff --git a/website/content/docs/agent-and-proxy/autoauth/methods/token_file.mdx b/website/content/docs/agent-and-proxy/autoauth/methods/token_file.mdx index f25dcafdd8..351208c7a2 100644 --- a/website/content/docs/agent-and-proxy/autoauth/methods/token_file.mdx +++ b/website/content/docs/agent-and-proxy/autoauth/methods/token_file.mdx @@ -1,15 +1,18 @@ --- -layout: docs -page_title: OpenBao Auto-Auth Token File Method +sidebar_label: Token file description: Token File Method for OpenBao Auto-Auth --- # OpenBao Auto-Auth token file method -~> Note: This authentication method is tailored for the development experience, +:::warning + +Note: This authentication method is tailored for the development experience, and to facilitate getting started with OpenBao Agent and OpenBao Proxy. OpenBao Agent and OpenBao Proxy should never be configured to use this auto-auth method in a production environment. +::: + The `token_file` method reads in an existing, valid OpenBao token from a file, and uses that token in lieu of authenticating itself. While it's a first class auto-auth method for all intents and purposes, it naturally doesn't authenticate itself, as it requires a token from elsewhere. Like @@ -25,7 +28,7 @@ auto-auth method, such that Agent and Proxy are issuing their own own authentica ## Example configuration -An example configuration for OpenBao Agent, using the `token_file` method to enable [auto-auth](/vault/docs/agent-and-proxy/autoauth), follows: +An example configuration for OpenBao Agent, using the `token_file` method to enable [auto-auth](/docs/agent-and-proxy/autoauth), follows: ```hcl pid_file = "./pidfile" diff --git a/website/content/docs/agent-and-proxy/autoauth/sinks/file.mdx b/website/content/docs/agent-and-proxy/autoauth/sinks/file.mdx index ff5c7113e9..283db3a918 100644 --- a/website/content/docs/agent-and-proxy/autoauth/sinks/file.mdx +++ b/website/content/docs/agent-and-proxy/autoauth/sinks/file.mdx @@ -1,6 +1,5 @@ --- -layout: docs -page_title: OpenBao Agent and OpenBao Proxy Auto-Auth File Sink +sidebar_label: File description: File sink for Auto-Auth --- @@ -23,5 +22,5 @@ written with `0640` permissions as default, but can be overridden with the optio - `path` `(string: required)` - The path to use to write the token file - `mode` `(int: optional)` - A string containing an octal number representing the bit pattern for the file mode, similar to chmod. Set to `0000` to prevent OpenBao from modifying the file mode. -~> Note: Configuration options for response-wrapping and encryption for the sink -file are located within the [options common to all sinks](/vault/docs/agent-and-proxy/autoauth#configuration-sinks) documentation. +Note: Configuration options for response-wrapping and encryption for the sink +file are located within the [options common to all sinks](/docs/agent-and-proxy/autoauth#configuration-sinks) documentation. diff --git a/website/content/docs/agent-and-proxy/autoauth/sinks/index.mdx b/website/content/docs/agent-and-proxy/autoauth/sinks/index.mdx index 1fbfe9c995..bacee5f538 100644 --- a/website/content/docs/agent-and-proxy/autoauth/sinks/index.mdx +++ b/website/content/docs/agent-and-proxy/autoauth/sinks/index.mdx @@ -1,6 +1,5 @@ --- -layout: docs -page_title: OpenBao Agent and OpenBao Proxy Auto-Auth Sinks +sidebar_label: Overview description: Sinks for Auto-Auth --- @@ -8,4 +7,4 @@ description: Sinks for Auto-Auth Every time an auto-auth authentication is successful, the token is written to the enabled Sinks, subject to their configuration. Today, we only support one -type of sink, [file sink](/vault/docs/agent-and-proxy/autoauth/sinks/file). +type of sink, [file sink](/docs/agent-and-proxy/autoauth/sinks/file). diff --git a/website/content/docs/agent-and-proxy/index.mdx b/website/content/docs/agent-and-proxy/index.mdx index 1c6504b20c..2d2d0e768a 100644 --- a/website/content/docs/agent-and-proxy/index.mdx +++ b/website/content/docs/agent-and-proxy/index.mdx @@ -1,6 +1,4 @@ --- -layout: docs -page_title: OpenBao Agent and OpenBao Proxy description: |- OpenBao Agent and OpenBao Proxy are daemons that can be used to perform some OpenBao functionality automatically. @@ -26,7 +24,7 @@ request secrets from OpenBao. This implies code changes to client applications along with additional testing and maintenance of the application. The following code example implements OpenBao API to authenticate with OpenBao -through [AppRole auth method](/vault/docs/auth/approle#code-example), and then uses +through [AppRole auth method](/docs/auth/approle#code-example), and then uses the returned client token to read secrets at `kv-v2/data/creds`. ```go @@ -98,12 +96,12 @@ To learn more, refer to the [OpenBao Agent][openbaoagent] or [OpenBao Proxy][openbaoproxy] documentation page. -[autoauth]: /vault/docs/agent-and-proxy/autoauth -[caching]: /vault/docs/agent-and-proxy/agent/caching -[apiproxy]: /vault/docs/agent-and-proxy/proxy/apiproxy -[template]: /vault/docs/agent-and-proxy/agent/template -[exec]: /vault/docs/agent-and-proxy/agent/process-supervisor -[template-config]: /vault/docs/agent-and-proxy/agent/template#template-configurations -[openbaoagent]: /vault/docs/agent-and-proxy/agent -[openbaoproxy]: /vault/docs/agent-and-proxy/proxy -[winsvc]: /vault/docs/agent-and-proxy/agent/winsvc +[autoauth]: /docs/agent-and-proxy/autoauth +[caching]: /docs/agent-and-proxy/agent/caching +[apiproxy]: /docs/agent-and-proxy/proxy/apiproxy +[template]: /docs/agent-and-proxy/agent/template +[exec]: /docs/agent-and-proxy/agent/process-supervisor +[template-config]: /docs/agent-and-proxy/agent/template#template-configurations +[openbaoagent]: /docs/agent-and-proxy/agent +[openbaoproxy]: /docs/agent-and-proxy/proxy +[winsvc]: /docs/agent-and-proxy/agent/winsvc diff --git a/website/content/docs/agent-and-proxy/proxy/apiproxy.mdx b/website/content/docs/agent-and-proxy/proxy/apiproxy.mdx index d004fa0fef..c18e9a5e97 100644 --- a/website/content/docs/agent-and-proxy/proxy/apiproxy.mdx +++ b/website/content/docs/agent-and-proxy/proxy/apiproxy.mdx @@ -1,6 +1,5 @@ --- -layout: docs -page_title: OpenBao Proxy API Proxy +sidebar_label: API proxy description: >- OpenBao Proxy's API Proxy functionality allows you to use OpenBao Proxy's API as a proxy for OpenBao's API. @@ -13,20 +12,20 @@ for OpenBao's API. ## Functionality -The [`listener` stanza](/vault/docs/agent#listener-stanza) for OpenBao Proxy configures a listener for OpenBao Proxy. If +The [`listener` stanza](/docs/agent#listener-stanza) for OpenBao Proxy configures a listener for OpenBao Proxy. If its `role` is not set to `metrics_only`, it will act as a proxy for the OpenBao server that -has been configured in the [`vault` stanza](/vault/docs/agent-and-proxy/proxy#vault-stanza) of Proxy Agent. This enables access to the OpenBao +has been configured in the [`vault` stanza](/docs/agent-and-proxy/proxy#vault-stanza) of Proxy Agent. This enables access to the OpenBao API from the Proxy API, and can be configured to optionally allow or force the automatic use of the Auto-Auth token for these requests, as described below. If a `listener` has been configured alongside a `cache` stanza, the API Proxy will first attempt to utilize the cache subsystem for qualifying requests, before forwarding the -request to OpenBao. See the [caching docs](/vault/docs/agent-and-proxy/proxy/caching) for more information on caching. +request to OpenBao. See the [caching docs](/docs/agent-and-proxy/proxy/caching) for more information on caching. ## Using Auto-Auth token OpenBao Proxy allows for easy authentication to OpenBao in a wide variety of -environments using [Auto-Auth](/vault/docs/agent-and-proxy/autoauth). By setting the +environments using [Auto-Auth](/docs/agent-and-proxy/autoauth). By setting the `use_auto_auth_token` (see below) configuration, clients will not be required to provide an OpenBao token to the requests made to the Agent. When this configuration is set, if the request doesn't already bear a token, then the @@ -40,7 +39,7 @@ request to the OpenBao server. OpenBao Proxy can be configured to force the use of the auto-auth token by using the value `force` for the `use_auto_auth_token` option. This configuration overrides the default behavior described above in [Using Auto-Auth -Token](/vault/docs/agent-and-proxy/proxy/apiproxy#using-auto-auth-token), and instead ignores any +Token](/docs/agent-and-proxy/proxy/apiproxy#using-auto-auth-token), and instead ignores any existing OpenBao token in the request and instead uses the auto-auth token. diff --git a/website/content/docs/agent-and-proxy/proxy/caching/index.mdx b/website/content/docs/agent-and-proxy/proxy/caching/index.mdx index ec6316d1ae..4077de1bf8 100644 --- a/website/content/docs/agent-and-proxy/proxy/caching/index.mdx +++ b/website/content/docs/agent-and-proxy/proxy/caching/index.mdx @@ -1,6 +1,5 @@ --- -layout: docs -page_title: OpenBao Proxy Caching +sidebar_label: Overview description: |- OpenBao Proxy Caching allows client-side caching of responses containing newly created tokens and responses containing leased secrets generated off of these @@ -37,7 +36,7 @@ OpenBao Proxy can restore tokens and leases from a persistent cache file created by a previous OpenBao Proxy process. Refer to the [OpenBao Proxy Persistent -Caching](/vault/docs/agent-and-proxy/proxy/caching/persistent-caches) page for more information on +Caching](/docs/agent-and-proxy/proxy/caching/persistent-caches) page for more information on this functionality. ## Cache evictions @@ -149,10 +148,14 @@ The top level `cache` block has the following configuration entry: - `persist` `(object: optional)` - Configuration for the persistent cache. --> **Note:** When the `cache` block is defined, a [listener][proxy-listener] must also be defined +:::info + +**Note:** When the `cache` block is defined, a [listener][proxy-listener] must also be defined in the config, otherwise there is no way to utilize the cache. -[proxy-listener]: /vault/docs/agent-and-proxy/proxy#listener-stanza +::: + +[proxy-listener]: /docs/agent-and-proxy/proxy#listener-stanza ### Configuration (Persist) @@ -181,9 +184,9 @@ Defaults to `/var/run/secrets/kubernetes.io/serviceaccount/token`. - `listener` `(array of objects: required)` - Configuration for the listeners. There can be one or more `listener` blocks at the top level. Adding a listener enables -the [API Proxy](/vault/docs/agent-and-proxy/proxy/apiproxy) and enables the API proxy to use the cache, if configured. +the [API Proxy](/docs/agent-and-proxy/proxy/apiproxy) and enables the API proxy to use the cache, if configured. These configuration values are common to both `tcp` and `unix` listener blocks. Blocks of type -`tcp` support the standard `tcp` [listener](/vault/docs/configuration/listener/tcp) +`tcp` support the standard `tcp` [listener](/docs/configuration/listener/tcp) options. Additionally, the `role` string option is available as part of the top level of the `listener` block, which can be configured to `metrics_only` to serve only metrics, or the default role, `default`, which serves everything (including metrics). diff --git a/website/content/docs/agent-and-proxy/proxy/caching/persistent-caches/index.mdx b/website/content/docs/agent-and-proxy/proxy/caching/persistent-caches/index.mdx index 27eff1a18a..a063e758fc 100644 --- a/website/content/docs/agent-and-proxy/proxy/caching/persistent-caches/index.mdx +++ b/website/content/docs/agent-and-proxy/proxy/caching/persistent-caches/index.mdx @@ -1,6 +1,5 @@ --- -layout: docs -page_title: OpenBao Proxy Persistent Caching +sidebar_label: Overview description: OpenBao Proxy Caching --- @@ -12,16 +11,24 @@ includes tuples encrypted by a generated encryption key. The encrypted tuples include the OpenBao token used to retrieve secrets, leases for tokens/secrets, and secret values. --> **Note:** OpenBao Proxy Persistent Caching will only restore _leased_ +:::info + +**Note:** OpenBao Proxy Persistent Caching will only restore _leased_ secrets. Secrets that are not renewable, such as KV v2, will not be persisted. +::: + In order to use OpenBao Proxy persistent cache, auto-auth must be used. If the auto-auth token has expired by the time the cache is restored, the cache will be invalidated and secrets will need to be re-fetched from OpenBao. --> **Note** OpenBao Proxy persistent cache is currently supported only in a +:::info + +**Note** OpenBao Proxy persistent cache is currently supported only in a Kubernetes environment. +::: + ## OpenBao proxy persistent cache types Please see the sidebar for available types and their usage/configuration. diff --git a/website/content/docs/agent-and-proxy/proxy/caching/persistent-caches/kubernetes.mdx b/website/content/docs/agent-and-proxy/proxy/caching/persistent-caches/kubernetes.mdx index f03b4eacc4..b1929a8e69 100644 --- a/website/content/docs/agent-and-proxy/proxy/caching/persistent-caches/kubernetes.mdx +++ b/website/content/docs/agent-and-proxy/proxy/caching/persistent-caches/kubernetes.mdx @@ -1,6 +1,5 @@ --- -layout: docs -page_title: Kubernetes - OpenBao Proxy Persistent Cache +sidebar_label: Kubernetes description: Kubernetes Persistent Cache for OpenBao Proxy Caching --- diff --git a/website/content/docs/agent-and-proxy/proxy/index.mdx b/website/content/docs/agent-and-proxy/proxy/index.mdx index 0486d3e0a3..2ee14abc90 100644 --- a/website/content/docs/agent-and-proxy/proxy/index.mdx +++ b/website/content/docs/agent-and-proxy/proxy/index.mdx @@ -1,6 +1,5 @@ --- -layout: docs -page_title: OpenBao Proxy +sidebar_label: Overview description: |- OpenBao Proxy is a daemon that can be used to perform some OpenBao functionality automatically, and act as a proxy for OpenBao's APIs. @@ -39,7 +38,7 @@ the Auto-Auth token for these requests. Please see the [API Proxy docs][apiproxy for more information. API Proxy functionality takes place within a defined `listener`, and its behaviour can be configured with an -[`api_proxy` stanza](/vault/docs/agent-and-proxy/proxy/apiproxy#configuration-api_proxy). +[`api_proxy` stanza](/docs/agent-and-proxy/proxy/apiproxy#configuration-api_proxy). ## Caching @@ -61,21 +60,21 @@ to only enable this on trusted interfaces, as it does not require any authorizat ### Cache -See the [caching](/vault/docs/agent-and-proxy/proxy/caching#api) page for details on the cache API. +See the [caching](/docs/agent-and-proxy/proxy/caching#api) page for details on the cache API. ## Configuration ### Command options -- `-log-level` ((#\_log_level)) `(string: "info")` - Log verbosity level. Supported values (in +- `-log-level` `(string: "info")` - Log verbosity level. Supported values (in order of descending detail) are `trace`, `debug`, `info`, `warn`, and `error`. This can also be specified via the `VAULT_LOG_LEVEL` environment variable. -- `-log-format` ((#\_log_format)) `(string: "standard")` - Log format. Supported values +- `-log-format` `(string: "standard")` - Log format. Supported values are `standard` and `json`. This can also be specified via the `VAULT_LOG_FORMAT` environment variable. -- `-log-file` ((#\_log_file)) - the absolute path where OpenBao Proxy should save +- `-log-file` - the absolute path where OpenBao Proxy should save log messages. Paths that end with a path separator use the default file name, `proxy.log`. Paths that do not end with a file extension use the default `.log` extension. If the log file rotates, OpenBao Proxy appends the current @@ -87,15 +86,15 @@ are `standard` and `json`. This can also be specified via the `/var/log/my-diary` | `/var/log/my-diary.log` | `/var/log/my-diary-{timestamp}.log` `/var/log/my-diary.txt` | `/var/log/my-diary.txt` | `/var/log/my-diary-{timestamp}.txt` -- `-log-rotate-bytes` ((#\_log_rotate_bytes)) - to specify the number of +- `-log-rotate-bytes` - to specify the number of bytes that should be written to a log before it needs to be rotated. Unless specified, there is no limit to the number of bytes that can be written to a log file. -- `-log-rotate-duration` ((#\_log_rotate_duration)) - to specify the maximum +- `-log-rotate-duration` - to specify the maximum duration a log should be written to before it needs to be rotated. Must be a duration value such as 30s. Defaults to 24h. -- `-log-rotate-max-files` ((#\_log_rotate_max_files)) - to specify the maximum +- `-log-rotate-max-files` - to specify the maximum number of older log file archives to keep. Defaults to `0` (no files are ever deleted). Set to `-1` to discard old log files when a new one is created. @@ -103,19 +102,23 @@ Set to `-1` to discard old log files when a new one is created. These are the currently-available general configuration options: -- `vault` ([vault][vault]: ) - Specifies the remote OpenBao server the Proxy connects to. +- `vault` ([vault][vault]: \) - Specifies the remote OpenBao server the Proxy connects to. -- `auto_auth` ([auto_auth][autoauth]: ) - Specifies the method and other options used for Auto-Auth functionality. +- `auto_auth` ([auto_auth][autoauth]: \) - Specifies the method and other options used for Auto-Auth functionality. -- `api_proxy` ([api_proxy][apiproxy]: ) - Specifies options used for API Proxy functionality. +- `api_proxy` ([api_proxy][apiproxy]: \) - Specifies options used for API Proxy functionality. -- `cache` ([cache][caching]: ) - Specifies options used for Caching functionality. +- `cache` ([cache][caching]: \) - Specifies options used for Caching functionality. -- `listener` ([listener][listener]: ) - Specifies the addresses and ports on which the Proxy will respond to requests. +- `listener` ([listener][listener]: \) - Specifies the addresses and ports on which the Proxy will respond to requests. -~> **Note:** On `SIGHUP` (`kill -SIGHUP $(pidof bao)`), OpenBao Proxy will attempt to reload listener TLS configuration. +:::warning + +**Note:** On `SIGHUP` (`kill -SIGHUP $(pidof bao)`), OpenBao Proxy will attempt to reload listener TLS configuration. This method can be used to refresh certificates used by OpenBao Proxy without having to restart its process. +::: + - `pid_file` `(string: "")` - Path to the file in which the Proxy's Process ID (PID) should be stored @@ -131,19 +134,23 @@ environment variable as a comma separated string. This environment variable will Valid values include: `auto-auth`, and `proxying`. Can also be configured by setting the `VAULT_PROXY_DISABLE_KEEP_ALIVES` environment variable as a comma separated string. This environment variable will override any values found in a configuration file. -- `template` ([template][template]: ) - Specifies options used for templating OpenBao secrets to files. +- `template` ([template][template]: \) - Specifies options used for templating OpenBao secrets to files. -- `template_config` ([template_config][template-config]: ) - Specifies templating engine behavior. +- `template_config` ([template_config][template-config]: \) - Specifies templating engine behavior. -- `telemetry` ([telemetry][telemetry]: ) – Specifies the telemetry -reporting system. See the [telemetry Stanza](/vault/docs/agent-and-proxy/proxy#telemetry-stanza) section below +- `telemetry` ([telemetry][telemetry]: \) – Specifies the telemetry +reporting system. See the [telemetry Stanza](/docs/agent-and-proxy/proxy#telemetry-stanza) section below for a list of metrics specific to Proxy. - `log_level` - Equivalent to the [`-log-level` command-line flag](#_log_level). -~> **Note:** On `SIGHUP` (`kill -SIGHUP $(pidof bao)`), OpenBao Proxy will update the log level to the value +:::warning + +**Note:** On `SIGHUP` (`kill -SIGHUP $(pidof bao)`), OpenBao Proxy will update the log level to the value specified by configuration file (including overriding values set using CLI or environment variable parameters). +::: + - `log_format` - Equivalent to the [`-log-format` command-line flag](#_log_format). - `log_file` - Equivalent to the [`-log-file` command-line flag](#_log_file). @@ -228,11 +235,11 @@ It can be configured to `metrics_only` to serve only metrics, or the default rol which serves everything (including metrics). The `require_request_header` does not apply to `metrics_only` listeners. -- `proxy_api` ([proxy_api][proxy-api]: ) - Manages optional Proxy API endpoints. +- `proxy_api` ([proxy_api][proxy-api]: \) - Manages optional Proxy API endpoints. #### proxy_api stanza -- `enable_quit` `(bool: false)` - If set to `true`, the Proxy will enable the [quit](/vault/docs/agent-and-proxy/proxy#quit) API. +- `enable_quit` `(bool: false)` - If set to `true`, the Proxy will enable the [quit](/docs/agent-and-proxy/proxy#quit) API. ### telemetry stanza @@ -253,7 +260,7 @@ runtime metrics about its performance, the auto-auth and the cache status: To run OpenBao Proxy: -1. [Download](/vault/downloads) the OpenBao binary where the client application runs +1. [Download](/downloads) the OpenBao binary where the client application runs (virtual machine, Kubernetes pod, etc.) 1. Create an OpenBao Proxy configuration file. (See the [Example @@ -340,14 +347,14 @@ listener "tcp" { } ``` -[vault]: /vault/docs/agent-and-proxy/proxy#vault-stanza -[autoauth]: /vault/docs/agent-and-proxy/autoauth -[caching]: /vault/docs/agent-and-proxy/proxy/caching -[apiproxy]: /vault/docs/agent-and-proxy/proxy/apiproxy -[persistent-cache]: /vault/docs/agent-and-proxy/proxy/caching/persistent-caches -[template]: /vault/docs/agent-and-proxy/proxy/template -[template-config]: /vault/docs/agent-and-proxy/proxy/template#template-configurations -[proxy-api]: /vault/docs/agent-and-proxy/proxy/#proxy_api-stanza -[listener]: /vault/docs/agent-and-proxy/proxy#listener-stanza -[listener_main]: /vault/docs/configuration/listener/tcp -[telemetry]: /vault/docs/configuration/telemetry +[vault]: /docs/agent-and-proxy/proxy#vault-stanza +[autoauth]: /docs/agent-and-proxy/autoauth +[caching]: /docs/agent-and-proxy/proxy/caching +[apiproxy]: /docs/agent-and-proxy/proxy/apiproxy +[persistent-cache]: /docs/agent-and-proxy/proxy/caching/persistent-caches +[template]: /docs/agent-and-proxy/proxy/template +[template-config]: /docs/agent-and-proxy/proxy/template#template-configurations +[proxy-api]: /docs/agent-and-proxy/proxy/#proxy_api-stanza +[listener]: /docs/agent-and-proxy/proxy#listener-stanza +[listener_main]: /docs/configuration/listener/tcp +[telemetry]: /docs/configuration/telemetry diff --git a/website/content/docs/agent-and-proxy/proxy/versions.mdx b/website/content/docs/agent-and-proxy/proxy/versions.mdx index 0cddf5188b..e1aaa4fca5 100644 --- a/website/content/docs/agent-and-proxy/proxy/versions.mdx +++ b/website/content/docs/agent-and-proxy/proxy/versions.mdx @@ -1,6 +1,5 @@ --- -layout: docs -page_title: OpenBao Proxy Version Compatibility +sidebar_label: Version compatibility description: |- Guidelines for running different versions of Proxy and Server --- diff --git a/website/content/docs/audit/file.mdx b/website/content/docs/audit/file.mdx index 2f4eb8afd7..a226e913a7 100644 --- a/website/content/docs/audit/file.mdx +++ b/website/content/docs/audit/file.mdx @@ -1,6 +1,5 @@ --- -layout: docs -page_title: File - Audit Devices +sidebar_label: File description: The "file" audit device writes audit logs to a file. --- @@ -43,7 +42,7 @@ Note the difference between `audit enable` command options and the `file` backen configuration options. Use `bao audit enable -help` to see the command options. The `file` audit device supports the common configuration options documented on -the [main Audit Devices page](/vault/docs/audit#common-configuration-options), and +the [main Audit Devices page](/docs/audit#common-configuration-options), and these device-specific options: - `file_path` `(string: )` - The path to where the audit log will be diff --git a/website/content/docs/audit/index.mdx b/website/content/docs/audit/index.mdx index 0a49978e77..7d4036c508 100644 --- a/website/content/docs/audit/index.mdx +++ b/website/content/docs/audit/index.mdx @@ -1,6 +1,5 @@ --- -layout: docs -page_title: Audit Devices +sidebar_label: Overview description: Audit devices are mountable devices that log requests and responses in OpenBao. --- @@ -44,14 +43,18 @@ a way to check for data tampering in the logs themselves. OpenBao considers a request to be successful if it can log to *at least* one configured audit device (see: [Blocked Audit -Devices](/vault/docs/audit#blocked-audit-devices) section below). Therefore in order +Devices](/docs/audit#blocked-audit-devices) section below). Therefore in order to build a complete picture of all audited actions, use the aggregate/union of the logs from each audit device. -~> Note: It is **highly recommended** that you configure OpenBao to use multiple audit +:::warning + +Note: It is **highly recommended** that you configure OpenBao to use multiple audit devices. Audit failures can prevent OpenBao from servicing requests, so it is important to provide at least one other device. +::: + ## Format @@ -69,20 +72,24 @@ unique identifier assigned to each request. Most strings contained within requests and responses are hashed with a salt using HMAC-SHA256. The purpose of the hash is so that secrets aren't in plaintext within your audit logs. However, you're still able to check the value of secrets by generating HMACs yourself; this can be done with the audit device's hash function and salt by using the `/sys/audit-hash` API endpoint (see the documentation for more details). -~> Currently, only strings that come from JSON or returned in JSON are +:::warning + +Currently, only strings that come from JSON or returned in JSON are HMAC'd. Other data types, like integers, booleans, and so on, are passed through in plaintext. We recommend that all sensitive data be provided as string values inside all JSON sent to OpenBao (i.e., that integer values are provided in quotes). -While most strings are hashed, OpenBao does make some exceptions, such as auth and secrets, and users can enable additional exceptions using the [secrets enable](/vault/docs/commands/secrets/enable) command, and then tune it afterward. +::: + +While most strings are hashed, OpenBao does make some exceptions, such as auth and secrets, and users can enable additional exceptions using the [secrets enable](/docs/commands/secrets/enable) command, and then tune it afterward. **see also**: -[secrets tune](/vault/docs/commands/secrets/tune) +[secrets tune](/docs/commands/secrets/tune) -[auth enable](/vault/docs/commands/auth/enable) +[auth enable](/docs/commands/auth/enable) -[auth tune](/vault/docs/commands/auth/tune) +[auth tune](/docs/commands/auth/tune) ## Enabling/Disabling audit devices @@ -100,19 +107,27 @@ In the command above, we passed the "file_path" parameter to specify the path where the audit log will be written to. Each audit device has its own set of parameters. See the documentation to the left for more details. -~> Note: Audit device configuration is replicated to all nodes within a cluster +:::warning + +Note: Audit device configuration is replicated to all nodes within a cluster by default. Before enabling an audit device, ensure that all nodes within the cluster(s) will be able to successfully log to the audit device to avoid OpenBao being blocked from serving requests. -An audit device can be limited to only within the node's cluster with the [`local`](/vault/api-docs/system/audit#local) parameter. +An audit device can be limited to only within the node's cluster with the [`local`](/api-docs/system/audit#local) parameter. + +::: When an audit device is disabled, it will stop receiving logs immediately. The existing logs that it did store are untouched. -~> Note: Once an audit device is disabled, you will no longer be able to HMAC values +:::warning + +Note: Once an audit device is disabled, you will no longer be able to HMAC values for comparison with entries in the audit logs. This is true even if you re-enable the audit device at the same path, as a new salt will be created for hashing. +::: + ## Blocked audit devices Audit device logs are critically important and ignoring auditing failures opens an avenue for attack. OpenBao will not respond to requests when no enabled audit devices can record them. @@ -127,17 +142,17 @@ In other words, OpenBao will not complete any requests until the blocked audit d ## Tutorial -Refer to [Blocked Audit Devices](/vault/tutorials/monitoring/blocked-audit-devices) for a step-by-step tutorial. +Refer to [Blocked Audit Devices](/tutorials/monitoring/blocked-audit-devices) for a step-by-step tutorial. ## API Audit devices also have a full HTTP API. Please see the [Audit device API -docs](/vault/api-docs/system/audit) for more details. +docs](/api-docs/system/audit) for more details. ## Common configuration options - `elide_list_responses` `(bool: false)` - See [Eliding list response - bodies](/vault/docs/audit#eliding-list-response-bodies) below. + bodies](/docs/audit#eliding-list-response-bodies) below. - `format` `(string: "json")` - Allows selecting the output format. Valid values are `"json"` and `"jsonx"`, which formats the normal log entries as XML. diff --git a/website/content/docs/audit/socket.mdx b/website/content/docs/audit/socket.mdx index 86ac1d767c..e89c14f6ef 100644 --- a/website/content/docs/audit/socket.mdx +++ b/website/content/docs/audit/socket.mdx @@ -1,6 +1,5 @@ --- -layout: docs -page_title: Socket - Audit Devices +sidebar_label: Socket description: The "socket" audit device writes audit writes to a TCP or UDP socket. --- @@ -8,9 +7,17 @@ description: The "socket" audit device writes audit writes to a TCP or UDP socke The `socket` audit device writes to a TCP, UDP, or UNIX socket. -~> **Warning:** The loss of audit logs may occur when using the UDP socket audit type. Because UDP socket audit type is connectionless, meaning the UDP endpoint becomes unavailable, it’s possible that any number of audit logs written to it may get lost, even though the request will still succeed. OpenBao does not provide an indication for the loss of audit logs. Therefore, we recommend using your device in conjunction with a secondary “non-socket” audit device to ensure accuracy and to guarantee that audit logs will not be lost. +:::warning -~> **Warning:** When using a TCP socket audit type, and connection loss to the socket occurs, a single audit entry may be omitted from the audit entry. The request from the TCP socket audit type will succeed despite the omission of the audit entry. +**Warning:** The loss of audit logs may occur when using the UDP socket audit type. Because UDP socket audit type is connectionless, meaning the UDP endpoint becomes unavailable, it’s possible that any number of audit logs written to it may get lost, even though the request will still succeed. OpenBao does not provide an indication for the loss of audit logs. Therefore, we recommend using your device in conjunction with a secondary “non-socket” audit device to ensure accuracy and to guarantee that audit logs will not be lost. + +::: + +:::warning + +**Warning:** When using a TCP socket audit type, and connection loss to the socket occurs, a single audit entry may be omitted from the audit entry. The request from the TCP socket audit type will succeed despite the omission of the audit entry. + +::: ## Enabling @@ -29,7 +36,7 @@ $ bao audit enable socket address=127.0.0.1:9090 socket_type=tcp ## Configuration The `socket` audit device supports the common configuration options documented on -the [main Audit Devices page](/vault/docs/audit#common-configuration-options), and +the [main Audit Devices page](/docs/audit#common-configuration-options), and these device-specific options: - `address` `(string: "")` - The socket server address to use. Example @@ -38,7 +45,7 @@ these device-specific options: - `socket_type` `(string: "tcp")` - The socket type to use, any type compatible with net.Dial is acceptable. It's important to note if TCP is used and the destination socket becomes unavailable - OpenBao may become unresponsive per [Blocked Audit Devices](/vault/docs/audit/#blocked-audit-devices). + OpenBao may become unresponsive per [Blocked Audit Devices](/docs/audit/#blocked-audit-devices). - `write_timeout` `(string: 2s)` - The (deadline) time in seconds to allow writes to be completed over the socket. A zero value means that write attempts will *not* time out. diff --git a/website/content/docs/audit/syslog.mdx b/website/content/docs/audit/syslog.mdx index 29e2884454..8876792b8b 100644 --- a/website/content/docs/audit/syslog.mdx +++ b/website/content/docs/audit/syslog.mdx @@ -1,6 +1,5 @@ --- -layout: docs -page_title: Syslog - Audit Devices +sidebar_label: Syslog description: The "syslog" audit device writes audit logs to syslog. --- @@ -12,7 +11,9 @@ It currently does not support a configurable syslog destination, and always sends to the local agent. This device is only supported on Unix systems, and should not be enabled if any standby OpenBao instances do not support it. -~> **Warning**: Audit messages generated for some operations can be quite +:::warning + +**Warning**: Audit messages generated for some operations can be quite large, and can be larger than a [maximum-size single UDP packet](https://tools.ietf.org/html/rfc5426#section-3.1). If possible with your syslog daemon, configure a TCP listener. Otherwise, consider using a `file` @@ -20,6 +21,8 @@ backend and having syslog configured to read entries from the file; or, enable both `file` and `syslog` so that a failure for a particular message to log directly to `syslog` will not result in OpenBao being blocked. +::: + ## Examples Audit `syslog` device can be enabled by the following command: @@ -37,7 +40,7 @@ $ bao audit enable syslog tag="openbao" facility="AUTH" ## Configuration The `syslog` audit device supports the common configuration options documented on -the [main Audit Devices page](/vault/docs/audit#common-configuration-options), and +the [main Audit Devices page](/docs/audit#common-configuration-options), and these device-specific options: - `facility` `(string: "AUTH")` - The syslog facility to use. diff --git a/website/content/docs/auth/approle.mdx b/website/content/docs/auth/approle.mdx index 930bc0f2a1..88d57e5d19 100644 --- a/website/content/docs/auth/approle.mdx +++ b/website/content/docs/auth/approle.mdx @@ -1,10 +1,11 @@ --- -layout: docs -page_title: AppRole - Auth Methods +sidebar_label: AppRole description: |- The AppRole auth method allows machines and services to authenticate with OpenBao. --- +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; # AppRole auth method @@ -69,10 +70,14 @@ The response will contain the token at `auth.client_token`: } ``` --> **Application Integration:** See the [Code Example](#code-example) section +:::info + +**Application Integration:** See the [Code Example](#code-example) section for a code snippet demonstrating the authentication with OpenBao using the AppRole auth method. +::: + ## Configuration Auth methods must be configured in advance before users or machines can @@ -98,7 +103,11 @@ management tool. secret_id_num_uses=40 ``` -~> **Note:** If the token issued by your approle needs the ability to create child tokens, you will need to set token_num_uses to 0. +:::warning + +**Note:** If the token issued by your approle needs the ability to create child tokens, you will need to set token_num_uses to 0. + +::: For the complete list of configuration options, please see the API documentation. @@ -216,7 +225,7 @@ full set of client credentials (RoleID and SecretID) in order to create the entry, even if these are then distributed via different paths. However, in Pull mode, even though the RoleID must be known in order to distribute it to the client, the SecretID can be kept confidential from all parties except for the -final authenticating client by using [Response Wrapping](/vault/docs/concepts/response-wrapping). +final authenticating client by using [Response Wrapping](/docs/concepts/response-wrapping). Push mode is available for App-ID workflow compatibility, which in some specific cases is preferable, but in most cases Pull mode is more secure and @@ -236,17 +245,42 @@ belonging to configured CIDR blocks on the AppRole. ## Tutorial Refer to the [AppRole Pull -Authentication](/vault/tutorials/auth-methods/approle) +Authentication](/tutorials/auth-methods/approle) tutorial to learn how to use the AppRole method to generate tokens for machines or apps. ## User lockout -@include 'user-lockout.mdx' +If a user provides bad credentials several times in quick succession, +OpenBao will stop trying to validate their credentials for a while, instead returning immediately +with a permission denied error. We call this behavior "user lockout". The time for which +a user will be locked out is called “lockout duration”. The user will be able to login after the lockout +duration has passed. The number of failed login attempts after which the user is locked out is called +“lockout threshold”. The lockout threshold counter is reset to zero after a few minutes without login attempts, +or upon a successful login attempt. The duration after which the counter will be reset to zero +after no login attempts is called "lockout counter reset". This can defeat both automated and targeted requests +i.e, user-based password guessing attacks as well as automated attacks. + +The user lockout feature is enabled by default. The default values for "lockout threshold" is 5 attempts, +"lockout duration" is 15 minutes, "lockout counter reset" is 15 minutes. + +The user lockout feature can be disabled as follows: +- It can be disabled globally using environment variable `VAULT_DISABLE_USER_LOCKOUT`. +- It can be disabled for all supported auth methods (ldap, userpass and approle) or a specific supported auth method using the `disable_lockout` + parameter within `user_lockout` stanza in configuration file. + Please see [user lockout configuration](/docs/configuration/user-lockout#user_lockout-stanza) for more details. +- It can be disabled for a specific auth mount using "auth tune". Please see [auth tune command](/docs/commands/auth/tune) + or [auth tune api](/api-docs/system/auth#tune-auth-method) for more details. + +:::warning + +**NOTE**: This feature is only supported by the userpass, ldap, and approle auth methods. + +::: ## API The AppRole auth method has a full HTTP API. Please see the -[AppRole API](/vault/api-docs/auth/approle) for more +[AppRole API](/api-docs/auth/approle) for more details. ## Code example @@ -254,9 +288,8 @@ details. The following example demonstrates AppRole authentication with response wrapping. - - - + + ```go package main @@ -327,6 +360,5 @@ func getSecretWithAppRole() (string, error) { } ``` - - - + + diff --git a/website/content/docs/auth/cert.mdx b/website/content/docs/auth/cert.mdx index ccc1f335a5..e77ffdbdfb 100644 --- a/website/content/docs/auth/cert.mdx +++ b/website/content/docs/auth/cert.mdx @@ -1,6 +1,5 @@ --- -layout: docs -page_title: TLS Certificates - Auth Methods +sidebar_label: TLS Certificates description: >- The "cert" auth method allows users to authenticate with OpenBao using TLS client certificates. @@ -8,7 +7,15 @@ description: >- # TLS certificates auth method -@include 'x509-sha1-deprecation.mdx' +:::warning + +**Note**: This engine can use external X.509 certificates as part of TLS or signature validation. + Verifying signatures against X.509 certificates that use SHA-1 is deprecated and is no longer + usable without a workaround. See the + [deprecation FAQ](/docs/deprecation/faq#q-what-is-the-impact-of-removing-support-for-x-509-certificates-with-signatures-that-use-sha-1) + for more information. + +::: The `cert` auth method allows authentication using SSL/TLS client certificates which are either signed by a CA or self-signed. SSL/TLS client certificates @@ -75,11 +82,15 @@ role. Note that the name `web` ties to the configuration example below writing to a path of `auth/cert/certs/web`. If a certificate role name is not specified, the auth method will try to authenticate against all trusted certificates. -~> **NOTE** The `-ca-cert` value used here is for the OpenBao TLS Listener CA +:::warning + +**NOTE** The `-ca-cert` value used here is for the OpenBao TLS Listener CA certificate, not the CA that issued the client authentication certificate. This can be omitted if the CA used to issue the OpenBao server certificate is trusted by the local system executing this command. +::: + ```shell-session $ bao login \ -method=cert \ @@ -96,11 +107,15 @@ TLS certificate and when the login endpoint is hit, the auth method will determine if there is a matching trusted certificate to authenticate the client. Optionally, you may specify a single certificate role to authenticate against. -~> **NOTE** The `--cacert` value used here is for the OpenBao TLS Listener CA +:::warning + +**NOTE** The `--cacert` value used here is for the OpenBao TLS Listener CA certificate, not the CA that issued the client authentication certificate. This can be omitted if the CA used to issue the OpenBao server certificate is trusted by the local system executing this command. +::: + ```shell-session $ curl \ --request POST \ @@ -141,4 +156,4 @@ management tool. ## API The TLS Certificate auth method has a full HTTP API. Please see the -[TLS Certificate API](/vault/api-docs/auth/cert) for more details. +[TLS Certificate API](/api-docs/auth/cert) for more details. diff --git a/website/content/docs/auth/index.mdx b/website/content/docs/auth/index.mdx index 12344170a2..d2782a16fb 100644 --- a/website/content/docs/auth/index.mdx +++ b/website/content/docs/auth/index.mdx @@ -1,6 +1,5 @@ --- -layout: docs -page_title: Auth Methods +sidebar_label: Overview description: Auth methods are mountable methods that perform authentication for OpenBao. --- @@ -15,12 +14,12 @@ external auth method (e.g., Kubernetes). Having multiple auth methods enables you to use an auth method that makes the most sense for your use case of OpenBao and your organization. -For example, on developer machines, the [Userpass](/vault/docs/auth/userpass) -is easiest to use. But for servers the [AppRole](/vault/docs/auth/approle) +For example, on developer machines, the [Userpass](/docs/auth/userpass) +is easiest to use. But for servers the [AppRole](/docs/auth/approle) method is the recommended choice. To learn more about authentication, see the -[authentication concepts page](/vault/docs/concepts/auth). +[authentication concepts page](/docs/concepts/auth). ## Enabling/Disabling auth methods @@ -30,7 +29,7 @@ Auth methods can be enabled/disabled using the CLI or the API. $ bao auth enable userpass ``` -When enabled, auth methods are similar to [secrets engines](/vault/docs/secrets): +When enabled, auth methods are similar to [secrets engines](/docs/secrets): they are mounted within the OpenBao mount table and can be accessed and configured using the standard read/write API. All auth methods are mounted underneath the `auth/` prefix. @@ -54,5 +53,5 @@ of an entity changes in the external system (e.g., an account expires or is disabled), OpenBao denies requests to **renew** tokens associated with the entity. However, any existing token remain valid for the original grant period unless they are explicitly revoked within OpenBao. Operators should set appropriate -[token TTLs](/vault/docs/concepts/tokens#the-general-case) when using external +[token TTLs](/docs/concepts/tokens#the-general-case) when using external authN methods. diff --git a/website/content/docs/auth/jwt/index.mdx b/website/content/docs/auth/jwt/index.mdx index a8bbbd144f..e4ab2799f6 100644 --- a/website/content/docs/auth/jwt/index.mdx +++ b/website/content/docs/auth/jwt/index.mdx @@ -1,6 +1,5 @@ --- -layout: docs -page_title: JWT/OIDC - Auth Methods +sidebar_label: Overview description: >- The JWT/OIDC auth method allows authentication using OIDC and user-provided JWTs @@ -8,7 +7,15 @@ description: >- # JWT/OIDC auth method -@include 'x509-sha1-deprecation.mdx' +:::warning + +**Note**: This engine can use external X.509 certificates as part of TLS or signature validation. + Verifying signatures against X.509 certificates that use SHA-1 is deprecated and is no longer + usable without a workaround. See the + [deprecation FAQ](/docs/deprecation/faq#q-what-is-the-impact-of-removing-support-for-x-509-certificates-with-signatures-that-use-sha-1) + for more information. + +::: The `jwt` auth method can be used to authenticate with OpenBao using [OIDC](https://en.wikipedia.org/wiki/OpenID_Connect) or by providing a @@ -28,7 +35,7 @@ examples of OIDC and JWT usage. ## OIDC authentication This section covers the setup and use of OIDC roles. If a JWT is to be provided directly, -refer to the [JWT Authentication](/vault/docs/auth/jwt#jwt-authentication) section below. Basic +refer to the [JWT Authentication](/docs/auth/jwt#jwt-authentication) section below. Basic familiarity with [OIDC concepts](https://developer.okta.com/blog/2017/07/25/oidc-primer-part-1) is assumed. The Authorization Code flow makes use of the Proof Key for Code Exchange (PKCE) extension. @@ -60,7 +67,7 @@ Logging in via the OpenBao UI requires a redirect URI of the form: The "host:port" must be correct for the OpenBao server, and "path" must match the path the JWT backend is mounted at (e.g. "oidc" or "jwt"). -If the [oidc_response_mode](/vault/api-docs/auth/jwt#oidc_response_mode) is set to `form_post`, then +If the [oidc_response_mode](/api-docs/auth/jwt#oidc_response_mode) is set to `form_post`, then logging in via the OpenBao UI requires a redirect URI of the form: `https://{host:port}/v1/auth/{path}/oidc/callback` @@ -105,7 +112,7 @@ not required to be set: The OIDC authentication flow has been successfully tested with a number of providers. A full guide to configuring OAuth/OIDC applications is beyond the scope of OpenBao documentation, but a collection of provider configuration steps has been collected to help get started: -[OIDC Provider Setup](/vault/docs/auth/jwt/oidc-providers) +[OIDC Provider Setup](/docs/auth/jwt/oidc-providers) ### OIDC configuration troubleshooting @@ -151,7 +158,7 @@ EOF `cat jwt.json | jq -r .access_token | cut -d. -f2 | base64 -D` -- The [`verbose_oidc_logging`](/vault/api-docs/auth/jwt#verbose_oidc_logging) role +- The [`verbose_oidc_logging`](/api-docs/auth/jwt#verbose_oidc_logging) role option is available which will log the received OIDC token to the _server_ logs if debug-level logging is enabled. This can be helpful when debugging provider setup and verifying that the received claims are what you expect. Since claims data is logged verbatim and may contain sensitive information, this option should not be @@ -159,7 +166,7 @@ EOF - Azure requires some additional configuration when a user is a member of more than 200 groups, described in [Azure-specific handling - configuration](/vault/docs/auth/jwt/oidc-providers/azuread#optional-azure-specific-configuration) + configuration](/docs/auth/jwt/oidc-providers/azuread#optional-azure-specific-configuration) ## JWT authentication @@ -238,7 +245,7 @@ management tool. 1. Use the `/config` endpoint to configure OpenBao. To support JWT roles, either local keys, a JWKS URL, or an OIDC Discovery URL must be present. For OIDC roles, OIDC Discovery URL, OIDC Client ID and OIDC Client Secret are required. For the - list of available configuration options, please see the [API documentation](/vault/api-docs/auth/jwt). + list of available configuration options, please see the [API documentation](/api-docs/auth/jwt). ```text $ bao write auth/jwt/config \ @@ -305,7 +312,7 @@ To limit authorization to a set of email addresses: } ``` -Bound claims can optionally be configured with globs. See the [API documentation](/vault/api-docs/auth/jwt#bound_claims_type) for more details. +Bound claims can optionally be configured with globs. See the [API documentation](/api-docs/auth/jwt#bound_claims_type) for more details. ### Claims as metadata @@ -354,13 +361,13 @@ JSON Pointer can be used as a selector. Refer to the Refer to the following tutorials for OIDC auth method usage examples: -- [OIDC Auth Method](/vault/tutorials/auth-methods/oidc-auth) +- [OIDC Auth Method](/tutorials/auth-methods/oidc-auth) - [Azure Active Directory with OIDC Auth Method and External - Groups](/vault/tutorials/auth-methods/oidc-auth-azure) -- [OIDC Authentication with Okta](/vault/tutorials/auth-methods/vault-oidc-okta) -- [OIDC Authentication with Google Workspace](/vault/tutorials/auth-methods/google-workspace-oauth) + Groups](/tutorials/auth-methods/oidc-auth-azure) +- [OIDC Authentication with Okta](/tutorials/auth-methods/vault-oidc-okta) +- [OIDC Authentication with Google Workspace](/tutorials/auth-methods/google-workspace-oauth) ## API The JWT Auth Plugin has a full HTTP API. Please see the -[API docs](/vault/api-docs/auth/jwt) for more details. +[API docs](/api-docs/auth/jwt) for more details. diff --git a/website/content/docs/auth/jwt/oidc-providers/auth0.mdx b/website/content/docs/auth/jwt/oidc-providers/auth0.mdx index ce37b6a27c..a16536e91e 100644 --- a/website/content/docs/auth/jwt/oidc-providers/auth0.mdx +++ b/website/content/docs/auth/jwt/oidc-providers/auth0.mdx @@ -1,6 +1,4 @@ --- -layout: docs -page_title: OIDC Provider Setup - Auth Methods - Auth0 description: OIDC provider configuration for Auth0 --- diff --git a/website/content/docs/auth/jwt/oidc-providers/azuread.mdx b/website/content/docs/auth/jwt/oidc-providers/azuread.mdx index c69c88816e..1bb68d38d1 100644 --- a/website/content/docs/auth/jwt/oidc-providers/azuread.mdx +++ b/website/content/docs/auth/jwt/oidc-providers/azuread.mdx @@ -1,15 +1,17 @@ --- -layout: docs -page_title: OIDC Provider Setup - Auth Methods - Azure Active Directory description: OIDC provider configuration for Azure Active Directory --- ## Azure active directory (AAD) -~> **Note:** Azure Active Directory Applications that have custom signing keys as a result of using +:::warning + +**Note:** Azure Active Directory Applications that have custom signing keys as a result of using the [claims-mapping](https://docs.microsoft.com/en-us/azure/active-directory/develop/active-directory-claims-mapping) feature are currently not supported for OIDC authentication. +::: + Reference: [Azure Active Directory v2.0 and the OpenID Connect protocol](https://docs.microsoft.com/en-us/azure/active-directory/develop/v2-protocols-oidc) 1. Choose your Azure tenant. @@ -36,12 +38,12 @@ Reference: [Azure Active Directory v2.0 and the OpenID Connect protocol](https:/ ### Connect AD group with OpenBao external group -Reference: [Azure Active Directory with OIDC Auth Method and External Groups](/vault/tutorials/auth-methods/oidc-auth-azure) +Reference: [Azure Active Directory with OIDC Auth Method and External Groups](/tutorials/auth-methods/oidc-auth-azure) -To connect the AD group with a [OpenBao external groups](/vault/docs/secrets/identity#external-vs-internal-groups), +To connect the AD group with a [OpenBao external groups](/docs/secrets/identity#external-vs-internal-groups), you will need [Azure AD v2.0 endpoints](https://docs.microsoft.com/en-gb/azure/active-directory/develop/azure-ad-endpoint-comparison). -You should set up a [OpenBao policy](/vault/tutorials/policies/policies) for the Azure AD group to use. +You should set up a [OpenBao policy](/tutorials/policies/policies) for the Azure AD group to use. 1. Go to **Azure Active Directory** and choose your OpenBao application. @@ -61,7 +63,7 @@ You should set up a [OpenBao policy](/vault/tutorials/policies/policies) for the oidc_discovery_url="https://login.microsoftonline.com/tenant_id/v2.0" ``` -1. Configure the [OIDC Role](/vault/api-docs/auth/jwt#create-role) with the following: +1. Configure the [OIDC Role](/api-docs/auth/jwt#create-role) with the following: - `user_claim` should be `"sub"` or `"oid"` following the [recommendation](https://docs.microsoft.com/en-us/azure/active-directory/develop/id-tokens#using-claims-to-reliably-identify-a-user-subject-and-object-id) @@ -79,16 +81,16 @@ You should set up a [OpenBao policy](/vault/tutorials/policies/policies) for the policies=default ``` -1. In OpenBao, create the [external group](/vault/api-docs/secret/identity/group). +1. In OpenBao, create the [external group](/api-docs/secret/identity/group). Record the group ID as you will need it for the group alias. -1. From OpenBao, retrieve the [OIDC accessor ID](/vault/api-docs/system/auth#list-auth-methods) +1. From OpenBao, retrieve the [OIDC accessor ID](/api-docs/system/auth#list-auth-methods) from the OIDC auth method as you will need it for the group alias's `mount_accessor`. 1. Go to the Azure AD Group you want to attach to OpenBao's external group. Record the `objectId` as you will need it as the group alias name in OpenBao. -1. In OpenBao, create a [group alias](/vault/api-docs/secret/identity/group-alias) +1. In OpenBao, create a [group alias](/api-docs/secret/identity/group-alias) for the external group and set the `objectId` as the group alias name. ```shell bao write identity/group-alias \ diff --git a/website/content/docs/auth/jwt/oidc-providers/forgerock.mdx b/website/content/docs/auth/jwt/oidc-providers/forgerock.mdx index 95e1f09bd7..a9ad892e38 100644 --- a/website/content/docs/auth/jwt/oidc-providers/forgerock.mdx +++ b/website/content/docs/auth/jwt/oidc-providers/forgerock.mdx @@ -1,6 +1,4 @@ --- -layout: docs -page_title: OIDC Provider Setup - Auth Methods - ForgeRock description: OIDC provider configuration for ForgeRock --- @@ -29,7 +27,7 @@ description: OIDC provider configuration for ForgeRock oidc_discovery_url="https://openam.example.com:8443/openam/oauth2" ``` -1. Configure the [OIDC Role](/vault/api-docs/auth/jwt) with the following: +1. Configure the [OIDC Role](/api-docs/auth/jwt) with the following: - `user_claim` should be `"sub"`. - `allowed_redirect_uris` should be the two redirect URIs for OpenBao CLI and UI access. - `oidc_scopes` should be set to the OIDC scopes. diff --git a/website/content/docs/auth/jwt/oidc-providers/gitlab.mdx b/website/content/docs/auth/jwt/oidc-providers/gitlab.mdx index 4ef5620daf..c86001f922 100644 --- a/website/content/docs/auth/jwt/oidc-providers/gitlab.mdx +++ b/website/content/docs/auth/jwt/oidc-providers/gitlab.mdx @@ -1,6 +1,4 @@ --- -layout: docs -page_title: OIDC Provider Setup - Auth Methods - Gitlab description: OIDC provider configuration for Gitlab --- diff --git a/website/content/docs/auth/jwt/oidc-providers/google.mdx b/website/content/docs/auth/jwt/oidc-providers/google.mdx index c9281423a5..56bb043861 100644 --- a/website/content/docs/auth/jwt/oidc-providers/google.mdx +++ b/website/content/docs/auth/jwt/oidc-providers/google.mdx @@ -1,6 +1,4 @@ --- -layout: docs -page_title: OIDC Provider Setup - Auth Methods - Google description: OIDC provider configuration for Google --- @@ -14,7 +12,7 @@ Main reference: [Using OAuth 2.0 to Access Google APIs](https://developers.googl 1. Create a new credential via Credentials > Create Credentials > OAuth Client ID. 1. Configure the OAuth Consent Screen. Application Name is required. Save. 1. Select application type: "Web Application". -1. Configure Authorized [Redirect URIs](/vault/docs/auth/jwt#redirect-uris). +1. Configure Authorized [Redirect URIs](/docs/auth/jwt#redirect-uris). 1. Save client ID and secret. ### Optional google-specific configuration @@ -23,7 +21,7 @@ Google-specific configuration is available when using Google as an identity prov OpenBao JWT/OIDC auth method. The configuration allows OpenBao to obtain Google Workspace group membership and user information during the JWT/OIDC authentication flow. The group membership obtained from Google Workspace may be used for Identity group alias association. The user information obtained from Google Workspace can be -used to copy claims data into resulting auth token and alias metadata via [claim_mappings](/vault/api-docs/auth/jwt#claim_mappings). +used to copy claims data into resulting auth token and alias metadata via [claim_mappings](/api-docs/auth/jwt#claim_mappings). #### Setup @@ -51,9 +49,13 @@ the only OAuth scopes that should be granted are: - `https://www.googleapis.com/auth/admin.directory.group.readonly` - `https://www.googleapis.com/auth/admin.directory.user.readonly` -~> This is an **important security step** in order to give the service account the least set of privileges +:::warning + +This is an **important security step** in order to give the service account the least set of privileges that enable the feature. +::: + #### Configuration - `provider` `(string: )` - Name of the provider. Must be set to "gsuite". @@ -65,7 +67,7 @@ that enable the feature. - `fetch_user_info` `(bool: false)` - If set to true, user info will be fetched from Google Workspace using the configured [user_custom_schemas](#user_custom_schemas). - `groups_recurse_max_depth` `(int: )` - Group membership recursion max depth. Defaults to 0, which means don't recurse. - `user_custom_schemas` `(string: )` - Comma-separated list of Google Workspace [custom schemas](https://developers.google.com/admin-sdk/directory/v1/guides/manage-schemas). - Values set for Google Workspace users using custom schema fields will be fetched and made available as claims that can be used with [claim_mappings](/vault/api-docs/auth/jwt#claim_mappings). Required if [fetch_user_info](#fetch_user_info) is set to true. + Values set for Google Workspace users using custom schema fields will be fetched and made available as claims that can be used with [claim_mappings](/api-docs/auth/jwt#claim_mappings). Required if [fetch_user_info](#fetch_user_info) is set to true. Example configuration: @@ -91,7 +93,7 @@ EOF #### Role -The [user_claim](/vault/api-docs/auth/jwt#user_claim) value of the role must be set to +The [user_claim](/api-docs/auth/jwt#user_claim) value of the role must be set to one of either `sub` or `email` for the Google Workspace group and user information queries to succeed. diff --git a/website/content/docs/auth/jwt/oidc-providers/ibmisam.mdx b/website/content/docs/auth/jwt/oidc-providers/ibmisam.mdx index beb240ee1d..d39b16315d 100644 --- a/website/content/docs/auth/jwt/oidc-providers/ibmisam.mdx +++ b/website/content/docs/auth/jwt/oidc-providers/ibmisam.mdx @@ -1,6 +1,4 @@ --- -layout: docs -page_title: OIDC Provider Setup - Auth Methods - IBM Security Access Manager (ISAM) description: OIDC provider configuration for IBM Security Access Manager (recently renamed to IBM Security Verify Access) --- @@ -29,6 +27,6 @@ EOH ``` This will instruct the OIDC Auth Method to parse the space-separated groups claims string -into individual groups. Note that the role's [`groups_claim`](/vault/api-docs/auth/jwt#groups_claim) +into individual groups. Note that the role's [`groups_claim`](/api-docs/auth/jwt#groups_claim) value must be properly configured to target the groups claim for your IBM ISAM identity provider. diff --git a/website/content/docs/auth/jwt/oidc-providers/index.mdx b/website/content/docs/auth/jwt/oidc-providers/index.mdx index 40edf3d48b..08719b3590 100644 --- a/website/content/docs/auth/jwt/oidc-providers/index.mdx +++ b/website/content/docs/auth/jwt/oidc-providers/index.mdx @@ -1,6 +1,5 @@ --- -layout: docs -page_title: OIDC Provider Setup - Auth Methods +sidebar_label: Overview description: OIDC provider configuration quick starts --- @@ -8,20 +7,20 @@ description: OIDC provider configuration quick starts This page collects high-level setup steps on how to configure an OIDC application for various providers. For more general usage and operation -information, see the [OpenBao JWT/OIDC method documentation](/vault/docs/auth/jwt). +information, see the [OpenBao JWT/OIDC method documentation](/docs/auth/jwt). OIDC providers are often highly configurable, and you should become familiar with their recommended settings and best practices. The guides listed below are largely community-driven and intended to help you get started. Corrections and additions may be submitted via the [OpenBao Github repository](https://github.com/openbao/openbao). -- [Auth0](/vault/docs/auth/jwt/oidc-providers/auth0) -- [Azure AD](/vault/docs/auth/jwt/oidc-providers/azuread) -- [ForgeRock](/vault/docs/auth/jwt/oidc-providers/forgerock) -- [Gitlab](/vault/docs/auth/jwt/oidc-providers/gitlab) -- [Google](/vault/docs/auth/jwt/oidc-providers/google) -- [Keycloak](/vault/docs/auth/jwt/oidc-providers/keycloak) -- [Kubernetes](/vault/docs/auth/jwt/oidc-providers/kubernetes) -- [Okta](/vault/docs/auth/jwt/oidc-providers/okta) -- [SecureAuth](/vault/docs/auth/jwt/oidc-providers/secureauth) -- [IBMISAM](/vault/docs/auth/jwt/oidc-providers/ibmisam) +- [Auth0](/docs/auth/jwt/oidc-providers/auth0) +- [Azure AD](/docs/auth/jwt/oidc-providers/azuread) +- [ForgeRock](/docs/auth/jwt/oidc-providers/forgerock) +- [Gitlab](/docs/auth/jwt/oidc-providers/gitlab) +- [Google](/docs/auth/jwt/oidc-providers/google) +- [Keycloak](/docs/auth/jwt/oidc-providers/keycloak) +- [Kubernetes](/docs/auth/jwt/oidc-providers/kubernetes) +- [Okta](/docs/auth/jwt/oidc-providers/okta) +- [SecureAuth](/docs/auth/jwt/oidc-providers/secureauth) +- [IBMISAM](/docs/auth/jwt/oidc-providers/ibmisam) diff --git a/website/content/docs/auth/jwt/oidc-providers/keycloak.mdx b/website/content/docs/auth/jwt/oidc-providers/keycloak.mdx index 7510108881..52f078cd36 100644 --- a/website/content/docs/auth/jwt/oidc-providers/keycloak.mdx +++ b/website/content/docs/auth/jwt/oidc-providers/keycloak.mdx @@ -1,6 +1,4 @@ --- -layout: docs -page_title: OIDC Provider Setup - Auth Methods - Keycloak description: OIDC provider configuration for Keycloak --- diff --git a/website/content/docs/auth/jwt/oidc-providers/kubernetes.mdx b/website/content/docs/auth/jwt/oidc-providers/kubernetes.mdx index caf50a4114..01ee30b297 100644 --- a/website/content/docs/auth/jwt/oidc-providers/kubernetes.mdx +++ b/website/content/docs/auth/jwt/oidc-providers/kubernetes.mdx @@ -1,6 +1,4 @@ --- -layout: docs -page_title: OIDC Provider Setup - Auth Methods - Kubernetes description: OIDC provider configuration for Kubernetes --- @@ -9,12 +7,16 @@ description: OIDC provider configuration for Kubernetes Kubernetes can function as an OIDC provider such that OpenBao can validate its service account tokens using JWT/OIDC auth. --> **Note:** The JWT auth engine does **not** use Kubernetes' `TokenReview` API +:::info + +**Note:** The JWT auth engine does **not** use Kubernetes' `TokenReview` API during authentication, and instead uses public key cryptography to verify the contents of JWTs. This means tokens that have been revoked by Kubernetes will still be considered valid by OpenBao until their expiry time. To mitigate this risk, use short TTLs for service account tokens or use -[Kubernetes auth](/vault/docs/auth/kubernetes) which _does_ use the `TokenReview` API. +[Kubernetes auth](/docs/auth/kubernetes) which _does_ use the `TokenReview` API. + +::: ### Using service account issuer discovery @@ -62,10 +64,14 @@ Configuration steps: 1. Alternatively, if OpenBao is _not_ running in Kubernetes: - -> **Note:** When OpenBao is outside the cluster, the `$ISSUER` endpoint below may +:::info + +**Note:** When OpenBao is outside the cluster, the `$ISSUER` endpoint below may or may not be reachable. If not, you can configure JWT auth using [`jwt_validation_pubkeys`](#using-jwt-validation-public-keys) instead. +::: + ```bash bao auth enable jwt bao write auth/jwt/config oidc_discovery_url="${ISSUER}" diff --git a/website/content/docs/auth/jwt/oidc-providers/okta.mdx b/website/content/docs/auth/jwt/oidc-providers/okta.mdx index e6309d4933..0252e37748 100644 --- a/website/content/docs/auth/jwt/oidc-providers/okta.mdx +++ b/website/content/docs/auth/jwt/oidc-providers/okta.mdx @@ -1,6 +1,4 @@ --- -layout: docs -page_title: OIDC Provider Setup - Auth Methods - Okta description: OIDC provider configuration for Okta --- diff --git a/website/content/docs/auth/jwt/oidc-providers/secureauth.mdx b/website/content/docs/auth/jwt/oidc-providers/secureauth.mdx index 0bda96078b..5e7d1fa5c7 100644 --- a/website/content/docs/auth/jwt/oidc-providers/secureauth.mdx +++ b/website/content/docs/auth/jwt/oidc-providers/secureauth.mdx @@ -1,6 +1,4 @@ --- -layout: docs -page_title: OIDC Provider Setup - Auth Methods - SecureAuth description: OIDC provider configuration for SecureAuth --- @@ -29,6 +27,6 @@ EOH ``` This will instruct the OIDC Auth Method to parse the comma-separated groups claims string -into individual groups. Note that the role's [`groups_claim`](/vault/api-docs/auth/jwt#groups_claim) +into individual groups. Note that the role's [`groups_claim`](/api-docs/auth/jwt#groups_claim) value must be properly configured to target the groups claim for your SecureAuth identity provider. diff --git a/website/content/docs/auth/kerberos.mdx b/website/content/docs/auth/kerberos.mdx index 4776241837..ff31b03fd1 100644 --- a/website/content/docs/auth/kerberos.mdx +++ b/website/content/docs/auth/kerberos.mdx @@ -1,12 +1,19 @@ --- -layout: docs -page_title: Kerberos - Auth Methods +sidebar_label: Kerberos description: The Kerberos auth method allows automated authentication of Kerberos entities. --- # Kerberos auth method -@include 'x509-sha1-deprecation.mdx' +:::warning + +**Note**: This engine can use external X.509 certificates as part of TLS or signature validation. + Verifying signatures against X.509 certificates that use SHA-1 is deprecated and is no longer + usable without a workaround. See the + [deprecation FAQ](/docs/deprecation/faq#q-what-is-the-impact-of-removing-support-for-x-509-certificates-with-signatures-that-use-sha-1) + for more information. + +::: The `kerberos` auth method provides an automated mechanism to retrieve an OpenBao token for Kerberos entities. @@ -27,7 +34,7 @@ it into HashiCorp's maintenance. ## Prerequisites Kerberos is a very hands-on auth method. Other auth methods like -[LDAP](/vault/docs/auth/ldap) only require +[LDAP](/docs/auth/ldap) only require a cursory amount of knowledge for configuration and use. Kerberos, on the other hand, is best used by people already familiar with it. We recommend that you use simpler authentication methods if @@ -113,14 +120,14 @@ $ bao write auth/kerberos/config/ldap \ ``` The LDAP above relies upon the same code as the LDAP auth method. -See [its documentation](/vault/docs/auth/ldap) +See [its documentation](/docs/auth/ldap) for further discussion of available parameters. - Configure the OpenBao policies that should be granted to those who successfully authenticate based on their LDAP group membership. Since this is identical to the LDAP auth method, see - [Group Membership Resolution](/vault/docs/auth/ldap#group-membership-resolution) - and [LDAP Group -> Policy Mapping](/vault/docs/auth/ldap#ldap-group-policy-mapping) + [Group Membership Resolution](/docs/auth/ldap#group-membership-resolution) + and [LDAP Group -> Policy Mapping](/docs/auth/ldap#ldap-group-policy-mapping) for further discussion. ```shell-session @@ -204,7 +211,7 @@ in the `keytab` file. ### Additional troubleshooting resources -- [Troubleshooting OpenBao](/vault/tutorials/monitoring/troubleshooting-vault) +- [Troubleshooting OpenBao](/tutorials/monitoring/troubleshooting-vault) - [The plugin's code](https://github.com/hashicorp/vault-plugin-auth-kerberos) The OpenBao Kerberos library has a working integration test environment that @@ -224,5 +231,5 @@ client. ## API The Kerberos auth method has a full HTTP API. Please see the -[Kerberos auth method API](/vault/api-docs/auth/kerberos) for more +[Kerberos auth method API](/api-docs/auth/kerberos) for more details. diff --git a/website/content/docs/auth/kubernetes.mdx b/website/content/docs/auth/kubernetes.mdx index 806f7fa223..5c3a6d611c 100644 --- a/website/content/docs/auth/kubernetes.mdx +++ b/website/content/docs/auth/kubernetes.mdx @@ -1,14 +1,23 @@ --- -layout: docs -page_title: Kubernetes - Auth Methods +sidebar_label: Kubernetes description: |- The Kubernetes auth method allows automated authentication of Kubernetes Service Accounts. --- +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; # Kubernetes auth method -@include 'x509-sha1-deprecation.mdx' +:::warning + +**Note**: This engine can use external X.509 certificates as part of TLS or signature validation. + Verifying signatures against X.509 certificates that use SHA-1 is deprecated and is no longer + usable without a workaround. See the + [deprecation FAQ](/docs/deprecation/faq#q-what-is-the-impact-of-removing-support-for-x-509-certificates-with-signatures-that-use-sha-1) + for more information. + +::: The `kubernetes` auth method can be used to authenticate with OpenBao using a Kubernetes Service Account Token. This method of authentication makes it easy to @@ -19,11 +28,15 @@ See the section on [How to work with short-lived Kubernetes tokens][short-lived- for a summary of why you might want to use JWT auth instead and how it compares to Kubernetes auth. --> **Note:** If you are upgrading to Kubernetes v1.21+, ensure the config option +:::info + +**Note:** If you are upgrading to Kubernetes v1.21+, ensure the config option `disable_iss_validation` is set to true. Assuming the default mount path, you can check with `bao read -field disable_iss_validation auth/kubernetes/config`. See [Kubernetes 1.21](#kubernetes-1-21) below for more details. +::: + ## Authentication ### Via the CLI @@ -83,7 +96,7 @@ management tool. 1. Use the `/config` endpoint to configure OpenBao to talk to Kubernetes. Use `kubectl cluster-info` to validate the Kubernetes host address and TCP port. For the list of available configuration options, please see the - [API documentation](/vault/api-docs/auth/kubernetes). + [API documentation](/api-docs/auth/kubernetes). ```bash bao write auth/kubernetes/config \ @@ -92,14 +105,18 @@ management tool. kubernetes_ca_cert=@ca.crt ``` - !> **Note:** The pattern OpenBao uses to authenticate Pods depends on sharing +:::danger + + **Note:** The pattern OpenBao uses to authenticate Pods depends on sharing the JWT token over the network. Given the [security model of - OpenBao](/vault/docs/internals/security), this is allowable because OpenBao is + OpenBao](/docs/internals/security), this is allowable because OpenBao is part of the trusted compute base. In general, Kubernetes applications should **not** share this JWT with other applications, as it allows API calls to be made on behalf of the Pod and can result in unintended access being granted to 3rd parties. +::: + 1. Create a named role: ```text @@ -114,7 +131,7 @@ management tool. namespace and it gives it the default policy. For the complete list of configuration options, please see the [API - documentation](/vault/api-docs/auth/kubernetes). + documentation](/api-docs/auth/kubernetes). ## Kubernetes 1.21 @@ -127,7 +144,7 @@ Kubernetes auth: * The value of the JWT's `"iss"` claim depends on the cluster's configuration. The changes to token lifetime are important when configuring the -[`token_reviewer_jwt`](/vault/api-docs/auth/kubernetes#token_reviewer_jwt) option. +[`token_reviewer_jwt`](/api-docs/auth/kubernetes#token_reviewer_jwt) option. If a short-lived token is used, Kubernetes will revoke it as soon as the pod or service account are deleted, or if the expiry time passes, and OpenBao will no longer be able to use the @@ -159,12 +176,16 @@ table summarizes the options, each of which is explained in more detail below. | Use long-lived token as reviewer JWT | No | Yes | | | Use JWT auth instead | Yes | No | | --> **Note:** By default, Kubernetes currently extends the lifetime of admission +:::info + +**Note:** By default, Kubernetes currently extends the lifetime of admission injected service account tokens to a year to help smooth the transition to short-lived tokens. If you would like to disable this, set [--service-account-extend-token-expiration=false][k8s-extended-tokens] for `kube-apiserver` or specify your own `serviceAccountToken` volume mount. See -[here](/vault/docs/auth/jwt/oidc-providers/kubernetes#specifying-ttl-and-audience) for an example. +[here](/docs/auth/jwt/oidc-providers/kubernetes#specifying-ttl-and-audience) for an example. + +::: [k8s-extended-tokens]: https://kubernetes.io/docs/reference/command-line-tools-reference/kube-apiserver/#options @@ -232,7 +253,7 @@ JWT tokens Kubernetes generates can also be verified using Kubernetes as an OIDC provider. The JWT auth method documentation has [instructions][k8s-jwt-auth] for setting up JWT auth with Kubernetes as the OIDC provider. -[k8s-jwt-auth]: /vault/docs/auth/jwt/oidc-providers/kubernetes +[k8s-jwt-auth]: /docs/auth/jwt/oidc-providers/kubernetes This solution allows you to use short-lived tokens for all clients and removes the need for a reviewer JWT. However, the client tokens cannot be revoked before @@ -241,14 +262,18 @@ limitation in mind. ### Discovering the service account `issuer` --> **Note:** `disable_iss_validation` and `issuer` are deprecated and the +:::info + +**Note:** `disable_iss_validation` and `issuer` are deprecated and the default for `disable_iss_validation` has changed to `true` for new Kubernetes auth mounts. The following section only applies if you have set `disable_iss_validation=false` , but `disable_iss_validation=true` is the new recommended value for all versions of OpenBao. +::: + Kubernetes 1.21+ clusters may require setting the service account -[`issuer`](/vault/api-docs/auth/kubernetes#issuer) to the same value as +[`issuer`](/api-docs/auth/kubernetes#issuer) to the same value as `kube-apiserver`'s `--service-account-issuer` flag. This is because the service account JWTs for these clusters may have an issuer specific to the cluster itself, instead of the old default of `kubernetes/serviceaccount`. If you are @@ -310,7 +335,7 @@ subjects: ## API The Kubernetes Auth Plugin has a full HTTP API. Please see the -[API docs](/vault/api-docs/auth/kubernetes) for more details. +[API docs](/api-docs/auth/kubernetes) for more details. [k8s-tokenreview]: https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.22/#tokenreview-v1-authentication-k8s-io @@ -319,9 +344,8 @@ The Kubernetes Auth Plugin has a full HTTP API. Please see the The following example demonstrates the Kubernetes auth method to authenticate with OpenBao. - - - + + ```go package main @@ -384,5 +408,6 @@ func getSecretWithKubernetesAuth() (string, error) { return value, nil } ``` - - + + + diff --git a/website/content/docs/auth/ldap.mdx b/website/content/docs/auth/ldap.mdx index 373b040c1c..89747efcb0 100644 --- a/website/content/docs/auth/ldap.mdx +++ b/website/content/docs/auth/ldap.mdx @@ -1,6 +1,5 @@ --- -layout: docs -page_title: LDAP - Auth Methods +sidebar_label: LDAP description: |- The "ldap" auth method allows users to authenticate with OpenBao using LDAP credentials. @@ -8,7 +7,15 @@ description: |- # LDAP auth method -@include 'x509-sha1-deprecation.mdx' +:::warning + +**Note**: This engine can use external X.509 certificates as part of TLS or signature validation. + Verifying signatures against X.509 certificates that use SHA-1 is deprecated and is no longer + usable without a workaround. See the + [deprecation FAQ](/docs/deprecation/faq#q-what-is-the-impact-of-removing-support-for-x-509-certificates-with-signatures-that-use-sha-1) + for more information. + +::: The `ldap` auth method allows authentication using an existing LDAP server and user/password credentials. This allows OpenBao to be integrated @@ -120,7 +127,14 @@ There are two alternate methods of resolving the user object used to authenticat - `userattr` (string, optional) - Attribute on user attribute object matching the username passed when authenticating. Examples: `sAMAccountName`, `cn`, `uid` - `userfilter` (string, optional) - Go template used to construct a ldap user search filter. The template can access the following context variables: \[`UserAttr`, `Username`\]. The default userfilter is `({{.UserAttr}}={{.Username}})` or `(userPrincipalName={{.Username}}@UPNDomain)` if the `upndomain` parameter is set. The user search filter can be used to restrict what user can attempt to log in. For example, to limit login to users that are not contractors, you could write `(&(objectClass=user)({{.UserAttr}}={{.Username}})(!(employeeType=Contractor)))`. -@include 'ldap-auth-userfilter-warning.mdx' +:::warning + +When specifying a `userfilter`, either the templated value `{{.UserAttr}}` or +the literal value that matches `userattr` should be present in the filter to +ensure that the search returns a unique result that takes `userattr` into +consideration for entity alias mapping purposes and avoid possible collisions on login. + +::: #### Binding - anonymous search @@ -131,7 +145,14 @@ There are two alternate methods of resolving the user object used to authenticat - `deny_null_bind` (bool, optional) - This option prevents users from bypassing authentication when providing an empty password. The default is `true`. - `anonymous_group_search` (bool, optional) - Use anonymous binds when performing LDAP group searches. Defaults to `false`. -@include 'ldap-auth-userfilter-warning.mdx' +:::warning + +When specifying a `userfilter`, either the templated value `{{.UserAttr}}` or +the literal value that matches `userattr` should be present in the filter to +ensure that the search returns a unique result that takes `userattr` into +consideration for entity alias mapping purposes and avoid possible collisions on login. + +::: #### Alias dereferencing @@ -272,10 +293,35 @@ It should be noted that user -> policy mapping happens at token creation time. A ## User lockout -@include 'user-lockout.mdx' +If a user provides bad credentials several times in quick succession, +OpenBao will stop trying to validate their credentials for a while, instead returning immediately +with a permission denied error. We call this behavior "user lockout". The time for which +a user will be locked out is called “lockout duration”. The user will be able to login after the lockout +duration has passed. The number of failed login attempts after which the user is locked out is called +“lockout threshold”. The lockout threshold counter is reset to zero after a few minutes without login attempts, +or upon a successful login attempt. The duration after which the counter will be reset to zero +after no login attempts is called "lockout counter reset". This can defeat both automated and targeted requests +i.e, user-based password guessing attacks as well as automated attacks. + +The user lockout feature is enabled by default. The default values for "lockout threshold" is 5 attempts, +"lockout duration" is 15 minutes, "lockout counter reset" is 15 minutes. + +The user lockout feature can be disabled as follows: +- It can be disabled globally using environment variable `VAULT_DISABLE_USER_LOCKOUT`. +- It can be disabled for all supported auth methods (ldap, userpass and approle) or a specific supported auth method using the `disable_lockout` + parameter within `user_lockout` stanza in configuration file. + Please see [user lockout configuration](/docs/configuration/user-lockout#user_lockout-stanza) for more details. +- It can be disabled for a specific auth mount using "auth tune". Please see [auth tune command](/docs/commands/auth/tune) + or [auth tune api](/api-docs/system/auth#tune-auth-method) for more details. + +:::warning + +**NOTE**: This feature is only supported by the userpass, ldap, and approle auth methods. + +::: ## API The LDAP auth method has a full HTTP API. Please see the -[LDAP auth method API](/vault/api-docs/auth/ldap) for more +[LDAP auth method API](/api-docs/auth/ldap) for more details. diff --git a/website/content/docs/auth/login-mfa/faq.mdx b/website/content/docs/auth/login-mfa/faq.mdx index 3110b3feed..a500889b4e 100644 --- a/website/content/docs/auth/login-mfa/faq.mdx +++ b/website/content/docs/auth/login-mfa/faq.mdx @@ -1,6 +1,5 @@ --- -layout: docs -page_title: Login MFA FAQ +sidebar_label: FAQ description: An FAQ page to answer the most commonly asked questions about login mfa. --- @@ -18,17 +17,21 @@ This FAQ section contains frequently asked questions about the Login MFA feature | MFA workflow | What does it do? | Who manages the MFA? | | ---------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------- | -| [Login MFA](/vault/docs/auth/login-mfa) | MFA in OpenBao provides MFA on login. CLI, API, and UI-based login are supported. | MFA is managed by OpenBao | -| [Okta Auth MFA](/vault/docs/auth/okta#mfa) | This is MFA as part of [Okta Auth method](/vault/docs/auth/okta) in OpenBao, where MFA is enforced by Okta on login. MFA must be satisfied for authentication to be successful. This is different from the Okta MFA method used with Login MFA. CLI/API login are supported. | MFA is managed externally by Okta | +| [Login MFA](/docs/auth/login-mfa) | MFA in OpenBao provides MFA on login. CLI, API, and UI-based login are supported. | MFA is managed by OpenBao | +| [Okta Auth MFA](/docs/auth/okta#mfa) | This is MFA as part of [Okta Auth method](/docs/auth/okta) in OpenBao, where MFA is enforced by Okta on login. MFA must be satisfied for authentication to be successful. This is different from the Okta MFA method used with Login MFA. CLI/API login are supported. | MFA is managed externally by Okta | ### Q: what is Single-Phase MFA vs. Two-Phase MFA? - **Single-Phase MFA:** This is a single request mechanism where the required MFA information, such as MFA method ID, is provided via the X-Vault-MFA header in a single MFA request that is used to authenticate into Openbao. -~> **Note**: If the configured MFA methods need a passcode, it needs to be provided in the request, such as in the case of TOTP or Duo. +:::warning + +**Note**: If the configured MFA methods need a passcode, it needs to be provided in the request, such as in the case of TOTP or Duo. If the configured MFA methods, such as PingID, Okta, or Duo, do not require a passcode and have out of band mechanisms for verifying the extra factor, Openbao will send an inquiry to the other service's APIs to determine whether the MFA request has yet been verified. +::: + - **Two-Phase MFA:** This is a two-request MFA method that is more conventionally used. - The MFA passcode required for the configured MFA method is not provided in a header of the login request that is MFA-restricted. Instead, the user first authenticates to the auth method, and on successful authentication to the auth method, an MFA requirement is returned to the user. The MFA requirement contains the MFA RequestID and constraints applicable to the MFA as configured by the operator. - The user then must make a second request to the new endpoint `sys/mfa/validate`, providing the MFA RequestID in the request, and an MFA payload which includes the MFA methodIDs passcode (if applicable). If MFA validation passes, the new Openbao token will be persisted and returned to the user in the response, just like a regular Openbao token created using a non-MFA-restricted auth method. @@ -37,15 +40,15 @@ If the configured MFA methods, such as PingID, Okta, or Duo, do not require a pa | MFA workflow | Configuration methods | Details | | ---------------------------------------------- | ----------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| [Login MFA](/vault/docs/auth/login-mfa) | CLI/API | Configured using the `identity/mfa/method` endpoints, then passing those method IDs to the `identity/mfa/login-enforcement` endpoint. MFA methods supported: TOTP, Okta, Duo, PingID. | -| [Okta Auth MFA](/vault/docs/auth/okta) | CLI/API | MFA methods supported: [TOTP](https://help.okta.com/en/prod/Content/Topics/Security/mfa-totp-seed.htm) , [Okta Verify Push](https://help.okta.com/en/prod/Content/Topics/Mobile/ov-admin-config.htm). | +| [Login MFA](/docs/auth/login-mfa) | CLI/API | Configured using the `identity/mfa/method` endpoints, then passing those method IDs to the `identity/mfa/login-enforcement` endpoint. MFA methods supported: TOTP, Okta, Duo, PingID. | +| [Okta Auth MFA](/docs/auth/okta) | CLI/API | MFA methods supported: [TOTP](https://help.okta.com/en/prod/Content/Topics/Security/mfa-totp-seed.htm) , [Okta Verify Push](https://help.okta.com/en/prod/Content/Topics/Mobile/ov-admin-config.htm). | ### Q: which MFA mechanism is used with the different MFA workflows in OpenBao? | MFA workflow | UI | CLI/API | Single-Phase | Two-Phase | | ---------------------------------------------- | --------- | ----------------------------------------------------------------------------------------------------------------------------------------- | --------------------------- | --------------------------- | -| [Login MFA](/vault/docs/auth/login-mfa) | Supported | Supported. You can select single-phase MFA by supplying the X-Vault-MFA header. In the absence of this header, the Two- Phase MFA is used | N/A | Supported | -| [Okta Auth MFA](/vault/docs/auth/okta) | N/A | N/A | MFA is not managed by OpenBao | MFA is not managed by OpenBao | +| [Login MFA](/docs/auth/login-mfa) | Supported | Supported. You can select single-phase MFA by supplying the X-Vault-MFA header. In the absence of this header, the Two- Phase MFA is used | N/A | Supported | +| [Okta Auth MFA](/docs/auth/okta) | N/A | N/A | MFA is not managed by OpenBao | MFA is not managed by OpenBao | ### Q: i use the OpenBao agent. does MFA pose any challenges for me? diff --git a/website/content/docs/auth/login-mfa/index.mdx b/website/content/docs/auth/login-mfa/index.mdx index 709332a205..3456c1f6af 100644 --- a/website/content/docs/auth/login-mfa/index.mdx +++ b/website/content/docs/auth/login-mfa/index.mdx @@ -1,6 +1,5 @@ --- -layout: docs -page_title: Multi-Factor Authentication (MFA) for Login - Auth Methods +sidebar_label: Overview description: |- Multi-factor authentication (MFA) is supported for several authentication methods. @@ -38,16 +37,20 @@ MFA in OpenBao includes the following login types: ## Login MFA procedure -~> **NOTE:** OpenBao's built-in Login MFA feature does not protect against brute forcing of -TOTP passcodes by default. We recommend that per-client [rate limits](/vault/docs/concepts/resource-quotas) +:::warning + +**NOTE:** OpenBao's built-in Login MFA feature does not protect against brute forcing of +TOTP passcodes by default. We recommend that per-client [rate limits](/docs/concepts/resource-quotas) are applied to the relevant login and/or mfa paths (e.g. `/sys/mfa/validate`). External MFA methods (`Duo`, `Ping` and `Okta`) may already provide configurable rate limiting. Rate limiting of Login MFA paths are enforced by default. +::: + Login MFA can be configured to secure further authenticating to an auth method. To enable login -MFA, an MFA method needs to be configured. Please see [Login MFA API](/vault/api-docs/secret/identity/mfa) for details +MFA, an MFA method needs to be configured. Please see [Login MFA API](/api-docs/secret/identity/mfa) for details on how to configure an MFA method. Once an MFA method is configured, an operator can configure an MFA enforcement using the returned unique MFA method ID. -Please see [Login MFA Enforcement API](/vault/api-docs/secret/identity/mfa/login-enforcement) +Please see [Login MFA Enforcement API](/api-docs/secret/identity/mfa/login-enforcement) for details on how to configure an MFA enforcement config. MFA could be enforced for an entity, a group of entities, a specific auth method accessor, or an auth method type. A login request that matches any MFA enforcement restrictions is subject to further MFA validation, @@ -162,10 +165,10 @@ note that this can affect the login response on any auth mount protected by MFA Note that the `uses_passcode` boolean value will always show true for TOTP, and false for Okta and PingID. For Duo method, the value can be configured as part of the method configuration, using the `use_passcode` parameter. -Please see [Duo API](/vault/api-docs/secret/identity/mfa/duo) for details +Please see [Duo API](/api-docs/secret/identity/mfa/duo) for details on how to configure the boolean value for Duo. -To validate the MFA restricted login request, the user sends a second request to the [validate](/vault/api-docs/system/mfa/validate) +To validate the MFA restricted login request, the user sends a second request to the [validate](/api-docs/system/mfa/validate) endpoint including the MFA request ID and MFA payload. MFA payload contains a map of methodIDs and their associated credentials. If the configured MFA methods, such as PingID, Okta, and Duo, do not require a passcode, the associated credentials will be a list with one empty string. @@ -225,7 +228,7 @@ To disable the interactive login experience, a user needs to pass in the `non-in $ bao write -non-interactive sys/mfa/validate -format=json @payload.json ``` -To get started with Login MFA, refer to the [Login MFA](/vault/tutorials/auth-methods/multi-factor-authentication) tutorial. +To get started with Login MFA, refer to the [Login MFA](/tutorials/auth-methods/multi-factor-authentication) tutorial. ### TOTP passcode validation rate limit diff --git a/website/content/docs/auth/radius.mdx b/website/content/docs/auth/radius.mdx index cd8c81a9cc..8cfb1f570c 100644 --- a/website/content/docs/auth/radius.mdx +++ b/website/content/docs/auth/radius.mdx @@ -1,6 +1,5 @@ --- -layout: docs -page_title: RADIUS - Auth Methods +sidebar_label: RADIUS description: |- The "radius" auth method allows users to authenticate with OpenBao using an existing RADIUS server. @@ -78,5 +77,5 @@ The response will contain a token at `auth.client_token`: ## API The RADIUS auth method has a full HTTP API. Please see the -[RADIUS Auth API](/vault/api-docs/auth/radius) for more +[RADIUS Auth API](/api-docs/auth/radius) for more details. diff --git a/website/content/docs/auth/token.mdx b/website/content/docs/auth/token.mdx index b28a9f7bba..6aeab9d484 100644 --- a/website/content/docs/auth/token.mdx +++ b/website/content/docs/auth/token.mdx @@ -1,6 +1,5 @@ --- -layout: docs -page_title: Token - Auth Methods +sidebar_label: Tokens description: The token store auth method is used to authenticate using tokens. --- @@ -17,7 +16,7 @@ The token store can also be used to bypass any other auth method: you can create tokens directly, as well as perform a variety of other operations on tokens such as renewal and revocation. -Please see the [token concepts](/vault/docs/concepts/tokens) page dedicated +Please see the [token concepts](/docs/concepts/tokens) page dedicated to tokens. ## Authentication @@ -36,5 +35,5 @@ either `X-Vault-Token: ` or `Authorization: Bearer `. ## API The Token auth method has a full HTTP API. Please see the -[Token auth method API](/vault/api-docs/auth/token) for more +[Token auth method API](/api-docs/auth/token) for more details. diff --git a/website/content/docs/auth/userpass.mdx b/website/content/docs/auth/userpass.mdx index 5ca4eaec45..5f7c9b38a1 100644 --- a/website/content/docs/auth/userpass.mdx +++ b/website/content/docs/auth/userpass.mdx @@ -1,6 +1,5 @@ --- -layout: docs -page_title: Userpass - Auth Methods +sidebar_label: Username and Password description: >- The "userpass" auth method allows users to authenticate with OpenBao using a username and password. @@ -89,9 +88,34 @@ management tool. ## User lockout -@include 'user-lockout.mdx' +If a user provides bad credentials several times in quick succession, +OpenBao will stop trying to validate their credentials for a while, instead returning immediately +with a permission denied error. We call this behavior "user lockout". The time for which +a user will be locked out is called “lockout duration”. The user will be able to login after the lockout +duration has passed. The number of failed login attempts after which the user is locked out is called +“lockout threshold”. The lockout threshold counter is reset to zero after a few minutes without login attempts, +or upon a successful login attempt. The duration after which the counter will be reset to zero +after no login attempts is called "lockout counter reset". This can defeat both automated and targeted requests +i.e, user-based password guessing attacks as well as automated attacks. + +The user lockout feature is enabled by default. The default values for "lockout threshold" is 5 attempts, +"lockout duration" is 15 minutes, "lockout counter reset" is 15 minutes. + +The user lockout feature can be disabled as follows: +- It can be disabled globally using environment variable `VAULT_DISABLE_USER_LOCKOUT`. +- It can be disabled for all supported auth methods (ldap, userpass and approle) or a specific supported auth method using the `disable_lockout` + parameter within `user_lockout` stanza in configuration file. + Please see [user lockout configuration](/docs/configuration/user-lockout#user_lockout-stanza) for more details. +- It can be disabled for a specific auth mount using "auth tune". Please see [auth tune command](/docs/commands/auth/tune) + or [auth tune api](/api-docs/system/auth#tune-auth-method) for more details. + +:::warning + +**NOTE**: This feature is only supported by the userpass, ldap, and approle auth methods. + +::: ## API The Userpass auth method has a full HTTP API. Please see the [Userpass auth -method API](/vault/api-docs/auth/userpass) for more details. +method API](/api-docs/auth/userpass) for more details. diff --git a/website/content/docs/browser-support.mdx b/website/content/docs/browser-support.mdx index 533e3073a0..480c961879 100644 --- a/website/content/docs/browser-support.mdx +++ b/website/content/docs/browser-support.mdx @@ -1,7 +1,5 @@ --- -layout: docs -page_title: Browser Support -sidebar_title: Browser Support +sidebar_label: Browser Support description: |- List of browser suppport. --- @@ -15,6 +13,10 @@ OpenBao currently supports all 'evergreen' and updated browsers. the following b - Safari - Microsoft Edge -!> **Warning**: Using an unsupported browser such as Internet Explorer 11 (IE 11) may cause degradation in feature functionality, and in some cases, OpenBao features may not operate. We encourage using one of the supported browsers listed for OpenBao UI. +:::danger + +**Warning**: Using an unsupported browser such as Internet Explorer 11 (IE 11) may cause degradation in feature functionality, and in some cases, OpenBao features may not operate. We encourage using one of the supported browsers listed for OpenBao UI. + +::: Please note that OpenBao, in alignment with Microsoft's stance on IE 11, no longer supports Internet Explorer 11 (IE 11). For further information on IE 11, please reference Microsoft's [support site](https://docs.microsoft.com/en-US/lifecycle/faq/internet-explorer-microsoft-edge). diff --git a/website/content/docs/commands/agent.mdx b/website/content/docs/commands/agent.mdx index 394f607aa7..b7258f0292 100644 --- a/website/content/docs/commands/agent.mdx +++ b/website/content/docs/commands/agent.mdx @@ -1,9 +1,7 @@ --- -layout: docs -page_title: agent - Command description: The "agent" command is used to start OpenBao Agent --- # agent -Please see the [OpenBao Agent documentation page](/vault/docs/agent-and-proxy/agent). +Please see the [OpenBao Agent documentation page](/docs/agent-and-proxy/agent). diff --git a/website/content/docs/commands/audit/disable.mdx b/website/content/docs/commands/audit/disable.mdx index 7e1ba71ace..13230ecd58 100644 --- a/website/content/docs/commands/audit/disable.mdx +++ b/website/content/docs/commands/audit/disable.mdx @@ -1,6 +1,5 @@ --- -layout: docs -page_title: audit disable - Command +sidebar_label: disable description: |- The "audit disable" command disables an audit device at a given path, if one exists. This command is idempotent, meaning it succeeds even if no audit @@ -18,10 +17,14 @@ data associated with the audit device is unaffected. For example, if you disabled an audit device that was logging to a file, the file would still exist and have stored contents. -~> Note: Once an audit device is disabled, you will no longer be able to HMAC values +:::warning + +Note: Once an audit device is disabled, you will no longer be able to HMAC values for comparison with entries in the audit logs. This is true even if you re-enable the audit device at the same path, as a new salt will be created for hashing. +::: + ## Examples Disable the audit device enabled at "file/": @@ -33,5 +36,5 @@ Success! Disabled audit device (if it was enabled) at: file/ ## Usage -There are no flags beyond the [standard set of flags](/vault/docs/commands) +There are no flags beyond the [standard set of flags](/docs/commands) included on all commands. diff --git a/website/content/docs/commands/audit/enable.mdx b/website/content/docs/commands/audit/enable.mdx index 3acffe9811..bfa8bee7c0 100644 --- a/website/content/docs/commands/audit/enable.mdx +++ b/website/content/docs/commands/audit/enable.mdx @@ -1,6 +1,5 @@ --- -layout: docs -page_title: audit enable - Command +sidebar_label: enable description: The "audit enable" command enables an audit device at a given path. --- @@ -24,12 +23,12 @@ Success! Enabled the file audit device at: file/ ``` Full configuration parameters for each audit device are available on the -[Audit Devices](/vault/docs/audit) page. +[Audit Devices](/docs/audit) page. ## Usage The following flags are available in addition to the [standard set of -flags](/vault/docs/commands) included on all commands. +flags](/docs/commands) included on all commands. - `-description` `(string: "")` - Human-friendly description for the purpose of this audit device. diff --git a/website/content/docs/commands/audit/index.mdx b/website/content/docs/commands/audit/index.mdx index 6fbc020db0..b81c09d74c 100644 --- a/website/content/docs/commands/audit/index.mdx +++ b/website/content/docs/commands/audit/index.mdx @@ -1,6 +1,5 @@ --- -layout: docs -page_title: audit - Command +sidebar_label: Overview description: |- The "audit" command groups subcommands for interacting with OpenBao's audit devices. Users can list, enable, and disable audit devices. @@ -12,7 +11,7 @@ The `audit` command groups subcommands for interacting with OpenBao's audit devices. Users can list, enable, and disable audit devices. For more information, please see the [audit device -documentation](/vault/docs/audit) +documentation](/docs/audit) ## Examples @@ -39,10 +38,14 @@ $ bao audit disable file/ Success! Disabled audit device (if it was enabled) at: file/ ``` -~> Note: Once an audit device is disabled, you will no longer be able to HMAC values +:::warning + +Note: Once an audit device is disabled, you will no longer be able to HMAC values for comparison with entries in the audit logs. This is true even if you re-enable the audit device at the same path, as a new salt will be created for hashing. +::: + ## Usage ```text diff --git a/website/content/docs/commands/audit/list.mdx b/website/content/docs/commands/audit/list.mdx index 066dd78fda..135e6b268b 100644 --- a/website/content/docs/commands/audit/list.mdx +++ b/website/content/docs/commands/audit/list.mdx @@ -1,6 +1,5 @@ --- -layout: docs -page_title: audit list - Command +sidebar_label: list description: |- The "audit list" command lists the audit devices enabled. The output lists the enabled audit devices and options for those devices. @@ -34,7 +33,7 @@ file/ file n/a replicated file_path=/var/log/audit.log ## Usage The following flags are available in addition to the [standard set of -flags](/vault/docs/commands) included on all commands. +flags](/docs/commands) included on all commands. ### Output options diff --git a/website/content/docs/commands/auth/disable.mdx b/website/content/docs/commands/auth/disable.mdx index c37d2056f6..08ba69ce06 100644 --- a/website/content/docs/commands/auth/disable.mdx +++ b/website/content/docs/commands/auth/disable.mdx @@ -1,6 +1,5 @@ --- -layout: docs -page_title: auth disable - Command +sidebar_label: disable description: |- The "auth disable" command disables an auth method at a given path, if one exists. This command is idempotent, meaning it succeeds even if no auth method @@ -28,5 +27,5 @@ Success! Disabled the auth method (if it existed) at: userpass/ ## Usage -There are no flags beyond the [standard set of flags](/vault/docs/commands) +There are no flags beyond the [standard set of flags](/docs/commands) included on all commands. diff --git a/website/content/docs/commands/auth/enable.mdx b/website/content/docs/commands/auth/enable.mdx index 0709940890..39fdfea840 100644 --- a/website/content/docs/commands/auth/enable.mdx +++ b/website/content/docs/commands/auth/enable.mdx @@ -1,6 +1,5 @@ --- -layout: docs -page_title: auth enable - Command +sidebar_label: enable description: |- The "auth enable" command enables an auth method at a given path. If an auth method already exists at the given path, an error is returned. After the auth @@ -17,7 +16,7 @@ auth method. An auth method is responsible for authenticating users or machines and assigning them policies and a token with which they can access OpenBao. Authentication is usually mapped to policy. Please see the [policies -concepts](/vault/docs/concepts/policies) page for more information. +concepts](/docs/concepts/policies) page for more information. ## Examples @@ -36,17 +35,17 @@ Success! Data written to: auth/userpass/users/sethvargo ``` For more information on the specific configuration options and paths, please see -the [auth method](/vault/docs/auth) documentation. +the [auth method](/docs/auth) documentation. ## Usage The following flags are available in addition to the [standard set of -flags](/vault/docs/commands) included on all commands. +flags](/docs/commands) included on all commands. - `-audit-non-hmac-request-keys` `(string: "")` - Key that will not be HMAC'd by audit devices in the request data object. Note that multiple keys may be specified by providing this option multiple times, each time with 1 key. - An example of this is provided in the [tune section](/vault/docs/commands/auth/tune). + An example of this is provided in the [tune section](/docs/commands/auth/tune). - `-audit-non-hmac-response-keys` `(string: "")` - Key that will not be HMAC'd by audit devices in the response data object. Note that multiple keys may be @@ -55,7 +54,7 @@ flags](/vault/docs/commands) included on all commands. - `-default-lease-ttl` `(duration: "")` - The default lease TTL for this auth method. If unspecified, this defaults to the OpenBao server's globally configured default lease TTL, or a previously configured value for the auth - method. Uses [duration format strings](/vault/docs/concepts/duration-format). + method. Uses [duration format strings](/docs/concepts/duration-format). - `-passthrough-request-headers` `(string: "")` - request header values that will be sent to the auth method. Note that multiple keys may be diff --git a/website/content/docs/commands/auth/help.mdx b/website/content/docs/commands/auth/help.mdx index 96264218db..264b7eb8f4 100644 --- a/website/content/docs/commands/auth/help.mdx +++ b/website/content/docs/commands/auth/help.mdx @@ -1,6 +1,5 @@ --- -layout: docs -page_title: auth help - Command +sidebar_label: help description: The "auth help" command prints usage and help for an auth method. --- @@ -39,5 +38,5 @@ $ bao auth help my-method/ ## Usage -There are no flags beyond the [standard set of flags](/vault/docs/commands) +There are no flags beyond the [standard set of flags](/docs/commands) included on all commands. diff --git a/website/content/docs/commands/auth/index.mdx b/website/content/docs/commands/auth/index.mdx index a0a7cddc57..b20baf9c1f 100644 --- a/website/content/docs/commands/auth/index.mdx +++ b/website/content/docs/commands/auth/index.mdx @@ -1,6 +1,5 @@ --- -layout: docs -page_title: auth - Command +sidebar_label: Overview description: |- The "auth" command groups subcommands for interacting with OpenBao's auth methods. Users can list, enable, disable, and get help for different auth @@ -13,10 +12,10 @@ The `auth` command groups subcommands for interacting with OpenBao's auth method Users can list, enable, disable, and get help for different auth methods. For more information, please see the [auth method -documentation](/vault/docs/auth) or the [authentication -concepts](/vault/docs/concepts/auth) page. +documentation](/docs/auth) or the [authentication +concepts](/docs/concepts/auth) page. -To authenticate to OpenBao as a user or machine, use the [`bao login`](/vault/docs/commands/login) command instead. This command is for +To authenticate to OpenBao as a user or machine, use the [`bao login`](/docs/commands/login) command instead. This command is for interacting with the auth methods themselves, not authenticating to OpenBao. ## Examples diff --git a/website/content/docs/commands/auth/list.mdx b/website/content/docs/commands/auth/list.mdx index 11b4e6ef53..6799ba6e2e 100644 --- a/website/content/docs/commands/auth/list.mdx +++ b/website/content/docs/commands/auth/list.mdx @@ -1,6 +1,5 @@ --- -layout: docs -page_title: auth list - Command +sidebar_label: list description: |- The "auth list" command lists the auth methods enabled. The output lists the enabled auth methods and options for those methods. @@ -58,7 +57,7 @@ token/ token auth_token_aafab997 system system defaul ## Usage The following flags are available in addition to the [standard set of -flags](/vault/docs/commands) included on all commands. +flags](/docs/commands) included on all commands. ### Output options diff --git a/website/content/docs/commands/auth/move.mdx b/website/content/docs/commands/auth/move.mdx index 7f25a66ab8..44de0d641d 100644 --- a/website/content/docs/commands/auth/move.mdx +++ b/website/content/docs/commands/auth/move.mdx @@ -1,6 +1,5 @@ --- -layout: docs -page_title: auth move - Command +sidebar_label: move description: |- The "auth move" command moves an existing auth method to a new path. All tokens from the old auth method are revoked, but all configurations @@ -30,5 +29,5 @@ $ bao auth move ns1/auth/approle/ ns2/auth/new-approle/ ## Usage -There are no flags beyond the [standard set of flags](/vault/docs/commands) +There are no flags beyond the [standard set of flags](/docs/commands) included on all commands. diff --git a/website/content/docs/commands/auth/tune.mdx b/website/content/docs/commands/auth/tune.mdx index e8671c3b08..5431ff3383 100644 --- a/website/content/docs/commands/auth/tune.mdx +++ b/website/content/docs/commands/auth/tune.mdx @@ -1,6 +1,5 @@ --- -layout: docs -page_title: auth tune - Command +sidebar_label: tune description: |- The "auth tune" command tunes the configuration options for the auth method at the given PATH. @@ -11,12 +10,12 @@ description: |- The `auth tune` command tunes the configuration options for the auth method at the given PATH. - +:::note The argument corresponds to the **path** where the auth method is enabled, not the auth **type**. - +::: ## Examples @@ -44,9 +43,7 @@ Success! Tuned the auth method at: github/ Verify the updated configuration. - - -```shell-session +```shell-session {1,4} $ bao read sys/auth/github/tune Key Value --- ----- @@ -57,8 +54,6 @@ max_lease_ttl 768h token_type default-service ``` - - To restore back to the system default, you can use `-1`. ```shell-session @@ -68,9 +63,7 @@ Success! Tuned the auth method at: github/ Verify the updated configuration. - - -```shell-session +```shell-session {1,4} $ bao read sys/auth/github/tune Key Value --- ----- @@ -81,8 +74,6 @@ max_lease_ttl 768h token_type default-service ``` - - You can specify multiple audit non-hmac request keys. ```shell-session @@ -93,8 +84,8 @@ Success! Tuned the auth method at: github/ ### Enable user lockout User lockout feature is only supported for -[userpass](/vault/docs/auth/userpass), [ldap](/vault/docs/auth/ldap), and -[approle](/vault/docs/auth/approle) auth methods. +[userpass](/docs/auth/userpass), [ldap](/docs/auth/ldap), and +[approle](/docs/auth/approle) auth methods. Tune the `userpass/` auth method to lock out the user after 10 failed login attempts within 10 minutes. @@ -106,9 +97,7 @@ Success! Tuned the auth method at: userpass/ View the current configuration of the auth method enabled at `userpass/`. - - -```shell-session +```shell-session {1,11-13} $ bao read sys/auth/userpass/tune Key Value @@ -124,13 +113,10 @@ user_lockout_duration 10m user_lockout_threshold 10 ``` - - - ## Usage The following flags are available in addition to the [standard set of -flags](/vault/docs/commands) included on all commands. +flags](/docs/commands) included on all commands. - `-allowed-response-headers` `(string: "")` - response header values that the auth method will be allowed to set. @@ -157,7 +143,7 @@ flags](/vault/docs/commands) included on all commands. - `-max-lease-ttl` `(duration: "")` - The maximum lease TTL for this auth method. If unspecified, this defaults to the OpenBao server's globally - configured [maximum lease TTL](/vault/docs/configuration#max_lease_ttl), or a + configured [maximum lease TTL](/docs/configuration#max_lease_ttl), or a previously configured value for the auth method. This value is allowed to override the server's global max TTL; it can be longer or shorter. @@ -170,7 +156,7 @@ flags](/vault/docs/commands) included on all commands. - `-plugin-version` `(string: "")` - Configures the semantic version of the plugin to use. The new version will not start running until the mount is - [reloaded](/vault/docs/commands/plugin/reload). + [reloaded](/docs/commands/plugin/reload). - `-user-lockout-threshold` `(string: "")` - Specifies the number of failed login attempts after which the user is locked out. diff --git a/website/content/docs/commands/debug.mdx b/website/content/docs/commands/debug.mdx index 174fe2e252..06c8497e8d 100644 --- a/website/content/docs/commands/debug.mdx +++ b/website/content/docs/commands/debug.mdx @@ -1,6 +1,4 @@ --- -layout: docs -page_title: debug - Command description: |- The "debug" command monitors an OpenBao server, probing information about it for a certain duration. @@ -150,7 +148,7 @@ $ bao debug -target=host -target=metrics ## Usage The following flags are available in addition to the [standard set of -flags](/vault/docs/commands) included on all commands. +flags](/docs/commands) included on all commands. ### Command options diff --git a/website/content/docs/commands/delete.mdx b/website/content/docs/commands/delete.mdx index a69226931d..ed632117ea 100644 --- a/website/content/docs/commands/delete.mdx +++ b/website/content/docs/commands/delete.mdx @@ -1,6 +1,4 @@ --- -layout: docs -page_title: delete - Command description: |- The "delete" command deletes secrets and configuration from OpenBao at the given path. The behavior of "delete" is delegated to the backend corresponding to @@ -28,9 +26,9 @@ $ bao delete transit/keys/my-key ``` Note: changing the `deletion_allowed` parameter to `true` is necessary for the -key to be successfully deleted, you can read more on key parameters [here](/vault/api-docs/secret/transit#update-key-configuration) +key to be successfully deleted, you can read more on key parameters [here](/api-docs/secret/transit#update-key-configuration) ## Usage -There are no flags beyond the [standard set of flags](/vault/docs/commands) +There are no flags beyond the [standard set of flags](/docs/commands) included on all commands. diff --git a/website/content/docs/commands/index.mdx b/website/content/docs/commands/index.mdx index f692cb5c1d..3be49693d6 100644 --- a/website/content/docs/commands/index.mdx +++ b/website/content/docs/commands/index.mdx @@ -1,6 +1,5 @@ --- -layout: docs -page_title: Commands (CLI) +sidebar_label: Overview description: |- In addition to a verbose HTTP API, OpenBao features a command-line interface that wraps common functionality and formats output. The OpenBao CLI is a single @@ -10,7 +9,7 @@ description: |- # OpenBao commands (CLI) -In addition to a verbose [HTTP API](/vault/api-docs), OpenBao features a command-line +In addition to a verbose [HTTP API](/api-docs), OpenBao features a command-line interface (CLI) that wraps common functionality and formats output. The OpenBao CLI is a single static binary. It is a thin wrapper around the HTTP API. Every CLI command maps directly to the HTTP API internally. @@ -24,26 +23,26 @@ command-specific options. Construct your OpenBao CLI command such that the command options precede its path and arguments if any: - - ```text bao [options] [path] [args] ``` - - -- `options` - [Flags](/vault/docs/commands#flags) to specify additional settings +- `options` - [Flags](/docs/commands#flags) to specify additional settings - `args` - API arguments specific to the operation --> **NOTE:** Use the [command help](#command-help) to display available options +:::info + +**NOTE:** Use the [command help](#command-help) to display available options and arguments. +::: + #### Examples: The following `write` command creates a new user (`bob`) in the userpass auth method. It passes the `-address` flag to specify the OpenBao server address which precedes the path (`auth/userpass/users/bob`) and its -[argument](/vault/api-docs/auth/userpass#create-update-user) +[argument](/api-docs/auth/userpass#create-update-user) (`password="long-password"`) at last. ```shell-session @@ -51,7 +50,7 @@ $ bao write -address="http://127.0.0.1:8200" auth/userpass/users/bob password="l ``` If multiple options (`-address` and `-namespace`) and -[arguments](/vault/api-docs/auth/userpass#create-update-user) (`password` and +[arguments](/api-docs/auth/userpass#create-update-user) (`password` and `policies`) are specified, the command would look like: ```shell-session @@ -62,9 +61,9 @@ $ bao write -address="http://127.0.0.1:8200" -namespace="my-organization" \ The options (flags) come after the command (or subcommand) preceding the path, and the args always follow the path to set API parameter values. -The four most common operations in OpenBao are [read](/vault/docs/commands/read), -[write](/vault/docs/commands/write), [delete](/vault/docs/commands/delete), and -[list](/vault/docs/commands/list). These operations work on most paths in OpenBao. Some +The four most common operations in OpenBao are [read](/docs/commands/read), +[write](/docs/commands/write), [delete](/docs/commands/delete), and +[list](/docs/commands/list). These operations work on most paths in OpenBao. Some paths will contain secrets while other paths may contain configuration. Whatever it is, the primary interface for reading and writing data to OpenBao is similar. @@ -117,10 +116,10 @@ The help output displays available subcommands, parameters, and command flags. ### API help -To invoke the OpenBao API paths, you can use the [read](/vault/docs/commands/read) (for -HTTP GET), [write](/vault/docs/commands/write) (for HTTP PUT or POST), -[delete](/vault/docs/commands/delete) (for HTTP DELETE), and -[list](/vault/docs/commands/list) (for HTTP LIST) commands. +To invoke the OpenBao API paths, you can use the [read](/docs/commands/read) (for +HTTP GET), [write](/docs/commands/write) (for HTTP PUT or POST), +[delete](/docs/commands/delete) (for HTTP DELETE), and +[list](/docs/commands/list) (for HTTP LIST) commands. Use `path-help` to get OpenBao API help: @@ -132,7 +131,7 @@ The `path-help` retrieves API help on any API paths. OpenBao API paths provide built-in help in markdown format. This includes system paths, secret engines, and auth methods. -**Example:** API help on the [`sys/mounts/`](/vault/api-docs/system/mounts) path. +**Example:** API help on the [`sys/mounts/`](/api-docs/system/mounts) path. ```shell-session $ bao path-help sys/mounts @@ -244,7 +243,11 @@ Enable autocompletion by running: $ bao -autocomplete-install ``` -~> Be sure to **restart your shell** after installing autocompletion! +:::warning + +Be sure to **restart your shell** after installing autocompletion! + +::: When you start typing an OpenBao command, press the `` character to show a list of available completions. Type `-` to show available flag completions. @@ -275,7 +278,7 @@ available to the OpenBao process will be logged during startup. OpenBao authentication token. Conceptually similar to a session token on a website, the `VAULT_TOKEN` environment variable holds the contents of the token. For more information, please see the [token -concepts](/vault/docs/concepts/tokens) page. +concepts](/docs/concepts/tokens) page. ### `VAULT_ADDR` @@ -338,7 +341,7 @@ High Availability mode. Do not verify OpenBao's presented certificate before communicating with it. Setting this variable is not recommended and voids OpenBao's [security -model](/vault/docs/internals/security). +model](/docs/internals/security). ### `VAULT_TLS_SERVER_NAME` @@ -362,7 +365,7 @@ limiting is off by default. _Note:_ The rate is limited for each invocation of the `bao` CLI. Since each invocation of the `bao` CLI typically only makes a few requests, this environment variable is most useful when using the Go -[OpenBao client API](/vault/api-docs/libraries#go). +[OpenBao client API](/api-docs/libraries#go). ### `VAULT_NAMESPACE` @@ -390,20 +393,32 @@ HTTP or HTTPS proxy location which should be used by all requests to access Open When present, this overrides the default proxy resolution behavior. Format should be `http://server:port` or `https://server:port`. -~> Note: When using `VAULT_HTTP_PROXY` or `VAULT_PROXY_ADDR` any of the standard +:::warning + +Note: When using `VAULT_HTTP_PROXY` or `VAULT_PROXY_ADDR` any of the standard proxy variables found in the environment will be ignored. Specifically `HTTP_PROXY`, `HTTPS_PROXY` and `NO_PROXY`. All requests will resolve the specified proxy; there is no way to exclude domains from consulting the proxy server. -~> Note: If both `VAULT_HTTP_PROXY` and `VAULT_PROXY_ADDR` environment +::: + +:::warning + +Note: If both `VAULT_HTTP_PROXY` and `VAULT_PROXY_ADDR` environment variables are supplied, `VAULT_PROXY_ADDR` will be prioritized and preferred. +::: + ### `VAULT_DISABLE_REDIRECTS` Prevents the OpenBao client from following redirects. By default, the OpenBao client will automatically follow a single redirect. -~> **Note:** Disabling redirect following behavior could cause issues with commands such as 'bao operator raft snapshot' as this command redirects the request to the cluster's primary node. +:::warning + +**Note:** Disabling redirect following behavior could cause issues with commands such as 'bao operator raft snapshot' as this command redirects the request to the cluster's primary node. + +::: ## Flags diff --git a/website/content/docs/commands/kv/delete.mdx b/website/content/docs/commands/kv/delete.mdx index aa8d16d869..df555e39c6 100644 --- a/website/content/docs/commands/kv/delete.mdx +++ b/website/content/docs/commands/kv/delete.mdx @@ -1,6 +1,5 @@ --- -layout: docs -page_title: kv delete - Command +sidebar_label: delete description: |- The "kv delete" command deletes the data for the provided path in the key/value secrets engine. --- @@ -30,7 +29,7 @@ Success! Data deleted (if it existed) at: secret/data/creds ## Usage -There are no flags beyond the [standard set of flags](/vault/docs/commands) +There are no flags beyond the [standard set of flags](/docs/commands) included on all commands. ### Command options @@ -45,4 +44,4 @@ included on all commands. data will not be deleted, but it will no longer be returned in normal get requests. -~> **NOTE:** The `-versions` command option is only for K/V v2. +**NOTE:** The `-versions` command option is only for K/V v2. diff --git a/website/content/docs/commands/kv/destroy.mdx b/website/content/docs/commands/kv/destroy.mdx index 01cdfca3d2..46e4dafba7 100644 --- a/website/content/docs/commands/kv/destroy.mdx +++ b/website/content/docs/commands/kv/destroy.mdx @@ -1,6 +1,5 @@ --- -layout: docs -page_title: kv destroy - Command +sidebar_label: destroy description: |- The "kv destroy" command permanently removes the specified version data for the provided key and version numbers from the key-value store. @@ -8,9 +7,13 @@ description: |- # kv destroy -~> **NOTE:** This is a [K/V Version 2](/vault/docs/secrets/kv/kv-v2) secrets +:::warning + +**NOTE:** This is a [K/V Version 2](/docs/secrets/kv/kv-v2) secrets engine command, and not available for Version 1. +::: + The `kv destroy` command permanently removes the specified versions' data from the key/value secrets engine. If no key exists at the path, no action is taken. @@ -26,7 +29,7 @@ Success! Data written to: secret/destroy/creds ## Usage -There are no flags beyond the [standard set of flags](/vault/docs/commands) +There are no flags beyond the [standard set of flags](/docs/commands) included on all commands. ### Output options diff --git a/website/content/docs/commands/kv/enable-versioning.mdx b/website/content/docs/commands/kv/enable-versioning.mdx index 02be5b2180..6a3e46b006 100644 --- a/website/content/docs/commands/kv/enable-versioning.mdx +++ b/website/content/docs/commands/kv/enable-versioning.mdx @@ -1,6 +1,5 @@ --- -layout: docs -page_title: kv enable-versioning - Command +sidebar_label: enable-versioning description: |- The "kv enable-versioning" command turns on versioning for the backend at the provided path. @@ -23,7 +22,7 @@ Success! Tuned the secrets engine at: secret/ ## Usage -There are no flags beyond the [standard set of flags](/vault/docs/commands) +There are no flags beyond the [standard set of flags](/docs/commands) included on all commands. ### Output options diff --git a/website/content/docs/commands/kv/get.mdx b/website/content/docs/commands/kv/get.mdx index 3663522c5d..50fd6d4722 100644 --- a/website/content/docs/commands/kv/get.mdx +++ b/website/content/docs/commands/kv/get.mdx @@ -1,6 +1,5 @@ --- -layout: docs -page_title: kv get - Command +sidebar_label: get description: |- The "kv get" command retrieves the value from OpenBao's key-value store at the given key name. If no key exists with that name, an error is returned. If a diff --git a/website/content/docs/commands/kv/index.mdx b/website/content/docs/commands/kv/index.mdx index 095c70cd23..4ae1d6bbe0 100644 --- a/website/content/docs/commands/kv/index.mdx +++ b/website/content/docs/commands/kv/index.mdx @@ -1,6 +1,5 @@ --- -layout: docs -page_title: kv - Command +sidebar_label: Overview description: |- The "kv" command groups subcommands for interacting with OpenBao's key/value secret engine. @@ -9,8 +8,8 @@ description: |- # kv The `kv` command groups subcommands for interacting with OpenBao's key/value -secrets engine (both [K/V Version 1](/vault/docs/secrets/kv/kv-v1) and [K/V -Version 2](/vault/docs/secrets/kv/kv-v2). +secrets engine (both [K/V Version 1](/docs/secrets/kv/kv-v1) and [K/V +Version 2](/docs/secrets/kv/kv-v2). ## Syntax diff --git a/website/content/docs/commands/kv/list.mdx b/website/content/docs/commands/kv/list.mdx index 9304a32aad..524e8ae85e 100644 --- a/website/content/docs/commands/kv/list.mdx +++ b/website/content/docs/commands/kv/list.mdx @@ -1,6 +1,5 @@ --- -layout: docs -page_title: kv list - Command +sidebar_label: list description: |- The "kv list" command lists data from OpenBao's K/V secrets engine at the given path. @@ -33,7 +32,7 @@ release ## Usage -There are no flags beyond the [standard set of flags](/vault/docs/commands) +There are no flags beyond the [standard set of flags](/docs/commands) included on all commands. ### Output options diff --git a/website/content/docs/commands/kv/metadata.mdx b/website/content/docs/commands/kv/metadata.mdx index ae011afe13..e6cb39ccd5 100644 --- a/website/content/docs/commands/kv/metadata.mdx +++ b/website/content/docs/commands/kv/metadata.mdx @@ -1,6 +1,5 @@ --- -layout: docs -page_title: kv metadata - Command +sidebar_label: metadata description: |- The "kv metadata" command has subcommands for interacting with the metadata endpoint in OpenBao's key-value store. @@ -8,9 +7,13 @@ description: |- # kv metadata -~> **NOTE:** This is a [K/V Version 2](/vault/docs/secrets/kv/kv-v2) secrets +:::warning + +**NOTE:** This is a [K/V Version 2](/docs/secrets/kv/kv-v2) secrets engine command, and not available for Version 1. +::: + The `kv metadata` command has subcommands for interacting with the metadata and versions for the versioned secrets (K/V Version 2 secrets engine) at the specified path. @@ -150,7 +153,7 @@ be applied to new versions. to a duration to specify the `deletion_time` for all new versions written to this key. If not set, the backend's `delete_version_after` will be used. If the value is greater than the backend's `delete_version_after`, the backend's - `delete_version_after` will be used. Accepts [duration format strings](/vault/docs/concepts/duration-format). + `delete_version_after` will be used. Accepts [duration format strings](/docs/concepts/duration-format). - `-custom-metadata` `(string: "")` - Specifies a key-value pair for the `custom_metadata` field. This can be specified multiple times to add multiple diff --git a/website/content/docs/commands/kv/patch.mdx b/website/content/docs/commands/kv/patch.mdx index e3e579b6e1..60a71836e2 100644 --- a/website/content/docs/commands/kv/patch.mdx +++ b/website/content/docs/commands/kv/patch.mdx @@ -1,6 +1,5 @@ --- -layout: docs -page_title: kv patch - Command +sidebar_label: patch description: |- The "kv patch" command writes the data to the given path in the key-value store. The data can be of any type. @@ -8,9 +7,13 @@ description: |- # kv patch -~> **NOTE:** This is a [K/V Version 2](/vault/docs/secrets/kv/kv-v2) secrets +:::warning + +**NOTE:** This is a [K/V Version 2](/docs/secrets/kv/kv-v2) secrets engine command, and not available for Version 1. +::: + The `kv patch` command writes the data to the given path in the K/V v2 secrets engine. The data can be of any type. Unlike the `kv put` command, the `patch` command combines the change with existing data instead of replacing them. diff --git a/website/content/docs/commands/kv/put.mdx b/website/content/docs/commands/kv/put.mdx index fbeb5dd724..3c2efa48f6 100644 --- a/website/content/docs/commands/kv/put.mdx +++ b/website/content/docs/commands/kv/put.mdx @@ -1,6 +1,5 @@ --- -layout: docs -page_title: kv put - Command +sidebar_label: put description: |- The "kv put" command writes the data to the given path in the K/V secrets engine. The data can be of any type. @@ -43,7 +42,7 @@ $ echo "abcd1234" | bao kv put -mount=secret foo bar=- ## Usage -There are no flags beyond the [standard set of flags](/vault/docs/commands) +There are no flags beyond the [standard set of flags](/docs/commands) included on all commands. ### Output options diff --git a/website/content/docs/commands/kv/rollback.mdx b/website/content/docs/commands/kv/rollback.mdx index 9b3ee217c8..1ecf2c0b5d 100644 --- a/website/content/docs/commands/kv/rollback.mdx +++ b/website/content/docs/commands/kv/rollback.mdx @@ -1,6 +1,5 @@ --- -layout: docs -page_title: kv rollback - Command +sidebar_label: rollback description: |- The "kv rollback" command restores a given previous version to the current version at the given path. @@ -8,9 +7,13 @@ description: |- # kv rollback -~> **NOTE:** This is a [K/V Version 2](/vault/docs/secrets/kv/kv-v2) secrets +:::warning + +**NOTE:** This is a [K/V Version 2](/docs/secrets/kv/kv-v2) secrets engine command, and not available for Version 1. +::: + The `kv rollback` command restores a given previous version to the current version at the given path. The value is written as a new version; for instance, if the current version is 5 and the rollback version is 2, the data from version @@ -33,7 +36,7 @@ version 6 ## Usage -There are no flags beyond the [standard set of flags](/vault/docs/commands) +There are no flags beyond the [standard set of flags](/docs/commands) included on all commands. ### Output options diff --git a/website/content/docs/commands/kv/undelete.mdx b/website/content/docs/commands/kv/undelete.mdx index 8a9d1886f2..16d67d3506 100644 --- a/website/content/docs/commands/kv/undelete.mdx +++ b/website/content/docs/commands/kv/undelete.mdx @@ -1,6 +1,5 @@ --- -layout: docs -page_title: kv undelete - Command +sidebar_label: undelete description: |- The "kv undelete" command undeletes the data for the provided version and path in the key-value store. This restores the data, allowing it to be returned on @@ -9,9 +8,13 @@ description: |- # kv undelete -~> **NOTE:** This is a [K/V Version 2](/vault/docs/secrets/kv/kv-v2) secrets +:::warning + +**NOTE:** This is a [K/V Version 2](/docs/secrets/kv/kv-v2) secrets engine command, and not available for Version 1. +::: + The `kv undelete` command undoes the deletes of the data for the provided version and path in the key-value store. This restores the data, allowing it to be returned on get requests. @@ -27,7 +30,7 @@ Success! Data written to: secret/undelete/creds ## Usage -There are no flags beyond the [standard set of flags](/vault/docs/commands) +There are no flags beyond the [standard set of flags](/docs/commands) included on all commands. ### Output options diff --git a/website/content/docs/commands/lease/index.mdx b/website/content/docs/commands/lease/index.mdx index 9d87820154..3101005825 100644 --- a/website/content/docs/commands/lease/index.mdx +++ b/website/content/docs/commands/lease/index.mdx @@ -1,6 +1,5 @@ --- -layout: docs -page_title: lease - Command +sidebar_label: Overview description: |- The "lease" command groups subcommands for interacting with leases attached to secrets. @@ -9,7 +8,7 @@ description: |- # lease The `lease` command groups subcommands for interacting with leases attached to -secrets. For leases attached to tokens, use the [`bao token`](/vault/docs/commands/token) subcommand. +secrets. For leases attached to tokens, use the [`bao token`](/docs/commands/token) subcommand. ## Examples diff --git a/website/content/docs/commands/lease/lookup.mdx b/website/content/docs/commands/lease/lookup.mdx index bba3663e75..f91a9fd8a3 100644 --- a/website/content/docs/commands/lease/lookup.mdx +++ b/website/content/docs/commands/lease/lookup.mdx @@ -1,6 +1,5 @@ --- -layout: docs -page_title: lease lookup - Command +sidebar_label: lookup description: |- The "lease lookup" command retrieves information about a lease. --- @@ -30,5 +29,5 @@ ttl 9m52s ## Usage -There are no flags beyond the [standard set of flags](/vault/docs/commands) +There are no flags beyond the [standard set of flags](/docs/commands) included on all commands. diff --git a/website/content/docs/commands/lease/renew.mdx b/website/content/docs/commands/lease/renew.mdx index 4f5de2e5c7..3d85bff927 100644 --- a/website/content/docs/commands/lease/renew.mdx +++ b/website/content/docs/commands/lease/renew.mdx @@ -1,6 +1,5 @@ --- -layout: docs -page_title: lease renew - Command +sidebar_label: renew description: |- The "lease renew" command renews the lease on a secret, extending the time that it can be used before it is revoked by OpenBao. @@ -31,7 +30,7 @@ lease_renewable true ## Usage The following flags are available in addition to the [standard set of -flags](/vault/docs/commands) included on all commands. +flags](/docs/commands) included on all commands. - `-increment` `(duration: "")` - Request a specific increment in seconds. OpenBao is not required to honor this request. diff --git a/website/content/docs/commands/lease/revoke.mdx b/website/content/docs/commands/lease/revoke.mdx index 8228fe881d..af41ff3448 100644 --- a/website/content/docs/commands/lease/revoke.mdx +++ b/website/content/docs/commands/lease/revoke.mdx @@ -1,6 +1,5 @@ --- -layout: docs -page_title: lease revoke - Command +sidebar_label: revoke description: |- The "lease revoke" command revokes the lease on a secret, invalidating the underlying secret. @@ -30,7 +29,7 @@ Success! Revoked any leases with prefix: database/creds ## Usage The following flags are available in addition to the [standard set of -flags](/vault/docs/commands) included on all commands. +flags](/docs/commands) included on all commands. - `-force` `(bool: false)` - Delete the lease from OpenBao even if the secret engine revocation fails. This is meant for recovery situations where the diff --git a/website/content/docs/commands/list.mdx b/website/content/docs/commands/list.mdx index d5a661a1a9..e078a35f47 100644 --- a/website/content/docs/commands/list.mdx +++ b/website/content/docs/commands/list.mdx @@ -1,6 +1,4 @@ --- -layout: docs -page_title: list - Command description: |- The "list" command lists data from OpenBao at the given path. This can be used to list keys in a, given secrets engine. @@ -21,5 +19,5 @@ $ bao list identity/entity/id ## Usage -There are no flags beyond the [standard set of flags](/vault/docs/commands) +There are no flags beyond the [standard set of flags](/docs/commands) included on all commands. diff --git a/website/content/docs/commands/login.mdx b/website/content/docs/commands/login.mdx index 5e7cfa095c..bed9da2281 100644 --- a/website/content/docs/commands/login.mdx +++ b/website/content/docs/commands/login.mdx @@ -1,6 +1,4 @@ --- -layout: docs -page_title: login - Command description: |- The "login" command authenticates users or machines to OpenBao using the provided arguments. A successful authentication results in an OpenBao token - @@ -96,9 +94,13 @@ policies ["default"] token_meta_username my-username ``` -~> Notice that the command option (`-method=userpass`) precedes the command +:::warning + +Notice that the command option (`-method=userpass`) precedes the command argument (`username=my-username`). +::: + If a github auth method was enabled at the path "github-prod": ```shell-session @@ -123,7 +125,7 @@ token_meta_username my-username ## Usage The following flags are available in addition to the [standard set of -flags](/vault/docs/commands) included on all commands. +flags](/docs/commands) included on all commands. ### Output options diff --git a/website/content/docs/commands/monitor.mdx b/website/content/docs/commands/monitor.mdx index 811a5d67ee..a645d1fe14 100644 --- a/website/content/docs/commands/monitor.mdx +++ b/website/content/docs/commands/monitor.mdx @@ -1,6 +1,4 @@ --- -layout: docs -page_title: monitor - Command description: |- The "monitor" command displays the server logs of an OpenBao server in real time. @@ -34,7 +32,7 @@ $ bao monitor -log-level=debug ## Usage The following flags are available in addition to the [standard set of -flags](/vault/docs/commands) included on all commands. +flags](/docs/commands) included on all commands. ### Output options diff --git a/website/content/docs/commands/operator/diagnose.mdx b/website/content/docs/commands/operator/diagnose.mdx index 965a45f3b4..b13473f83a 100644 --- a/website/content/docs/commands/operator/diagnose.mdx +++ b/website/content/docs/commands/operator/diagnose.mdx @@ -1,6 +1,5 @@ --- -layout: docs -page_title: operator diagnose - Command +sidebar_label: diagnose description: |- "bao operator diagnose" is a new operator-centric command, focused on providing a clear description of what is working in OpenBao, and what is not working. The command focuses on why OpenBao cannot serve requests, @@ -23,7 +22,7 @@ messages or warnings. ## Usage The following flags are available in addition to the [standard set of -flags](/vault/docs/commands) included on all commands. +flags](/docs/commands) included on all commands. ### Output options diff --git a/website/content/docs/commands/operator/generate-root.mdx b/website/content/docs/commands/operator/generate-root.mdx index 5dd407f15f..757a379f51 100644 --- a/website/content/docs/commands/operator/generate-root.mdx +++ b/website/content/docs/commands/operator/generate-root.mdx @@ -1,6 +1,5 @@ --- -layout: docs -page_title: operator generate-root - Command +sidebar_label: generate-root description: |- The "operator generate-root" command generates a new root token by combining a quorum of share holders. @@ -20,14 +19,14 @@ One of the following must be provided to start the root token generation: final value. - A file containing a PGP key or a - [keybase](/vault/docs/concepts/pgp-gpg-keybase) username in the `-pgp-key` + [keybase](/docs/concepts/pgp-gpg-keybase) username in the `-pgp-key` flag. The resulting token is encrypted with this public key. An unseal key may be provided directly on the command line as an argument to the command. If key is specified as "-", the command will read from stdin. If a TTY is available, the command will prompt for text. -Please see the [generate root guide](/vault/tutorials/operations/generate-root) for +Please see the [generate root guide](/tutorials/operations/generate-root) for step-by-step instructions. ## Examples @@ -53,7 +52,7 @@ $ bao operator generate-root -otp="..." ## Usage The following flags are available in addition to the [standard set of -flags](/vault/docs/commands) included on all commands. +flags](/docs/commands) included on all commands. ### Output options diff --git a/website/content/docs/commands/operator/index.mdx b/website/content/docs/commands/operator/index.mdx index 66349413a8..26deda4302 100644 --- a/website/content/docs/commands/operator/index.mdx +++ b/website/content/docs/commands/operator/index.mdx @@ -1,6 +1,5 @@ --- -layout: docs -page_title: operator - Command +sidebar_label: Overview description: |- The "operator" command groups subcommands for operators interacting with OpenBao. Most users will not need to interact with these commands. diff --git a/website/content/docs/commands/operator/init.mdx b/website/content/docs/commands/operator/init.mdx index e9d3424143..6114898805 100644 --- a/website/content/docs/commands/operator/init.mdx +++ b/website/content/docs/commands/operator/init.mdx @@ -1,6 +1,5 @@ --- -layout: docs -page_title: operator init - Command +sidebar_label: init description: |- The "operator init" command initializes an OpenBao server. Initialization is the process by which OpenBao's storage backend is prepared to receive data. Since @@ -20,7 +19,7 @@ During initialization, OpenBao generates a root key, which is stored in the stor The default OpenBao configuration uses [Shamir's Secret Sharing](https://en.wikipedia.org/wiki/Shamir%27s_Secret_Sharing) to split the root key into a configured number of shards (referred as key shares, or unseal keys). A certain threshold of shards is required to reconstruct the root key, which is then used to decrypt the OpenBao's encryption key. -Refer to the [Seal/Unseal](/vault/docs/concepts/seal#seal-unseal) documentation for further details. +Refer to the [Seal/Unseal](/docs/concepts/seal#seal-unseal) documentation for further details. ## Examples @@ -57,7 +56,7 @@ $ bao operator init -root-token-pgp-key="keybase:hashicorp" ## Usage The following flags are available in addition to the [standard set of -flags](/vault/docs/commands) included on all commands. +flags](/docs/commands) included on all commands. ### Output options @@ -108,17 +107,17 @@ flags](/vault/docs/commands) included on all commands. ### HSM and KMS options - `-recovery-pgp-keys` `(string: "...")` - Behaves like `-pgp-keys`, but for the - recovery key shares. This is only available with [Auto Unseal](/vault/docs/concepts/seal#auto-unseal) seals (HSM, KMS and Transit seals). + recovery key shares. This is only available with [Auto Unseal](/docs/concepts/seal#auto-unseal) seals (HSM, KMS and Transit seals). - `-recovery-shares` `(int: 5)` - Number of key shares to split the recovery key - into. This is only available with [Auto Unseal](/vault/docs/concepts/seal#auto-unseal) seals (HSM, KMS and Transit seals). + into. This is only available with [Auto Unseal](/docs/concepts/seal#auto-unseal) seals (HSM, KMS and Transit seals). - `-recovery-threshold` `(int: 3)` - Number of key shares required to - reconstruct the recovery key. This is only available with [Auto Unseal](/vault/docs/concepts/seal#auto-unseal) seals (HSM, KMS and Transit seals). + reconstruct the recovery key. This is only available with [Auto Unseal](/docs/concepts/seal#auto-unseal) seals (HSM, KMS and Transit seals). - `-stored-shares` `(int: 0)` - Number of unseal keys to store on an HSM. This must be equal to `-key-shares`. --> **Recovery keys:** Refer to the - [Seal/Unseal](/vault/docs/concepts/seal#recovery-key) documentation to learn more +**Recovery keys:** Refer to the + [Seal/Unseal](/docs/concepts/seal#recovery-key) documentation to learn more about recovery keys. diff --git a/website/content/docs/commands/operator/key-status.mdx b/website/content/docs/commands/operator/key-status.mdx index a88fc7c3e5..bd761b7868 100644 --- a/website/content/docs/commands/operator/key-status.mdx +++ b/website/content/docs/commands/operator/key-status.mdx @@ -1,6 +1,5 @@ --- -layout: docs -page_title: operator key-status - Command +sidebar_label: key-status description: |- The "operator key-status" provides information about the active encryption key. @@ -25,7 +24,7 @@ Encryption Count 4494 ## Usage The following flags are available in addition to the [standard set of -flags](/vault/docs/commands) included on all commands. +flags](/docs/commands) included on all commands. ### Output options diff --git a/website/content/docs/commands/operator/members.mdx b/website/content/docs/commands/operator/members.mdx index e7fcf54307..32aaec8a18 100644 --- a/website/content/docs/commands/operator/members.mdx +++ b/website/content/docs/commands/operator/members.mdx @@ -1,6 +1,5 @@ --- -layout: docs -page_title: operator members - Command +sidebar_label: members description: |- The "operator members" command provides information about the nodes making up an HA cluster. --- @@ -29,7 +28,7 @@ josh-C02ZT9DYMD6R http://127.0.0.5:8200 https://127.0.0.5:8201 false ## Usage The following flags are available in addition to the [standard set of -flags](/vault/docs/commands) included on all commands. +flags](/docs/commands) included on all commands. ### Output options diff --git a/website/content/docs/commands/operator/migrate.mdx b/website/content/docs/commands/operator/migrate.mdx index 726a1966bc..e37c636419 100644 --- a/website/content/docs/commands/operator/migrate.mdx +++ b/website/content/docs/commands/operator/migrate.mdx @@ -1,6 +1,5 @@ --- -layout: docs -page_title: operator migrate - Command +sidebar_label: migrate description: >- The "operator migrate" command copies data between storage backends to facilitate @@ -48,7 +47,7 @@ $ bao operator migrate -config migrate.hcl -start "data/logical/fd" The `operator migrate` command uses a dedicated configuration file to specify the source and destination storage backends. The format of the storage stanzas is identical -to that used to [configure OpenBao](/vault/docs/configuration/storage), +to that used to [configure OpenBao](/docs/configuration/storage), with the only difference being that two stanzas are required: `storage_source` and `storage_destination`. ```hcl @@ -66,9 +65,9 @@ storage_destination "file" { The below configuration will migrate away from Filesystem storage to integrated raft storage. The raft data will be stored on the local filesystem in the defined `path`. `node_id` can optionally be set to identify this node. -[cluster_addr](/vault/docs/configuration#cluster_addr) must be set to the +[cluster_addr](/docs/configuration#cluster_addr) must be set to the cluster hostname of this node. For more configuration options see the [raft -storage configuration documentation](/vault/docs/configuration/storage/raft). +storage configuration documentation](/docs/configuration/storage/raft). If the original configuration uses "raft" for `ha_storage` a different `path` needs to be declared for the path in `storage_destination` and the new @@ -104,7 +103,7 @@ $ bao operator migrate -config migrate.hcl After migration has completed, the data is stored on the local file system. To use the new storage backend with OpenBao, update OpenBao's configuration file as described in the [raft storage configuration -documentation](/vault/docs/configuration/storage/raft). Then start and unseal the +documentation](/docs/configuration/storage/raft). Then start and unseal the OpenBao server. ### Join additional nodes @@ -132,5 +131,5 @@ The following flags are available for the `operator migrate` command. the cost of more resources (e.g. CPU, memory). Permitted values range from `1` (synchronous) to the maximum value for an `integer`. If not supplied, a default of `10` parallel goroutines will be used. - ~> Note: The maximum number of concurrent requests handled by a storage backend is ultimately governed by the + Note: The maximum number of concurrent requests handled by a storage backend is ultimately governed by the storage backend configuration setting, which enforces a maximum number of concurrent requests (`max_parallel`). diff --git a/website/content/docs/commands/operator/raft.mdx b/website/content/docs/commands/operator/raft.mdx index 81cbcf5401..360de27279 100644 --- a/website/content/docs/commands/operator/raft.mdx +++ b/website/content/docs/commands/operator/raft.mdx @@ -1,6 +1,5 @@ --- -layout: docs -page_title: operator raft - Command +sidebar_label: raft description: >- The "operator raft" command is used to interact with the integrated Raft storage backend. --- @@ -78,7 +77,11 @@ The following flags are available for the `operator raft join` command. - `-retry` `(bool: false)` - Continuously retry joining the Raft cluster upon failures. The default is false. -~> **Note:** Please be aware that the content (not the path to the file) of the certificate or key is expected for these parameters: `-leader-ca-cert`, `-leader-client-cert`, `-leader-client-key`. +:::note + +Please be aware that the content (not the path to the file) of the certificate or key is expected for these parameters: `-leader-ca-cert`, `-leader-client-cert`, `-leader-client-key`. + +::: ## list-peers @@ -137,9 +140,9 @@ Usage: bao operator raft remove-peer $ bao operator raft remove-peer node1 ``` - +:::note Once a node is removed, its Raft data needs to be deleted before it may be joined back into an existing cluster. This requires shutting down the OpenBao process, deleting the data, then restarting the OpenBao process on the removed node. - +::: ## snapshot @@ -171,7 +174,11 @@ Usage: bao operator raft snapshot save $ bao operator raft snapshot save raft.snap ``` -~> **Note:** Snapshot is not supported when Raft is used only for `ha_storage`. +:::note + +Snapshot is not supported when Raft is used only for `ha_storage`. + +::: ### snapshot restore @@ -191,7 +198,7 @@ This command groups subcommands for operators interacting with the autopilot functionality of the integrated Raft storage backend. There are 3 subcommands supported: `get-config`, `set-config` and `state`. -For a more detailed overview of autopilot features, see the [concepts page](/vault/docs/concepts/integrated-storage/autopilot). +For a more detailed overview of autopilot features, see the [concepts page](/docs/concepts/integrated-storage/autopilot). ```text Usage: bao operator raft autopilot [options] [args] @@ -293,7 +300,11 @@ Flags applicable to this command are the following: a server can go without leader contact before being considered failed. This takes effect only when `cleanup_dead_servers` is set as `true`. Defaults to `24h`. - -> **Note:** A failed server that autopilot has removed from the raft configuration cannot rejoin the cluster without being reinitialized. +:::note + +A failed server that autopilot has removed from the raft configuration cannot rejoin the cluster without being reinitialized. + +::: - `max-trailing-logs` `(int)` - Amount of entries in the Raft Log that a server can be behind before being considered unhealthy. Defaults to `1000`. diff --git a/website/content/docs/commands/operator/rekey.mdx b/website/content/docs/commands/operator/rekey.mdx index 36c7d4947f..a2e8c5dac8 100644 --- a/website/content/docs/commands/operator/rekey.mdx +++ b/website/content/docs/commands/operator/rekey.mdx @@ -1,6 +1,5 @@ --- -layout: docs -page_title: operator rekey - Command +sidebar_label: rekey description: |- The "operator rekey" command generates a new set of unseal keys. This can optionally change the total number of key shares or the required threshold of @@ -21,7 +20,7 @@ An unseal key may be provided directly on the command line as an argument to the command. If key is specified as "-", the command will read from stdin. If a TTY is available, the command will prompt for text. -Please see the [rotating and rekeying](/vault/tutorials/operations/rekeying-and-rotating) for +Please see the [rotating and rekeying](/tutorials/operations/rekeying-and-rotating) for step-by-step instructions. ## Examples @@ -106,7 +105,7 @@ $ bao operator rekey -verify -nonce="..." ## Usage The following flags are available in addition to the [standard set of -flags](/vault/docs/commands) included on all commands. +flags](/docs/commands) included on all commands. ### Output options @@ -143,7 +142,7 @@ flags](/vault/docs/commands) included on all commands. providing an unseal key. The default is false. - `-target` `(string: "barrier")` - Target for rekeying. "recovery" only applies - when HSM support is enabled or using [Auto Unseal](/vault/docs/concepts/seal#auto-unseal). + when HSM support is enabled or using [Auto Unseal](/docs/concepts/seal#auto-unseal). - `-verify` `(bool: false)` - Indicate during the phase `-init` that the verification process is activated for the rekey. Along with `-nonce` option diff --git a/website/content/docs/commands/operator/rotate.mdx b/website/content/docs/commands/operator/rotate.mdx index 1b5be0c345..55aab3bfe6 100644 --- a/website/content/docs/commands/operator/rotate.mdx +++ b/website/content/docs/commands/operator/rotate.mdx @@ -1,6 +1,5 @@ --- -layout: docs -page_title: operator rotate - Command +sidebar_label: rotate description: |- The "operator rotate" rotates the underlying encryption key which is used to secure data written to the storage backend. This installs a new key in the key @@ -32,7 +31,7 @@ Install Time 01 May 17 10:30 UTC ## Usage The following flags are available in addition to the [standard set of -flags](/vault/docs/commands) included on all commands. +flags](/docs/commands) included on all commands. ### Output options diff --git a/website/content/docs/commands/operator/seal.mdx b/website/content/docs/commands/operator/seal.mdx index 39af5c0c4b..70c64ad284 100644 --- a/website/content/docs/commands/operator/seal.mdx +++ b/website/content/docs/commands/operator/seal.mdx @@ -1,6 +1,5 @@ --- -layout: docs -page_title: operator seal - Command +sidebar_label: seal description: >- The "operator seal" command seals the OpenBao server. Sealing tells the OpenBao server to @@ -25,7 +24,7 @@ Users will have to re-enter their portions of the root key again. This command does nothing if the OpenBao server is already sealed. For more information on sealing and unsealing, please the [seal concepts -page](/vault/docs/concepts/seal). +page](/docs/concepts/seal). ## Examples @@ -38,5 +37,5 @@ Success! OpenBao is sealed. ## Usage -There are no flags beyond the [standard set of flags](/vault/docs/commands) +There are no flags beyond the [standard set of flags](/docs/commands) included on all commands. diff --git a/website/content/docs/commands/operator/step-down.mdx b/website/content/docs/commands/operator/step-down.mdx index 5102224c45..3e0cfe8b60 100644 --- a/website/content/docs/commands/operator/step-down.mdx +++ b/website/content/docs/commands/operator/step-down.mdx @@ -1,6 +1,5 @@ --- -layout: docs -page_title: operator step-down - Command +sidebar_label: step-down description: |- The "operator step-down" forces the OpenBao server at the given address to step down from active duty. @@ -8,7 +7,7 @@ description: |- # operator step-down -The `operator step-down` forces the active OpenBao node within an [HA cluster](/vault/docs/concepts/ha) +The `operator step-down` forces the active OpenBao node within an [HA cluster](/docs/concepts/ha) to step down from active duty. When executed against a standby node, the request will be forwarded to the active node. While the affected node will have a delay before attempting to acquire the leader lock again, if no other @@ -26,5 +25,5 @@ Success! Stepped down: http://127.0.0.1:8200 ## Usage -There are no flags beyond the [standard set of flags](/vault/docs/commands) +There are no flags beyond the [standard set of flags](/docs/commands) included on all commands. diff --git a/website/content/docs/commands/operator/unseal.mdx b/website/content/docs/commands/operator/unseal.mdx index f9b36565d4..989cc7b601 100644 --- a/website/content/docs/commands/operator/unseal.mdx +++ b/website/content/docs/commands/operator/unseal.mdx @@ -1,6 +1,5 @@ --- -layout: docs -page_title: operator unseal - Command +sidebar_label: unseal description: |- The "operator unseal" allows the user to provide a portion of the root key to unseal an OpenBao server. @@ -28,7 +27,7 @@ Key (will be hidden): IXyR0OJnSFobekZMMCKCoVEpT7wI6l+USMzE3IcyDyo= ``` For more information on sealing and unsealing, please the [seal concepts -page](/vault/docs/concepts/seal). +page](/docs/concepts/seal). ## Examples @@ -46,7 +45,7 @@ Unseal Progress: 0 ## Usage The following flags are available in addition to the [standard set of -flags](/vault/docs/commands) included on all commands. +flags](/docs/commands) included on all commands. ### Output options diff --git a/website/content/docs/commands/operator/usage.mdx b/website/content/docs/commands/operator/usage.mdx index 86194c44cd..b5ee282d13 100644 --- a/website/content/docs/commands/operator/usage.mdx +++ b/website/content/docs/commands/operator/usage.mdx @@ -1,6 +1,5 @@ --- -layout: docs -page_title: operator usage - Command +sidebar_label: usage description: |- "operator usage" produces a report on active clients. --- @@ -8,7 +7,7 @@ description: |- # operator usage The `operator usage` command allows an administrator to retrieve a -[client count](/vault/docs/concepts/client-count) report +[client count](/docs/concepts/client-count) report for the default reporting period, or for a specific time range of months. The command output will list clients by distinct entities, non-entity tokens, and total @@ -17,7 +16,7 @@ indicate that no data is available for the requested time range, which may be because the client count reporting is disabled, the time range is too far in the past, or no data has yet been collected since the feature was enabled. -> Refer to the [OpenBao Usage Metrics](/vault/tutorials/monitoring/usage-metrics) tutorial to learn more about usage metrics, +> Refer to the [OpenBao Usage Metrics](/tutorials/monitoring/usage-metrics) tutorial to learn more about usage metrics, > including required policy and data collection details. ## Examples @@ -53,7 +52,7 @@ Total 954 176 1130 ## Usage The following flags are available in addition to the [standard set of -flags](/vault/docs/commands) included on all commands. +flags](/docs/commands) included on all commands. ### Output options diff --git a/website/content/docs/commands/patch.mdx b/website/content/docs/commands/patch.mdx index 6126a48870..738f5935be 100644 --- a/website/content/docs/commands/patch.mdx +++ b/website/content/docs/commands/patch.mdx @@ -1,6 +1,4 @@ --- -layout: docs -page_title: patch - Command description: |- The "patch" command updates data in OpenBao at the given path. The data can be credentials, secrets, configuration, or arbitrary data. The specific behavior @@ -28,7 +26,7 @@ from stdin. This argument will be ignored if used in conjunction with any For a full list of examples and paths, please see the documentation that corresponds to the secrets engines in use. -Unlike [the `write` command](/vault/docs/commands/write), the `patch` command only +Unlike [the `write` command](/docs/commands/write), the `patch` command only modifies data specified on the command line. ## Examples @@ -68,7 +66,7 @@ The `bao patch` command simplifies the API call. ## Usage The following flags are available in addition to the [standard set of -flags](/vault/docs/commands) included on all commands. +flags](/docs/commands) included on all commands. ### Output options diff --git a/website/content/docs/commands/path-help.mdx b/website/content/docs/commands/path-help.mdx index 0e3d6ae8cf..716a794030 100644 --- a/website/content/docs/commands/path-help.mdx +++ b/website/content/docs/commands/path-help.mdx @@ -1,6 +1,4 @@ --- -layout: docs -page_title: path-help - Command description: |- The "path-help" command retrieves API help for paths. All endpoints in OpenBao provide built-in help in markdown format. This includes system paths, secret @@ -87,5 +85,5 @@ user of this backend. ## Usage -There are no flags beyond the [standard set of flags](/vault/docs/commands) +There are no flags beyond the [standard set of flags](/docs/commands) included on all commands. diff --git a/website/content/docs/commands/pki/health-check.mdx b/website/content/docs/commands/pki/health-check.mdx index f86a57d834..ff4068f640 100644 --- a/website/content/docs/commands/pki/health-check.mdx +++ b/website/content/docs/commands/pki/health-check.mdx @@ -1,6 +1,5 @@ --- -layout: docs -page_title: pki health-check - Command +sidebar_label: health-check description: |- The "pki health-check" command verifies the health of the given PKI secrets engine mount against an optional configuration. @@ -135,12 +134,12 @@ This health check will check each issuer in the mount for validity status, retur **Remediation steps**: -1. Perform a [CA rotation operation](/vault/docs/secrets/pki/rotation-primitives) +1. Perform a [CA rotation operation](/docs/secrets/pki/rotation-primitives) to check for CAs that are about to expire. 1. Migrate from expiring CAs to new CAs. 1. Delete any expired CAs with one of the following options: - - Run [tidy](/vault/api-docs/secret/pki#tidy) manually with `bao write /tidy tidy_expired_issuers=true`. - - Use the OpenBao API to call [delete issuer](/vault/api-docs/secret/pki#delete-issuer). + - Run [tidy](/api-docs/secret/pki#tidy) manually with `bao write /tidy tidy_expired_issuers=true`. + - Use the OpenBao API to call [delete issuer](/api-docs/secret/pki#delete-issuer). ### CRL validity period @@ -260,19 +259,20 @@ other (potentially dangerous) quirks. Checks each role to see whether `no_store` is set to `false`. - +:::warning + OpenBao will provide warnings and performance will suffer if you have a large number of certificates without temporal CRL auto-rebuilding and set `no_store` to `true`. - +::: **Remediation steps**: 1. Update none-ACME roles with `no_store=false`. **NOTE**: Roles used for ACME issuance must have `no_store` set to `true`. 1. Set your certificate lifetimes as short as possible. -1. Use [BYOC revocations](/vault/api-docs/secret/pki#revoke-certificate) to +1. Use [BYOC revocations](/api-docs/secret/pki#revoke-certificate) to revoke certificates as needed. ### Accessibility of audit information @@ -483,7 +483,7 @@ This health check verifies that this cluster has a reasonable number of certific lifetimes should reflect the expected usage of the certificate. If the TTL is set appropriately, most certificates renew at approximately 2/3 of their lifespan. -1. Consider setting the `no_store` field for all roles to `true` and use [BYOC revocations](/vault/api-docs/secret/pki#revoke-certificate) to avoid storage. +1. Consider setting the `no_store` field for all roles to `true` and use [BYOC revocations](/api-docs/secret/pki#revoke-certificate) to avoid storage. ### Enable ACME issuance @@ -500,7 +500,7 @@ This health check verifies that this cluster has a reasonable number of certific This health check verifies that ACME is enabled within a mount that contains an intermediary issuer, as this is considered a best-practice to support a self-rotating PKI infrastructure. -Review the [ACME Certificate Issuance](/vault/api-docs/secret/pki#acme-certificate-issuance) +Review the [ACME Certificate Issuance](/api-docs/secret/pki#acme-certificate-issuance) API documentation to learn about enabling ACME support in OpenBao. ### ACME response headers diff --git a/website/content/docs/commands/pki/index.mdx b/website/content/docs/commands/pki/index.mdx index 50d440278e..d046d834f4 100644 --- a/website/content/docs/commands/pki/index.mdx +++ b/website/content/docs/commands/pki/index.mdx @@ -1,6 +1,5 @@ --- -layout: docs -page_title: pki - Command +sidebar_label: Overview description: |- The "pki" command groups subcommands for interacting with OpenBao's PKI secrets engine. @@ -9,7 +8,7 @@ description: |- # pki The `pki` command groups subcommands for interacting with OpenBao's -[PKI Secrets Engine](/vault/docs/secrets/pki). +[PKI Secrets Engine](/docs/secrets/pki). ## Syntax @@ -17,7 +16,7 @@ Option flags for a given subcommand are provided after the subcommand, but befor ## Example health check -To [health check](/vault/docs/commands/pki/health-check) a mount, use the +To [health check](/docs/commands/pki/health-check) a mount, use the `bao pki health-check ` command: ``` @@ -33,7 +32,7 @@ ok /pki/issuer/da41ffb1-cc6d-5a5c-f147-e4d7beeb1b73 Issuer's validity ## Example verify sign -To [verify](/vault/docs/commands/pki/verify-sign) the signature between two +To [verify](/docs/commands/pki/verify-sign) the signature between two issuer certificates, use the `bao pki verify-sign ` command: ```shell-session @@ -52,7 +51,7 @@ signature_match true ## Example list child issuers -To [list intermediate](/vault/docs/commands/pki/list-intermediates) certificates +To [list intermediate](/docs/commands/pki/list-intermediates) certificates potentially issued by a certificate inside OpenBao, use the `bao pki list-intermediates ` command: @@ -69,7 +68,7 @@ pki_int/issuer/b8cc0b41-e0e9-1a92-12c4-6849c9d6f837 true ## Example issue -To [issue](/vault/docs/commands/pki/issue) a new issuer certificate, use the +To [issue](/docs/commands/pki/issue) a new issuer certificate, use the `bao pki issue ` command: ```shell-session @@ -82,7 +81,7 @@ MIIDsDCCApigAwIBAgIULEPuHTW7UDtAQg+qcc18osNWgZIwDQYJKoZIhvcNAQEL... ## Example reissue -To [reissue](/vault/docs/commands/pki/reissue) an issuer certificate, using the +To [reissue](/docs/commands/pki/reissue) an issuer certificate, using the same fields as an existing issuer template, use the `bao pki reissue