plugins/ad: Add rotate-role endpoint (hashicorp#11942)

* plugins/ad: add rotate-role

* Add doc

* changelog

* Add note about rotate-role in overview

changelog/11942.txt

@@ -0,0 +1,3 @@
+```release-note:improvement
+plugins/ad: Added rotate-role endpoint for manual service account password rotations
+```

go.mod

@@ -95,7 +95,7 @@ require (
 	github.com/hashicorp/vault-plugin-database-mongodbatlas v0.3.0
 	github.com/hashicorp/vault-plugin-database-snowflake v0.1.1
 	github.com/hashicorp/vault-plugin-mock v0.16.1
-	github.com/hashicorp/vault-plugin-secrets-ad v0.9.1
+	github.com/hashicorp/vault-plugin-secrets-ad v0.10.0
 	github.com/hashicorp/vault-plugin-secrets-alicloud v0.8.0
 	github.com/hashicorp/vault-plugin-secrets-azure v0.9.1
 	github.com/hashicorp/vault-plugin-secrets-gcp v0.9.0

go.sum

@@ -711,8 +711,8 @@ github.com/hashicorp/vault-plugin-database-snowflake v0.1.1 h1:QKNjvd1GuI69u7ZLN
 github.com/hashicorp/vault-plugin-database-snowflake v0.1.1/go.mod h1:gUfFbYrFFxITKxeLJe2IHPnNkmSG5ldVF1OOxp1WW3c=
 github.com/hashicorp/vault-plugin-mock v0.16.1 h1:5QQvSUHxDjEEbrd2REOeacqyJnCLPD51IQzy71hx8P0=
 github.com/hashicorp/vault-plugin-mock v0.16.1/go.mod h1:83G4JKlOwUtxVourn5euQfze3ZWyXcUiLj2wqrKSDIM=
-github.com/hashicorp/vault-plugin-secrets-ad v0.9.1 h1:MRhMMWxome1VOIKbYF+Iw76wjLrfKqu196Z2CLE8viw=
-github.com/hashicorp/vault-plugin-secrets-ad v0.9.1/go.mod h1:L5L6NoJFxRvgxhuA2sWhloc3sbgmE7KxhNcoRxcaH9U=
+github.com/hashicorp/vault-plugin-secrets-ad v0.10.0 h1:iMS1SfIQtPfvPbw24W8HbNBb6o6wqSRjJwxNcZWEiw0=
+github.com/hashicorp/vault-plugin-secrets-ad v0.10.0/go.mod h1:4AN/0ynq1Krn7LhwzoP/roj9JRdxiuptPpktq7ftLjo=
 github.com/hashicorp/vault-plugin-secrets-alicloud v0.8.0 h1:dg1vrZl+XwGipfjet7M9UqGM8nCDx4FNnN7zlqiHQWU=
 github.com/hashicorp/vault-plugin-secrets-alicloud v0.8.0/go.mod h1:SSkKpSTOMnX84PfgYiWHgwVg+YMhxHNjo+YCJGNBoZk=
 github.com/hashicorp/vault-plugin-secrets-azure v0.9.1 h1:vZhWEafEedxLS7t906QSYFKT+jiNM6Mv6fDHxOX6O5I=
@@ -901,6 +901,7 @@ github.com/mitchellh/iochan v1.0.0 h1:C+X3KsSTLFVBr/tK1eYN/vs4rJcvsiLU338UhYPJWe
 github.com/mitchellh/iochan v1.0.0/go.mod h1:JwYml1nuB7xOzsp52dPpHFffvOCDupsG0QubkSMEySY=
 github.com/mitchellh/mapstructure v0.0.0-20160808181253-ca63d7c062ee/go.mod h1:FVVH3fgwuzCH5S8UJGiWEs2h04kUh9fWfEaFds41c1Y=
 github.com/mitchellh/mapstructure v1.1.2/go.mod h1:FVVH3fgwuzCH5S8UJGiWEs2h04kUh9fWfEaFds41c1Y=
+github.com/mitchellh/mapstructure v1.2.2/go.mod h1:bFUtVrKA4DC2yAKiSyO/QUcy7e+RRV2QTWOzhPopBRo=
 github.com/mitchellh/mapstructure v1.3.2/go.mod h1:bFUtVrKA4DC2yAKiSyO/QUcy7e+RRV2QTWOzhPopBRo=
 github.com/mitchellh/mapstructure v1.3.3 h1:SzB1nHZ2Xi+17FP0zVQBHIZqvwRN9408fJO8h+eeNA8=
 github.com/mitchellh/mapstructure v1.3.3/go.mod h1:bFUtVrKA4DC2yAKiSyO/QUcy7e+RRV2QTWOzhPopBRo=

website/content/api-docs/secret/ad.mdx

@@ -499,3 +499,24 @@ $ curl \
     --request POST \
     http://127.0.0.1:8200/v1/ad/rotate-root
 ```
+
+## Rotate Role Credentials
+
+Manually rotate the password of a managed Active Directory service account.
+
+### Endpoints
+
+| Method | Path                         |                                        |
+| :----- | :--------------------------- | -------------------------------------- |
+| `POST` | `/ad/rotate-role/:role_name` | `204 (empty body) or 200 with warning` |
+
+Generally, `rotate-role` returns a 204. However, if `rotate-role` is already in progress, it may return a 200 with a warning that credential rotation is already in progress.
+
+### Sample Post Request
+
+```shell-session
+$ curl \
+    --header "X-Vault-Token: ..." \
+    --request POST \
+    http://127.0.0.1:8200/v1/ad/rotate-role/my-application
+```

website/content/docs/secrets/ad.mdx

@@ -16,7 +16,8 @@ a shared password simultaneously. With a simple set up and a simple creds API,
 it doesn't require instances to be manually registered in advance to gain access.
 As long as access has been granted to the creds path via a method like
 [AppRole](/api/auth/approle), they're available. Passwords are
-lazily rotated based on preset TTLs and can have a length configured to meet your needs.
+lazily rotated based on preset TTLs and can have a length configured to meet your needs. Additionally,
+passwords can be manually rotated using the [rotate-role](/api-docs/secret/ad#rotate-role-credentials) endpoint.
 
 The second feature (service account check-out) is where a library of service accounts can
 be checked out by a person or by machines. Vault will automatically rotate the password