Azure Key Vault v1.0.0

About the connector

Azure Key Vault is a cloud-based key management and security service that enables securing cryptographic keys, passwords, and other secret services used by cloud applications and services. This connector provides automated actions to list, get and delete vaults, keys, secrets, and certificates

This document provides information about the Azure Key Vault Connector, which facilitates automated interactions, with an Azure Key Vault server using FortiSOAR™ playbooks. Add the Azure Key Vault Connector as a step in FortiSOAR™ playbooks and perform automated operations with Azure Key Vault.

Version information

Connector Version: 1.0.0

FortiSOAR™ Version Tested on: 7.3.2-2150

Azure Key Vault Version Tested on: Cloud instance

Authored By: Fortinet

Certified: Yes

Getting Access Tokens

You can get authentication tokens to access the Azure Key Vault using the Without a User- Application Permission method. For more information see, https://learn.microsoft.com/en-us/graph/auth-register-app-v2.

Getting Access Tokens using the Without a User - Application Permission method

1. Register your app. To register an app refer to App Registration Quickstart.
2. Assign the role of Key Vault Contributor. To assign roles, refer to Assign Azure roles using the Azure portal.
   • Alternatively, you can create custom roles. To create custom roles, refer to Azure custom roles. Add the following permissions to the custom role:
     • Microsoft.KeyVault/vaults/read
     • Microsoft.KeyVault/vaults/delete
     • Microsoft.KeyVault/vaults/accessPolicies/write
3. To assign an access policy, navigate to the Key Vault resource.
   • Select Access policies, then select Create.
   • Select following permissions under Secret permissions, Certificate permissions, and Key Permissions:
     • Get
     • List
     • Delete
   • Enter the name of the app in the search field and select the app, under the Principal selection pane.
   • Review the access policy changes and select Create to save the access policy.
4. Copy the following information to use when configuring the connector.
   • Tenant ID
   • Subscription ID
   • Application (client) ID
   • Application (Client) Secret

Installing the connector

Use the Content Hub to install the connector. For a detailed procedure to install a connector, click here.

You can also use the yum command as a root user to install the connector:

yum install cyops-connector-azure-key-vault

Prerequisites to configuring the connector

• The FortiSOAR™ server should have outbound connectivity to port 443 on the Azure Key Vault server.

Minimum Permissions Required

• Not applicable

Configuring the connector

For the procedure to configure a connector, click here

Configuration parameters

In FortiSOAR™, on the Connectors page, click the Azure Key Vault connector row (if you are in the Grid view on the Connectors page) and in the Configurations tab enter the required configuration details:

Parameter	Description
Directory (tenant) ID	Tenant ID that you have been provided for your Azure Active Directory instance
Subscription ID	Subscription credentials which uniquely identify Microsoft Azure subscription.
Application (client) ID	Unique ID of the Azure Active Directory application that is used to create an authentication token required to access the API.
Application (Client) Secret	Unique Client Secret of the Azure Active Directory application that is used to create an authentication token required to access the API. For information on how to get the secret key, see https://docs.microsoft.com/en-us/windows/security/threat-protection/microsoft-defender-atp/exposed-apis-create-app-webapp.
Verify SSL	Specifies whether the SSL certificate for the server is to be verified or not. By default, this option is set to True.

Actions supported by the connector

The following automated operations can be included in playbooks and you can also use the annotations to access operations:

Function	Description	Annotation and Category
List Key Vaults	Gets information about the vaults associated with the subscription ID specified in the configuration parameters.	list_key_vault Investigation
Get Key Vault	Gets the specified Azure key vault based on the vault name and resource group name you have specified.	get_key_vault Investigation
Delete Key Vault	Deletes the specified vault from Azure key vault based on the vault name and resource group name you have specified.	delete_key_vault Investigation
Update Vault's Access Policies	Updates access policies in the specified Azure key vault based on the vault name, resource group name, and other parameters you have specified.	update_vault_access_policy Investigation
Get All Keys	Retrieves a list of the keys from the Azure Key Vault based on the vault name you have specified.	list_keys Investigation
Get Key Details	Gets the public part of a stored key from Azure Key Vault based on the vault name, key name, and the key version you have specified.	get_key Investigation
Delete Key	Deletes a key from storage in Azure Key Vault based on the vault name and the key name you have specified.	delete_key Investigation
Get All Secrets	Retrieves a list of the secrets from the Azure Key Vault based on the vault name you have specified.	list_secret Investigation
Get Secret Details	Gets a Secret from specified Azure Key Vault vault name, secret name, and the secret version you have specified.	get_secret Investigation
Delete Secret	Deletes the Secret from specified vault in Azure Key Vault based on the vault name and the secret name you have specified..	delete_secret Investigation
Get All Certificates	Retrieves a list of the certificates from the Azure Key Vault based on the vault name you have specified.	list_certificate Investigation
Get Certificate Details	Retrieves the certificate details from the Azure Key Vault based on the vault name, certificate name, and the certificate version you have specified.	get_certificate Investigation
Delete Certificate	Deletes certificate from the Azure Key Vault based on the vault name and the certificate name you have specified.	delete_certificate Investigation
Get Certificate Policy	Retrieves the specified certificate policy resources in the specified key vault based on the vault name and the certificate name you have specified.	get_certificate_policy Investigation
Get Versions	Gets Versions of specified secret, key, or certificate from Azure Key Vault based on the vault name and the object name you have specified.	get_versions Investigation

