Add an unwrap plugin/module

[chrisdola]

SUMMARY

The existing plugins/modules for the HashiVault collection do not provide a method to unwrap a token.

ISSUE TYPE

In some cases, the playbook will be given a wrapped token at execution time that needs to first be unwrapped before calling vault login. There is no ability to call the unwrap endpoint via the hashivault plugins.

COMPONENT NAME

vault_unwrap

ADDITIONAL INFORMATION

It would be much more streamlined if the unwrap endpoint was exposed via a lookup plugin or module so that we don't need to use a basic uri module first to call vault unwrap before using the hashivault plugins.

"{{ lookup('community.hashi_vault.vault_unwrap', url='https://vault', token='wrapped_token') }}"

[briantist]

Hi @chrisdola thanks for opening this feature request. A PR for a lookup and/or module for unwrapping would be welcome if anyone would like to submit it.

In the meantime, you should be able to achieve this by using vault_write against the sys/wrapping/unwrap endpoint.

There is both a module and lookup version of vault_write.

In the documentation for the lookup you can see an example of wrapping a secret, but unwrapping should work just as well. You would want to use token authentication with the call, where the token given is the "wrapped" secret.

I would highly recommend using the module version of vault_write for this purpose though, because the token is one-time-use and it is very easy for lookups to end up being called multiple times due to Ansible's late resolution of templating, see also:

• https://docs.ansible.com/ansible/latest/collections/community/hashi_vault/docsite/lookup_guide.html

[chrisdola]

More than happy to take a look at it. Just didn't want to put in a rando PR without an issue first. :)

[chrisdola]

Are there any guidelines or requirements when it comes to module functionality that you all are trying to follow? Modules must support the ability to pass in multiple tokens as a dict, etc? I didn't see anything on the devel contribution page that stood out, but figured I'd at least make sure. :)

[briantist]

Are there any guidelines or requirements when it comes to module functionality that you all are trying to follow? Modules must support the ability to pass in multiple tokens as a dict, etc? I didn't see anything on the devel contribution page that stood out, but figured I'd at least make sure. :)

For this use case we would not want to support taking in multiple tokens. That would be covered by Ansible's loop support.

There are two ways that the unwrap endpoint can be called:

1. Use the wrapping token as the client token (in our terminology: use the token auth method and set the token option to the wrapping token)
2. Use a different authentication mechanism, and pass the wrapping token as an option (data sent to the endpoint)

The module should support both use cases.

Since the docs say that using the wrapping token in both the client token and token data parameter is not supported (and would render the token useless), we should do checks in the module to ensure that we fail if all of the following are true:

• token auth is used
• a token is provided as data
• the client token and data token match

---

That's all that stands out to me at the moment, other than the general advice of ensuring you have a good local dev environment set up and can run the tests locally so that you aren't always waiting for CI. As a new contributor I will have to approve CI runs for every push. There's some info in the contributor guide on getting set up for local development:

• https://docs.ansible.com/ansible/latest/collections/community/hashi_vault/docsite/contributor_guide.html

I generally look for both unit and integration tests on new content and I target 100% coverage. The existing tests should be very helpful for seeing how that's done and I can usually help figure out any small gaps in coverage.

Thank you for your interest!

[briantist]

Also here are the docs on hvac's unwrap method which you'll be using in the module:

• https://hvac.readthedocs.io/en/stable/usage/system_backend/wrapping.html#unwrap

[chrisdola]

Perfect. Thanks!