Python Pycapi Reference

This section covers the objects, methods, and other details for the Pycapi module.

Pycapi Module Methods

The following table provides a summary of the available methods in the pycapi module. Click the method name to go to the details for that method.

Method Name Method description Return value type Return description
GetMajorVersion() Returns the CAPI library's major version number. int The CAPI library's major version number
GetMinorVersion() Returns the CAPI library's minor version number. int The CAPI library's minor version number
Shutdown() Does housekeeping in preparation for exiting a program that is using the CAPI library. Calling this function is optional, but if the in-memory SID cache is enabled it will take care of freeing up any allocated memory associated with the cache. n/a
GetCdcCodeStr(code) Returns the string associated with the supplied code. parameter: code (int) -code string The string associated with the code.
GetErrSystemStr(system) Returns the name of the error subsystem with an ID. parameters: system (int) - error system ID string The name of the error subsystem.
DomainFromDN() Returns the Active Directory domain name from the distinguished name or canonical name in upper case. Parameters: dn (string) - error system ID string The Active Directory domain name

Pycapi Module Objects

There are two objects in the Pycapi module:

  • Session

    This object works with the agent. When you construct this object, it creates a session with the agent automatically. When you delete this object, the session closes automatically.

  • Error

Session Object Methods

This section lists details about each method that you can use with the Session object.

_init_(majorVersion, minorVersion)

Create a session with the agent using the open method.

_del_()

Disconnect from the agent using the close method.

close()

Disconnect from the agent and free all resources associated with the session.

open(majorVersion, minorVersion)

Parameters:

  • majorVersion(int): major version of required CAPI version

  • minorVersion(int): minor version of required CAPI version

If you specify majorVersion:

  • You must specify the major version of the Centrify API (CAPI). If the current version of CAPI is lower than the specified version, this method call fails.

  • Optionally you can also specify the minorVersion.

If you don't specify the version parameters, the service doesn't do any version checking.

Raises

  • Error - if any error occurred

getOption(option)

Get an option's current setting with an ID.

Parameters:

Returns:

  • value as (int)

Raises:

  • Error - if any error occurred

setOption(option, value)

Set an option with an ID and a value.

Parameters:

  • option (int): option ID (see Option in Constants)

  • value (int): option value

Raises:

  • Error - if any error occurred

setSessionID(id)

Set a session-specific string. This string will show up in the agent event logs to provide an easy way to track logging events specific to requests generated by this CAPI session.

Parameters:

  • id (str) - session-specific string

Raises:

  • Error - if any error occurred

isSessionConnected()

Check whether the session is connected to the DirectControl agent and the session is valid.

Returns:

  • code as (int). If the session is connected and valid, the code value will be

    CODE_SUCCESS (see Code constants).

getSessionCode()

Get the code from the last session transaction.

Returns:

ldapFetch(domain, dn, attrs)

Fetch a specific object from Active Directory.

Parameters:

  • domain (str) - domain to search in. Specify either a domain name, or "$" to use global catalog or "" to use the default domain controller.

  • dn (str) - the DN to return. An empty string "" can be used to specify the DSE root.

  • attrs (list of str) - the attributes to return. An empty list or None will return only the attributes DirectControl normally caches for the matched object.

Returns:

Object (see Object)

Raises:

Error - if any error occurred

lookupObjectByUnixId(type, id)

Look up a user or group by Unix ID.

Parameters:

Returns:

Raises:

  • Error - if any error occurred

lookupObjectByName(category, name)

Look up a user or group by name in a category.

Parameters:

  • category (str) - category (see AD Category constants ) to limit the search

  • name (str) - user name or group name

Returns:

  • Object (see Object)

Raises:

  • Error - if any error occurred

lookupObjectByGuid(guid)

Look up a user or group by GUID.

Parameters:

  • guid (str) - GUID

Returns:

Raises:

  • Error - if any error occurred

lookupObjectBySid(sid)

Look up a user or group by SID.

Parameters:

  • sid (str) - SID

Returns:

  • Object (see Object)

Raises:

  • Error - if any error occurred

getDomainRids()

Get the domain map of all of the accessible domains with their corresponding RID information.

Returns:

Raises:

  • Error - if any error occurred. If the domain map construction is not

    complete, the code will be TRY_AGAIN.

networkChange()

Notify adclient that there was a network change on the system.

