Security azure-key-vaults endpoint overview

05/08/2024 Contributors

Overview

Azure Key Vault (AKV) is a cloud key management service (KMS) that provides a secure store for secrets. This feature allows ONTAP to securely store its encryption keys using AKV. In order to use AKV with ONTAP, you must first deploy an Azure application with the appropriate access to an AKV and then provide ONTAP with the necessary details, such as key vault name, application ID so that ONTAP can communicate with the deployed Azure application.

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/a8e619fd8f234db3b0b95c59540e2a74",
    "_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.azre.vault.net/\", \"key_id\": \"https://keyvault-test.vault.azure.net/keys/key1/a8e619fd8f234db3b0b95c59540e2a74\", \"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/a8e619fd8f234db3b0b95c59540e2a74",
    "_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/a8e619fd8f234db3b0b95c59540e2a74",
    "state": {
      "cluster_state": true,
      "message": "",
      "code": 0
    },
    "_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/a8e619fd8f234db3b0b95c59540e2a74",
    "state": {
      "cluster_state": true,
      "message": "",
      "code": 0
    },
    "_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/a8e619fd8f234db3b0b95c59540e2a74",
"state": {
  "cluster_state": true,
  "message": "",
  "code": 0
},
"_links": {
  "self": {
    "href": "/api/security/azure-key-vaults/85619643-9a06-11ea-8d52-005056bbeba5"
  }
}
}

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"
    }
  }
}
}