ldap auth method - add missing configure params by vault api names

hvac/api/auth_methods/ldap.py

@@ -12,40 +12,130 @@ class Ldap(VaultApiBase):
     Reference: https://www.vaultproject.io/api/auth/ldap/index.html
     """
 
+    @utils.aliased_parameter(
+        "userdn", "user_dn", removed_in_version="3.0.0", position=1
+    )
+    @utils.aliased_parameter(
+        "groupdn", "group_dn", removed_in_version="3.0.0", position=2
+    )
+    @utils.aliased_parameter(
+        "binddn", "bind_dn", removed_in_version="3.0.0", position=10
+    )
+    @utils.aliased_parameter(
+        "bindpass", "bind_pass", removed_in_version="3.0.0", position=11
+    )
+    @utils.aliased_parameter(
+        "userattr", "user_attr", removed_in_version="3.0.0", position=12
+    )
+    @utils.aliased_parameter(
+        "discoverdn", "discover_dn", removed_in_version="3.0.0", position=13
+    )
+    @utils.aliased_parameter(
+        "upndomain", "upn_domain", removed_in_version="3.0.0", position=15
+    )
+    @utils.aliased_parameter(
+        "groupfilter", "group_filter", removed_in_version="3.0.0", position=16
+    )
+    @utils.aliased_parameter(
+        "groupattr", "group_attr", removed_in_version="3.0.0", position=17
+    )
     def configure(
         self,
-        user_dn=None,
-        group_dn=None,
+        userdn=None,
+        groupdn=None,
         url=None,
         case_sensitive_names=None,
         starttls=None,
         tls_min_version=None,
         tls_max_version=None,
         insecure_tls=None,
         certificate=None,
-        bind_dn=None,
-        bind_pass=None,
-        user_attr=None,
-        discover_dn=None,
+        binddn=None,
+        bindpass=None,
+        userattr=None,
+        discoverdn=None,
         deny_null_bind=True,
-        upn_domain=None,
-        group_filter=None,
-        group_attr=None,
+        upndomain=None,
+        groupfilter=None,
+        groupattr=None,
         use_token_groups=None,
         token_ttl=None,
         token_max_ttl=None,
         mount_point=DEFAULT_MOUNT_POINT,
+        *,
+        anonymous_group_search=None,
+        client_tls_cert=None,
+        client_tls_key=None,
+        connection_timeout=None,
+        dereference_aliases=None,
+        max_page_size=None,
+        request_timeout=None,
+        token_bound_cidrs=None,
+        token_explicit_max_ttl=None,
+        token_no_default_policy=None,
+        token_num_uses=None,
+        token_period=None,
+        token_policies=None,
+        token_type=None,
+        userfilter=None,
+        username_as_alias=None,
     ):
         """
         Configure the LDAP auth method.
 
         Supported methods:
             POST: /auth/{mount_point}/config. Produces: 204 (empty body)
 
