ActiveDirectory Class

Properties   Methods   Events   Config Settings   Errors  

The ActiveDirectory class can be used to authenticate users against Active Directory using Kerberos 5.0.

Syntax

class ipworksauth.ActiveDirectory

Remarks

The ActiveDirectory class authenticates users against Active Directory. Authentication is performed using the Kerberos protocol defined in RFC 1510 and RFC 4120.

Authentication

When authenticate is called the class will attempt to authenticate the user with the Active Directory server. The class will communicate with the ad_host to obtain a service ticket and populate auth_token. The following properties are required when calling this method:

• spn (required)
• user (required)
• password (required)
• ad_host (required)

A typical sequence of messages would be:

• KRB_AS_REQ -> KDC
• KRB_AS_REP <- KDC
• KRB_TGS_REQ -> KDC
• KRB_TGS_REP <- KDC
• auth_token is populated with the constructed KRB_AP_REP message.

Communication with the ad_host can be seen through the on_pi_trail event.

Property List

---

The following is the full list of the properties of the class with short descriptions. Click on the links for further details.

Method List

---

The following is the full list of the methods of the class with short descriptions. Click on the links for further details.

Event List

---

The following is the full list of the events fired by the class with short descriptions. Click on the links for further details.

Config Settings

---

The following is a list of config settings for the class with short descriptions. Click on the links for further details.

ad_host Property

The domain name or IP address of the Active Directory server.

Syntax

def get_ad_host() -> str: ...
def set_ad_host(value: str) -> None: ...

ad_host = property(get_ad_host, set_ad_host)

Default Value

""

Remarks

This property specifies the IP address (IP number in dotted internet format) or Domain Name of the Active Directory server.

If this property is set to a Domain Name, a DNS request is initiated and upon successful termination of the request, this property is set to the corresponding address. If the search is not successful, an error is returned.

ad_port Property

The port for the Active Directory server.

Syntax

def get_ad_port() -> int: ...
def set_ad_port(value: int) -> None: ...

ad_port = property(get_ad_port, set_ad_port)

Default Value

88

Remarks

This property specifies the port for the Active Directory server. The default value is 88.

auth_mechanism Property

The authentication mechanism to be used when connecting to the Active Directory server.

Syntax

def get_auth_mechanism() -> int: ...
def set_auth_mechanism(value: int) -> None: ...

auth_mechanism = property(get_auth_mechanism, set_auth_mechanism)

Default Value

6

Remarks

This property specifies the authentication mechanism used. Possible values are:

auth_token Property

The authentication token.

Syntax

def get_auth_token() -> bytes: ...

auth_token = property(get_auth_token, None)

Default Value

""

Remarks

This property holds the authentication token.

This property will be populated after calling authenticate. This may be used in by another entity to authenticate to the service. For instance this may be used in HTTP to authenticate to a web service.

The content of this property is a KRB_AP_REQ message. This is sometimes referred to as an "Authentication Header". It is comprised of the service ticket that was obtained from the TGS and an encrypted authenticator.

This property is read-only.

password Property

The user's password.

Syntax

def get_password() -> str: ...
def set_password(value: str) -> None: ...

password = property(get_password, set_password)

Default Value

""

Remarks

This property specifies the user's password. This must be set before calling authenticate.

spn Property

The Service Principal Name (SPN).

Syntax

def get_spn() -> str: ...
def set_spn(value: str) -> None: ...

spn = property(get_spn, set_spn)

Default Value

""

Remarks

This property specifies the Service Principal Name (SPN). This must be set before calling authenticate.

timeout Property

A timeout for the class.

Syntax

def get_timeout() -> int: ...
def set_timeout(value: int) -> None: ...

timeout = property(get_timeout, set_timeout)

Default Value

60

Remarks

If the timeout property is set to 0, all operations will run uninterrupted until successful completion or an error condition is encountered.

If timeout is set to a positive value, the class will wait for the operation to complete before returning control.

