MS Active Directory

https://github.com/zorn96/ms_active_directory
Admin
MS Active Directory is a Python library designed for integrating with Microsoft Active Directory...
Tokens:59,086
Snippets:419
Trust Score:5.2
License:MIT
Update:2 months ago
Show doc for...
Tokens:
Raw
### Authenticate as a user

Source: https://github.com/zorn96/ms_active_directory/blob/main/docs/source/example_create_session.md

Examples of user authentication using default simple binds or NTLM.

```python
from ldap3 import NTLM
from ms_active_directory import ADDomain
domain = ADDomain('example.com')

session = domain.create_session_as_user('username@example.com', 'password')
ntlm_session =  domain.create_session_as_user('username@example.com', 'password', authentication_mechanism=NTLM)
```

--------------------------------

### Join AD Domain by Taking Over Existing Computer

Source: https://github.com/zorn96/ms_active_directory/blob/main/docs/source/example_join_domain.md

Demonstrates joining a domain using a pre-created account via a standalone function or an ADDomain object.

```python
from ms_active_directory import ADDomain, join_ad_domain_by_taking_over_existing_computer

domain_dns_name = 'example.com'
site = 'us-eastern-dc'
existing_computer_name = 'precreated-comp'
user = 'single-account-admin@example.com'
password = 'password2'

computer_obj = join_ad_domain_by_taking_over_existing_computer(domain_dns_name, user, password,
                                                               ad_site=site, computer_name=existing_computer_name)

# or use a domain object to use various power-user domain features
domain = ADDomain(domain_dns_name, site=site,
                  source_ip='10.25.21.30', dns_nameservers=['10.25.21.20'])
domain.join_by_taking_over_existing_computer(user, password, computer_name=existing_computer_name)
```

--------------------------------

### Add Permission to Computer Security Descriptor

Source: https://github.com/zorn96/ms_active_directory/blob/main/docs/source/ad_session.md

Grants specific permissions to SIDs on a computer object, such as access masks, rights GUIDs, or property read/write access.

```python
add_permission_to_computer_security_descriptor(self, computer: Union[str, ms_active_directory.core.ad_objects.ADComputer], sids_to_grant_permissions_to: List[Union[str, ms_active_directory.environment.security.security_descriptor_utils.ObjectSid, ms_active_directory.environment.security.security_config_constants.WellKnownSID]], access_masks_to_add: List[ms_active_directory.environment.security.security_descriptor_utils.AccessMask] = None, rights_guids_to_add: List[Union[ms_active_directory.environment.security.ad_security_guids.ADRightsGuid, str]] = None, read_property_guids_to_add: List[str] = None, write_property_guids_to_add: List[str] = None, allow_new_permissions: bool = True, raise_exception_on_failure: bool = True, skip_validation: bool = False) -> bool
```

--------------------------------

### Join Domain with Security and Location Customizations

Source: https://github.com/zorn96/ms_active_directory/blob/main/docs/source/example_join_domain.md

Demonstrates joining a domain while specifying encryption types, a custom computer name, and a specific organizational unit location using either LDAP or canonical path formats.

```python
from ms_active_directory import join_ad_domain, ADEncryptionType

domain = 'example.com'
less_privileged_user = 'ops-manager@example.com'
password = 'password2'
# ldap-style relative distinguished name of a location
less_privileged_loc = 'OU=service-machines,OU=ops'
computer_name = 'workstation10'

legacy_enc_type = ADEncryptionType.RC4_HMAC
new_enc_type = ADEncryptionType.AES256_CTS_HMAC_SHA1_96

comp = join_ad_domain(domain, less_privileged_user, password, computer_name=computer_name,
                      computer_location=less_privileged_loc, computer_encryption_types=[legacy_enc_type, new_enc_type])

alt_format_loc = '/ops/service-machines'
comp = join_ad_domain(domain, less_privileged_user, password, computer_name=computer_name,
                      computer_location=alt_format_loc, computer_encryption_types=[legacy_enc_type, new_enc_type])
```

--------------------------------

### Add permissions to a group security descriptor

Source: https://github.com/zorn96/ms_active_directory/blob/main/docs/source/ad_session.md

Use this method to grant or deny specific permissions to SIDs on an Active Directory group. It supports adding access masks, rights GUIDs, and property-specific read/write permissions.

```python
add_permission_to_group_security_descriptor(self, group, sids_to_grant_permissions_to: List[Union[str, ms_active_directory.environment.security.security_descriptor_utils.ObjectSid, ms_active_directory.environment.security.security_config_constants.WellKnownSID]], access_masks_to_add: List[ms_active_directory.environment.security.security_descriptor_utils.AccessMask] = None, rights_guids_to_add: List[Union[ms_active_directory.environment.security.ad_security_guids.ADRightsGuid, str]] = None, read_property_guids_to_add: List[str] = None, write_property_guids_to_add: List[str] = None, allow_new_permissions: bool = True, raise_exception_on_failure: bool = True, skip_validation: bool = False) -> bool
```

--------------------------------

### Join an AD domain with default configurations

Source: https://github.com/zorn96/ms_active_directory/blob/main/docs/source/example_join_domain.md

Uses the local hostname and default AD containers to join the domain. Requires administrative credentials and writes the resulting kerberos keys to /etc/krb5.keytab.

```python
from ms_active_directory import join_ad_domain

comp = join_ad_domain('example.com', 'Administrator@example.com', 'example-password')
```

--------------------------------

### ADDomain.__init__

Source: https://github.com/zorn96/ms_active_directory/blob/main/docs/source/ad_domain.md

Initializes an interface for defining an AD domain and interacting with it.