-        :param user_dn: Base DN under which to perform user search. Example: ou=Users,dc=example,dc=com
+        :param anonymous_group_search: Use anonymous binds when performing LDAP group searches (note: even when true,
+            the initial credentials will still be used for the initial connection test).
+        :type anonymous_group_search: bool
+        :param client_tls_cert: Client certificate to provide to the LDAP server, must be x509 PEM encoded.
+        :type client_tls_cert: str | unicode
+        :param client_tls_key: Client certificate key to provide to the LDAP server, must be x509 PEM encoded.
+        :type client_tls_key: str | unicode
+        :param connection_timeout: Timeout, in seconds, when attempting to connect to the LDAP server before trying the
+            next URL in the configuration.
+        :type connection_timeout: int
+        :param dereference_aliases: When aliases should be dereferenced on search operations.
+            Accepted values are 'never', 'finding', 'searching', 'always'.
+        :type dereference_aliases: str | unicode
+        :param max_page_size: If set to a value greater than 0, the LDAP backend will use the LDAP server's paged search
+            control to request pages of up to the given size.
+        :type max_page_size: int
+        :param request_timeout: Timeout, in seconds, for the connection when making requests against the server before
+            returning back an error.
+        :type request_timeout: str | unicode
+        :param token_bound_cidrs: List of CIDR blocks; if set, specifies blocks of IP addresses which can authenticate
+            successfully, and ties the resulting token to these blocks as well.
+        :type token_bound_cidrs: list
+        :param token_explicit_max_ttl: If set, will encode an explicit max TTL onto the token. This is a hard cap even
+            if token_ttl and token_max_ttl would otherwise allow a renewal.
+        :type token_explicit_max_ttl: str | unicode
+        :param token_no_default_policy: If set, the default policy will not be set on generated tokens; otherwise it
+            will be added to the policies set in token_policies.
+        :type token_no_default_policy: bool
+        :param token_num_uses: The maximum number of times a generated token may be used (within its lifetime); 0 means
+            unlimited.
+        :type token_num_uses: int
+        :param token_period: The maximum allowed period value when a periodic token is requested from this role.
+        :type token_period: str | unicode
+        :param token_policies: List of token policies to encode onto generated tokens.
+        :type token_policies: list
+        :param token_type: The type of token that should be generated.
+        :type token_type: str | unicode
+        :param userfilter: An optional LDAP user search filter.
+        :type userfilter: str | unicode
+        :param username_as_alias: If set to true, forces the auth method to use the username passed by the user as the
+            alias name.
+        :type username_as_alias: bool
+        :param userdn: Base DN under which to perform user search. Example: ou=Users,dc=example,dc=com
+        :type userdn: str | unicode
+        :param user_dn: Alias for userdn. This alias will be removed in v3.0.0.
         :type user_dn: str | unicode
-        :param group_dn: LDAP search base to use for group membership search. This can be the root containing either
+        :param groupdn: LDAP search base to use for group membership search. This can be the root containing either
             groups or users. Example: ou=Groups,dc=example,dc=com
+        :type groupdn: str | unicode
+        :param group_dn: Alias for groupdn. This alias will be removed in v3.0.0.
         :type group_dn: str | unicode
         :param url: The LDAP server to connect to. Examples: ldap://ldap.myorg.com, ldaps://ldap.myorg.com:636.
             Multiple URLs can be specified with commas, e.g. ldap://ldap.myorg.com,ldap://ldap2.myorg.com; these will be