The class will use do_events to enter an efficient wait loop during any potential waiting period, making sure that all system events are processed immediately as they arrive. This ensures that the host application does not "freeze" and remains responsive.

If timeout expires, and the operation is not yet complete, the class fails with an error.

Please note that by default, all timeouts are inactivity timeouts, i.e. the timeout period is extended by timeout seconds when any amount of data is successfully sent or received.

The default value for the timeout property is 60 seconds.

user Property

The name and domain of the user to authenticate.

Syntax

def get_user() -> str: ...
def set_user(value: str) -> None: ...

user = property(get_user, set_user)

Default Value

""

Remarks

This property specifies the name and realm/domain of the user. The value specified must be in one of the following formats:

• user@domain
• domain/user

authenticate Method

Authenticates the user.

Syntax

def authenticate() -> None: ...

Remarks

This method authenticates the user.

Authentication

When authenticate is called the class will attempt to authenticate the user with the Active Directory server. The class will communicate with the ad_host to obtain a service ticket and populate auth_token. The following properties are required when calling this method:

• spn (required)
• user (required)
• password (required)
• ad_host (required)

A typical sequence of messages would be:

• KRB_AS_REQ -> KDC
• KRB_AS_REP <- KDC
• KRB_TGS_REQ -> KDC
• KRB_TGS_REP <- KDC
• auth_token is populated with the constructed KRB_AP_REP message.

Communication with the ad_host can be seen through the on_pi_trail event.

change_password Method

Changes the password for the specified user.

Syntax

def change_password(user: str, old_password: str, new_password: str) -> None: ...

Remarks

This method changes the password for the specified user.

The User parameter is the name of the user for which the password will be changed. OldPassword specifies the current paswsword and NewPassword specifies the new password.

Note: This operation can only be performed over the SSL Port. Set ad_port to the SSL port of the server (typically 636) before calling this method.

Note: If the user is an administrator the old password is not required.

config Method

Sets or retrieves a configuration setting.

Syntax

def config(configuration_string: str) -> str: ...

Remarks

config is a generic method available in every class. It is used to set and retrieve configuration settings for the class.

These settings are similar in functionality to properties, but they are rarely used. In order to avoid "polluting" the property namespace of the class, access to these internal properties is provided through the config method.

To set a configuration setting named PROPERTY, you must call Config("PROPERTY=VALUE"), where VALUE is the value of the setting expressed as a string. For boolean values, use the strings "True", "False", "0", "1", "Yes", or "No" (case does not matter).

To read (query) the value of a configuration setting, you must call Config("PROPERTY"). The value will be returned as a string.

do_events Method

Processes events from the internal message queue.

Syntax

def do_events() -> None: ...

Remarks

When do_events is called, the class processes any available events. If no events are available, it waits for a preset period of time, and then returns.

interrupt Method

Interrupt the current method.

Syntax

def interrupt() -> None: ...

Remarks

If there is no method in progress, interrupt simply returns, doing nothing.

list_computers Method

Lists all computers in the directory.

Syntax

def list_computers() -> None: ...

Remarks

This method lists all computers in the directory. The on_computer_list event will be fired once for each computer returned.

list_group_members Method

List all members of a group.

Syntax

def list_group_members(group: str) -> None: ...

Remarks

This method lists all members of the specified group. The on_user_list event will be fired once for each member returned.

list_groups Method

List all groups in the directory.

Syntax

def list_groups() -> None: ...

Remarks

This method lists all groups in the directory. The on_group_list event will be fired once for each group returned.

list_user_groups Method

Lists all groups a user is a part of.

Syntax

def list_user_groups(user: str) -> None: ...

Remarks

This method lists all groups that the user specified by user is a part of. The on_group_list event will fire once for each group the user is a part of.

reset Method

Resets the class properties to their default values.

Syntax

def reset() -> None: ...

Remarks

This method resets the properties to their default values.

on_computer_list Event

Fired for each computer entry returned.