```APIDOC
## ADDomain.__init__

### Description
Initializes an interface for defining an AD domain and interacting with it.

### Parameters
- **domain** (str) - Required - The domain name.
- **site** (str) - Optional - The site name.
- **ldap_servers_or_uris** (List) - Optional - List of LDAP servers or URIs.
- **kerberos_uris** (List[str]) - Optional - List of Kerberos URIs.
- **encrypt_connections** (bool) - Optional - Whether to encrypt connections (default: True).
- **ca_certificates_file_path** (str) - Optional - Path to CA certificates file.
- **discover_ldap_servers** (bool) - Optional - Whether to discover LDAP servers (default: True).
- **discover_kerberos_servers** (bool) - Optional - Whether to discover Kerberos servers (default: True).
- **dns_nameservers** (List[str]) - Optional - List of DNS nameservers.
- **source_ip** (str) - Optional - Source IP address.
- **netbios_name** (str) - Optional - NetBIOS name.
- **auto_configure_kerberos_client** (bool) - Optional - Whether to auto-configure the Kerberos client (default: False).
```

--------------------------------

### Authenticate as a computer using NTLM

Source: https://github.com/zorn96/ms_active_directory/blob/main/docs/source/example_create_session.md

Shows how to use NTLM authentication for computer sessions.

```python
from ldap3 import NTLM
from ms_active_directory import ADDomain
domain = ADDomain('example.com')

ntlm_name = 'EXAMPLE.COM\computer01'
password = 'password1'
session = domain.create_session_as_computer(ntlm_name, password, authentication_mechanism=NTLM)
```

--------------------------------

### Importing the join_ad_domain_by_taking_over_existing_computer function

Source: https://github.com/zorn96/ms_active_directory/blob/main/docs/source/join_ad_domain_by_taking_over_existing_computer.md

Import the standalone function directly from the library to initiate the domain join process.

```python
>>> from ms_active_directory import join_ad_domain_by_taking_over_existing_computer
```

--------------------------------

### Join Domain with Manual Password and Key Path

Source: https://github.com/zorn96/ms_active_directory/blob/main/docs/source/example_join_domain.md

Shows how to override the default random password generation and specify a custom file path for the Kerberos keytab.

```python
from ms_active_directory import join_ad_domain

domain = 'example.com'
user = 'ops-manager@example.com'
password = 'password2'
kerberos_key_location = '/usr/shared/keys/workstation-key.keytab'
computer_name = 'workstation10'
computer_password = 'workstation-shared-pw'

comp = join_ad_domain(domain, user, password, computer_key_file_path=kerberos_key_location,
                      computer_name=computer_name, computer_password=computer_password)
```

--------------------------------

### Create user session with simple bind or NTLM

Source: https://github.com/zorn96/ms_active_directory/blob/main/README.md

Authenticates a user session using simple binds by default, or NTLM.

```python
from ldap3 import NTLM
from ms_active_directory import ADDomain
domain = ADDomain('example.com')

session = domain.create_session_as_user('username@example.com', 'password')
ntlm_session =  domain.create_session_as_user('username@example.com', 'password',
                                              authentication_mechanism=NTLM)
```

--------------------------------

### join_ad_domain_by_taking_over_existing_computer_using_session

Source: https://github.com/zorn96/ms_active_directory/blob/main/docs/source/join_ad_domain_by_taking_over_existing_computer_using_session.md

Joins the local machine to an AD domain by taking over a pre-created computer account using an existing AD session.

```APIDOC
## join_ad_domain_by_taking_over_existing_computer_using_session(ad_session, computer_name=None, computer_password=None, old_computer_password=None, computer_key_file_path='/etc/krb5.keytab')

### Description
This function joins the local machine to an AD domain by taking over a pre-created computer account. It is useful for scenarios where the computer account is pre-configured in the domain.

### Parameters
- **ad_session** (ms_active_directory.core.ad_session.ADSession) - Required - The ADSession object representing a connection with the domain.
- **computer_name** (str) - Optional - The sAMAccountName of the computer to take over. Defaults to the local system's hostname.
- **computer_password** (str) - Optional - The password to set for the computer. If not provided, a random 120-character password is generated.
- **old_computer_password** (str) - Optional - The current password of the computer. Providing this allows for a 'change password' operation instead of a 'reset password' operation, requiring fewer permissions.
- **computer_key_file_path** (str) - Optional - The path to write the generated keytab file. Defaults to '/etc/krb5.keytab'.

### Returns
- **ManagedADComputer** - An object representing the computer that was taken over.
```

--------------------------------

### Join Domain by Taking Over Existing Computer

Source: https://github.com/zorn96/ms_active_directory/blob/main/docs/source/ad_domain.md

Use this function to join a domain by taking over an existing computer account. It requires administrative credentials and supports various authentication mechanisms.

