Skip to main content
A newer release of this product is available.

Security azure-key-vaults endpoint overview

Contributors
PDFs

Overview

Azure Key Vault (AKV) is a cloud key management service (KMS) that provides a secure store for secrets. This feature allows the Azure NetApp Files Cloud Volume Services to securely store its encryption keys using AKV. In order to use AKV with Azure NetApp Files Cloud Volume Services, you must first deploy an Azure application with the appropriate access to an AKV and then provide Azure NetApp Files Cloud Volume Services with the necessary details, such as key vault name, application ID so that Azure NetApp Files Cloud Volume Services can communicate with the deployed Azure application. The properties "state", "azure_reachability" and "ekmip_reachability" are considered advanced properties and are populated only when explicitly requested. Note: This feature is only available to the Azure NetApp Files Cloud Volume Services.

Examples

Creating an AKV for a cluster

The example AKV is configured at the cluster-scope. Note the return_records=true query parameter is used to obtain the newly created key manager configuration.

# The API:
POST /api/security/azure-key-vaults

# The call:
curl -X POST 'https://<mgmt-ip>/api/security/azure-key-vaults?return_records=true' -H 'accept: application/hal+json' -d "{ \"client_id\": \"client1\", \"tenant_id\": \"tenant1\", \"name\": \"https:://mykeyvault.azure.vault.net/\", \"key_id\": \"https://keyvault-test.vault.azure.net/keys/key1/a8e619fd8f234db3b0b95c59540e2a74\", \"client_secret\" : \"myclientPwd\" }"

# The response:
{
"num_records": 1,
"records": [
  {
    "uuid": "85619643-9a06-11ea-8d52-005056bbeba5",
    "client_id": "client1",
    "tenant_id": "tenant1",
    "name": "https:://mykeyvault.azure.vault.net/",
    "key_id": "https://keyvault-test.vault.azure.net/keys/key1",
    "_links": {
      "self": {
        "href": "/api/security/azure-key-vaults/85619643-9a06-11ea-8d52-005056bbeba5"
      }
    }
  }
]
}

Creating an AKV for an SVM

The example AKV is configured for a specific SVM. Note the return_records=true query parameter is used to obtain the newly created key manager configuration.

# The API:
POST /api/security/azure-key-vaults

# The call:
curl -X POST 'https://<mgmt-ip>/api/security/azure-key-vaults?return_records=true' -H 'accept: application/hal+json' -d "{ \"svm\": { \"uuid\": \"4f7abf4c-9a07-11ea-8d52-005056bbeba5\" }, \"client_id\": \"client1\", \"tenant_id\": \"tenant1\", \"name\": \"https:://mykeyvault.azure.vault.net/\", \"key_id\": \"https://keyvault-test.vault.azure.net/keys/key1\", \"client_secret\" : \"myclientPwd\" }"

# The response:
{
"num_records": 1,
"records": [
  {
    "uuid": "024cd3cf-9a08-11ea-8d52-005056bbeba5",
    "svm": {
      "uuid": "4f7abf4c-9a07-11ea-8d52-005056bbeba5",
      "name": "vs0"
    },
    "client_id": "client1",
    "tenant_id": "tenant1",
    "name": "https:://mykeyvault.azure.vault.net/",
    "key_id": "https://keyvault-test.vault.azure.net/keys/key1",
    "_links": {
      "self": {
        "href": "/api/security/azure-key-vaults/024cd3cf-9a08-11ea-8d52-005056bbeba5"
      }
    }
  }
]
}

Retrieving the AKVs configured for all clusters and SVMs

The following example shows how to retrieve all configured AKVs along with their configurations.

# The API:
GET /api/security/azure-key-vaults

# The call:
curl -X GET 'https://<mgmt-ip>/api/security/azure-key-vaults?fields=*'

# The response:
{
"records": [
  {
    "uuid": "024cd3cf-9a08-11ea-8d52-005056bbeba5",
    "scope": "svm",
    "svm": {
      "uuid": "4f7abf4c-9a07-11ea-8d52-005056bbeba5",
      "name": "vs0"
    },
    "client_id": "client1",
    "tenant_id": "tenant1",
    "name": "https:://mykeyvault.azure.vault.net/",
    "key_id": "https://keyvault-test.vault.azure.net/keys/key1",
    "_links": {
      "self": {
        "href": "/api/security/azure-key-vaults/024cd3cf-9a08-11ea-8d52-005056bbeba5"
      }
    }
  },
  {
    "uuid": "85619643-9a06-11ea-8d52-005056bbeba5",
    "scope": "cluster",
    "client_id": "client1",
    "tenant_id": "tenant1",
    "name": "https:://mykeyvault.azure.vault.net/",
    "key_id": "https://keyvault-test.vault.azure.net/keys/key1",
    "_links": {
      "self": {
        "href": "/api/security/azure-key-vaults/85619643-9a06-11ea-8d52-005056bbeba5"
      }
    }
  }
],
"num_records": 2,
"_links": {
  "self": {
    "href": "/api/security/azure-key-vaults?fields=*"
  }
}
}

