Skip to content

Commit bedff7c

Browse files
LDAP secret engine support (#1032) (#1033)
* Initial commit for LDAP secrets engine No dynamic role support yet * Fix docs and linting issues * Fix linting error * Run tests with docker container so we don't need to install vault Use LDAP server in docker as well Configure Vault/LDAP with terraform Added LDAP tests - not yet finished * More tests * Fix indentation * Fix client not being available * Various test fixes * Reverting the changes prior to implementing unit tests * Reverting the changes prior to implementing unit tests * Reverting the changes prior to implementing unit tests * Unit tests for LDAP secrets * Reverting the changes prior to implementing unit tests * Linting * Fix newline? * Fix newline? * Fix linting * Apply suggestions from code review Documentation updates * Update hvac/api/secrets_engines/ldap.py remove unused args/kwargs * nit: remove docs character * remove use of arbitrary kwargs * use example.com in tests * add unit test for generate_static_credentials --------- Co-authored-by: Brian Scholer <[email protected]>
1 parent 781156f commit bedff7c

5 files changed

Lines changed: 662 additions & 0 deletions

File tree

‎docs/usage/secrets_engines/index.rst‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -10,6 +10,7 @@ Secrets Engines
1010
database
1111
gcp
1212
identity
13+
ldap
1314
pki
1415
kv
1516
kv_v1
Lines changed: 146 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,146 @@
1+
LDAP
2+
================
3+
4+
.. contents::
5+
6+
Configure LDAP Secrets Secrets Engine
7+
-------------------------------------
8+
9+
Configure the LDAP secrets engine to either manage service accounts or service account libraries.
10+
11+
Source reference: :py:meth:`hvac.api.secrets_engines.ldap.configure`
12+
13+
.. code:: python
14+
15+
import hvac
16+
client = hvac.Client()
17+
18+
# Authenticate to Vault using client.auth.x
19+
20+
# Not all these settings may apply to your setup, refer to Vault
21+
# documentation for context of what to use here
22+
23+
config_response = client.secrets.ldap.configure(
24+
binddn='[email protected]', # A upn or DN can be used for this value, Vault resolves the user to a dn silently
25+
bindpass='***********',
26+
url='ldaps://domain.fqdn',
27+
userdn='cn=Users,dn=domain,dn=fqdn',
28+
upndomain='domain.fqdn',
29+
userattr="cn",
30+
schema="openldap"
31+
)
32+
print(config_response)
33+
34+
35+
Read Config
36+
-----------
37+
38+
Return the LDAP Secret Engine configuration.
39+
40+
Source reference: :py:meth:`hvac.api.secrets_engines.ldap.read_config`
41+
42+
.. code:: python
43+
44+
import hvac
45+
client = hvac.Client()
46+
47+
# Authenticate to Vault using client.auth.x
48+
49+
config_response = client.secrets.ldap.read_config()
50+
51+
52+
Create or Update Static Role
53+
----------------------------
54+
55+
Create or Update a role which allows the retrieval and rotation of an LDAP account. Retrieve and rotate the actual credential via generate_static_credentials().
56+
57+
Source reference: :py:meth:`hvac.api.secrets_engines.ldap.create_or_update_static_role`
58+
59+
.. code:: python
60+
61+
import hvac
62+
client = hvac.Client()
63+
64+
# Authenticate to Vault using client.auth.x
65+
66+
role_response = client.secrets.ldap.create_or_update_static_role(
67+
name='hvac-role',
68+
username='sql-service-account',
69+
dn='cn=sql-service-account,dc=petshop,dc=com',
70+
rotation_period="60s")
71+
72+
73+
Read Static Role
74+
----------------
75+
76+
Retrieve the role configuration which allows the retrieval and rotation of an LDAP account. Retrieve and rotate the actual credential via generate_static_credentials().
77+
78+
Source reference: :py:meth:`hvac.api.secrets_engines.ldap.read_static_role`
79+
80+
.. code:: python
81+
82+
import hvac
83+
client = hvac.Client()
84+
85+
# Authenticate to Vault using client.auth.x
86+
87+
role_response = client.secrets.ldap.read_static_role(name='sql-service-account')
88+
89+
90+
List Static Roles
91+
-----------------
92+
93+
List all configured roles which allows the retrieval and rotation of an LDAP account. Retrieve and rotate the actual credential via generate_static_credentials().
94+
95+
Source reference: :py:meth:`hvac.api.secrets_engines.ldap.list_static_roles`
96+
97+
.. code:: python
98+
99+
import hvac
100+
client = hvac.Client()
101+
102+
# Authenticate to Vault using client.auth.x
103+
104+
all_static_roles = client.secrets.ldap.list_static_roles()
105+
106+
107+
Delete Static Role
108+
------------------
109+
110+
Remove the role configuration which allows the retrieval and rotation of an LDAP account.
111+
112+
Passwords are not rotated upon deletion of a static role. The password should be manually rotated prior to deleting the role or revoking access to the static role.
113+
114+
Source reference: :py:meth:`hvac.api.secrets_engines.ldap.delete_static_role`
115+
116+
.. code:: python
117+
118+
import hvac
119+
client = hvac.Client()
120+
121+
# Authenticate to Vault using client.auth.x
122+
123+
deletion_response = client.secrets.ldap.delete_static_role(name='sql-service-account')
124+
125+
Generate Static Credentials
126+
---------------------------
127+
128+
Retrieve a service account password from LDAP. Return the previous password (if known). Vault shall rotate
129+
the password before returning it, if it has breached its configured ttl.
130+
131+
Source reference: :py:meth:`hvac.api.secrets_engines.ldap.generate_static_credentials`
132+
133+
.. code:: python
134+
135+
import hvac
136+
client = hvac.Client()
137+
138+
# Authenticate to Vault using client.auth.x
139+
140+
gen_creds_response = client.secrets.ldap.generate_static_credentials(
141+
name='hvac-role',
142+
)
143+
print('Retrieved Service Account Password: {access} (Current) / {secret} (Old)'.format(
144+
access=gen_creds_response['data']['current_password'],
145+
secret=gen_creds_response['data']['old_password'],
146+
))

‎hvac/api/secrets_engines/__init__.py‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -9,6 +9,7 @@
99
from hvac.api.secrets_engines.kv import Kv
1010
from hvac.api.secrets_engines.kv_v1 import KvV1
1111
from hvac.api.secrets_engines.kv_v2 import KvV2
12+
from hvac.api.secrets_engines.ldap import Ldap
1213
from hvac.api.secrets_engines.pki import Pki
1314
from hvac.api.secrets_engines.rabbitmq import RabbitMQ
1415
from hvac.api.secrets_engines.ssh import Ssh
@@ -25,6 +26,7 @@
2526
"Kv",
2627
"KvV1",
2728
"KvV2",
29+
"Ldap",
2830
"Pki",
2931
"Transform",
3032
"Transit",
@@ -45,6 +47,7 @@ class SecretsEngines(VaultApiCategory):
4547
ActiveDirectory,
4648
Identity,
4749
Kv,
50+
Ldap,
4851
Pki,
4952
Transform,
5053
Transit,

‎hvac/api/secrets_engines/ldap.py‎

Lines changed: 193 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,193 @@
1+
#!/usr/bin/env python
2+
"""LDAP methods module."""
3+
4+
from hvac import utils
5+
from hvac.api.vault_api_base import VaultApiBase
6+
7+
DEFAULT_MOUNT_POINT = "ldap"
8+
9+
10+
class Ldap(VaultApiBase):
11+
"""LDAP Secrets Engine (API).
12+
Reference: https://www.vaultproject.io/api/secret/ldap/index.html
13+
"""
14+
15+
def configure(
16+
self,
17+
binddn=None,
18+
bindpass=None,
19+
url=None,
20+
password_policy=None,
21+
schema=None,
22+
userdn=None,
23+
userattr=None,
24+
upndomain=None,
25+
mount_point=DEFAULT_MOUNT_POINT,
26+
):
27+
"""Configure shared information for the ldap secrets engine.
28+
29+
Supported methods:
30+
POST: /{mount_point}/config. Produces: 204 (empty body)
31+
32+
:param binddn: Distinguished name of object to bind when performing user and group search.
33+
:type binddn: str | unicode
34+
:param bindpass: Password to use along with binddn when performing user search.
35+
:type bindpass: str | unicode
36+
:param url: Base DN under which to perform user search.
37+
:type url: str | unicode
38+
:param userdn: Base DN under which to perform user search.
39+
:type userdn: str | unicode
40+
:param upndomain: userPrincipalDomain used to construct the UPN string for the authenticating user.
41+
:type upndomain: str | unicode
42+
:param password_policy: The name of the password policy to use to generate passwords.
43+
:type password_policy: str | unicode
44+
:param schema: The LDAP schema to use when storing entry passwords. Valid schemas include ``openldap``, ``ad``, and ``racf``.
45+
:type schema: str | unicode
46+
:param mount_point: The "path" the method/backend was mounted on.
47+
:type mount_point: str | unicode
48+
:return: The response of the request.
49+
:rtype: requests.Response
50+
"""
51+
params = utils.remove_nones(
52+
{
53+
"binddn": binddn,
54+
"bindpass": bindpass,
55+
"url": url,
56+
"userdn": userdn,
57+
"userattr": userattr,
58+
"upndomain": upndomain,
59+
"password_policy": password_policy,
60+
"schema": schema,
61+
}
62+
)
63+
64+
api_path = utils.format_url("/v1/{mount_point}/config", mount_point=mount_point)
65+
return self._adapter.post(
66+
url=api_path,
67+
json=params,
68+
)
69+
70+
def read_config(self, mount_point=DEFAULT_MOUNT_POINT):
71+
"""Read the configured shared information for the ldap secrets engine.
72+
73+
Credentials will be omitted from returned data.
74+
75+
Supported methods:
76+
GET: /{mount_point}/config. Produces: 200 application/json
77+
78+
:param mount_point: The "path" the method/backend was mounted on.
79+
:type mount_point: str | unicode
80+
:return: The JSON response of the request.
81+
:rtype: dict
82+
"""
83+
api_path = utils.format_url("/v1/{mount_point}/config", mount_point=mount_point)
84+
return self._adapter.get(
85+
url=api_path,
86+
)
87+
88+
def rotate_root(self, mount_point=DEFAULT_MOUNT_POINT):
89+
"""Rotate the root password for the binddn entry used to manage the ldap secrets engine.
90+
91+
Supported methods:
92+
POST: /{mount_point}/rotate root. Produces: 200 application/json
93+
94+
:param mount_point: The "path" the method/backend was mounted on.
95+
:type mount_point: str | unicode
96+
:return: The JSON response of the request.
97+
:rtype: dict
98+
"""
99+
api_path = utils.format_url(
100+
"/v1/{mount_point}/rotate-root", mount_point=mount_point
101+
)
102+
return self._adapter.post(url=api_path)
103+
104+
def create_or_update_static_role(
105+
self,
106+
name,
107+
username=None,
108+
dn=None,
109+
rotation_period=None,
110+
mount_point=DEFAULT_MOUNT_POINT,
111+
):
112+
"""This endpoint creates or updates the ldap static role definition.
113+
114+
:param name: Specifies the name of an existing static role against which to create this ldap credential.
115+
:type name: str | unicode
116+
:param username: The name of a pre-existing service account in LDAP that maps to this static role.
117+
This value is required on create and cannot be updated.
118+
:type username: str | unicode
119+
:param dn: Distinguished name of the existing LDAP entry to manage password rotation for (takes precedence over username).
120+
Optional but cannot be modified after creation.
121+
:type dn: str | unicode
122+
:param rotation_period: How often Vault should rotate the password.
123+
This is provided as a string duration with a time suffix like "30s" or "1h" or as seconds.
124+
If not provided, the default Vault rotation_period is used.
125+
:type rotation_period: str | unicode
126+
:param mount_point: Specifies the place where the secrets engine will be accessible (default: ad).
127+
:type mount_point: str | unicode
128+
:return: The response of the request.
129+
:rtype: requests.Response
130+
"""
131+
api_path = utils.format_url("/v1/{}/static-role/{}", mount_point, name)
132+
params = {"username": username, "rotation_period": rotation_period}
133+
params.update(utils.remove_nones({"dn": dn}))
134+
return self._adapter.post(
135+
url=api_path,
136+
json=params,
137+
)
138+
139+
def read_static_role(self, name, mount_point=DEFAULT_MOUNT_POINT):
140+
"""This endpoint queries for information about an ldap static role with the given name.
141+
If no role exists with that name, a 404 is returned.
142+
:param name: Specifies the name of the static role to query.
143+
:type name: str | unicode
144+
:param mount_point: Specifies the place where the secrets engine will be accessible (default: ad).
145+
:type mount_point: str | unicode
146+
:return: The response of the request.
147+
:rtype: requests.Response
148+
"""
149+
api_path = utils.format_url("/v1/{}/static-role/{}", mount_point, name)
150+
return self._adapter.get(
151+
url=api_path,
152+
)
153+
154+
def list_static_roles(self, mount_point=DEFAULT_MOUNT_POINT):
155+
"""This endpoint lists all existing static roles in the secrets engine.
156+
:return: The response of the request.
157+
:rtype: requests.Response
158+
"""
159+
api_path = utils.format_url("/v1/{}/static-role", mount_point)
160+
return self._adapter.list(
161+
url=api_path,
162+
)
163+
164+
def delete_static_role(self, name, mount_point=DEFAULT_MOUNT_POINT):
165+
"""This endpoint deletes an ldap static role with the given name.
166+
Even if the role does not exist, this endpoint will still return a successful response.
167+
:param name: Specifies the name of the role to delete.
168+
:type name: str | unicode
169+
:param mount_point: Specifies the place where the secrets engine will be accessible (default: ad).
170+
:type mount_point: str | unicode
171+
:return: The response of the request.
172+
:rtype: requests.Response
173+
"""
174+
api_path = utils.format_url("/v1/{}/static-role/{}", mount_point, name)
175+
return self._adapter.delete(
176+
url=api_path,
177+
)
178+
179+
def generate_static_credentials(self, name, mount_point=DEFAULT_MOUNT_POINT):
180+
"""This endpoint retrieves the previous and current LDAP password for
181+
the associated account (or rotate if required)
182+
183+
:param name: Specifies the name of the static role to request credentials from.
184+
:type name: str | unicode
185+
:param mount_point: Specifies the place where the secrets engine will be accessible (default: ad).
186+
:type mount_point: str | unicode
187+
:return: The response of the request.
188+
:rtype: requests.Response
189+
"""
190+
api_path = utils.format_url("/v1/{}/static-cred/{}", mount_point, name)
191+
return self._adapter.get(
192+
url=api_path,
193+
)

0 commit comments

Comments
 (0)