```default
join_by_taking_over_existing_computer(self, admin_username: str, admin_password: str = None,
                                      authentication_mechanism: str = 'SIMPLE', computer_name: str = None,
                                      computer_password: str = None, old_computer_password: str = None,
                                      computer_key_file_path: str = '/etc/krb5.keytab',
                                      **additional_connection_attributes) -> ms_active_directory.core.managed_ad_objects.ManagedADComputer

    A super simple 'join the domain' function that requires minimal input - just admin user credentials
    to use in the join process.
    Given those basic inputs, the domain's settings are used to establish a connection, and an account is taken over
    based on inputs. The account's attributes are then read and used to generate kerberos keys and set other attributes
    of the returned object.
    :param admin_username: The username of a user or computer with the rights to reset the password of the computer
                           being taken over.
                           This username should be formatted based on the authentication protocol being used.
                           For example, DOMAIN\username for NTLM as opposed to username@DOMAIN for GSSAPI, or
                           a distinguished name for SIMPLE.
                           If `old_computer_password` is specified, then this account only needs permission to
                           change the password of the computer being taken over, which is different from the reset
                           password permission.
    :param admin_password: The password for the user. Optional, as SASL authentication mechanisms can use
                           `sasl_credentials` specified as a keyword argument, and things like KERBEROS will use
                           default system kerberos credentials if they're available.
    :param authentication_mechanism: An LDAP authentication mechanism or SASL mechanism. If 'SASL' is specified,
                                     then the keyword argument `sasl_mechanism` must also be specified. Valid values
                                     include all authentication mechanisms and SASL mechanisms from the ldap3
                                     library, such as SIMPLE, NTLM, KERBEROS, etc.
    :param computer_name: The name of the computer to take over in the domain. This should be the sAMAccountName
                          of the computer, though if computer has a trailing $ in its sAMAccountName and that is
                          omitted, that's ok. If not specified, we will attempt to find a computer with a name
                          matching the local system's hostname.
    :param computer_password: The password to set for the computer when taking it over. If not specified, a random
                              120 character password will be generated and set.
    :param old_computer_password: The current password of the computer being taken over. If specified, the action
                                  of taking over the computer will use a "change password" operation, which is less
                                  privileged than a "reset password" operation. So specifying this reduces the
                                  permissions needed by the user specified.
    :param computer_key_file_path: The path of where to write the keytab file for the computer after taking it over.
                                   This will include keys for both user and server keys for the computer.
                                   If not specified, defaults to /etc/krb5.keytab
    :param additional_connection_attributes: Additional keyword arguments may be specified for any properties of
                                             the `Connection` object from the `ldap3` library that is desired to
                                             be set on the connection used in the session created for taking over
                                             the computer. Examples include `sasl_credentials`, `client_strategy`,
                                             `cred_store`, and `pool_lifetime`.
    :returns: A ManagedADComputer object representing the computer taken over.
```

--------------------------------

### join_ad_domain(domain_dns_name, admin_username, admin_password, ...)

Source: https://github.com/zorn96/ms_active_directory/blob/main/docs/source/join_ad_domain.md

Joins the local machine to an Active Directory domain by creating a new computer account. It automatically discovers domain controllers and configures the account with strong security defaults.

```APIDOC
## join_ad_domain

### Description
A function to join a machine to an AD domain. It creates a new computer account, sets a strong random password, enables encryption, and generates Kerberos keys.

### Signature
`join_ad_domain(domain_dns_name: str, admin_username: str, admin_password: str, authentication_mechanism: str = 'SIMPLE', ad_site: str = None, computer_name: str = None, computer_location: str = None, computer_password: str = None, computer_encryption_types: List[Union[str, ADEncryptionType]] = None, computer_hostnames: List[str] = None, computer_services: List[str] = None, supports_legacy_behavior: bool = False, computer_key_file_path: str = '/etc/krb5.keytab', **additional_account_attributes) -> ManagedADComputer`

### Parameters
- **domain_dns_name** (str) - Required - The DNS name of the domain being joined.
- **admin_username** (str) - Required - The username with rights to create the computer account.
- **admin_password** (str) - Optional - The password for the admin user.
- **authentication_mechanism** (str) - Optional - LDAP or SASL authentication mechanism (e.g., 'SIMPLE', 'NTLM', 'KERBEROS').
- **ad_site** (str) - Optional - The AD site to confine communication.
- **computer_name** (str) - Optional - The sAMAccountName of the computer.
- **computer_location** (str) - Optional - LDAP-style RDN or Windows canonical path for the computer object.
- **computer_password** (str) - Optional - Password to set for the computer account.
- **computer_key_file_path** (str) - Optional - Path to write the generated Kerberos keytab (default: /etc/krb5.keytab).

### Returns
- **ManagedADComputer** - An object providing helper functions for managing the created computer account.
```

--------------------------------

### Discovering Domain Servers with Smart Defaults

Source: https://github.com/zorn96/ms_active_directory/blob/main/docs/source/example_discover_domain.md

Initializes an ADDomain object to automatically discover and sort LDAP and Kerberos servers using system DNS.

```python
from ms_active_directory import ADDomain

example_domain_dns_name = 'example.com'
domain = ADDomain(example_domain_dns_name)
ldap_servers = domain.get_ldap_uris()
kerberos_servers = domain.get_kerberos_uris()

# re-discover servers in dns and sort them by RTT again at a later time to pick up changes
domain.refresh_ldap_server_discovery()
domain.refresh_kerberos_server_discovery()
```

--------------------------------

### Initialize ADDomain object

Source: https://github.com/zorn96/ms_active_directory/blob/main/docs/source/ad_domain.md

Constructor for defining an AD domain interface and configuring connection parameters.

```default
class ADDomain(builtins.object)

    __init__(self, domain: str, site: str = None,
             ldap_servers_or_uris: List = None,
             kerberos_uris: List[str] = None,
             encrypt_connections: bool = True,
             ca_certificates_file_path: str = None,
             discover_ldap_servers: bool = True,
             discover_kerberos_servers: bool = True,
             dns_nameservers: List[str] = None,
             source_ip: str = None,
             netbios_name: str = None,
             auto_configure_kerberos_client: bool = False)
        Initializes an interface for defining an AD domain and interacting with it.
```

--------------------------------

### Join domain by taking over an existing account

Source: https://github.com/zorn96/ms_active_directory/blob/main/README.md

Allows joining by taking over a pre-created computer account, which can restrict the required permissions for the joining user account.

