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:
-
option (int) - option ID (see Option constants)
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:
-
code as (int) (see Code constants)
lookupObjectByUnixId(type, id)
Look up a user or group by Unix ID.
Parameters:
-
type (int) - object type (see Object type constants)
-
id (int) - Unix user ID or group ID
Returns:
-
Object (see Object)
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
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:
-
Object (see Object)
Raises:
-
Error - if any error occurred
lookupObjectByGuid(guid)
Look up a user or group by GUID.
Parameters:
-
guid (str) - GUID
Returns:
-
Object (see Object)
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:
-
KeyValueSet (see KeyValueSet)
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:
-
name (str) - user name
-
flags (int) - validate flags (see Validate Flag constants)
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:
-
KeyValueSet (see KeyValueSet)
Raises:
-
Error - if any error occurred
getForestList(flags)
Get the trusted forest information list.
Parameters:
-
flags (int) - flags (see Get DC Flag constants)
Returns:
-
ObjectList (see ObjectList)
Raises:
-
Error - if any error occurred
getDomainList(flags)
Get the trusted domain information.
Parameters:
-
flags (int) - flags (see Get DC Flag constants)
Returns:
-
ObjectList (see ObjectList)
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:
-
Object (see Object)
Raises:
-
Error - if any error occurred
getDomainControllers(name, flags)
Get a list of domain controllers for specific domain.
Parameters:
-
name (str) - name of the domain
-
getDcFlags (int) - flags (see Get DC Flag constants)
Returns:
-
StringSet (see StringSet)
Raises:
-
Error - if any error occurred
getAuditLevel(name)
Get audit level of a user.
Parameters:
-
name (str) - user name
Returns:
-
audit level as (int) (see Audit Level constants)
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:
-
message as (str) (see Audit Level constants)
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.