[keyvault] azadmin module (Azure#20296)

Author: gracewilcox

eng/config.json

@@ -84,6 +84,10 @@
         {
             "Name": "resourcemanager",
             "CoverageGoal": 0.0
+        },
+        {
+            "Name": "security/keyvault/azadmin",
+            "CoverageGoal": 0.80
         }
     ]
 }

sdk/security/keyvault/azadmin/CHANGELOG.md

@@ -0,0 +1,2 @@
+## 0.1.0 (2023-03-13)
+* This is the initial release of the `azadmin` library

sdk/security/keyvault/azadmin/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) Microsoft Corporation. All rights reserved.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE

sdk/security/keyvault/azadmin/README.md

@@ -0,0 +1,148 @@
+# Azure KeyVault Administration client module for Go
+
+>**Note:** The Administration module only works with [Managed HSM][managed_hsm] – functions targeting a Key Vault will fail.
+
+* Vault administration (this module) - role-based access control (RBAC), settings, and vault-level backup and restore options
+* Certificate management ([azcertificates](https://aka.ms/azsdk/go/keyvault-certificates/docs)) - create, manage, and deploy public and private SSL/TLS certificates
+* Cryptographic key management ([azkeys](https://pkg.go.dev/github.com/Azure/azure-sdk-for-go/sdk/keyvault/azkeys)) - create, store, and control access to the keys used to encrypt your data
+* Secrets management ([azsecrets](https://aka.ms/azsdk/go/keyvault-secrets/docs)) - securely store and control access to tokens, passwords, certificates, API keys, and other secrets
+
+Azure Key Vault Managed HSM is a fully-managed, highly-available, single-tenant, standards-compliant cloud service that enables you to safeguard
+cryptographic keys for your cloud applications using FIPS 140-2 Level 3 validated HSMs.
+
+The Azure Key Vault administration library clients support administrative tasks such as full backup / restore, key-level role-based access control (RBAC), and settings management.
+
+Source code | Package (pkg.go.dev)| [Product documentation][managed_hsm_docs] | Samples
+
+## Getting started
+
+### Install the package
+
+Install `azadmin` and `azidentity` with `go get`:
+```
+go get github.com/Azure/azure-sdk-for-go/sdk/security/keyvault/azadmin
+go get github.com/Azure/azure-sdk-for-go/sdk/azidentity
+```
+[azidentity][azure_identity] is used for Azure Active Directory authentication during client contruction.
+
+
+### Prerequisites
+
+* An [Azure subscription][azure_sub].
+* A supported Go version (the Azure SDK supports the two most recent Go releases)
+* An existing [Key Vault Managed HSM][managed_hsm]. If you need to create one, you can do so using the Azure CLI by following the steps in [this document][create_managed_hsm].
+
+### Authentication
+
+This document demonstrates using [azidentity.NewDefaultAzureCredential][default_cred_ref] to authenticate. This credential type works in both local development and production environments. We recommend using a [managed identity][managed_identity] in production.
+
+The clients accept any [azidentity][azure_identity] credential. See the [azidentity][azure_identity] documentation for more information about other credential types.
+
+#### Create a client
+
+Constructing the client also requires your Managed HSM's URL, which you can get from the Azure CLI or the Azure Portal.
+
+## Key concepts
+
+### RoleDefinition
+
+A `RoleDefinition` is a collection of permissions. A role definition defines the operations that can be performed, such as read, write,
+and delete. It can also define the operations that are excluded from allowed operations.
+
+RoleDefinitions can be listed and specified as part of a `RoleAssignment`.
+
+### RoleAssignment
+
+A `RoleAssignment` is the association of a RoleDefinition to a service principal. They can be created, listed, fetched individually, and deleted.
+
+### rbac.Client
+
+An `rbac.Client` allows for management of `RoleDefinition` and `RoleAssignment` types.
+
+### backup.Client
+
+A `backup.Client` allows for performing full key backups, full key restores, and selective key restores.
+
+### settings.Client
+
+A `settings.Client` provides methods to update, get, and list settings for a Managed HSM.
+
+## Examples
+
+Get started with our examples.
+
+## Troubleshooting
+
+### Error Handling
+
+All methods which send HTTP requests return `*azcore.ResponseError` when these requests fail. `ResponseError` has error details and the raw response from Key Vault.
+
+```go
+import "github.com/Azure/azure-sdk-for-go/sdk/azcore"
+
+settings, err := client.GetSettings(context.Background(), nil)
+if err != nil {
+    var httpErr *azcore.ResponseError
+    if errors.As(err, &httpErr) {
+        // TODO: investigate httpErr
+    } else {
+        // TODO: not an HTTP error
+    }
+}
+```
+
+### Logging
+
+This module uses the logging implementation in `azcore`. To turn on logging for all Azure SDK modules, set `AZURE_SDK_GO_LOGGING` to `all`. By default the logger writes to stderr. Use the `azcore/log` package to control log output. For example, logging only HTTP request and response events, and printing them to stdout:
+
+```go
+import azlog "github.com/Azure/azure-sdk-for-go/sdk/azcore/log"
+
+// Print log events to stdout
+azlog.SetListener(func(cls azlog.Event, msg string) {
+	fmt.Println(msg)
+})
+
+// Includes only requests and responses in credential logs
+azlog.SetEvents(azlog.EventRequest, azlog.EventResponse)
+```
+
+### Accessing `http.Response`
+
+You can access the raw `*http.Response` returned by Key Vault using the `runtime.WithCaptureResponse` method and a context passed to any client method.
+
+```go
+import "github.com/Azure/azure-sdk-for-go/sdk/azcore/runtime"
+
+var response *http.Response
+ctx := runtime.WithCaptureResponse(context.TODO(), &response)
+_, err = client.GetSettings(context.Background(), nil)
+if err != nil {
+    // TODO: handle error
+}
+// TODO: do something with response
+```
+
+## Contributing
+
+This project welcomes contributions and suggestions.  Most contributions require
+you to agree to a Contributor License Agreement (CLA) declaring that you have
+the right to, and actually do, grant us the rights to use your contribution. For
+details, visit <https://cla.microsoft.com>.
+
+This project has adopted the [Microsoft Open Source Code of Conduct][code_of_conduct].
+For more information see the [Code of Conduct FAQ][coc_faq]
+or contact [email protected] with any
+additional questions or comments.
+
+<!-- LINKS -->
+[azure_identity]: https://pkg.go.dev/github.com/Azure/azure-sdk-for-go/sdk/azidentity
+[azure_sub]: https://azure.microsoft.com/free
+[create_managed_hsm]: https://learn.microsoft.com/azure/key-vault/managed-hsm/quick-create-cli
+[code_of_conduct]: https://opensource.microsoft.com/codeofconduct/
+[default_cred_ref]: https://github.com/Azure/azure-sdk-for-go/tree/main/sdk/azidentity#defaultazurecredential
+[managed_hsm]: https://docs.microsoft.com/azure/key-vault/managed-hsm/overview
+[managed_hsm_docs]: https://learn.microsoft.com/azure/key-vault/managed-hsm/
+[managed_identity]: https://docs.microsoft.com/azure/active-directory/managed-identities-azure-resources/overview
+[coc_faq]: https://opensource.microsoft.com/codeofconduct/faq/
+

sdk/security/keyvault/azadmin/assets.json

@@ -0,0 +1,6 @@
+{
+  "AssetsRepo": "Azure/azure-sdk-assets",
+  "AssetsRepoPrefixPath": "go",
+  "TagPrefix": "go/security/keyvault/azadmin",
+  "Tag": "go/security/keyvault/azadmin_6b57e62028"
+}

sdk/security/keyvault/azadmin/backup/autorest.md

@@ -0,0 +1,90 @@
+## Go
+
+```yaml
+clear-output-folder: false
+export-clients: true
+go: true
+input-file: 
+    - https://github.com/Azure/azure-rest-api-specs/blob/551275acb80e1f8b39036b79dfc35a8f63b601a7/specification/keyvault/data-plane/Microsoft.KeyVault/stable/7.4/backuprestore.json
+license-header: MICROSOFT_MIT_NO_VERSION
+openapi-type: "data-plane"
+output-folder: ../backup
+override-client-name: Client
+security: "AADToken"
+security-scopes: "https://vault.azure.net/.default"
+use: "@autorest/[email protected]"
+version: "^3.0.0"
+
+directive:
+
+  # make vault URL a parameter of the client constructor
+  - from: swagger-document
+    where: $["x-ms-parameterized-host"]
+    transform: $.parameters[0]["x-ms-parameter-location"] = "client"
+
+  # rename restore operation from BeginFullRestoreOperation to BeginFullRestore
+  - rename-operation:
+      from: FullRestoreOperation
+      to: FullRestore
+  - rename-operation:
+      from: SelectiveKeyRestoreOperation
+      to: SelectiveKeyRestore
+
+  # make SASToken parameter required
+  - from: swagger-document
+    where: $.paths["/backup"].post.parameters[0]
+    transform: $["required"] = true
+
+  # delete backup and restore status methods
+  - from: swagger-document
+    where: $["paths"]
+    transform: >
+        delete $["/backup/{jobId}/pending"];
+  - from: swagger-document
+    where: $["paths"]
+    transform: >
+        delete $["/restore/{jobId}/pending"];
+
+  # delete generated client constructor
+  - from: client.go
+    where: $
+    transform: return $.replace(/(?:\/\/.*\s)+func NewClient.+\{\s(?:.+\s)+\}\s/, "");
+
+  # delete unused error models
+  - from: models.go
+    where: $
+    transform: return $.replace(/(?:\/\/.*\s)+type (?:Error|KeyVaultError).+\{(?:\s.+\s)+\}\s/g, "");
+  - from: models_serde.go
+    where: $
+    transform: return $.replace(/(?:\/\/.*\s)+func \(\w \*?(?:Error|KeyVaultError)\).*\{\s(?:.+\s)+\}\s/g, "");
+  - from: models.go
+    where: $
+    transform: return $.replace(/Error \*Error/g, "Error *ServerError");
+
+  # modify Restore to use implementation with custom poller handler
+  - from: client.go
+    where: $
+    transform:  return $.replace(/\[ClientFullRestoreResponse\], error\) \{\s(?:.+\s)+\}/, "[ClientFullRestoreResponse], error) {return client.beginFullRestore(ctx, restoreBlobDetails, options)}");
+  - from: client.go
+    where: $
+    transform:  return $.replace(/\[ClientSelectiveKeyRestoreResponse\], error\) \{\s(?:.+\s)+\}/, "[ClientSelectiveKeyRestoreResponse], error) {return client.beginSelectiveKeyRestore(ctx, keyName, restoreBlobDetails, options)}");
+
+  # delete client name prefix from method options and response types
+  - from:
+      - client.go
+      - models.go
+      - response_types.go
+    where: $
+    transform: return $.replace(/Client(\w+)((?:Options|Response))/g, "$1$2");
+
+  # add doc comments for models with missing descriptions
+  - from: swagger-document
+    where: $.definitions.SASTokenParameter
+    transform: $["description"] = "Contains the information required to access blob storage."
+  - from: swagger-document
+    where: $.definitions.RestoreOperationParameters
+    transform: $["description"] = "Parameters for the restore operation"
+  - from: swagger-document
+    where: $.definitions.SelectiveKeyRestoreOperationParameters
+    transform: $["description"] = "Parameters for the selective restore operation"
+```