```python
from ms_active_directory import ADDomain, join_ad_domain_by_taking_over_existing_computer

domain_dns_name = 'example.com'
site = 'us-eastern-dc'
existing_computer_name = 'precreated-comp'
user = 'single-account-admin@example.com'
password = 'password2'

computer_obj = join_ad_domain_by_taking_over_existing_computer(domain_dns_name, user, password,
                                                               ad_site=site, computer_name=existing_computer_name)
                                                               
# or use a domain object to use various power-user domain features
domain = ADDomain(domain_dns_name, site=site,
                  source_ip='10.25.21.30', dns_nameservers=['10.25.21.20'])
domain.join_by_taking_over_existing_computer(user, password, computer_name=existing_computer_name)
```

--------------------------------

### Enable Account

Source: https://github.com/zorn96/ms_active_directory/blob/main/docs/source/ad_session.md

Enables a specified user or computer account.

```default
enable_account(self, account: Union[str, ms_active_directory.core.ad_objects.ADComputer, ms_active_directory.core.ad_objects.ADUser]) -> bool
    Enable a user account.
    :param account: The string name of the user/computer account to enable. This may either be a
                    sAMAccountName, a distinguished name, or a unique common name. This can also be an ADObject,
                    and the distinguished name will be extracted from it.
    :returns: True if the operation succeeds. If the operation fails, either an exception will be raised or False
              will be returned depending on whether the ldap connection for this session has "raise_exceptions"
              set to True or not.
```

--------------------------------

### join(self, admin_username, admin_password, ...)

Source: https://github.com/zorn96/ms_active_directory/blob/main/docs/source/ad_domain.md

Joins the local machine to an Active Directory domain, creating a computer object with specified or default attributes.

```APIDOC
## join(admin_username, admin_password, ...)

### Description
Joins the local machine to a domain. This action creates a computer object in the domain representing the local machine and configures Kerberos keys.

### Parameters
- **admin_username** (str) - Required - The username of a user or computer with rights to create the computer.
- **admin_password** (str) - Optional - The password for the user.
- **authentication_mechanism** (str) - Optional - LDAP or SASL authentication mechanism (e.g., 'SIMPLE', 'NTLM', 'KERBEROS'). Defaults to 'SIMPLE'.
- **computer_name** (str) - Optional - The sAMAccountName of the computer to take over.
- **computer_location** (str) - Optional - The LDAP-style RDN or Windows canonical path where the computer object will be created.
- **computer_password** (str) - Optional - The password to set for the computer. If omitted, a random 120-character password is generated.
- **computer_encryption_types** (List) - Optional - List of encryption types (AES256-SHA1, AES128-SHA1, RC4-HMAC) to enable.

### Returns
- **ManagedADComputer** - An object providing helper functions for managing the created computer account.
```

--------------------------------

### Joining a domain with join_ad_domain

Source: https://github.com/zorn96/ms_active_directory/blob/main/docs/source/join_ad_domain.md

Use this function to join the machine to a domain, creating a new computer account with default security settings and Kerberos key generation.

```default
join_ad_domain(domain_dns_name: str, admin_username: str, admin_password: str, authentication_mechanism: str = 'SIMPLE',
               ad_site: str = None, computer_name: str = None, computer_location: str = None, computer_password: str = None,
               computer_encryption_types: List[Union[str, ms_active_directory.environment.security.security_config_constants.ADEncryptionType]] = None,
               computer_hostnames: List[str] = None, computer_services: List[str] = None,
               supports_legacy_behavior: bool = False, computer_key_file_path: str = '/etc/krb5.keytab',
               **additional_account_attributes) -> ms_active_directory.core.managed_ad_objects.ManagedADComputer
```

--------------------------------

### Importing the join function

Source: https://github.com/zorn96/ms_active_directory/blob/main/docs/source/join_ad_domain_using_session.md

Import the standalone function directly from the library to initiate the domain join process.

```default
>>> from ms_active_directory import join_ad_domain_using_session
```

--------------------------------

### join_by_taking_over_existing_computer

Source: https://github.com/zorn96/ms_active_directory/blob/main/docs/source/ad_domain.md

A function to join a domain by taking over an existing computer account using administrative credentials.

```APIDOC
## join_by_taking_over_existing_computer

### Description
This function performs a domain join by taking over an existing computer account. It requires administrative credentials to establish a connection and update the computer account attributes.

### Signature
`join_by_taking_over_existing_computer(admin_username: str, admin_password: str = None, authentication_mechanism: str = 'SIMPLE', computer_name: str = None, computer_password: str = None, old_computer_password: str = None, computer_key_file_path: str = '/etc/krb5.keytab', **additional_connection_attributes) -> ManagedADComputer`

### Parameters
- **admin_username** (str) - Required - The username of a user or computer with rights to reset the computer password.
- **admin_password** (str) - Optional - The password for the admin user.
- **authentication_mechanism** (str) - Optional - LDAP or SASL authentication mechanism (e.g., 'SIMPLE', 'NTLM', 'KERBEROS'). Defaults to 'SIMPLE'.
- **computer_name** (str) - Optional - The sAMAccountName of the computer to take over. Defaults to local hostname.
- **computer_password** (str) - Optional - The password to set for the computer. If omitted, a random 120-character password is generated.
- **old_computer_password** (str) - Optional - The current password of the computer. If provided, a 'change password' operation is used instead of 'reset password'.
- **computer_key_file_path** (str) - Optional - Path to write the keytab file. Defaults to '/etc/krb5.keytab'.
- **additional_connection_attributes** (dict) - Optional - Additional keyword arguments for the ldap3 Connection object.

### Returns
- **ManagedADComputer** - An object representing the computer that was taken over.
```

--------------------------------

### join_ad_domain_by_taking_over_existing_computer

Source: https://github.com/zorn96/ms_active_directory/blob/main/docs/source/join_ad_domain_by_taking_over_existing_computer.md

Joins an Active Directory domain by taking over an existing computer account using provided admin credentials.

