From cbf3b5e2138fadf537bf77346723194066167030 Mon Sep 17 00:00:00 2001 From: Patrick Hallisey Date: Mon, 8 May 2023 11:43:32 -0700 Subject: [PATCH] Add additional documentation to Secrets Rotator (#6095) * Fix copy-paste errors in KeyVaultSecretStore text * Add documentation for supported stores --- .../KeyVaultSecretStore.cs | 4 ++-- tools/secret-management/README.md | 15 +++++++++++- .../docs/stores/aad-application-secret.md | 18 +++++++++++++++ .../ado-service-connection-parameter.md | 22 ++++++++++++++++++ .../docs/stores/azure-website.md | 19 +++++++++++++++ .../docs/stores/keyvault-certificate.md | 16 +++++++++++++ .../docs/stores/keyvault-secret.md | 18 +++++++++++++++ .../docs/stores/manual-action.md | 16 +++++++++++++ .../docs/stores/random-string.md | 23 +++++++++++++++++++ .../docs/stores/service-account-ado-pat.md | 22 ++++++++++++++++++ 10 files changed, 170 insertions(+), 3 deletions(-) create mode 100644 tools/secret-management/docs/stores/aad-application-secret.md create mode 100644 tools/secret-management/docs/stores/ado-service-connection-parameter.md create mode 100644 tools/secret-management/docs/stores/azure-website.md create mode 100644 tools/secret-management/docs/stores/keyvault-certificate.md create mode 100644 tools/secret-management/docs/stores/keyvault-secret.md create mode 100644 tools/secret-management/docs/stores/manual-action.md create mode 100644 tools/secret-management/docs/stores/random-string.md create mode 100644 tools/secret-management/docs/stores/service-account-ado-pat.md diff --git a/tools/secret-management/Azure.Sdk.Tools.SecretRotation.Stores.KeyVault/KeyVaultSecretStore.cs b/tools/secret-management/Azure.Sdk.Tools.SecretRotation.Stores.KeyVault/KeyVaultSecretStore.cs index 8cf29fae354..ac07be278e4 100644 --- a/tools/secret-management/Azure.Sdk.Tools.SecretRotation.Stores.KeyVault/KeyVaultSecretStore.cs +++ b/tools/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 index ad553871300..7d1aea859b8 100644 --- 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 new file mode 100644 index 00000000000..3f7194c3686 --- /dev/null +++ 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 new file mode 100644 index 00000000000..d2d1061097b --- /dev/null +++ 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 new file mode 100644 index 00000000000..be53ea524f2 --- /dev/null +++ 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 new file mode 100644 index 00000000000..5750ccda78b --- /dev/null +++ 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 new file mode 100644 index 00000000000..fe816581925 --- /dev/null +++ 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 new file mode 100644 index 00000000000..e8f5718e3c6 --- /dev/null +++ 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 | \ No newline at end of file diff --git a/tools/secret-management/docs/stores/random-string.md b/tools/secret-management/docs/stores/random-string.md new file mode 100644 index 00000000000..34015fff655 --- /dev/null +++ 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. \ No newline at end of file diff --git a/tools/secret-management/docs/stores/service-account-ado-pat.md b/tools/secret-management/docs/stores/service-account-ado-pat.md new file mode 100644 index 00000000000..c27a382ad26 --- /dev/null +++ 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)` |