Syntax

class ActiveDirectoryComputerListEventParams(object):
  @property
  def name() -> str: ...

  @property
  def operating_system() -> str: ...

  @property
  def last_logon() -> str: ...

  @property
  def logon_count() -> int: ...

  @property
  def dn() -> str: ...

# In class ActiveDirectory:
@property
def on_computer_list() -> Callable[[ActiveDirectoryComputerListEventParams], None]: ...
@on_computer_list.setter
def on_computer_list(event_hook: Callable[[ActiveDirectoryComputerListEventParams], None]) -> None: ...

Remarks

This event is fired once for each computer returned when the list_computers method is called.

on_error Event

Information about errors during data delivery.

Syntax

class ActiveDirectoryErrorEventParams(object):
  @property
  def error_code() -> int: ...

  @property
  def description() -> str: ...

# In class ActiveDirectory:
@property
def on_error() -> Callable[[ActiveDirectoryErrorEventParams], None]: ...
@on_error.setter
def on_error(event_hook: Callable[[ActiveDirectoryErrorEventParams], None]) -> None: ...

Remarks

The on_error event is fired in case of exceptional conditions during message processing. Normally the class fails with an error.

ErrorCode contains an error code and Description contains a textual description of the error. For a list of valid error codes and their descriptions, please refer to the Error Codes section.

on_group_list Event

Fired for each group entry returned.

Syntax

class ActiveDirectoryGroupListEventParams(object):
  @property
  def name() -> str: ...

  @property
  def description() -> str: ...

  @property
  def dn() -> str: ...

# In class ActiveDirectory:
@property
def on_group_list() -> Callable[[ActiveDirectoryGroupListEventParams], None]: ...
@on_group_list.setter
def on_group_list(event_hook: Callable[[ActiveDirectoryGroupListEventParams], None]) -> None: ...

Remarks

This event is fired once for each group entry returned when either of the list_groups or list_user_groups methods are called.

on_log Event

Fires once for each log message.

Syntax

class ActiveDirectoryLogEventParams(object):
  @property
  def log_level() -> int: ...

  @property
  def message() -> str: ...

  @property
  def log_type() -> str: ...

# In class ActiveDirectory:
@property
def on_log() -> Callable[[ActiveDirectoryLogEventParams], None]: ...
@on_log.setter
def on_log(event_hook: Callable[[ActiveDirectoryLogEventParams], None]) -> None: ...

Remarks

This event fires once for each log message generated by the class. The verbosity is controlled by the LogLevel setting.

LogLevel indicates the level of the Message. Possible values are:

The value 1 (Info) logs basic information, including the URL, HTTP version, and status details.

The value 2 (Verbose) logs additional information about the request and response.

The value 3 (Debug) logs the headers and body for both the request and response, as well as additional debug information (if any).

LogType identifies the type of log entry. Possible values are:

• Info
• Verbose
• Debug

on_pi_trail Event

Traces the messages sent to the server, and the respective replies.

Syntax

class ActiveDirectoryPITrailEventParams(object):
  @property
  def direction() -> int: ...

  @property
  def message() -> str: ...

# In class ActiveDirectory:
@property
def on_pi_trail() -> Callable[[ActiveDirectoryPITrailEventParams], None]: ...
@on_pi_trail.setter
def on_pi_trail(event_hook: Callable[[ActiveDirectoryPITrailEventParams], None]) -> None: ...

Remarks

The on_pi_trail event is useful for debugging purposes. It shows all the interaction between the client and the server. To include the raw packets set LogKerberosPackets to True.

The Message parameter contains the full text of the message. The Direction parameter shows the originator of the message:

on_user_list Event

Fired once for each user entry returned.

Syntax

class ActiveDirectoryUserListEventParams(object):
  @property
  def name() -> str: ...

  @property
  def description() -> str: ...

  @property
  def last_logon() -> str: ...

  @property
  def member_of() -> str: ...

  @property
  def dn() -> str: ...

