cisco.intersight.intersight_ldap_policy module – Manage LDAP Policies for Cisco Intersight

Note

This module is part of the cisco.intersight collection (version 2.18.0).

You might already have this collection installed if you are using the ansible package. It is not included in ansible-core. To check whether it is installed, run ansible-galaxy collection list.

To install it, use: ansible-galaxy collection install cisco.intersight.

To use it in a playbook, specify: cisco.intersight.intersight_ldap_policy.

Synopsis
Parameters
Examples
Return Values

Synopsis

Create, update, and delete LDAP Policies on Cisco Intersight.
Manage LDAP groups and providers associated with LDAP policies.
LDAP policies enable authentication of Cisco IMC users using an LDAP server.
For more information see Cisco Intersight.

Parameters

Parameter	Comments
api_key_id string / required	Public API Key ID associated with the private key. If not set, the value of the INTERSIGHT_API_KEY_ID environment variable is used.
api_private_key path / required	Filename (absolute path) or string of PEM formatted private key data to be used for Intersight API authentication. If a string is used, Ansible vault should be used to encrypt string data. Ex. ansible-vault encrypt_string --vault-id tme@/Users/dsoper/Documents/vault_password_file ‘-----BEGIN EC PRIVATE KEY----- <your private key data> -----END EC PRIVATE KEY-----’ If not set, the value of the INTERSIGHT_API_PRIVATE_KEY environment variable is used.
api_uri string	URI used to access the Intersight API. If not set, the value of the INTERSIGHT_API_URI environment variable is used. Default: `"https://intersight.com/api/v1"`
attribute string	Role and locale information of the user. Required when state is present.
base_dn string	Base Distinguished Name (DN). Starting point from where server will search for users and groups. Required when state is present.
bind_dn string	Distinguished Name (DN) of the user, that is used to authenticate against LDAP servers. Required when bind_method is configuredcredentials.
bind_method string	Authentication method to access LDAP servers. `logincredentials` uses the user credentials entered at login. `anonymous` uses no credentials to access the LDAP server. `configuredcredentials` uses a specific set of credentials configured for the LDAP server. Choices: `"logincredentials"` ← (default) `"anonymous"` `"configuredcredentials"`
description aliases: descr string	The user-defined description for the LDAP Policy. Description can contain letters(a-z, A-Z), numbers(0-9), hyphen(-), period(.), colon(:), or an underscore(_).
dns_source string	Source of the domain name used for the DNS SRV request. `extracted` extracts the domain name from the login ID entered by the user. `configured` uses the configured search domain. `configuredextracted` uses configured search domain first, then extracted. Only applicable when enable_dns is true. Choices: `"extracted"` ← (default) `"configured"` `"configuredextracted"`
domain string	The IPv4 domain that all users must be in. Required when state is present.
enable_dns boolean	Enables DNS to access LDAP servers. When enabled, LDAP providers cannot be specified (DNS discovery is used instead). When disabled, at least one LDAP provider must be configured. Choices: `false` ← (default) `true`
enable_encryption boolean	If enabled, the endpoint encrypts all information it sends to the LDAP server. Choices: `false` ← (default) `true`
enable_ldap boolean	If enabled, LDAP server performs authentication. Choices: `false` `true` ← (default)
filter string	Criteria to identify entries in search requests. Required when state is present.
group_attribute string	Groups to which an LDAP entry belongs. Required when state is present.
group_authorization boolean	If enabled, user authorization is also done at the group level for LDAP users not in the local user database. Choices: `false` ← (default) `true`
ldap_groups list / elements=dictionary	List of LDAP groups to be created and attached to the LDAP policy. Each group defines the mapping between LDAP server groups and Intersight roles.
domain string	LDAP server domain the Group resides in.
group_dn string	LDAP Group DN in the LDAP server database. Required when state is present.
name string / required	LDAP Group name in the LDAP server database.
role string	Role assigned to all users in this LDAP server group. `admin` provides full administrative access. `readonly` provides read-only access. `user` provides standard user access. Only ‘admin’ role is supported in domain. Required when state is present. Choices: `"admin"` ← (default) `"readonly"` `"user"`
state string	Whether to create/update or delete the LDAP group. Choices: `"present"` ← (default) `"absent"`
ldap_providers list / elements=dictionary	List of LDAP providers (servers) to be created and attached to the LDAP policy. Providers define the LDAP servers to connect to. Cannot be specified when enable_dns is true (DNS discovery is used instead). Required when enable_dns is false (at least one provider must be specified).
port integer	Port number on which the LDAP server is listening. Default: `389`
server string / required	IP address or hostname of the LDAP server. Required when state is present.
state string	Whether to create/update or delete the LDAP provider. Choices: `"present"` ← (default) `"absent"`
vendor string	Type of LDAP server. `openldap` for OpenLDAP servers. `msad` for Microsoft Active Directory. Choices: `"openldap"` ← (default) `"msad"`
name string / required	The name assigned to the LDAP Policy. Must be unique within the organization. The name must be between 1 and 62 alphanumeric characters, allowing special characters :-_.
nested_group_search boolean	If enabled, an extended search walks the chain of ancestry all the way to the root. Returns all the groups and subgroups, each of those groups belong to recursively. Choices: `false` ← (default) `true`
nested_group_search_depth integer	Search depth to look for a nested LDAP group in an LDAP group map. Valid range is 1-128. Only applicable when nested_group_search is true. Default: `128`
organization string	The name of the Organization this resource is assigned to. Policies created within a Custom Organization are applicable only to devices in the same Organization. Use ‘default’ for the default organization. Default: `"default"`
password string	The password of the user for initial bind process. Can have any character except spaces, tabs, line breaks. Cannot be more than 254 characters. Required when bind_method is configuredcredentials.
search_domain string	Domain name that acts as a source for a DNS query. Required when dns_source is configured or configuredextracted.
search_forest string	Forest name that acts as a source for a DNS query. Required when dns_source is configured or configuredextracted.
state string	If `present`, will verify the resource is present and will create if needed. If `absent`, will verify the resource is absent and will delete if needed. Choices: `"present"` ← (default) `"absent"`
tags list / elements=dictionary	List of tags in Key:<user-defined key> Value:<user-defined value> format.
timeout integer	LDAP authentication timeout duration, in seconds. Valid range is 0-180. Default: `0`
use_proxy boolean	If `no`, it will not use a proxy, even if one is defined in an environment variable on the target hosts. Choices: `false` `true` ← (default)
user_search_precedence string	Search precedence between local user database and LDAP user database. `localuserdb` searches local user database first. `ldapuserdb` searches LDAP user database first. Choices: `"localuserdb"` ← (default) `"ldapuserdb"`
validate_certs boolean	Boolean control for verifying the api_uri TLS certificate Choices: `false` `true` ← (default)