```APIDOC
## join_ad_domain_by_taking_over_existing_computer

### Description
A function to join an Active Directory domain by taking over an existing computer account. It automatically discovers domain controllers and configures the local system to represent the computer account in the domain.

### Signature
`join_ad_domain_by_taking_over_existing_computer(domain_dns_name: str, admin_username: str, admin_password: str, authentication_mechanism: str = 'SIMPLE', ad_site: str = None, computer_name: str = None, computer_password: str = None, old_computer_password: str = None, computer_key_file_path: str = '/etc/krb5.keytab', **additional_connection_attributes) -> ms_active_directory.core.managed_ad_objects.ManagedADComputer`

### Parameters
- **domain_dns_name** (str) - Required - The DNS name of the domain being joined.
- **admin_username** (str) - Required - The username of a user or computer with rights to reset the computer password.
- **admin_password** (str) - Required - The password for the admin user.
- **authentication_mechanism** (str) - Optional - LDAP or SASL authentication mechanism (default: 'SIMPLE').
- **ad_site** (str) - Optional - The site within the AD domain for communication.
- **computer_name** (str) - Optional - The sAMAccountName of the computer to take over.
- **computer_password** (str) - Optional - The new password to set for the computer.
- **old_computer_password** (str) - Optional - The current password of the computer (enables change password operation).
- **computer_key_file_path** (str) - Optional - Path to write the keytab file (default: '/etc/krb5.keytab').
- **additional_connection_attributes** (dict) - Optional - Additional keyword arguments for the ldap3 Connection object.

### Returns
- **ManagedADComputer** - An object representing the computer taken over.
```

--------------------------------

### Importing the join function

Source: https://github.com/zorn96/ms_active_directory/blob/main/docs/source/join_ad_domain_by_taking_over_existing_computer_using_session.md

Import the standalone function directly from the library to join an AD domain using an existing session.

```default
>>> from ms_active_directory import join_ad_domain_by_taking_over_existing_computer_using_session
```

--------------------------------

### Authenticate as a computer

Source: https://github.com/zorn96/ms_active_directory/blob/main/docs/source/example_create_session.md

Demonstrates computer authentication using default Kerberos or explicit SASL credentials.

```python
from ms_active_directory import ADDomain
domain = ADDomain('example.com')

# when using kerberos auth, the default is to use the kerberos
# credential cache on the machine, so no password is needed
computer_name = 'machine01'
session1 = domain.create_session_as_computer(computer_name)

# but you can pass sasl credentials, and if you use gssapi you can
# specify a username and password
# see the ldap3 documentation for details on SASL credentials and other
# connection options
other_name = 'other-machine-identity'
password = 'password01'
session2 = domain.create_session_as_computer(other_name, sasl_credentials=('', other_name, password))
```

--------------------------------

### Create LDAP connection as computer

Source: https://github.com/zorn96/ms_active_directory/blob/main/docs/source/ad_domain.md

Establishes an LDAP connection authenticated as a specific computer account.

```default
create_ldap_connection_as_computer(self, computer_name: str, computer_password: str = None,
                                   check_name_format: bool = True, authentication_mechanism: str = 'GSSAPI',
                                   **kwargs) -> ldap3.core.connection.Connection
    Create an LDAP connection with AD domain authenticated as the specified computer.

    :param computer_name: The name of the computer to use when authenticating with the domain.
    :param computer_password: Optional, the password of the computer to use when authenticating with the domain.
                              If using an authentication mechanism like NTLM, this must be specified. But for
                              authentication mechanisms such as kerberos or external, either `sasl_credentials`
                              can be specified as a keyword argument or default system credentials will be used
                              in accordance with the auth mechanism.
    :param check_name_format: If True, the `computer_name` will be processed to try and format it based on the
                              authentication mechanism in use. For NTLM we will try to format it as
                              `domain`\`computer_name`, and for Kerberos/GSSAPI we will try to format is ass
                              `computer_name`@`domain`.
                              Defaults to True.
    :param authentication_mechanism: An LDAP authentication mechanism or SASL mechanism. If 'SASL' is specified,
                                     then the keyword argument `sasl_mechanism` must also be specified. Valid values
                                     include all authentication mechanisms and SASL mechanisms from the ldap3
                                     library, such as SIMPLE, NTLM, KERBEROS, etc.
    :returns: A Connection object representing a ldap connection with the domain.
```

--------------------------------

### Join a domain using ADDomain

Source: https://github.com/zorn96/ms_active_directory/blob/main/docs/source/ad_domain.md

Use this function to join the local machine to a domain, creating a computer object with default or custom security configurations.

```default
join(self, admin_username: str, admin_password: str, authentication_mechanism: str = 'SIMPLE',
     computer_name: str = None, computer_location: str = None, computer_password: str = None,
     computer_encryption_types: List[Union[str, ms_active_directory.environment.security.security_config_constants.ADEncryptionType]] = None,
     computer_hostnames: List[str] = None, computer_services: List[str] = None,
     supports_legacy_behavior: bool = False, computer_key_file_path: str = '/etc/krb5.keytab',
     **additional_account_attributes) -> ms_active_directory.core.managed_ad_objects.ManagedADComputer
```

--------------------------------

### Join domain with custom network and service settings

Source: https://github.com/zorn96/ms_active_directory/blob/main/docs/source/example_join_domain.md

Use join_ad_domain to specify custom hostnames and services. Joining will fail if specified services or hostnames conflict with existing domain objects.

```python
from ms_active_directory import join_ad_domain

domain = 'example.com'
user = 'ops-manager@example.com'
password = 'password2'

