Add additional documentation to Secrets Rotator (#6095)

* Fix copy-paste errors in KeyVaultSecretStore text * Add documentation for supported stores
Azure · May 8, 2023 · cbf3b5e · cbf3b5e
1 parent ec3435f
commit cbf3b5e
Show file tree

Hide file tree

Showing 10 changed files with 170 additions and 3 deletions.
diff --git a/...s/secret-management/Azure.Sdk.Tools.SecretRotation.Stores.KeyVault/KeyVaultSecretStore.cs b/...s/secret-management/Azure.Sdk.Tools.SecretRotation.Stores.KeyVault/KeyVaultSecretStore.cs
@@ -264,7 +264,7 @@ public override async Task MarkRotationCompleteAsync(SecretValue secretValue, Da
         if (whatIf)
         {
             this.logger.LogInformation(
-                "WHAT IF: Add tag 'rotation-complete' to secret '{CertificateName}' in vault '{Vault}'",
+                "WHAT IF: Add tag 'rotation-complete' to secret '{SecretName}' in vault '{Vault}'",
                 this.secretName, this.vaultUri);
             return;
         }
@@ -275,7 +275,7 @@ public override async Task MarkRotationCompleteAsync(SecretValue secretValue, Da
                 "The PrimaryState value passed to KeyVaultSecretStore was not of type KeyVaultSecret");
         }
 
-        this.logger.LogInformation("Adding tag 'rotation-complete' to certificate '{CertificateName}' in vault '{Vault}'",
+        this.logger.LogInformation("Adding tag 'rotation-complete' to secret '{SecretName}' in vault '{Vault}'",
             this.secretName, this.vaultUri);
 
         secret.Properties.Tags.Add("rotation-complete", "true");

diff --git a/tools/secret-management/README.md b/tools/secret-management/README.md
@@ -1,3 +1,5 @@
+Additional documentation can be found in the [docs folder](docs/).
+
 # Secret Management
 
 The secret management tool provides configuration driven orchestration of:
@@ -18,4 +20,15 @@ If the tool's installed globally, it's invoked like:
 secrets --help
 ```
 
-Additional documentation can be found in the [docs folder](docs/).
+# Implemented Stores
+
+| Configuration Key                | Links                                                            |
+| -------------------------------- | ---------------------------------------------------------------- |
+| AAD Application Secret           | [documentation](docs/stores/aad-application-secret.md)           |
+| ADO Service Connection Parameter | [documentation](docs/stores/ado-service-connection-parameter.md) |
+| Azure Website                    | [documentation](docs/stores/azure-website.md)                    |
+| Key Vault Certificate            | [documentation](docs/stores/keyvault-certificate.md)             |
+| Key Vault Secret                 | [documentation](docs/stores/keyvault-secret.md)                  |
+| Manual Action                    | [documentation](docs/stores/manual-action.md)                    |
+| Random String                    | [documentation](docs/stores/random-string.md)                    |
+| Service Account ADO PAT          | [documentation](docs/stores/service-account-ado-pat.md)          |
diff --git a/tools/secret-management/docs/stores/aad-application-secret.md b/tools/secret-management/docs/stores/aad-application-secret.md
@@ -0,0 +1,18 @@
+# AAD Application Secret
+
+## Implementing Class
+[AadApplicationSecretStore](../../Azure.Sdk.Tools.SecretRotation.Stores.AzureActiveDirectory/AadApplicationSecretStore.cs)
+
+## Configuration Key
+AAD Application Secret
+
+## Supported Functions
+Origin
+
+## Parameters
+
+| Name             | Type   | Description                                                              |
+| ---------------- | ------ | ------------------------------------------------------------------------ |
+| applicationId    | string | The ID of the AAD Application Registration on which to create the secret |
+| displayName      | string | The name of the application secret to create                             |
+| revocationAction | string | optional, one of ( `delete`, `none` ). defaults to none                  |
diff --git a/tools/secret-management/docs/stores/ado-service-connection-parameter.md b/tools/secret-management/docs/stores/ado-service-connection-parameter.md
@@ -0,0 +1,22 @@
+# ADO Service Connection Parameter
+
+## Implementing Class
+[ServiceConnectionParameterStore](../../Azure.Sdk.Tools.SecretRotation.Stores.AzureDevOps/ServiceConnectionParameterStore.cs)
+
+## Configuration Key
+ADO Service Connection Parameter
+
+## Supported Functions
+Secondary
+
+## Parameters
+
+| Name          | Type   | Description                                                                                                                                                           |
+| ------------- | ------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| accountName   | string | The name of the Azure DevOps organization. e.g.  For `https://dev.azure.com/azure-sdk`, use `azure-sdk`                                                               |
+| projectName   | string | The name of the Azure DevOps project that contains the service connection                                                                                             |
+| connectionId  | string | The GUID of the service connection to configure                                                                                                                       |
+| parameterName | string | The name of the parameter on the service connection.|
+
+## Notes
+The `parameterName` string is internal to the Azure DevOps connection provider and isn't visible in the UI. You may need to inspect a POST request in the ADO UI to get the correct parameter name.
diff --git a/tools/secret-management/docs/stores/azure-website.md b/tools/secret-management/docs/stores/azure-website.md
@@ -0,0 +1,19 @@
+# Azure Website
+
+## Implementing Class
+[AzureWebsiteStore](../../Azure.Sdk.Tools.SecretRotation.Stores.AzureAppService/AzureWebsiteStore.cs)
+
+## Configuration Key
+Azure Website
+
+## Supported Functions
+Secondary
+
+## Parameters
+
+| Name           | Type   | Description                                                     |
+| -------------- | ------ | --------------------------------------------------------------- |
+| subscriptionId | string | The website's Azure subscription id                             |
+| resourceGroup  | string | The website's resource group name                               |
+| website        | string | The website's resource name                                     |
+| rotationAction | string | optional, one of ( `restartWebsite`, `none` ). defaults to none |
diff --git a/tools/secret-management/docs/stores/keyvault-certificate.md b/tools/secret-management/docs/stores/keyvault-certificate.md
@@ -0,0 +1,16 @@
+# Key Vault Certificate
+
+## Implementing Class
+[KeyVaultCertificateStore](../../Azure.Sdk.Tools.SecretRotation.Stores.KeyVault/KeyVaultCertificateStore.cs)
+
+## Configuration Key
+Key Vault Certificate
+
+## Supported Functions
+Origin
+
+## Parameters
+
+| Name           | Type | Description                                                                                                |
+| -------------- | ---- | ---------------------------------------------------------------------------------------------------------- |
+| certificateUri | uri  | uri of the certificate in the form of `https://{VaultName}.vault.azure.net/certificates/{CertificateName}` |
diff --git a/tools/secret-management/docs/stores/keyvault-secret.md b/tools/secret-management/docs/stores/keyvault-secret.md
@@ -0,0 +1,18 @@
+# Key Vault Secret
+
+## Implementing Class
+[KeyVaultSecretStore](../../Azure.Sdk.Tools.SecretRotation.Stores.KeyVault/KeyVaultSecretStore.cs)
+
+## Configuration Key
+Key Vault Secret
+
+## Supported Functions
+Primary, Secondary
+
+## Parameters
+
+| Name             | Type   | Description                                                                                           |
+| ---------------- | ------ | ----------------------------------------------------------------------------------------------------- |
+| secretUri        | uri    | uri of the secret in the form of `https://{VaultName}.vault.azure.net/secrets/{SecretName}` |
+| revocationAction | string | one of ( `disableVersion`, `none` )                                                                   |
+| contentType      | string | The content type string that should be recorded on new secret versions                                |
diff --git a/tools/secret-management/docs/stores/manual-action.md b/tools/secret-management/docs/stores/manual-action.md
@@ -0,0 +1,16 @@
+# Manual Action
+
+## Implementing Class
+[ManualActionStore](../../Azure.Sdk.Tools.SecretRotation.Stores.Generic/ManualActionStore.cs)
+
+## Configuration Key
+Manual Action
+
+## Supported Functions
+Origin, Secondary
+
+## Parameters
+
+| Name   | Type   | Description                                     |
+| ------ | ------ | ----------------------------------------------- |
+| prompt | string | the prompt that should be presented to the user |
diff --git a/tools/secret-management/docs/stores/random-string.md b/tools/secret-management/docs/stores/random-string.md
@@ -0,0 +1,23 @@
+# Random String
+
+## Implementing Class
+[RandomStringGenerator](../../Azure.Sdk.Tools.SecretRotation.Stores.Generic/RandomStringGenerator.cs)
+
+## Configuration Key
+Random String
+
+## Supported Functions
+Origin
+
+## Parameters
+
+| Name                 | Type    | Description                                                             |
+| -------------------- | ------- | ----------------------------------------------------------------------- |
+| length               | integer | The length of the string to create                                      |
+| useLowercase         | bool    | optional, should lowercase letters appear in the string `[a-z]`         |
+| useUppercase         | bool    | optional, should uppercase letters appear in the string `[A-Z]`         |
+| useNumbers           | bool    | optional, should numbers appear in the string `[0-9]`                   |
+| useSpecialCharacters | bool    | optional, should special characters appear in the string `[!@#$%^&*()]` |
+
+## Notes
+At least one character class must be used. The resulting string will include at least one character from each of the character classes used.
diff --git a/tools/secret-management/docs/stores/service-account-ado-pat.md b/tools/secret-management/docs/stores/service-account-ado-pat.md
@@ -0,0 +1,22 @@
+# Service Account ADO PAT
+
+## Implementing Class
+[ServiceAccountPersonalAccessTokenStore](../../Azure.Sdk.Tools.SecretRotation.Stores.AzureDevOps/ServiceAccountPersonalAccessTokenStore.cs)
+
+## Configuration Key
+Service Account ADO PAT
+
+## Supported Functions
+Origin
+
+## Parameters
+
+| Name           | Type | Description                                                                                                |
+| -------------- | ---- | ---------------------------------------------------------------------------------------------------------- |
+| organization   | string | The name of the Azure DevOps organization. e.g.  For `https://dev.azure.com/azure-sdk`, use `azure-sdk`                                                               |
+| patDisplayName   | string | The name to give the new personal access token |
+| scopes | string | a comma separated list of scopes to grant the token |
+| serviceAccountName | string | the username of the service account |
+| serviceAccountPasswordSecret | string | the uri of a Key Vault secret containing the password the the service account |
+| serviceAccountTenantId | string | the AAD tenant of the service account |
+| revocationAction | string | optional, one of `(revoke, none)` |