hashicorp/vault-plugin-secrets-ad

Active Directory (AD) Secrets Plugin for Vault

Vault Plugin: Active Directory Secrets Backend

This is a standalone backend plugin for use with Hashicorp Vault. This plugin provides Active Directory functionality to Vault.

Please note: We take Vault's security and our users' trust very seriously. If you believe you have found a security issue in Vault, please responsibly disclose by contacting us at [email protected].

Quick Links

• Vault Website: https://www.vaultproject.io
• Active Directory Docs: https://developer.hashicorp.com/vault/docs/secrets/ad
• Main Project Github: https://www.github.com/hashicorp/vault

Getting Started

This is a Vault plugin and is meant to work with Vault. This guide assumes you have already installed Vault and have a basic understanding of how Vault works.

Otherwise, first read this guide on how to get started with Vault.

To learn specifically about how plugins work, see documentation on Vault plugins.

Usage

Please see documentation for the plugin on the Vault website.

This plugin is currently built into Vault and by default is accessed at ad. To enable this in a running Vault server:

$ vault secrets enable ad
Success! Enabled the ad secrets engine at: ad/

Additionally starting with Vault 0.10 this backend is by default mounted at secret/.

Developing

If you wish to work on this plugin, you'll first need Go installed on your machine (version 1.17+ is required).

For local dev first make sure Go is properly installed, including setting up a GOPATH.

To compile a development version of this plugin, run make or make dev. This will put the plugin binary in the bin and $GOPATH/bin folders. dev mode will only generate the binary for your platform and is faster:

$ make
$ make dev

Put the plugin binary into a location of your choice. This directory will be specified as the plugin_directory in the Vault config used to start the server.

plugin_directory = "path/to/plugin/directory"

Start a Vault server with this config file:

$ vault server -config=path/to/config.json ...
...

Once the server is started, register the plugin in the Vault server's plugin catalog:

$ vault plugin register \
        -sha256=<SHA256 Hex value of the plugin binary> \
        -command="vault-plugin-secrets-ad" \
        secret \
        custom-ad

Note you should generate a new sha256 checksum if you have made changes to the plugin. Example using openssl:

openssl dgst -sha256 $GOPATH/vault-plugin-secrets-ad
...
SHA256(.../go/bin/vault-plugin-secrets-ad)= 896c13c0f5305daed381952a128322e02bc28a57d0c862a78cbc2ea66e8c6fa1

Enable the secrets plugin backend using the secrets enable plugin command:

$ vault secrets enable custom-ad
...

Successfully enabled 'plugin' at 'custom-ad'!

Tests