services = ['HOST', 'nfs', 'cifs', 'HTTP']
computer_name = 'workstation10'
computer_host1 = 'central-mount-point.example.com'
computer_host2 = 'example-web-server.example.com'
comp = join_ad_domain(domain, user, password, computer_name=computer_name,
                      computer_hostnames=[computer_host1, computer_host2],
                      computer_services=services)
```

--------------------------------

### create_computer

Source: https://github.com/zorn96/ms_active_directory/blob/main/docs/source/ad_session.md

Creates a new computer object in the Active Directory domain and returns a ManagedADComputer instance.

```APIDOC
## create_computer(computer_name, computer_location=None, computer_password=None, encryption_types=None, hostnames=None, services=None, supports_legacy_behavior=False, **additional_account_attributes)

### Description
Creates a computer in the domain and returns a computer object. This method handles the configuration of service principal names, encryption types, and account attributes.

### Parameters
- **computer_name** (str) - Required - The common name of the computer to create.
- **computer_location** (str) - Optional - The distinguished name of the location where the computer will be created.
- **computer_password** (str) - Optional - The password for the computer account.
- **encryption_types** (List[Union[str, ADEncryptionType]]) - Optional - Encryption types supported by the computer.
- **hostnames** (List[str]) - Optional - Hostnames for configuring service principal names.
- **services** (List[str]) - Optional - Services to enable on each hostname.
- **supports_legacy_behavior** (bool) - Optional - Whether to support legacy behaviors like NTLM.
- **additional_account_attributes** (dict) - Optional - Additional LDAP attributes to set on the account.

### Returns
- **ManagedADComputer** - An object representing the created computer.

### Raises
- **DomainJoinException** - If validation fails or conflicts occur.
- **ObjectCreationException** - If creation fails due to external factors like permissions.
```

--------------------------------

### Importing the join_ad_domain function

Source: https://github.com/zorn96/ms_active_directory/blob/main/docs/source/join_ad_domain.md

Import the standalone function directly from the library to initiate the domain join process.

```default
>>> from ms_active_directory import join_ad_domain
```

--------------------------------

### join_ad_domain_using_session

Source: https://github.com/zorn96/ms_active_directory/blob/main/docs/source/join_ad_domain_using_session.md

Joins the local machine to an AD domain using an existing AD session, creating a new computer account with configurable attributes.

```APIDOC
## join_ad_domain_using_session(ad_session, computer_name=None, computer_location=None, computer_password=None, computer_encryption_types=None, computer_hostnames=None, computer_services=None, supports_legacy_behavior=False, computer_key_file_path='/etc/krb5.keytab', **additional_account_attributes)

### Description
Joins the local machine to an Active Directory domain by creating a new computer account. This function leverages an existing AD session, allowing for flexible connection methods without requiring direct user credentials.

### Parameters
- **ad_session** (ADSession) - Required - The ADSession object representing a connection with the domain to be joined.
- **computer_name** (str) - Optional - The sAMAccountName of the computer. Defaults to the local system's hostname.
- **computer_location** (str) - Optional - The LDAP-style RDN or Windows canonical path where the computer account will be created. Defaults to CN=Computers.
- **computer_password** (str) - Optional - The password for the computer account. Defaults to a random 120-character string.
- **computer_encryption_types** (list) - Optional - A list of encryption types (e.g., AES256-SHA1, AES128-SHA1, RC4-HMAC). Defaults to [AES256-SHA1].
- **computer_hostnames** (list) - Optional - Hostnames to set for the computer in AD. Defaults to [computer_name, computer_name.domain].
- **computer_services** (list) - Optional - Services to enable on the computer's hostnames to set service principal names.
- **supports_legacy_behavior** (bool) - Optional - Flag to enable legacy behavior. Defaults to False.
- **computer_key_file_path** (str) - Optional - Path to write the generated Kerberos keytab. Defaults to /etc/krb5.keytab.
- **additional_account_attributes** (dict) - Optional - Additional attributes to set on the computer account.

### Returns
- **ManagedADComputer** - An object providing helper functions for managing the created computer and its keys.
```

--------------------------------

### ADSession.__init__

Source: https://github.com/zorn96/ms_active_directory/blob/main/docs/source/ad_session.md

Initializes a new ADSession object to manage communication with an Active Directory domain.

```APIDOC
## ADSession(ldap_connection, domain, search_paging_size=100, trusted_domain_cache_lifetime_seconds=86400)

### Description
Creates a session object for a connection to an AD domain. This object handles the state for LDAP operations and multi-domain functionality.

### Parameters
- **ldap_connection** (ldap3.core.connection.Connection) - Required - An ldap3 Connection object representing the connection to LDAP servers.
- **domain** (ADDomain) - Required - An ADDomain object representing the domain.
- **search_paging_size** (int) - Optional - The page size for paginated searches. Defaults to 100.
- **trusted_domain_cache_lifetime_seconds** (int) - Optional - Lifetime of the trusted domain cache in seconds. Defaults to 86400 (24 hours).
```

--------------------------------

### Join Domain with Security Customizations

Source: https://github.com/zorn96/ms_active_directory/blob/main/README.md

Configures specific encryption types, custom computer names, and alternative organizational unit locations for the computer account.

```python
from ms_active_directory import join_ad_domain, ADEncryptionType

domain = 'example.com'
less_privileged_user = 'ops-manager@example.com'
password = 'password2'
# ldap-style relative distinguished name of a location
less_privileged_loc = 'OU=service-machines,OU=ops'
computer_name = 'workstation10'

legacy_enc_type = ADEncryptionType.RC4_HMAC
new_enc_type = ADEncryptionType.AES256_CTS_HMAC_SHA1_96

comp = join_ad_domain(domain, less_privileged_user, password, computer_name=computer_name,
                      computer_location=less_privileged_loc, computer_encryption_types=[legacy_enc_type, new_enc_type])
                      
