#Azure Key Vault

Azure Key Vault is a cloud service for securely storing and managing cryptographic keys, secrets, and certificates. It provides a secure and reliable way to protect sensitive information and control access to keys used by cloud applications and services.

#Prerequisites

An Azure account with an active subscription. Create an account.
An Azure Key Vault instance. Create a Key Vault.
An Azure AD application with access to the Key Vault. Create an Azure AD application.

#Setup

Create an Azure AD application with access to the Key Vault. Note down the Application (client) ID and Directory (tenant) ID.
Create a client secret for the Azure AD application. Note down the Client Secret.
Assign permissions to the Azure AD application to access the Key Vault. Grant the Key permissions and Secret permissions to the application.
Get the Key Vault URL. Note down the Key Vault URL from the Azure portal.
Configure the issuer API to use the Azure Key Vault. Provide the Key Vault URL, Application ID, Tenant ID, and Client Secret in the issuer API configuration.
Generate a key in the Key Vault. Use the issuer API to generate a key in the Azure Key Vault.
Sign and issue credentials using the key stored in the Azure Key Vault.

#Key Generation

To create the key you can use the onboard endpoint provided by the issuer API and provide the necessary parameters to create the key in the Azure Key Vault service.

#Creation via Issuer API

Request

Response

Endpoint:/onboard/issuer | API Reference

Example Request

curl -X 'POST' \
  'https://issuer.portal.walt-test.cloud/onboard/issuer' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
  "key": {
    "backend": "azure",
    "keyType": "secp256r1",
    "config": {
       "auth": {
          "keyVaultUrl": "https://<key-vault-name>.vault.azure.net/",
          "clientId": "<application-id>",
          "tenantId": "<tenant-id>",
          "clientSecret": "<client-secret>"
      }
    }
  },
  "did": {
    "method": "jwk"
  }
}'

Body

{
  "key": {
    "backend": "azure",
    "keyType": "secp256r1",
    "config": {
      "auth": {
        "keyVaultUrl": "https://<key-vault-name>.vault.azure.net/",
        "clientId": "<application-id>",
        "tenantId": "<tenant-id>",
        "clientSecret": "<client-secret>"
      }
    }
  },
  "did": {
    "method": "jwk"
  }
}

Body Parameters

key
- backend: String - Specifies the storage type of key. It can be jwk (manged by you), azure (managed by Azure Key Vault using Rest api requests ) and others. Learn more about different types here.
- keyType: String - the algorithm used to generate the key. For Vault only ed25519 is possible.
- config
  - keyVaultUrl: String - The URL of the Azure Key Vault.
  - clientId: String - The client ID of the Azure AD application.
  - tenantId: String - The tenant ID of the Azure AD application.
  - clientSecret: String - The client secret of the Azure AD application.
did:
- method: String - Specifies the DID method. It can be key, jwk, web, cheqd.

#Key Usage

Once you have successfully created a key that is one of the supported types listed above, you can use it in sign and issue operations offered by the issuer API.

If you've already had a look at our /sign, /issue, /batchIssue endpoints, you have seen that they all follow a similar request body structure, where the key that should be used for signing credentials is provided via the issuerKey property. Now instead of providing the key as JWK, we provide a reference to a key stored in Vault with the required parameters and access credentials.

Below you can see an example of issuerKey object referencing a key stored in AWS.

Example IssuerKey Object

Example Issuance Request

{
  "issuerKey": {
    "type": "azure",
    "id": "https://kv-nhd-vp-core-dev.vault.azure.net/keys/541693094/be4a95477f274b38826938a92f990fd5",
    "auth": {
      "keyVaultUrl": "https://<key-vault-name>.vault.azure.net/",
      "clientId": "<application-id>",
      "tenantId": "<tenant-id>",
      "clientSecret": "<client-secret>"
    },
    "_keyType": "secp256r1",
    "_publicKey": {
      "type": "jwk",
      "jwk": {
        "kty": "EC",
        "crv": "P-256",
        "kid": "https://kv-nhd-vp-core-dev.vault.azure.net/keys/541693094/be4a95477f274b38826938a92f990fd5",
        "key_ops": [
          "sign",
          "verify"
        ],
        "x": "gWLUzx_B-36rcSdwlf78IjCRqVzchZFj6ino_ueu1y8",
        "y": "dL6LiFRFDwSyQphljk5YB0gXGlB5eg8sPZV_m1DTl2o"
      }
    }
  },
  "issuerDid": "did:jwk:eyJrdHkiOiJFQyIsImNydiI6IlAtMjU2Iiwia2lkIjoiaHR0cHM6Ly9rdi1uaGQtdnAtY29yZS1kZXYudmF1bHQuYXp1cmUubmV0L2tleXMvNTQxNjkzMDk0L2JlNGE5NTQ3N2YyNzRiMzg4MjY5MzhhOTJmOTkwZmQ1Iiwia2V5X29wcyI6WyJzaWduIiwidmVyaWZ5Il0sIngiOiJnV0xVenhfQi0zNnJjU2R3bGY3OElqQ1JxVnpjaFpGajZpbm9fdWV1MXk4IiwieSI6ImRMNkxpRlJGRHdTeVFwaGxqazVZQjBnWEdsQjVlZzhzUFpWX20xRFRsMm8ifQ"
}

Properties

type: String - the type of key can be either "aws" when using AWS KMS or "jwk" when providing the key in full as JWK.
id: String - the ID of the key in the Transit Engine.
config
- keyVaultUrl: String - The URL of the Azure Key Vault.
- clientId: String - The client ID of the Azure AD application.
- tenantId: String - The tenant ID of the Azure AD application.
- clientSecret: String - The client secret of the Azure AD application.
_publicKey (optional): Array - The public key can be fetched by the issuer API or directly provided, saving resources and reducing network requests.
_keyType (optional): String - The key type can be fetched by the issuer API or directly provided, saving resources and reducing network requests. ::

Oracle Vault Issue W3C Credentials (JWT / SD-JWT) via OID4VC