Examples

- name: Create LDAP Policy with DNS enabled
  cisco.intersight.intersight_ldap_policy:
    api_private_key: "{{ api_private_key }}"
    api_key_id: "{{ api_key_id }}"
    organization: "default"
    name: "ldap-dns-policy"
    description: "LDAP policy using DNS for server discovery"
    enable_ldap: true
    base_dn: "dc=example,dc=com"
    domain: "example.com"
    timeout: 30
    enable_encryption: true
    bind_method: "logincredentials"
    filter: "sAMAccountName"
    group_attribute: "memberOf"
    attribute: "CiscoAvPair"
    group_authorization: true
    nested_group_search: true
    nested_group_search_depth: 64
    enable_dns: true
    dns_source: "configured"
    search_domain: "example.com"
    search_forest: "example.com"
    user_search_precedence: "localuserdb"
    ldap_groups:
      - name: "admin-group"
        group_dn: "cn=admins,ou=groups,dc=example,dc=com"
        domain: "example.com"
        role: "admin"
      - name: "readonly-group"
        group_dn: "cn=readers,ou=groups,dc=example,dc=com"
        role: "readonly"
    tags:
      - Key: "Environment"
        Value: "Production"
    state: present

- name: Create LDAP Policy with providers
  cisco.intersight.intersight_ldap_policy:
    api_private_key: "{{ api_private_key }}"
    api_key_id: "{{ api_key_id }}"
    organization: "default"
    name: "ldap-provider-policy"
    description: "LDAP policy with specific servers"
    enable_ldap: true
    base_dn: "company"
    domain: "company.local"
    timeout: 0
    enable_encryption: false
    bind_method: "anonymous"
    filter: "sAMAccountName"
    group_attribute: "memberOf"
    attribute: "CiscoAvPair"
    group_authorization: false
    nested_group_search: false
    enable_dns: false
    user_search_precedence: "localuserdb"
    ldap_providers:
      - server: "10.10.10.10"
        port: 389
        vendor: "openldap"
      - server: "10.10.10.11"
        port: 389
        vendor: "openldap"
    ldap_groups:
      - name: "users-group"
        group_dn: "company"
        role: "user"
    state: present