# In class ActiveDirectory:
@property
def on_user_list() -> Callable[[ActiveDirectoryUserListEventParams], None]: ...
@on_user_list.setter
def on_user_list(event_hook: Callable[[ActiveDirectoryUserListEventParams], None]) -> None: ...

Remarks

This event is fired once for each user entry returned when the list_group_members method is called.

ActiveDirectory Config Settings

The class accepts one or more of the following configuration settings. Configuration settings are similar in functionality to properties, but they are rarely used. In order to avoid "polluting" the property namespace of the class, access to these internal properties is provided through the config method.

ActiveDirectory Config Settings

TCPClient Config Settings

Socket Config Settings

Base Config Settings

ActiveDirectory Errors

AD Errors

	950   Busy performing other action.
	951   Invalid username.
	952   Received error message. The error message contains the description.
	953   Message integrity check error.
	954   Unsupported encryption type.

UDP Errors

	104   UDP is already active.
	106   You cannot change the local_port while the class is active.
	107   You cannot change the local_host at this time. A connection is in progress.
	109   The class must be active for this operation.
	112   Cannot change MaxPacketSize while the class is active.
	113   Cannot change ShareLocalPort option while the class is active.
	114   Cannot change remote_host when UseConnection is set and the class active.
	115   Cannot change remote_port when UseConnection is set and the class is active.
	116   remote_port can't be zero when UseConnection is set. Please specify a valid service port number.
	117   Cannot change UseConnection while the class is active.
	118   Message can't be longer than MaxPacketSize.
	119   Message too short.
	434   Unable to convert string to selected CodePage

TCP/IP Errors

	10004   [10004] Interrupted system call.
	10009   [10009] Bad file number.
	10013   [10013] Access denied.
	10014   [10014] Bad address.
	10022   [10022] Invalid argument.
	10024   [10024] Too many open files.
	10035   [10035] Operation would block.
	10036   [10036] Operation now in progress.
	10037   [10037] Operation already in progress.
	10038   [10038] Socket operation on non-socket.
	10039   [10039] Destination address required.
	10040   [10040] Message too long.
	10041   [10041] Protocol wrong type for socket.
	10042   [10042] Bad protocol option.
	10043   [10043] Protocol not supported.
	10044   [10044] Socket type not supported.
	10045   [10045] Operation not supported on socket.
	10046   [10046] Protocol family not supported.
	10047   [10047] Address family not supported by protocol family.
	10048   [10048] Address already in use.
	10049   [10049] Can't assign requested address.
	10050   [10050] Network is down.
	10051   [10051] Network is unreachable.
	10052   [10052] Net dropped connection or reset.
	10053   [10053] Software caused connection abort.
	10054   [10054] Connection reset by peer.
	10055   [10055] No buffer space available.
	10056   [10056] Socket is already connected.
	10057   [10057] Socket is not connected.
	10058   [10058] Can't send after socket shutdown.
	10059   [10059] Too many references, can't splice.
	10060   [10060] Connection timed out.
	10061   [10061] Connection refused.
	10062   [10062] Too many levels of symbolic links.
	10063   [10063] File name too long.
	10064   [10064] Host is down.
	10065   [10065] No route to host.
	10066   [10066] Directory not empty
	10067   [10067] Too many processes.
	10068   [10068] Too many users.
	10069   [10069] Disc Quota Exceeded.
	10070   [10070] Stale NFS file handle.
	10071   [10071] Too many levels of remote in path.
	10091   [10091] Network subsystem is unavailable.
	10092   [10092] WINSOCK DLL Version out of range.
	10093   [10093] Winsock not loaded yet.
	11001   [11001] Host not found.
	11002   [11002] Non-authoritative 'Host not found' (try again or check DNS setup).
	11003   [11003] Non-recoverable errors: FORMERR, REFUSED, NOTIMP.
	11004   [11004] Valid name, no data record (check DNS setup).