operation: List Key Vaults

Input parameters

Parameter	Description
Skip Token	Specify a skip token if a previous operation returned a partial result. If the previous response contains a nextLink element, the value of the nextLink element includes a skip token parameter that specifies a starting point to use for subsequent calls.
Size	Specify the maximum number of key vaults that this operation should return from Azure Key Vault. The value should be in the range 1-1000.

Output

The output contains the following populated JSON schema:
{
"value": [
{
"id": "",
"name": "",
"type": "",
"location": "",
"tags": {}
}
],
"nextLink": ""
}

operation: Get Key Vault

Input parameters

Parameter	Description
Vault Name	Specify the name of the vault whose details you want to fetch from the Azure Key Vault.
Resource Group Name	Specify the name of the Resource Group to which this server belongs.

Output

The output contains the following populated JSON schema:
{
"id": "",
"name": "",
"type": "",
"location": "",
"tags": {},
"properties": {
"sku": {
"family": "",
"name": ""
},
"tenantId": "",
"accessPolicies": [
{
"tenantId": "",
"objectId": "",
"permissions": {
"keys": [],
"secrets": [],
"certificates": []
}
}
],
"enabledForDeployment": "",
"enabledForDiskEncryption": "",
"enabledForTemplateDeployment": "",
"enableSoftDelete": "",
"softDeleteRetentionInDays": "",
"enableRbacAuthorization": "",
"vaultUri": "",
"provisioningState": ""
}
}

operation: Delete Key Vault

Input parameters

Parameter	Description
Vault Name	Specify the name of the vault to delete from the Azure Key Vault.
Resource Group Name	Specify the name of the Resource Group to which this server belongs.

Output

The output contains the following populated JSON schema:
{
"status": "",
"result": ""
}

operation: Update Vault's Access Policies

Input parameters

Parameter	Description
Vault Name	Specify the name of the vault whose access policy you want to update in the Azure Key Vault.
Resource Group Name	Specify the name of the Resource Group to which this server belongs.
Operation	Select the operation to perform on the permissions of access policies. You can choose from the following options: Add Replace Remove
Policies	Specify the policies you want to update in the specified key vault. For Example, { "accessPolicies": [ { "tenantId": "00000000-0000-0000-0000-000000000000", "objectId": "00000000-0000-0000-0000-000000000000", "permissions": { "keys": [ "encrypt" ], "secrets": [ "get" ], "certificates": [ "get" ] } } ] }

Output

The output contains the following populated JSON schema:
{
"id": "",
"type": "",
"properties": {
"accessPolicies": [
{
"tenantId": "",
"objectId": "",
"permissions": {
"certificates": [],
"keys": [],
"secrets": []
}
}
]
}
}

operation: Get All Keys

Input parameters

Parameter	Description
Vault Name	Specify the name of the vault from which you want to retrieve the keys.
Skip Token	Specify a skip token if a previous operation returned a partial result. If the previous response contains a nextLink element, the value of the nextLink element includes a skip token parameter that specifies a starting point to use for subsequent calls.
Size	Specify the maximum number of keys that this operation should return from Azure Key Vault. The value should be between 1 and 25. In certain cases, the service might return fewer results than specified by this parameter (even 0 results) and also return a nextLink. Do not make any assumptions on the minimum number of results per page and enumerate all pages until the nextLink becomes null.

Output

The output contains the following populated JSON schema:
{
"value": [
{
"kid": "",
"attributes": {
"enabled": "",
"created": "",
"updated": "",
"recoveryLevel": "",
"exportable": ""
},
"tags": {}
}
],
"nextLink": ""
}

operation: Get Key Details

Input parameters

Parameter	Description
Vault Name	Specify the name of the vault from to retrieve the key.
Key Name	Specify the name of the key to retrieve from the specified key vault.
Key Version	Specify the version of the key to retrieve from the key vault.

Output

