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 minorversion 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 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)

Create a session with the agent.

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:

Raises:

  • Error - if any error occurred

lookupObjectBySamUpnName(category, name, attr)

Look up a user or group by sAMAccountName or userPrincipleName.

Parameters:

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

  • name (str) - user sAMAccountName or UPN or group sAMAccountName

  • attr (str) - Active Directory attribute of name, either CDC_AD_ATTR_USERNAME or CDC_ATTR_USER_PRINCIPAL_NAME (see AD Attribute constants)

Returns:

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:

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)

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:

 

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.