alt_format_loc = '/ops/service-machines'
comp = join_ad_domain(domain, less_privileged_user, password, computer_name=computer_name,
                      computer_location=alt_format_loc, computer_encryption_types=[legacy_enc_type, new_enc_type])
```

--------------------------------

### Configuring Site Awareness and Custom DNS

Source: https://github.com/zorn96/ms_active_directory/blob/main/docs/source/example_discover_domain.md

Limits server discovery to a specific Active Directory site and overrides system DNS with custom nameservers.

```python
from ms_active_directory import ADDomain

example_domain_dns_name = 'example.com'
site_name = 'us-eastern-datacenter'
domain = ADDomain(example_domain_dns_name, site=site_name,
                  dns_nameservers=['eastern-private-dns-01.local'])
```

--------------------------------

### Function signature for join_ad_domain_using_session

Source: https://github.com/zorn96/ms_active_directory/blob/main/docs/source/join_ad_domain_using_session.md

The function signature and parameter documentation for joining a domain using an existing session.

```default
join_ad_domain_using_session(ad_session: ms_active_directory.core.ad_session.ADSession, computer_name=None, computer_location=None,
                             computer_password=None, computer_encryption_types=None, computer_hostnames=None,
                             computer_services=None, supports_legacy_behavior=False, computer_key_file_path='/etc/krb5.keytab',
                             **additional_account_attributes) -> ms_active_directory.core.managed_ad_objects.ManagedADComputer
    A fairly simple 'join a domain' function that requires minimal input - an AD session.
    Given those basic inputs, the domain's nearest controllers are automatically discovered and an account is made
    with strong security settings. The account's attributes follow AD naming conventions based on the computer's
    hostname by default.
    By providing an AD session, one can build a connection to the domain however they so choose and then use it to
    join this computer, so you don't even need to necessarily use user credentials.
    :param ad_session: The ADSession object representing a connection with the domain to be joined.
    :param computer_name: The name of the computer to take over in the domain. This should be the sAMAccountName
                          of the computer, though if computer has a trailing $ in its sAMAccountName and that is
                          omitted, that's ok. If not specified, we will attempt to find a computer with a name
                          matching the local system's hostname.
    :param computer_location: The location in which to create the computer. This may be specified as an LDAP-style
                              relative distinguished name (e.g. OU=ServiceMachines,OU=Machines) or a windows path
                              style canonical name (e.g. example.com/Machines/ServiceMachines).
                              If not specified, defaults to CN=Computers which is the standard default for AD.
    :param computer_password: The password to set for the computer when taking it over. If not specified, a random
                              120 character password will be generated and set.
    :param computer_encryption_types: A list of encryption types, based on the ADEncryptionType enum, to enable on
                                      the account created. These may be strings or enums; if they are strings,
                                      they should be strings of the encryption types as written in kerberos
                                      RFCs or in AD management tools, and we will try to map them to enums and
                                      raise an error if they don't match any supported values.
                                      AES256-SHA1, AES128-SHA1, and RC4-HMAC encryption types are supported. DES
                                      encryption types aren not.
                                      If not specified, defaults to [AES256-SHA1].
    :param computer_hostnames: Hostnames to set for the computer. These will be used to set the dns hostname
                               attribute in AD. If not specified, the computer hostnames will default to
                               [`computer_name`, `computer_name`.`domain`] which is the AD standard default.
    :param computer_services: Services to enable on the computers hostnames. These services dictate what clients
                              can get kerberos tickets for when communicating with this computer, and this property
                              is used with `computer_hostnames` to set the service principal names for the computer.
```

--------------------------------

### Create LDAP connection as user

Source: https://github.com/zorn96/ms_active_directory/blob/main/docs/source/ad_domain.md

Establishes an LDAP connection authenticated as a specific user account.

```default
create_ldap_connection_as_user(self, user: str = None, password: str = None, authentication_mechanism: str = None,
                               **kwargs) -> ldap3.core.connection.Connection
    Create an LDAP connection with AD domain authenticated as the specified user.

    :param user: The name of the user to use when authenticating with the domain. This should be formatted based
                 on the authentication mechanism. For example, kerberos authentication expects username@domain,
                 NTLM expects domain\\username, and simple authentication can use a distinguished name,
                 username@domain, or other formats based on your domain's settings.
                 If not specified, anonymous authentication will be used. If specified, SIMPLE authentication
                 will be used by default if authentication_mechanism is not specified.
    :param password: The password to use when authenticating with the domain.
                     If not specified, anonymous authentication will be used. If specified, SIMPLE authentication
                     will be used by default if authentication_mechanism is not specified.
    :param authentication_mechanism: An LDAP authentication mechanism or SASL mechanism. If 'SASL' is specified,
                                     then the keyword argument `sasl_mechanism` must also be specified. Valid values
                                     include all authentication mechanisms and SASL mechanisms from the ldap3
                                     library, such as SIMPLE, NTLM, KERBEROS, etc.
    :param kwargs: Additional keyword arguments can be specified for any of the arguments to an ldap3 Connection
                   object and they will be used. This can be used to set things like `client_strategy` or
                   `pool_name`.
    :return: An ldap3 Connection object representing a connection with the domain.
```

--------------------------------

### ADDomain Constructor

Source: https://github.com/zorn96/ms_active_directory/blob/main/docs/source/ad_domain.md

Initializes a new ADDomain object to represent an Active Directory domain. The only required parameter is the domain DNS name.

```APIDOC
## ADDomain(domain, site=None, ldap_servers_or_uris=None, kerberos_uris=None, encrypt_connections=True, ca_certificates_file_path=None, discover_ldap_servers=True, discover_kerberos_servers=True, dns_nameservers=None, source_ip=None, netbios_name=None, auto_configure_kerberos_client=False)