- name: Create LDAP Policy with configured credentials
  cisco.intersight.intersight_ldap_policy:
    api_private_key: "{{ api_private_key }}"
    api_key_id: "{{ api_key_id }}"
    organization: "default"
    name: "ldap-configured-creds"
    description: "LDAP policy with configured bind credentials"
    enable_ldap: true
    base_dn: "dc=corp,dc=net"
    domain: "corp.net"
    timeout: 60
    enable_encryption: true
    bind_method: "configuredcredentials"
    bind_dn: "cn=admin,dc=corp,dc=net"
    password: "SecurePassword123"
    filter: "uid"
    group_attribute: "gidNumber"
    attribute: "description"
    group_authorization: true
    nested_group_search: true
    nested_group_search_depth: 128
    enable_dns: false
    user_search_precedence: "ldapuserdb"
    ldap_providers:
      - server: "ldap.corp.net"
        port: 636
        vendor: "msad"
    ldap_groups:
      - name: "administrators"
        group_dn: "cn=administrators,ou=groups,dc=corp,dc=net"
        domain: "corp.net"
        role: "admin"
    state: present

- name: Update LDAP Policy - manage group states
  cisco.intersight.intersight_ldap_policy:
    api_private_key: "{{ api_private_key }}"
    api_key_id: "{{ api_key_id }}"
    organization: "default"
    name: "ldap-dns-policy"
    description: "Updated LDAP policy"
    enable_ldap: true
    base_dn: "dc=example,dc=com"
    domain: "example.com"
    filter: "sAMAccountName"
    group_attribute: "memberOf"
    attribute: "CiscoAvPair"
    enable_dns: true
    ldap_groups:
      - name: "admin-group"
        group_dn: "cn=admins,ou=groups,dc=example,dc=com"
        role: "admin"
        state: present
      - name: "old-group"
        state: absent
      - name: "new-group"
        group_dn: "cn=new,ou=groups,dc=example,dc=com"
        role: "user"
        state: present
    state: present

- name: Delete LDAP Policy
  cisco.intersight.intersight_ldap_policy:
    api_private_key: "{{ api_private_key }}"
    api_key_id: "{{ api_key_id }}"
    name: "old-ldap-policy"
    state: absent

Return Values

Common return values are documented here, the following are the fields unique to this module:

Key	Description
api_response dictionary	The API response output returned by the specified resource. Returned: always Sample: {"api_response": {"BaseProperties": {"Attribute": "CiscoAvPair", "BaseDn": "dc=example,dc=com", "BindMethod": "LoginCredentials", "Domain": "example.com", "EnableEncryption": true, "EnableGroupAuthorization": true, "EnableNestedGroupSearch": true, "Filter": "sAMAccountName", "GroupAttribute": "memberOf", "NestedGroupSearchDepth": 64, "Timeout": 30}, "DnsParameters": {"SearchDomain": "example.com", "SearchForest": "example.com", "Source": "Configured"}, "EnableDns": true, "Enabled": true, "Groups": [{"Domain": "example.com", "GroupDn": "cn=admins,ou=groups,dc=example,dc=com", "Name": "admin-group"}], "Name": "ldap-dns-policy", "ObjectType": "iam.LdapPolicy", "Providers": [], "UserSearchPrecedence": "LocalUserDb"}}

Key

Description

api_response

dictionary

The API response output returned by the specified resource.

Returned: always

Sample: {"api_response": {"BaseProperties": {"Attribute": "CiscoAvPair", "BaseDn": "dc=example,dc=com", "BindMethod": "LoginCredentials", "Domain": "example.com", "EnableEncryption": true, "EnableGroupAuthorization": true, "EnableNestedGroupSearch": true, "Filter": "sAMAccountName", "GroupAttribute": "memberOf", "NestedGroupSearchDepth": 64, "Timeout": 30}, "DnsParameters": {"SearchDomain": "example.com", "SearchForest": "example.com", "Source": "Configured"}, "EnableDns": true, "Enabled": true, "Groups": [{"Domain": "example.com", "GroupDn": "cn=admins,ou=groups,dc=example,dc=com", "Name": "admin-group"}], "Name": "ldap-dns-policy", "ObjectType": "iam.LdapPolicy", "Providers": [], "UserSearchPrecedence": "LocalUserDb"}}

Authors

Ron Gershburg (@rgershbu)

Collection links

© 2012–2018 Michael DeHaan
© 2018–2025 Red Hat, Inc.
Licensed under the GNU General Public License version 3.
https://docs.ansible.com/projects/ansible/latest/collections/cisco/intersight/intersight_ldap_policy_module.html