search

microsoft / AzureKeyVaultExplorer

Azure Key Vault Explorer
MIT License
210 stars 68 forks source link

readme

bigKey Azure Key Vault Explorer

Azure Key Vault Explorer - be productive when working with secrets!

Click here to install the latest version (https://aka.ms/ve)

Authors: Eli Zeitlin, Gokhan Ozhan, Anna Zeitlin
Contact: [Azure Key Vault Explorer Developers](mailto:Azure Key Vault Explorer Developers vedev@microsoft.com>)

Table of Contents

Key features

How to add or open new vaults

There are 4 ways how you can make Vault Explorer to work with your vaults:

  1. In case Vault Explorer is not installed on the box, you may just run: https://aka.ms/ve?vault://[ENTER HERE YOUR VAULT NAME]
  2. In case Vault Explorer already installed on the box, you can just hit Win+R type vault://[ENTER HERE YOUR VAULT NAME] and hit Enter
    • Note: The above two methods do NOT allow for alternative account login
  3. Run Vault Explorer, open vault combo box, select last item "Pick vault from subscription..."
  4. Below is the recommended way, as it gives you a full control around vaults, aliases, access and secret kinds.
    Just complete the below fairly easy manual steps once:
    • Run Vault Explorer
    • Click on Settings, then go to About tab, and hit Install Location.
    • Copy Vaults.json, SecretKinds.json, CustomTags.json and VaultAliases.json (see below in the Configuration section what these files are)
    • Put all four files in some local folder let say "C:\Users\\My Documents\VaultExplorerConfig\" or some share folder which will be accessible to your team
    • Edit each file accordingly, read the Configuration section below
    • Go back to Options tab in the Settings dialog, and change "Root location" from .\ to point to where you put all four files
    • Hit OK button

Keyboard and mouse shortcuts

Configuration

There are five configuration files which controls Vault Explorer behaviour.

Vaults.json

Defines a dictionary of vault names and how access is gained. This is especially useful if the account that is running Vault Explorer does not have access to certain vaults. Customize this file to add credentials for specific vaults. Otherwise, editing this file is optional if the current account has access to the specified vault. Vault names are used later in VaultAliases.json. Vault Explorer uses only ReadWrite access. Supported Vault Access types are:

In case of dual vaults (primary and secondary) use $id and $ref to avoid duplication. Here an example for dual vault configuration.

{
  "myVault": {
    "$id": "1",
    "ReadOnly": [
      {
        "$type": "Microsoft.Vault.Library.VaultAccessClientCertificate, Microsoft.Vault.Library",
        "ClientId": "00000000-0000-0000-aaaa-aaaaaaaaaaaa",
        "CertificateThumbprint": "0000000000000000000000000000000000000000"
      }
    ],
    "ReadWrite": [
      {
        "$type": "Microsoft.Vault.Library.Vault.VaultAccessClientCertificate, Microsoft.Vault.Library",
        "ClientId": "00000000-0000-0000-aaaa-aaaaaaaaaaaa",
        "CertificateThumbprint": "0000000000000000000000000000000000000000"
      },
      {
        "$type": "Microsoft.Vault.Library.VaultAccessClientCredential, Microsoft.Vault.Library",
        "ClientId": "00000000-0000-0000-aaaa-aaaaaaaaaaaa",
        "ClientSecret": "aXRoIEJhc2U2NCBmb3Jtsdfsdf5534YXQ/IFRoZW4="
      },
      {
        "$type": "Microsoft.Vault.Library.VaultAccessUserInteractive, Microsoft.Vault.Library",
        "DomainHint": "xxx.yyy",
        "UserAliasType": "Alt" 
      }
    ]
  },
  "myVault": {
    "$ref": "1"
  }
}

VaultAliases.json

Defines a list of vault aliases that can be used to quickly access certain vaults. VaultNames do not need to be defined in Vaults.json. Each vault alias is a simple class with the following properties:

Here an example for vault alias element in the array:

  {
    "Alias": "Test Alias",
    "VaultNames": [ "myVault1", "myVault2" ],
    "SecretKinds": [ "Custom", "Service.Secret" ]
  },

Here is an example of a single vault not defined in Vaults.json

  {
    "Alias": "DEV",
    "VaultNames": [ "TestKeyVault" ]
  }

vaultalises

SecretKinds.json

Defines a dictionary of different secret kinds. Secret kind names can be used in VaultAliases.json to limit the types of secrets available in a certain vault. Selecting a Secret Kind will also add a SecretKind custom tag to the secret that can be referenced by external programs and scripts. By default, any new Secret is a Custom secret and the SecretKind tag will not be populated. Secret Kind is a simple class with the following properties:

Here an example for storage account secret kind:

  "My.StorageAccount": {
    "Alias": "Storage Account",
    "Description": "Azure storage account connection string in the following format: DefaultEndpointsProtocol=[http|https];AccountName=<myAccountName>;AccountKey=<myAccountKey>",
    "NameRegex": "^sa-(?<AccountName>[0-9a-z]{3,24})(?<Region>|-cus|-eus|-eus2|-ugi|-ugv|-ncu|-scu|-wus|-neu|-weu|-eas|-sas|-ejp|-wjp|-sbr|-eau|-sau|-all)$",
    "ValueRegex": "^DefaultEndpointsProtocol=(http|https);AccountName=(?<AccountName>[0-9a-z]{3,24});AccountKey=((?:[A-Za-z0-9+\/]{4})*(?:[A-Za-z0-9+\/]{2}==|[A-Za-z0-9+\/]{3}=)?)$",
    "ValueTemplate": "DefaultEndpointsProtocol=https;AccountName=...;AccountKey=...",
    "RequiredCustomTags": [ "MyTag" ],
    "OptionalCustomTags": [ "MyOptionalTag" ],
    "DefaultExpiration": "180.00:00:00",
    "MaxExpiration":  "180.00:00:00"
  },

Note: Total number of RequiredCustomTags and OptionalCustomTags must be less than 15 for any secret kind.

secretkinds

CustomTags.json

Defines a dictionary for different secret custom tags. Custom tags must be added to SecretKinds.json in the 'RequiredCustomTags' or 'OptionalCustomTags' sections. Each cutom tag is a simple class with the following properties:

Here are examples for couple of custom tags:

{
  "MyTag": {
    "Name": "Tag",
    "DefaultValue": "foo",
    "ValueRegex": ".{0,256}",
    "ValueList": [
      "foo",
      "bar"
    ]
  },
  "MyOptionalTag": {
    "Name": "Description",
    "DefaultValue": "",
    "ValueRegex": ".{0,256}"
  }
}

customtags

User.config

XML file which controls user settings, will be created only if user changed the default values via Settings dialog and clicked OK button. Here an example for location of the file: 

%LocalAppData%\Apps\2.0\Data\2310EVQO.1C1\Q6P3APKG.HY4\vaul..tion_7446cb71d1187222_07e0.03f5_fc3133cd208276e1\Data\2016.1013.1742.39\user.config

Telemetry

By default Azure Key Vault Explorer collects and sends aggregated telemetry to Application Insights about usage of the tool. Telemetry includes only the following:

All collected telemetry is stored for no more than 90 days. Telemetry can be disabled in the Settings dialog. Set Disable telemetry to True, hit OK button and restart the application.

Screen shots

Main window

mainwindow

Search and copy secret to clipboard

searchSecretAndCopy

Edit secret

editSecret

Rollback to specific secret version

editSecretVersions

Edit secret tags

secretTagsEditor

Edit Key Vault certificate

editSecret

Settings window

settings