The output contains the following populated JSON schema:
{
"key": {
"kid": "",
"kty": "",
"key_ops": [],
"n": "",
"e": ""
},
"attributes": {
"enabled": "",
"created": "",
"updated": "",
"recoveryLevel": ""
},
"tags": {}
}

operation: Delete Key

Input parameters

Parameter	Description
Vault Name	Specify the name of vault from which to delete the key.
Key Name	Specify the name of the key which to delete from the specified key vault.

Output

The output contains the following populated JSON schema:
{
"recoveryId": "",
"deletedDate": "",
"scheduledPurgeDate": "",
"key": {
"kid": "",
"kty": "",
"key_ops": [],
"n": "",
"e": ""
},
"attributes": {
"enabled": "",
"created": "",
"updated": "",
"recoveryLevel": "",
"exportable": ""
},
"tags": {}
}

operation: Get All Secrets

Input parameters

Parameter	Description
Vault Name	Specify the name of the vault from which you want to retrieve the Secrets.
Size	Specify the maximum number of secrets that this operation should return from Azure Key Vault. The value should be between 1 and 25. In certain cases, the service might return fewer results than specified by this parameter (even 0 results) and also return a nextLink. Do not make any assumptions on the minimum number of results per page and enumerate all pages until the nextLink becomes null.
Skip Token	Specify a skip token if a previous operation returned a partial result. If the previous response contains a nextLink element, the value of the nextLink element includes a skip token parameter that specifies a starting point to use for subsequent calls.

Output

The output contains the following populated JSON schema:
{
"value": [
{
"contentType": "",
"id": "",
"attributes": {
"enabled": "",
"nbf": "",
"exp": "",
"created": "",
"updated": "",
"recoveryLevel": ""
},
"tags": {}
}
],
"nextLink": ""
}

operation: Get Secret Details

Input parameters

Parameter	Description
Vault Name	Specify the name of the vault from which to retrieve the Secret.
Secret Name	Specify the name of the secret to retrieve from the key vault.
Secret Version	Specify the version of the secret to retrieve from the key vault.

Output

The output contains the following populated JSON schema:
{
"value": "",
"contentType": "",
"id": "",
"attributes": {
"enabled": "",
"nbf": "",
"exp": "",
"created": "",
"updated": "",
"recoveryLevel": ""
},
"tags": {}
}

operation: Delete Secret

Input parameters

Parameter	Description
Vault Name	Specify the name of the vault from which to delete the Secret.
Secret Name	Specify the name of the Secret to delete from the specified key vault.

Output

The output contains the following populated JSON schema:
{
"recoveryId": "",
"deletedDate": "",
"scheduledPurgeDate": "",
"contentType": "",
"id": "",
"attributes": {
"enabled": "",
"nbf": "",
"exp": "",
"created": "",
"updated": "",
"recoveryLevel": ""
},
"tags": {}
}

operation: Get All Certificates

Input parameters

Parameter	Description
Vault Name	Specify the name of the vault from which you want to retrieve the Certificates.
Include Pending	Specifies whether to include certificates that are not completely provisioned. By default, it is set to false.
Skip Token	Specify a skip token if a previous operation returned a partial result. If the previous response contains a nextLink element, the value of the nextLink element includes a skip token parameter that specifies a starting point to use for subsequent calls.
Size	Specify the maximum number of certificates that this operation should return from Azure Key Vault. The value should be between 1 and 25. In certain cases, the service might return fewer results than specified by this parameter (even 0 results) and also return a nextLink. Do not make any assumptions on the minimum number of results per page and enumerate all pages until the nextLink becomes null.

Output

The output contains the following populated JSON schema:
{
"value": [
{
"id": "",
"x5t": "",
"attributes": {
"enabled": "",
"nbf": "",
"exp": "",
"created": "",
"updated": ""
},
"tags": {},
"subject": ""
}
],
"nextLink": ""
}

operation: Get Certificate Details

Input parameters

Parameter	Description
Vault Name	Specify the name of the vault from which you want to retrieve the certificate details.
Certificate Name	Specify the name of the certificate which you want to retrieve from the key vault.
Certificate Version	Specify the version of the certificate which you want to retrieve from the key vault.

Output