Retrieving the AKV configured for a specific SVM

The following example retrieves a configured AKV for a specific SVM.

# The API:
GET /api/security/azure-key-vaults

# The call:
curl -X GET 'https://<mgmt-ip>/api/security/azure-key-vaults/85619643-9a06-11ea-8d52-005056bbeba5?fields=*'

# The response:
{
"uuid": "85619643-9a06-11ea-8d52-005056bbeba5",
"scope": "cluster",
"client_id": "client1",
"tenant_id": "tenant1",
"name": "https:://mykeyvault.azure.vault.net/",
"key_id": "https://keyvault-test.vault.azure.net/keys/key1",
"_links": {
  "self": {
    "href": "/api/security/azure-key-vaults/85619643-9a06-11ea-8d52-005056bbeba5"
  }
}
}

Retrieving the advanced properties of an AKV configured for a specific SVM

The following example retrieves the advanced properties of a configured AKV for a specific SVM.

# The API:
GET /api/security/azure-key-vaults

# The call:
curl -X GET 'https://<mgmt-ip>/api/security/azure-key-vaults/85619643-9a06-11ea-8d52-005056bbeba5?fields=state,azure_reachability,ekmip_reachability"'
{
"uuid": "fc0b7718-18c9-11eb-88e3-005056bb605d",
"name": "https://10.234.237.18",
"state": {
  "cluster_state": true,
  "message": "",
  "code": 0
},
"azure_reachability": {
  "reachable": true,
  "message": "",
  "code": 0
},
"ekmip_reachability": [
  {
    "node": {
        "uuid": "d208115f-7721-11eb-bf83-005056bb150e",
        "name": "node1",
        "_links": {
            "self": {
            "href": "/api/cluster/nodes/d208115f-7721-11eb-bf83-005056bb150e"
            }
        }
    },
    "reachable": true,
    "message": "",
    "code": 0
  },
  {
    "node": {
        "uuid": "e208115f-7721-11eb-bf83-005056bb150e",
        "name": "node2",
        "_links": {
            "self": {
            "href": "/api/cluster/nodes/e208115f-7721-11eb-bf83-005056bb150e"
            }
        }
    },
    "reachable": true,
    "message": "",
    "code": 0
  }
],
"_links": {
  "self": {
    "href": "/api/security/azure-key-vaults/fc0b7718-18c9-11eb-88e3-005056bb605d"
  }
}
}

Updating the client password of a specific SVM

The following example updates the client password of a configured AKV for a specific SVM.

# The API:
PATCH /api/security/azure-key-vaults

# The call:
curl -X PATCH 'https://<mgmt-ip>/api/security/azure-key-vaults/85619643-9a06-11ea-8d52-005056bbeba5' -d "{ \"client_secret\": \"newSecret\" }"

Deleting an AKV configuration for a specific SVM

The following example deletes a configured AKV for a specific SVM.

# The API:
DELETE /api/security/azure-key-vaults

# The call:
curl -X DELETE 'https://<mgmt-ip>/api/security/azure-key-vaults/85619643-9a06-11ea-8d52-005056bbeba5'

Restoring the keys for a specific SVM configured with an AKV

The following example restores all the keys of a specific SVM configured with an AKV.

# The API:
POST security/azure-key-vaults/{azure_key_vault.uuid}/restore

# The call:
curl -X POST 'https://<mgmt-ip>/api/security/azure-key-vaults/85619643-9a06-11ea-8d52-005056bbeba5/restore'

# The response:
{
"job": {
  "uuid": "6ab6946f-9a0c-11ea-8d52-005056bbeba5",
  "_links": {
    "self": {
      "href": "/api/cluster/jobs/6ab6946f-9a0c-11ea-8d52-005056bbeba5"
    }
  }
}
}

Rekeying the internal key for a specific SVM configured with an AKV

The following example rekeys the internal key of a specific SVM configured with an AKV.

# The API:
POST security/azure-key-vaults/{azure_key_vault.uuid}/rekey-internal

# The call:
curl -X POST 'https://<mgmt-ip>/api/security/azure-key-vaults/85619643-9a06-11ea-8d52-005056bbeba5/rekey-internal'

# The response:
{
"job": {
  "uuid": "6ab6946f-9a0c-11ea-8d52-005056bbeba5",
  "_links": {
    "self": {
      "href": "/api/cluster/jobs/6ab6946f-9a0c-11ea-8d52-005056bbeba5"
    }
  }
}
}