@@ -65,31 +155,45 @@ def configure(
         :type insecure_tls: bool
         :param certificate: CA certificate to use when verifying LDAP server certificate, must be x509 PEM encoded.
         :type certificate: str | unicode
-        :param bind_dn: Distinguished name of object to bind when performing user search. Example:
+        :param binddn: Distinguished name of object to bind when performing user search. Example:
             cn=vault,ou=Users,dc=example,dc=com
+        :type binddn: str | unicode
+        :param bind_dn: Alias for binddn. This alias will be removed in v3.0.0.
         :type bind_dn: str | unicode
-        :param bind_pass:  Password to use along with binddn when performing user search.
+        :param bindpass:  Password to use along with binddn when performing user search.
+        :type bindpass: str | unicode
+        :param bind_pass: Alias for bindpass. This alias will be removed in v3.0.0.
         :type bind_pass: str | unicode
-        :param user_attr: Attribute on user attribute object matching the username passed when authenticating. Examples:
+        :param userattr: Attribute on user attribute object matching the username passed when authenticating. Examples:
             sAMAccountName, cn, uid
+        :type userattr: str | unicode
+        :param user_attr: Alias for userattr. This alias will be removed in v3.0.0.
         :type user_attr: str | unicode
-        :param discover_dn: Use anonymous bind to discover the bind DN of a user.
+        :param discoverdn: Use anonymous bind to discover the bind DN of a user.
+        :type discoverdn: bool
+        :param discover_dn: Alias for discoverdn. This alias will be removed in v3.0.0.
         :type discover_dn: bool
         :param deny_null_bind: This option prevents users from bypassing authentication when providing an empty password.
         :type deny_null_bind: bool
-        :param upn_domain: The userPrincipalDomain used to construct the UPN string for the authenticating user. The
+        :param upndomain: The userPrincipalDomain used to construct the UPN string for the authenticating user. The
             constructed UPN will appear as [username]@UPNDomain. Example: example.com, which will cause vault to bind as
             username@example.com.
+        :type upndomain: str | unicode
+        :param upn_domain: Alias for upndomain. This alias will be removed in v3.0.0.
         :type upn_domain: str | unicode
-        :param group_filter: Go template used when constructing the group membership query. The template can access the
+        :param groupfilter: Go template used when constructing the group membership query. The template can access the
             following context variables: [UserDN, Username]. The default is
             `(|(memberUid={{.Username}})(member={{.UserDN}})(uniqueMember={{.UserDN}}))`, which is compatible with several
             common directory schemas. To support nested group resolution for Active Directory, instead use the following
             query: (&(objectClass=group)(member:1.2.840.113556.1.4.1941:={{.UserDN}})).
+        :type groupfilter: str | unicode
+        :param group_filter: Alias for groupfilter. This alias will be removed in v3.0.0.
         :type group_filter: str | unicode
-        :param group_attr: LDAP attribute to follow on objects returned by groupfilter in order to enumerate user group
+        :param groupattr: LDAP attribute to follow on objects returned by groupfilter in order to enumerate user group
             membership. Examples: for groupfilter queries returning group objects, use: cn. For queries returning user
             objects, use: memberOf. The default is cn.
+        :type groupattr: str | unicode
+        :param group_attr: Alias for groupattr. This alias will be removed in v3.0.0.
         :type group_attr: str | unicode
         :param use_token_groups: If true, groups are resolved through Active Directory tokens. This may speed up nested
             group membership resolution in large directories.
@@ -106,26 +210,41 @@ def configure(
         params = utils.remove_nones(
             {
                 "url": url,
-                "userdn": user_dn,
-                "groupdn": group_dn,
+                "anonymous_group_search": anonymous_group_search,
+                "binddn": binddn,
+                "bindpass": bindpass,
                 "case_sensitive_names": case_sensitive_names,
-                "starttls": starttls,
-                "tls_min_version": tls_min_version,
-                "tls_max_version": tls_max_version,
-                "insecure_tls": insecure_tls,
                 "certificate": certificate,
-                "userattr": user_attr,
-                "discoverdn": discover_dn,
+                "client_tls_cert": client_tls_cert,
+                "client_tls_key": client_tls_key,
+                "connection_timeout": connection_timeout,
                 "deny_null_bind": deny_null_bind,
-                "groupfilter": group_filter,
-                "groupattr": group_attr,
-                "upndomain": upn_domain,
-                "binddn": bind_dn,
-                "bindpass": bind_pass,
-                "certificate": certificate,
-                "use_token_groups": use_token_groups,
-                "token_ttl": token_ttl,
+                "dereference_aliases": dereference_aliases,
+                "discoverdn": discoverdn,
+                "groupattr": groupattr,
+                "groupdn": groupdn,
+                "groupfilter": groupfilter,
+                "insecure_tls": insecure_tls,
+                "max_page_size": max_page_size,
+                "request_timeout": request_timeout,
+                "starttls": starttls,
+                "tls_max_version": tls_max_version,
+                "tls_min_version": tls_min_version,
+                "token_bound_cidrs": token_bound_cidrs,
+                "token_explicit_max_ttl": token_explicit_max_ttl,
                 "token_max_ttl": token_max_ttl,
+                "token_no_default_policy": token_no_default_policy,
+                "token_num_uses": token_num_uses,
+                "token_period": token_period,
+                "token_policies": token_policies,
+                "token_ttl": token_ttl,
+                "token_type": token_type,
+                "upndomain": upndomain,
+                "use_token_groups": use_token_groups,
+                "userattr": userattr,
+                "userdn": userdn,
+                "userfilter": userfilter,
+                "username_as_alias": username_as_alias,
             }
         )
 

hvac/utils.py

@@ -49,6 +49,113 @@ def raise_for_error(
     )
 
 
+def aliased_parameter(
+    name, *aliases, removed_in_version, position=None, raise_on_multiple=True
+):
+    """A decorator that can be used to define one or more aliases for a parameter,
+    and optionally display a deprecation warning when aliases are used.
+    It can also optionally raise an exception if a value is supplied via multiple names.
+    LIMITATIONS:
+    If the canonical parameter can be specified unnamed (positionally),
+    then its position must be set to correctly detect multiple use and apply precedence.
+    To set multiple aliases with different values for the optional parameters, use the decorator multiple times with the same name.
+    This method will only work properly when the alias parameter is set as a keyword (named) arg, therefore the function in question
+    should ensure that any aliases come after \\*args or bare \\* (marking keyword-only arguments: https://peps.python.org/pep-3102/).
+    Note also that aliases do not have to appear in the original function's argument list.
+
+    :param name: The canonical name of the parameter.
+    :type name: str
+    :param aliases: One or more alias names for the parameter.
+    :type aliases: str
+    :param removed_in_version: The version in which the alias will be removed. This should typically have a value.
+        In the rare case that an alias is not deprecated, set this to None.
+    :type removed_in_version: str | None
+    :param position: The 0-based position of the canonical argument if it could be specified positionally. Use None for a keyword-only (named) argument.
+    :type position: int
+    :param raise_on_multiple: When True (default), raise an exception if a value is supplied via multiple names.
+    :type raise_on_multiple: bool
+    """
+
+    def decorator(method):
+        @functools.wraps(method)
+        def wrapper(*args, **kwargs):
+            has_canonical = False
+            try:
+                kwargs[name]
+            except KeyError:
+                if position is not None:
+                    try:
+                        args[position]
+                    except IndexError:
+                        pass
+                    else:
+                        has_canonical = True
+            else:
+                has_canonical = True
+
+            # At this point if has_canonical is True, we'll never use an alias value,
+            # but we're still looping so we can catch duplicates or deprecated aliases.
+            for alias in aliases:
+                if alias in kwargs:
+                    # do deprecation before (potentially) raising on a duplicate to aid the user in choosing the right parameter.
+                    if removed_in_version is not None:
+                        deprecation_message = generate_parameter_deprecation_message(
+                            to_be_removed_in_version=removed_in_version,
+                            old_parameter_name=alias,
+                            new_parameter_name=name,
+                        )
+                        warnings.warn(
+                            message=deprecation_message,
+                            category=DeprecationWarning,
+                            stacklevel=2,
+                        )
+
+                    if not (has_canonical or name in kwargs):
+                        kwargs[name] = kwargs[alias]
+                    else:
+                        if raise_on_multiple:
+                            raise ValueError(
+                                f"Parameter '{name}' was given a duplicate value via alias '{alias}'."
+                            )
+
+                    del kwargs[alias]
+
+            return method(*args, **kwargs)
+
+        return wrapper
+
+    return decorator
+
+
+def generate_parameter_deprecation_message(
+    to_be_removed_in_version,
+    old_parameter_name,
+    new_parameter_name=None,
+    extra_notes=None,
+):
+    """Generate a message to be used when warning about the use of deprecated paramers.
+
+    :param to_be_removed_in_version: Version of this module the deprecated parameter will be removed in.
+    :type to_be_removed_in_version: str
+    :param old_parameter_name: Deprecated parameter name.
+    :type old_parameter_name: str
+    :param new_parameter_name: Parameter intended to replace the deprecated parameter, if applicable.
+    :type new_parameter_name: str | None
+    :param extra_notes: Optional freeform text used to provide additional context, alternatives, or notes.
+    :type extra_notes: str | None
+    :return: Full deprecation warning message for the indicated parameter.
+    :rtype: str
+    """
+
+    message = f"Value supplied for deprecated parameter '{old_parameter_name}'. This parameter will be removed in version '{to_be_removed_in_version}'."
+    if new_parameter_name is not None:
+        message += f" Please use the '{new_parameter_name}' parameter moving forward."
+    if extra_notes is not None:
+        message += f" {extra_notes}"
+
+    return message
+
+
 def generate_method_deprecation_message(
     to_be_removed_in_version, old_method_name, method_name=None, module_name=None
 ):