If you are developing this plugin and want to verify it is still functioning (and you haven't broken anything else), we recommend running the tests.

To run the tests, run the following:

$ make test

You can also specify a TESTARGS variable to filter tests like so:

$ make test TESTARGS='--run=TestConfig'

vault-plugin-secrets-ad's Issues

AD secret engine returns ""returns “unable to find service account”?

Problem

I wrote the binding configurations and made sure that the binding has been successful via wireshark. When I write the role configuration by adding the "service_account_name="[email protected]"" attribute, it returns a message saying:

Code: 500. Errors: 
* 1 error occurred: 
* unable to find service account named testaccount in active directory, searches are case sensitive

The account is there and I can login to ldap server in this form [email protected].
I used wireshark to inspect the packets and it appears that 'userPrincipalName' is used to search for the account in ldap.

How to reproduce

Having an ldap server running and vault server running, unsealed and all variables are exported,
First, enable Active Directory secret engine:

vault secrets enable ad

Second, configure the secret engine:

vault write ad/config binddn='uid=testuser,cn=users,cn=accounts,dc=domain,dc=net' bindpass='testpass' userdn='cn=users,cn=accounts,dc=domain,dc=net' url="ldap://ldap.domain.net" insecure_tls=true

Third, write role configurations:

vault write ad/roles/testuser service_account_name='[email protected]'

Also, I am not sure why but it seems it is not an option to choose which filter to use for ldap searches which is userPrincipalName parameter. I recognized this from wireshark inspection then looked into the ad plugin afterwards.

Thanks

Can I create an account in Active Directory using Active Directory secrets engine?

I want to create an account in Active Directory using Active Directory secret engine. However, there is no parameter such as "creation_statements" in the Active Directory secrets engine. 

How to control the length of password generated by ad secret engine?

The password generated by ad secret engine is too long. I try to use the parameter "length", however, nothing happens as expected. Are there ways to control the length of password generated by ad secret engine?

instructions for quick test

hello,

I looked at:
https://github.com/hashicorp/vault-plugin-secrets-ad/blob/master/plugin/backend_test.go

and was hoping to use it to do a quick test.
so I started a vault server, enabled the ad engine: vault secrets enable ad

then created the following config

vault write ad/config \
    binddn='euclid' \
    bindpass='password' \
    url='ldap://ldap.forumsys.com:389' \
    userdn='cn=read-only-admin,dc=example,dc=com'

but I get an error on the role:

vault write ad/roles/test_role service_account_name="[email protected]" ttl="10"

Error writing data to ad/roles/test_role: Error making API request.

URL: PUT http://localhost:8200/v1/ad/roles/test_role
Code: 500. Errors:

* 1 error occurred:
	* LDAP Result Code 34 "Invalid DN Syntax": invalid DN

is that supposed to work?
if not, any instructions to achieve similar?

thanks

AD secrets engine has poor behaviour when an account has been renamed or deleted

Scenario:

• A role matching an AD account is configured in this secrets engine
• The AD account is later deleted, or has its userPrincipalName changed

Because *backend.readRole expects to be able to query AD:

vault-plugin-secrets-ad/plugin/path_roles.go

Lines 100 to 104 in 8359d89

	passwordLastSet, err := b.client.GetPasswordLastSet(engineConf.ADConf, role.ServiceAccountName)
	if err != nil {
	return nil, err
	}
	role.PasswordLastSet = passwordLastSet

two poor behaviours now occur:

• Any attempt to read the role (GET /ad/roles/:name) results in an internal server error
• Any attempt to update the role with the new userPrincipalName (POST/PUT /ad/roles/:name) also results in an error

Expected behaviours:

• Reading a role for which the corresponding account has gone missing in AD, should successfully return the existing configuration - possibly along with a warning.
• Writing new correct configuration over a role in this state should succeed, without requiring a workaround of deleting and recreating it.

Vault AD Engine Paths not working

Hey yall anyone having a hard time using the Vault AD Engine and trying to setup a library?
I get an error:
Error writing data to ad/library/x-team: Error making API request.

URL: PUT https://vault.x.io/v1/ad/library/x-team
Code: 404. Errors:

1 error occurred:

• unsupported path

This is my call:
vault write -f ad/library/x-team service_account_names="[email protected],[email protected]" ttl=2h max_ttl=8h

FWIW - The act of creating a role does work.

Has the path been deprecated? Is it specific to a version of Vault? I am on?

We are serving: Vault 1.2.4+prem
My local install of the vault CLI is: Vault v1.3.2+ent

Documentation and code issue for AD secret engine config

Issue Summary

The documentation for the AD secrets engine requires the following:

• binddn a distinguished name for the object that will be bound when attempting to search AD
• bindpass the password for the object identified by the binddn (above)

Additionally there are two optional configuration parameters:

• userdn the distinguished name of the base object (OU) to be used when searching for users
• upndomain a 'user principal name' domain (i.e. suffix of a userPrincipalName)

The documentation for upndomain contains the following:

The constructed UPN will appear as [username]@UPNDomain. Example: example.com, which will cause vault to bind as [email protected].

The first issue is that username doesn't appear in the documentation at all, and thus is confusing for the reader/Vault operator.

The second issue is that if upndomain is supplied then binddn is ignored as a DN, and instead, the value supplied for the binddn and the upndomain are concatenated together with an @ between them. Therefore binddn as a parameter name is misleading in this context.

This causes problems as it requires Vault operators to know that by supplying upndomain (e.g. vaultproject.io) they will be required to 'repurpose' binddn as the prefix for the userPrincipalName (i.e. bob in the userPrincipalName: [email protected]) that should be used to bind to LDAP.

From having a glance at the code, I believe this to be a bug, albeit one that's always been there, also the documentation isn't clear users.

Suggestion:

• Don't try to repurpose the Vault core ldaputil/config fields within this plugin, consider adding additional fields to the plugin/client/config such as binddn, bindupn
• Clarify and improve the public documentation about the priority/precedence of using the config params
• Stretch goal: userdn is also a bit misleading as it's actually just the base DN for searches to start at, it would be awesome if this could be renamed something more intuative such as searchbasedn

Unable to mount this plugin as an external plugin on current Vault master

When I add this plugin to Vault's plugin catalog then try to configure it, I receive:

2019-03-27T10:18:16.561-0700 [DEBUG] secrets.active-directory.active-directory_5b0eacd7.active-directory: starting plugin: path=/home/tbex/go/src/github.com/hashicorp/vault-plugin-secrets-ad/bin/vault-plugin-secrets-active-directory args=[/home/tbex/go/src/github.com/hashicorp/vault-plugin-secrets-ad/bin/vault-plugin-secrets-active-directory]
2019-03-27T10:18:16.562-0700 [DEBUG] secrets.active-directory.active-directory_5b0eacd7.active-directory: plugin started: path=/home/tbex/go/src/github.com/hashicorp/vault-plugin-secrets-ad/bin/vault-plugin-secrets-active-directory pid=25274
2019-03-27T10:18:16.562-0700 [DEBUG] secrets.active-directory.active-directory_5b0eacd7.active-directory: waiting for RPC address: path=/home/tbex/go/src/github.com/hashicorp/vault-plugin-secrets-ad/bin/vault-plugin-secrets-active-directory
2019-03-27T10:18:16.565-0700 [ERROR] secrets.active-directory.active-directory_5b0eacd7.active-directory.vault-plugin-secrets-active-directory: plugin tls init: error="no vault api_addr found" timestamp=2019-03-27T10:18:16.565-0700
2019-03-27T10:18:16.565-0700 [DEBUG] secrets.active-directory.active-directory_5b0eacd7.active-directory: plugin process exited: path=/home/tbex/go/src/github.com/hashicorp/vault-plugin-secrets-ad/bin/vault-plugin-secrets-active-directory pid=25274
2019-03-27T10:18:16.565-0700 [ERROR] core: failed to run existence check: error="plugin exited before we could connect"