diff --git a/website/content/api-docs/system/config-ui-login-default-auth.mdx b/website/content/api-docs/system/config-ui-login-default-auth.mdx new file mode 100644 index 0000000000..a1d9ca9057 --- /dev/null +++ b/website/content/api-docs/system/config-ui-login-default-auth.mdx @@ -0,0 +1,211 @@ +--- +layout: api +page_title: /sys/config/ui/login/default-auth - HTTP API +description: The '/sys/config/ui/login/default-auth' endpoint configures default authentication types that will display on a UI page per namespace. +--- + +# `/sys/config/ui/login/default-auth` + +@include 'alerts/enterprise-only.mdx' + +@include 'alerts/restricted-admin.mdx' + +Use the `/sys/config/ui/login/default-auth` endpoint to list, create, read, +update, or delete login configurations for the Vault GUI. + +Login configurations customize the Vault GUI login form by restricting the +list of authentication methods listed on the login form. + +## Create GUI default login configuration + +Use the default configuration endpoint to create a default authentication method for +the Vault GUI. You can only set one login configuration per namespace, but +namespaces can inherit configurations from the parent namespace with +inheritance enabled. + +| Method | Path | +| :----- | :-------------------------------- | +| `POST` | `/sys/config/ui/login/default-auth/:name` | + +### Parameters + +- `name` `(string: )` - Path parameter indicating the name of the + configuration. Names can contain letters, numbers, underscores, and dashes. + +- `namespace_path` `(string: "")` - Target namespace for the login configuration. + Leave `namespace_path` unset to apply the configuration to the `root` namespace. + +- `default_auth_type` `(string: )` - The default authentication method. + You must provide a default method if `backup_auth_types` is unset. Supported + authentication methods include: `github`, `jwt`, `ldap`, `oidc`, `okta`, + `radius`, `saml`, `token`, and `userpass`. + +- `backup_auth_types` `(array: [])` - A list of backup auth types. Vault + presents the backup methods in the `Sign in with other methods` tab. You must + provide at least one backup method if `default_auth_types` is unset. Supported + authentication methods include: `github`, `jwt`, `ldap`, `oidc`, `okta`, + `radius`, `saml`, `token`, and `userpass`. + +- `disable_inheritance` `(bool: false)` - Indicates whether child namespaces + should inherit `default_auth_type` and `backup_auth_types` settings from their + parent. Setting `disable_inheritance` to `true` disallows inheritence. + +### Sample payload + +```json +{ + "namespace_path": "it_admins", + "default_auth_type": "okta", + "backup_auth_types": ["userpass", "token"], + "disable_inheritance": "true" +} +``` + +### Sample request + +```shell-session +$ curl --header "X-Vault-Token: ..." \ + --request POST \ + --data @payload.json + http://127.0.0.1:8200/v1/sys/config/ui/login/default-auth/it-admin-rule +``` + +## List GUI default login configurations + +Return a list of all default configurations for the Vault GUI. + +| Method | Path | +| :----- | :-------------------------------- | +| `LIST` | `/sys/config/ui/login/default-auth` | + +### Sample request + +```shell-session +$ curl --header "X-Vault-Token: ..." \ + --request LIST \ + http://127.0.0.1:8200/v1/sys/config/ui/login/default-auth +``` + +### Sample response + +```json +{ + "data": { + "key_info": { + "default-ldap": { + "name":"default-ldap", + "namespace_path":"root", + "disable_inheritance":false + } + }, + "keys":["default-ldap"] + } +} +``` + + + +## Read GUI default auth configuration + +Returns the properties of a specific default authentication configuration. + +| Method | | +| :----- | :----------------------------------- | +| `GET` | `/sys/config/ui/login/default-auth/:name` | + +### Parameters + +- `name` `(string: )` - Path parameter indicating the name of login + configuration to fetch. + +### Sample request + +```shell-session +$ curl --header "X-Vault-Token: ..." \ + http://127.0.0.1:8200/v1/sys/config/ui/login/default-auth/it-admin-rule +``` + +### Sample response + +```json +{ + "data": { + "backup_auth_types":["token","userpass"], + "default_auth_type":"okta", + "disable_inheritance":false, + "namespace_path":"it_admins" + } +} +``` + +## Update GUI default auth configuration + +Update the properties of a specific GUI default auth configuration. + +| Method | | +| :----- | :----------------------------------- | +| `POST` | `/sys/config/ui/login/default-auth/:name` | + +### Parameters + +- `name` `(string: )` - Path parameter indicating the name of the + configuration. Names can contain letters, numbers, underscores, and dashes. + +- `namespace_path` `(string: "")` - Target namespace for the login configuration. + Leave `namespace_path` unset to update configurations under the `root` + namespace. + +- `default_auth_type` `(string: )` - The default authentication method. + You must provide a default method if `backup_auth_types` is unset. Supported + authentication methods include: `github`, `jwt`, `ldap`, `oidc`, `okta`, + `radius`, `saml`, `token`, and `userpass`. + +- `backup_auth_types` `(array: [])` - A list of backup auth types. Vault + presents the backup methods in the `Sign in with other methods` tab. You must + provide at least one backup method if `default_auth_types` is unset. Supported + authentication methods include: `github`, `jwt`, `ldap`, `oidc`, `okta`, + `radius`, `saml`, `token`, and `userpass`. + +- `disable_inheritance` `(bool: false)` - Indicates whether child namespaces + should inherit `default_auth_type` and `backup_auth_types` settings from their + parent. Setting `disable_inheritance` to `true` disallows inheritence. + +### Sample payload + +```json +{ + "namespace_path": "it_admins", + "default_auth_type": "ldap", + "backup_auth_types": ["userpass", "github"], + "disable_inheritance": "true" +} +``` + +### Sample request + +```shell-session +$ curl --header "X-Vault-Token: ..." \ + --request POST \ + --data @payload.json + http://127.0.0.1:8200/v1/sys/config/ui/login/default-auth/it-admin-rule +``` + +## Delete GUI default auth configuration + +Delete the target GUI auth configuration. + +| Method | | +| :------- | :----------------------------------- | +| `DELETE` | `/sys/config/ui/login/default-auth/:name` | + +### Parameters + +- `name` `(string: )` - Path parameter indicating the name of the + configuration. Names can contain letters, numbers, underscores, and dashes. + +### Sample request + +```shell-session +$ curl --header "X-Vault-Token: ..." \ + http://127.0.0.1:8200/v1/sys/config/ui/login/default-auth/it-admin-rule +``` diff --git a/website/content/api-docs/system/internal-ui-default-auth-methods.mdx b/website/content/api-docs/system/internal-ui-default-auth-methods.mdx new file mode 100644 index 0000000000..87d6a02cf9 --- /dev/null +++ b/website/content/api-docs/system/internal-ui-default-auth-methods.mdx @@ -0,0 +1,54 @@ +--- +layout: api +page_title: /sys/internal/ui/default-auth-methods - HTTP API +description: The '/sys/internal/ui/default-auth-methods' endpoint returns any configured or inherited default and backup auth methods for a given namespace. +--- + +# `/sys/internal/ui/default-auth-methods` + +@include 'alerts/enterprise-only.mdx' + +`/sys/internal/ui/default-auth-methods` is a Vault-internal endpoint used to +return the explicit, or inherited, default and backup auth method types for a +given namespace. + +The namespace is derived from the request itself in the `X-Vault-Namespace` header. + +This should only be used internally by the UI. Due to the nature of its +intended usage, there is no guarantee on backwards compatibility for this endpoint. + +## Get UI default login configuration + +@include 'alerts/unrestricted.mdx' + +Return any configured, or inherited, default and backup authentication methods +for a given namespace. + + +| Method | Path | +| :----- | :------------------------------------------ | +| `GET` | `/sys/internal/ui/default-auth-methods` | + +### Sample request + +```shell-session +$ curl + -- header "X-Vault-Namespace: it-admins" \ + --request LIST \ + http://127.0.0.1:8200/v1/sys/internal/ui/default-auth-methods +``` + +### Sample response + +```json +{ + "data": { + "backup_auth_types": [ + "token", + "userpass" + ], + "default_auth_type": "ldap", + "disable_inheritance": false + }, +} +``` diff --git a/website/data/api-docs-nav-data.json b/website/data/api-docs-nav-data.json index 5fa3b51fcc..3fb4dca26b 100644 --- a/website/data/api-docs-nav-data.json +++ b/website/data/api-docs-nav-data.json @@ -474,6 +474,15 @@ "title": "/sys/config/ui/headers", "path": "system/config-ui-headers" }, + { + "title": "/sys/config/ui/login/default-auth", + "path": "system/config-ui-login-default-auth", + "badge": { + "text": "ENT", + "type": "outlined", + "color": "neutral" + } + }, { "title": "/sys/control-group", "path": "system/control-group" @@ -535,6 +544,15 @@ "title": "/sys/internal/ui/authenticated-messages", "path": "system/internal-ui-authenticated-messages" }, + { + "title": "/sys/internal/ui/default-auth-methods", + "path": "system/internal-ui-default-auth-methods", + "badge": { + "text": "ENT", + "type": "outlined", + "color": "neutral" + } + }, { "title": "/sys/internal/ui/feature-flags", "path": "system/internal-ui-feature"