### Description
Creates an ADDomain object representing a specific Active Directory domain. This object handles server discovery, connection management, and configuration for domain operations.

### Parameters
- **domain** (string) - Required - The DNS name of the Active Directory domain.
- **site** (string) - Optional - The Active Directory site to operate within.
- **ldap_servers_or_uris** (list) - Optional - List of ldap3 Server objects or LDAP URIs.
- **kerberos_uris** (list) - Optional - List of kerberos server URIs.
- **encrypt_connections** (boolean) - Optional - Whether to secure LDAP connections with TLS. Defaults to True.
- **ca_certificates_file_path** (string) - Optional - Path to CA certificates for TLS trust.
- **discover_ldap_servers** (boolean) - Optional - Whether to discover LDAP servers via DNS. Defaults to True.
- **discover_kerberos_servers** (boolean) - Optional - Whether to discover Kerberos servers via DNS. Defaults to True.
- **dns_nameservers** (list) - Optional - List of DNS server IP addresses.
- **source_ip** (string) - Optional - Source IP address for DNS and LDAP connections.
- **netbios_name** (string) - Optional - The NetBIOS name of the domain.
- **auto_configure_kerberos_client** (boolean) - Optional - Whether to automatically configure the local system for Kerberos communication.
```

--------------------------------

### take_over_existing_computer

Source: https://github.com/zorn96/ms_active_directory/blob/main/docs/source/ad_session.md

Takes over a computer in the domain by resetting its password and returning a ManagedADComputer object.

```APIDOC
## take_over_existing_computer(computer, computer_password=None, old_computer_password=None)

### Description
Use the session to take over a computer in the domain and return a computer object. This resets the computer's password to prevent impersonation and reads attributes to return a ManagedADComputer object.

### Parameters
- **computer** (Union[ManagedADComputer, ADObject, str]) - Required - The computer object or identifier (common name, sAMAccountName, or distinguished name).
- **computer_password** (str) - Optional - The password to set for the computer. If not specified, a random 120-character password is generated.
- **old_computer_password** (str) - Optional - The current password for the computer, used to reduce required permissions.

### Returns
- **ManagedADComputer** - An object representing the taken-over computer.

### Raises
- **DomainJoinException** - If validation fails or attributes conflict.
- **ObjectNotFoundException** - If the computer cannot be found.
```

--------------------------------

### Initialize ADSession

Source: https://github.com/zorn96/ms_active_directory/blob/main/docs/source/ad_session.md

Create an ADSession object using an existing LDAP connection and domain object.

```default
class ADSession(builtins.object)
    ADSession(ldap_connection: ldap3.core.connection.Connection, domain: 'ADDomain', search_paging_size: int = 100, trusted_domain_cache_lifetime_seconds: int = 86400)

    Methods defined here:

    __init__(self, ldap_connection: ldap3.core.connection.Connection, domain: 'ADDomain', search_paging_size: int = 100, trusted_domain_cache_lifetime_seconds: int = 86400)
        Create a session object for a connection to an AD domain.
        Given an LDAP connection, a domain, and optional parameters relating to searches and multi-domain
        functionality, create an ADSession object.

        :param ldap_connection: An ldap3 Connection object representing the connection to LDAP servers within
                                the domain.
        :param domain: An ADDomain object representing the domain that we're communicating with.
        :param search_paging_size: Optional. The page size for paginated searches. If a search is expected to
                                   be able to have more than this many results, a paginated search will be
                                   performed. This is used as the page size in such searches. Changing this
                                   affects the balance between the number of queries made and the size of
                                   each query response in a large scale environment, and so it can be used
                                   to optimize behavior based on network topology and traffic.
                                   If not specified, defaults to 100.
        :param trusted_domain_cache_lifetime_seconds: Optional. How long to maintain our trusted domain cache in
                                                      seconds. The cache of trusted domain information exists because
                                                      trust relationships change infrequently, but will be used a lot
                                                      in searches and such when automatic traversal of trusts is
                                                      supported. Can be set to 0 to disable the cache.
                                                      If not specified, defaults to 24 hours.
```

--------------------------------

### enable_account

Source: https://github.com/zorn96/ms_active_directory/blob/main/docs/source/ad_session.md

Enables a specified user or computer account.

```APIDOC
## enable_account(account)

### Description
Enables a user or computer account in Active Directory.

### Parameters
- **account** (Union[str, ADUser, ADComputer]) - Required - The account name (sAMAccountName, DN, or CN) or object to enable.

### Returns
- **bool** - True if the operation succeeds.
```

--------------------------------

### create_session_as_computer

Source: https://github.com/zorn96/ms_active_directory/blob/main/docs/source/ad_domain.md

Creates a session with the AD domain authenticated as a specified computer, providing additional checks for computer-specific restrictions.

```APIDOC
## create_session_as_computer(computer_name: str, computer_password: str = None, check_name_format: bool = True, authentication_mechanism: str = 'GSSAPI', **kwargs) -> ADSession

### Description
Creates a session with the AD domain authenticated as the specified computer.

### Parameters
- **computer_name** (str) - Required - The name of the computer to use when authenticating.
- **computer_password** (str) - Optional - The password of the computer. Required for NTLM.
- **check_name_format** (bool) - Optional - If True, formats the computer name based on the authentication mechanism. Defaults to True.
- **authentication_mechanism** (str) - Optional - LDAP or SASL authentication mechanism (e.g., SIMPLE, NTLM, KERBEROS). Defaults to 'GSSAPI'.
- **kwargs** (dict) - Optional - Additional keyword arguments for the underlying connection.

### Returns
- **ADSession** - An object representing a connection with the domain.
```
Tokens:
Raw