Returns:

  • code as (int). If success, the code value will be CODE_SUCCESS (see

    Code constants

ping()

Test the connection to the agent.

Returns:

  • code as (int). If success, the code value will be CODE_SUCCESS (see

    Code constants)

getKerberosName(name, useSamName)

Get the Kerberos principal name of a user.

Parameters:

  • name (str) - user name

  • useSamName (int) - TRUE will use sAMAccount name (see Boolean constants)

Raises:

  • Error - if any error occurred

authValidateAccount(name, flags)

Check a user account to see if any logon restrictions currently apply.

Parameters:

Returns:

  • code as (int). If success, the code value will be CODE_SUCCESS (see Code constants)

authValidatePlainTextUserNonCDC(name, password)

Validate a non-DirectControl managed user.

Parameters:

  • name (str) - user name

  • password (str) - user password

Returns:

  • code as (int). If success, the code value will be CODE_SUCCESS (see

    Code constants)

authValidatePlainTextUser(name, password)

Validate a user and password using Kerberos.

Parameters:

  • name (str) - user name

  • password (str) - user password

Returns:

  • code as (int). If success, the code value will be CODE_SUCCESS (see

    Code constants)

systemHealthInfo(refresh=FALSE)

Return information about DirectControl's system health.

Parameters:

  • refresh (int) - if FALSE, return information from last API call. If TRUE,

    send a probe to collect updated information. (See [Boolean constants]#boolean-constants))

Returns:

Raises:

  • Error - if any error occurred

getForestList(flags)

Get the trusted forest information list.

Parameters:

Returns:

Raises:

  • Error - if any error occurred

getDomainList(flags)

Get the trusted domain information.

Parameters:

Returns:

Raises:

  • Error - if any error occurred

getDCInfo(name)

Get Information about a specific domain controller (DC).

Parameters:

  • name (str) - name of the domain controller

Returns:

Raises:

  • Error - if any error occurred

getDomainControllers(name, flags)

Get a list of domain controllers for specific domain.

Parameters:

Returns:

Raises:

  • Error - if any error occurred

getAuditLevel(name)

Get audit level of a user.

Parameters:

  • name (str) - user name

Returns:

Raises:

  • Error - if any error occurred

Throw Error exception in case of error.

Error Object Methods

The base class of Error is the Python Exception class.

message()

Returns a message as a string

Returns:

code()

Returns code

Returns:

  • code as (int) (see Code constants)

Pycapi Module Constants

This section lists out the different constant values that can be used with the Pycapi module.

Boolean Constants

Constant Value
TRUE 1
FALSE 0

Code Constants

Constant Value
CODE_SUCCESS 0
CODE_FAILURE 1
CODE_NOMEM 2
CODE_BAD_OPTION 3
CODE_BAD_PARAM 4
CODE_BAD_SESSION 5
CODE_LRPC_FAILED 6
CODE_NO_MORE 7
CODE_NO_SUCH_ATTR 8
CODE_NO_SUCH_OBJECT 9
CODE_SERVER_UNREACHABLE 10
CODE_SEARCH_IN_PROGRESS 11
CODE_BAD_VERSION 12
CODE_INVALID_USER 13
CODE_INVALID_PASSWORD 14
CODE_ACCOUNT_LOCKED 15
CODE_PASSWORD_EXPIRED 16
CODE_PASSWORD_POLICY_NOT_MATCHED 17
CODE_PASSWORD_CHANGE_REJECTED 18
CODE_ACCOUNT_EXPIRED 19
CODE_ACCOUNT_DISABLED 20
CODE_WORKSTATION_DENIED 21
CODE_PERMISSION 22
CODE_BAD_PACKET 23
CODE_BAD_DATA 24
CODE_NOT_JOINED 25
CODE_VALUE_NOT_SET 26
CODE_IO_ERROR 27
CODE_SYS_ERROR 28
CODE_NO_SYS_ERROR_INFO 29
CODE_WRONG_DATA_TYPE 30
CODE_MULTI_VALUE 31
CODE_NO_ADCLIENT 32
CODE_LOGON_FAILURE 33
CODE_NOT_GROUP_MEMBER 34
CODE_FOREIGN_DOMAIN 35
CODE_NOT_FOUND 36
CODE_EXISTS 37
CODE_TRUST_ERROR 38
CODE_ACCOUNT_LOGON_HOURS 39
CODE_ACCOUNT_WORKSTATION 40
TRY_AGAIN 41
CODE_NO_DNS 42
CODE_BAD_COMPUTER_OBJECT 43
CODE_ACCOUNT_RESTRICTION 44
CODE_ALREADY_JOINED 45
CODE_CLIENT_DISCONNECTED 46
CODE_GROUP_POLICY_NOT_FOUND 47
CODE_INVALID_CONTAINER 48
CODE_NAME_MATCHES_DC 49
CODE_NETWORK_ERROR 50
CODE_OUT_BOUND_TRUST 51
CODE_PROCESS_AUTHENTICATION 52
CODE_UNKNOWN 53
CODE_ZONE_ACCESS_PERMISSION 54
CODE_IN_ANOTHER_DOMAIN 55
CODE_FIPS_NONCOMPLIANT 56
CODE_BLOCKED 57
CODE_REENTERED 58
CODE_PASSWORD_DID_CHANGE 59

Error System Constants

Constant Value
ERR_SYS_NONE 0
ERR_SYS_KERBEROS 1
ERR_SYS_LDAP 2
ERR_SYS_NTSTATUS 3
ERR_SYS_BASE 4
ERR_SYS_AZMAN 5
ERR_SYS_DNS 6
ERR_SYS_NETWORK 7
ERR_SYS_GP 8
ERR_SYS_FIPS 9
ERR_SYS_EOL 10

Option Constants

Constant Value
OPT_UNIX_ONLY 0x00000001
OPT_CHECK_AD_FIRST 0x00000002
OPT_GROUP_MEMBERSHIP 0x00000004
OPT_UNIX_NAME 0x00000008
OPT_WINDOWS_NAME 0x00000010
OPT_APPLY_OVERRIDES 0x00000020
OPT_ZONE_SEARCH 0x00000040
OPT_AUTO_RECONNECT 0x00000080
OPT_AUTH_VALIDATE_ACCOUNT 0x00000100
OPT_CREATE_KRB5_CACHE 0x00000200
OPT_NO_CACHE 0x00000400
OPT_REFRESH_MEMBERSHIP 0x00000800
OPT_AUTH_VALIDATE_ACCT_PREFER_CACHE 0x00001000
OPT_LOCATE_ALL_SERVICES 0x00002000

Object Type Constants

Constant Value
OBJTYPE_USER 1
OBJTYPE_GROUP 2
OBJTYPE_COMPUTER 3

AD Category Constants

Constant Value
AD_CATEGORY_GROUP "Group"
AD_CATEGORY_USER "Person"
AD_CATEGORY_COMPUTER "Computer"
AD_CATEGORY_CONTAINER "Container"
AD_CATEGORY_ORGUNIT "Organizational-Unit"
AD_CATEGORY_SCP "Service-Connection-Point"
AD_CATEGORY_CLASS_STORE "Class-Store"
AD_CATEGORY_FSP "Foreign-Security-Principal"
AD_CATEGORY_ANY ""

Get DC Flag Constants

Constant Value
GETDC_FLAGS_GET_ALL 0x00000001
GETDC_FLAGS_WRITABLE 0x00000002
GETDC_FLAGS_NO_LIVE_TEST 0x00000004
GETDC_FLAGS_DONT_READ_CACHE 0x00000008
GETDC_FLAGS_IGNORE_KSET 0x00000010
GETDC_FLAGS_DEEP_SWEEP 0x000000020
GETDC_FLAGS_SPEED_SORT 0x000000040
GETDC_FLAGS_ANY_SITE 0x000000080

AD Attribute Constants

Constant Value
AD_ATTR_USERNAME "name"
AD_ATTR_USER_PRINCIPAL_NAME "_userPrincipalName"

Validate Flag Constants

Constant Value
VALIDATE_ACCT_LOCKOUT 0x00000001
VALIDATE_ACCT_DISABLED 0x00000002
VALIDATE_ACCT_EXPIRED 0x00000004
VALIDATE_PASSWD_EXPIRED 0x00000008
VALIDATE_WORKSTATIONS 0x00000010
VALIDATE_LOGON_HOURS 0x00000020
VALIDATE_ALL 0xffffffff

Audit Level Constants

Constant Value
AUDITLEVEL_NOTSET -1
AUDITLEVEL_AUDITIFPOSSIBLE 0
AUDITLEVEL_NOAUDIT 1
AUDITLEVEL_AUDITREQUIRED 2
AUDITLEVEL_SYSRIGHTS 3

Pycapi Dictionary Objects

Some of the pycapi methods return objects, those are described below. A dictionary is a data type in Python that's used to store a set of key:value pairs.

Object Name Description
Object The Object is a dictionary object that stores the attributes of the object returned. For each item in the dictionary object, the key is a string, and the value is a list of bytes objects. If the attribute has only one value, the attribute will be a list with only one bytes object.
ObjectList A list of objects.
StringSet A list of strings.
KeyValueSet A dictionary of strings.