The output contains the following populated JSON schema:
{
"id": "",
"kid": "",
"sid": "",
"x5t": "",
"cer": "",
"attributes": {
"enabled": "",
"nbf": "",
"exp": "",
"created": "",
"updated": "",
"recoveryLevel": ""
},
"tags": {},
"policy": {
"id": "",
"key_props": {
"exportable": "",
"kty": "",
"key_size": "",
"reuse_key": ""
},
"secret_props": {
"contentType": ""
},
"x509_props": {
"subject": "",
"sans": {
"dns_names": []
},
"ekus": [],
"key_usage": [],
"validity_months": "",
"basic_constraints": {
"ca": ""
}
},
"lifetime_actions": [
{
"trigger": {
"lifetime_percentage": ""
},
"action": {
"action_type": ""
}
}
],
"issuer": {
"name": ""
},
"attributes": {
"enabled": "",
"created": "",
"updated": ""
}
},
"pending": {
"id": ""
}
}

operation: Delete Certificate

Input parameters

Parameter	Description
Vault Name	Specify the name of the vault from which to delete the certificate.
Certificate Name	Specify the name of the certificate to delete from the key vault.

Output

The output contains the following populated JSON schema:
{
"recoveryId": "",
"deletedDate": "",
"scheduledPurgeDate": "",
"id": "",
"kid": "",
"sid": "",
"x5t": "",
"cer": "",
"attributes": {
"enabled": "",
"nbf": "",
"exp": "",
"created": "",
"updated": "",
"recoveryLevel": "",
"recoverableDays": ""
},
"tags": {},
"policy": {
"id": "",
"key_props": {
"exportable": "",
"kty": "",
"key_size": "",
"reuse_key": ""
},
"secret_props": {
"contentType": ""
},
"x509_props": {
"subject": "",
"sans": {
"dns_names": []
},
"ekus": [],
"key_usage": [],
"validity_months": "",
"basic_constraints": {
"ca": ""
}
},
"lifetime_actions": [
{
"trigger": {
"lifetime_percentage": ""
},
"action": {
"action_type": ""
}
}
],
"issuer": {
"name": ""
},
"attributes": {
"enabled": "",
"created": "",
"updated": ""
}
},
"pending": {
"id": ""
}
}

operation: Get Certificate Policy

Input parameters

Parameter	Description
Vault Name	Specify the name of the vault from which to retrieve the certificate policy.
Certificate Name	Specify the name of the certificate whose policy to retrieve from the key vault.

Output

The output contains the following populated JSON schema:
{
"id": "",
"key_props": {
"exportable": "",
"kty": "",
"key_size": "",
"reuse_key": ""
},
"secret_props": {
"contentType": ""
},
"x509_props": {
"subject": "",
"sans": {
"dns_names": []
},
"ekus": [],
"key_usage": [],
"validity_months": "",
"basic_constraints": {
"ca": ""
}
},
"lifetime_actions": [
{
"trigger": {
"lifetime_percentage": ""
},
"action": {
"action_type": ""
}
}
],
"issuer": {
"name": ""
},
"attributes": {
"enabled": "",
"created": "",
"updated": ""
}
}

operation: Get Versions

Input parameters

Parameter	Description
Vault Name	Specify the name of the vault from which you want to retrieve the versions of keys, secrets, or certificates.
Object Name	Select the type of object whose versions you want to retrieve from the Azure key vault. You can choose from the following options: Keys: Specify the key name, in the Key Name field, whose versions you want to retrieve from the Azure Key Vault. Secrets: Specify the secret name, in the Secret Name field, whose versions you want to retrieve from the Azure Key Vault. Certificate: Specify the certificate name, in the Certificate Name field, whose versions you want to retrieve from the Azure Key Vault.
Skip Token	Specify a skip token if a previous operation returned a partial result. If the previous response contains a nextLink element, the value of the nextLink element includes a skip token parameter that specifies a starting point to use for subsequent calls.
Size	Specify the maximum number of versions that this operation should return from Azure Key Vault. The value should be between 1 and 25. In certain cases, the service might return fewer results than specified by this parameter (even 0 results) and also return a nextLink. Do not make any assumptions on the minimum number of results per page and enumerate all pages until the nextLink becomes null.

Output

The output contains the following populated JSON schema:
{
"value": [],
"nextLink": ""
}

Included playbooks

The Sample - Azure Key Vault - 1.0.0 playbook collection comes bundled with the Azure Key Vault connector. These playbooks contain steps using which you can perform all supported actions. You can see bundled playbooks in the Automation > Playbooks section in FortiSOAR™ after importing the Azure Key Vault connector.

• Delete Certificate
• Delete Key
• Delete Key Vault
• Delete Secret
• Get All Certificates
• Get All Keys
• Get All Secrets
• Get Certificate Details
• Get Certificate Policy
• Get Key Details
• Get Key Vault
• Get Secret Details
• Get Versions
• List Key Vaults
• Update Vault's Access Policies

Note: If you are planning to use any of the sample playbooks in your environment, ensure that you clone those playbooks and move them to a different collection since the sample playbook collection gets deleted during the connector upgrade and delete.