azadmin

Azure KeyVault Administration client module for Go

Note: The Administration module only works with Managed HSM – functions targeting a Key Vault will fail.

• Managed HSM administration (this module) - role-based access control (RBAC), settings, and vault-level backup and restore options
• Certificate management (azcertificates) - create, manage, and deploy public and private SSL/TLS certificates
• Cryptographic key management (azkeys) - create, store, and control access to the keys used to encrypt your data
• Secrets management (azsecrets) - 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 | Samples (backup, rbac, settings)

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 is used for Azure Active Directory authentication. It creates a credential which is passed to the client contructor as shown in the examples below.

Prerequisites

• An Azure subscription.
• A supported Go version (the Azure SDK supports the two most recent Go releases)
• An existing Key Vault Managed HSM. If you need to create one, you can do so using the Azure CLI.

Authentication

This document demonstrates using azidentity.NewDefaultAzureCredential to authenticate. This credential type works in both local development and production environments. We recommend using a managed identity in production.

The clients accept any azidentity credential. See the azidentity 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.

• Example backup client
• Example rbac client
• Example settings client

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.

A RoleDefinition 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 manages RoleDefinition and RoleAssignment types.

backup.Client

A backup.Client performs 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:

• backup
• rbac
• settings

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.

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:

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 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.

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. For more information see the Code of Conduct FAQ or contact opencode@microsoft.com with any additional questions or comments.