accounts – Users, Groups, SIDs &c.

All security in windows is handled via Security Principals. These can be a user (the most common case), a group of users, a computer, or something else. Security principals are uniquely identified by their SID: a binary code represented by a string S-a-b-cd-efg... where each of the segments represents an aspect of the security authorities involved. (A computer, a domain etc.). Certain of the SIDs are considered well-known such as the AuthenticatedUsers account on each machine which will always have the same SID.

Most of the access to this module will be via the principal() or me() functions. Although the module is designed to be used standalone, it is imported directly into the security module’s namespace so its functionality can also be accessed from there.

Functions

principal(principal, cls=<Unset>)

Factory function for the Principal class. This is the most common way to create a Principal object:

from winsys import accounts
service_account = accounts.principal (accounts.WELL_KNOWN_SID.Service)
local_admin = accounts.principal ("Administrator")
domain_users = accounts.principal (r"DOMAIN\Domain Users")

Parameters:principal – any of None, a Principal, a PySID, a WELL_KNOWN_SID or a string Returns:a Principal object corresponding to principal

user(name)

If you know you’re after a user, use this. Particularly useful when a system user is defined as an alias type

group(name)

If you know you’re after a group, use this. Particularly useful when a system group is defined as an alias type

me()

Convenience function for the common case of getting the logged-on user’s account.

Classes

class Principal(sid, system=None)

Object wrapping a Windows security principal, represented by a SID and, where possible, a name. Principal compares and hashes by SID so can be sorted and used as a dictionary key, set element, etc.

A Principal is its own context manager, impersonating the corresponding user:

from winsys import accounts
with accounts.principal ("python"):
  print accounts.me ()

Note, though, that this will prompt for a password using the Win32 password UI. To logon with a password, use the impersonate() context-managed function. TODO: allow password to be set securely.

Initialise a Principal from and (optionally) a system name. The sid must be a PySID and the system name, if present must be a security authority, eg a machine or a domain.

classmethod from_sid(sid, system=None)

Return a Principal based on a sid and a security authority.

Parameters:

• sid – a PySID
• system_name – optional name of a security authority

Returns:

a Principal object for sid

classmethod from_string(string, system=None)

Return a Principal based on a name and a security authority. If string is blank, the logged-on user is assumed.

Parameters:

• string – name of an account in the form “domainname”. domain is optional so the simplest form is simply “name”
• system – name of a security authority (typically a machine or a domain)

Returns:

a Principal object for string

classmethod from_well_known(well_known, domain=None)

Return a Principal based on one of the WELL_KNOWN_SID values.

Parameters:

• well_known – one of the WELL_KNOWN_SID
• domain – anything accepted by principal() and corresponding to a domain

impersonate(*args, **kwds)

Context-managed function to impersonate this user and then revert:

from winsys import accounts, security
print accounts.me ()
python = accounts.principal ("python")
with python.impersonate ("Pa55w0rd"):
  print accounts.me ()
  open ("temp.txt", "w").close ()
print accounts.me ()
security.security ("temp.txt").owner == python

Note that the Principal class is also its own context manager but does not allow the password to be specified.

Parameters:

• password – password for this account
• logon_type – one of the LOGON values

logon(password=<Unset>, logon_type=<Unset>)

Log on as an authenticated user, returning that user’s token. This is used by security.impersonate which wraps the token in a Token object and manages its lifetime in a context.

(EXPERIMENTAL) If no password is given, a UI pops up to ask for a password.

Parameters:

• password – the password for this account
• logon_type – one of the LOGON values

Returns:

a pywin32 handle to a token

classmethod me()

Convenience factory method for the common case of referring to the logged-on user

pyobject()

Return the internal representation of this object.

Returns:pywin32 SID

class User(sid, system=None)

Initialise a Principal from and (optionally) a system name. The sid must be a PySID and the system name, if present must be a security authority, eg a machine or a domain.

classmethod create(username, password, system=None)

Create a new user with username and password. Return a User for the new user.

Parameters:

• username – username of the new user. Must not already exist on system
• password – password for the new user. Must meet security policy on system
• system – optional system name

Returns:

a User for username

delete()

Delete this user from system.

Parameters:system – optional security authority

groups()

Yield the groups this user belongs to

Parameters:system – optional security authority

join(other_group)

Add this user to a group

Parameters:other_group – anything accepted by group() Returns:self

leave(other_group)

Remove this user from a group

Parameters:other_group – anything accepted by group() Returns:self

runas(command_line, password=<Unset>, load_profile=False)

Run a command logged on as this user

Parameters:

• command_line – command line to run, quoted as necessary
• password – password; if not supplied, standard Windows prompt
• with_profile – if True, HKEY_CURRENT_USER is loaded [False]

class Group(sid, system=None)

Initialise a Principal from and (optionally) a system name. The sid must be a PySID and the system name, if present must be a security authority, eg a machine or a domain.

Constants

LOGON

Types of logon used by LogonUser and related APIs

Name	Val	Win32
PROVIDER_DEFAULT	0	LOGON32_PROVIDER_DEFAULT
PROVIDER_WINNT35	1	LOGON32_PROVIDER_WINNT35
PROVIDER_WINNT40	2	LOGON32_PROVIDER_WINNT40
LOGON_INTERACTIVE	2	LOGON32_PROVIDER_WINNT40
LOGON_NETWORK	3	LOGON32_PROVIDER_WINNT50
PROVIDER_WINNT50	3	LOGON32_PROVIDER_WINNT50
LOGON_BATCH	4	LOGON32_LOGON_BATCH
LOGON_SERVICE	5	LOGON32_LOGON_SERVICE
LOGON_UNLOCK	7	LOGON32_LOGON_UNLOCK
LOGON_NETWORK_CLEARTEXT	8	LOGON32_LOGON_NETWORK_CLEARTEXT
LOGON_NEW_CREDENTIALS	9	LOGON32_LOGON_NEW_CREDENTIALS

EXTENDED_NAME

Extended display formats for usernames

Name	Val	Win32
Unknown	0	NameUnknown
FullyQualifiedDN	1	NameFullyQualifiedDN
ServicePrincipal	10	NameServicePrincipal
DnsDomain	12	NameDnsDomain
SamCompatible	2	NameSamCompatible
Display	3	NameDisplay
UniqueId	6	NameUniqueId
Canonical	7	NameCanonical
UserPrincipal	8	NameUserPrincipal
CanonicalEx	9	NameCanonicalEx

WELL_KNOWN_SID

Well-known SIDs common to all computers

Name	Val	Win32
Null	0	WinNullSid
World	1	WinWorldSid
Batch	10	WinBatchSid
Interactive	11	WinInteractiveSid
Service	12	WinServiceSid
Anonymous	13	WinAnonymousSid
Proxy	14	WinProxySid
EnterpriseControllers	15	WinEnterpriseControllersSid
Self	16	WinSelfSid
AuthenticatedUser	17	WinAuthenticatedUserSid
RestrictedCode	18	WinRestrictedCodeSid
TerminalServer	19	WinTerminalServerSid
Local	2	WinLocalSid
RemoteLogonId	20	WinRemoteLogonIdSid
LogonIds	21	WinLogonIdsSid
LocalSystem	22	WinLocalSystemSid
LocalService	23	WinLocalServiceSid
NetworkService	24	WinNetworkServiceSid
BuiltinDomain	25	WinBuiltinDomainSid
BuiltinAdministrators	26	WinBuiltinAdministratorsSid
BuiltinUsers	27	WinBuiltinUsersSid
BuiltinGuests	28	WinBuiltinGuestsSid
BuiltinPowerUsers	29	WinBuiltinPowerUsersSid
CreatorOwner	3	WinCreatorOwnerSid
BuiltinAccountOperators	30	WinBuiltinAccountOperatorsSid
BuiltinSystemOperators	31	WinBuiltinSystemOperatorsSid
BuiltinPrintOperators	32	WinBuiltinPrintOperatorsSid
BuiltinBackupOperators	33	WinBuiltinBackupOperatorsSid
BuiltinReplicator	34	WinBuiltinReplicatorSid
BuiltinPreWindows2000CompatibleAccess	35	WinBuiltinPreWindows2000CompatibleAccessSid
BuiltinRemoteDesktopUsers	36	WinBuiltinRemoteDesktopUsersSid
BuiltinNetworkConfigurationOperators	37	WinBuiltinNetworkConfigurationOperatorsSid
AccountAdministrator	38	WinAccountAdministratorSid
AccountGuest	39	WinAccountGuestSid
CreatorGroup	4	WinCreatorGroupSid
AccountKrbtgt	40	WinAccountKrbtgtSid
AccountDomainAdmins	41	WinAccountDomainAdminsSid
AccountDomainUsers	42	WinAccountDomainUsersSid
AccountDomainGuests	43	WinAccountDomainGuestsSid
AccountComputers	44	WinAccountComputersSid
AccountControllers	45	WinAccountControllersSid
AccountCertAdmins	46	WinAccountCertAdminsSid
AccountSchemaAdmins	47	WinAccountSchemaAdminsSid
AccountEnterpriseAdmins	48	WinAccountEnterpriseAdminsSid
AccountPolicyAdmins	49	WinAccountPolicyAdminsSid
CreatorOwnerServer	5	WinCreatorOwnerServerSid
AccountRasAndIasServers	50	WinAccountRasAndIasServersSid
NTLMAuthentication	51	WinNTLMAuthenticationSid
DigestAuthentication	52	WinDigestAuthenticationSid
SChannelAuthentication	53	WinSChannelAuthenticationSid
ThisOrganization	54	WinThisOrganizationSid
OtherOrganization	55	WinOtherOrganizationSid
BuiltinIncomingForestTrustBuilders	56	WinBuiltinIncomingForestTrustBuildersSid
BuiltinPerfMonitoringUsers	57	WinBuiltinPerfMonitoringUsersSid
BuiltinPerfLoggingUsers	58	WinBuiltinPerfLoggingUsersSid
BuiltinAuthorizationAccess	59	WinBuiltinAuthorizationAccessSid
CreatorGroupServer	6	WinCreatorGroupServerSid
BuiltinTerminalServerLicenseServers	60	WinBuiltinTerminalServerLicenseServersSid
BuiltinDCOMUsers	61	WinBuiltinDCOMUsersSid
BuiltinIUsers	62	WinBuiltinIUsersSid
IUser	63	WinIUserSid
BuiltinCryptoOperators	64	WinBuiltinCryptoOperatorsSid
UntrustedLabel	65	WinUntrustedLabelSid
LowLabel	66	WinLowLabelSid
MediumLabel	67	WinMediumLabelSid
HighLabel	68	WinHighLabelSid
SystemLabel	69	WinSystemLabelSid
NtAuthority	7	WinNtAuthoritySid
WriteRestrictedCode	70	WinWriteRestrictedCodeSid
CreatorOwnerRights	71	WinCreatorOwnerRightsSid
CacheablePrincipalsGroup	72	WinCacheablePrincipalsGroupSid
NonCacheablePrincipalsGroup	73	WinNonCacheablePrincipalsGroupSid
EnterpriseReadonlyControllers	74	WinEnterpriseReadonlyControllersSid
AccountReadonlyControllers	75	WinAccountReadonlyControllersSid
Dialup	8	WinDialupSid
Network	9	WinNetworkSid

USER_PRIV

User-types for creating new users

Name	Val	Win32
GUEST	0	USER_PRIV_GUEST
USER	1	USER_PRIV_USER
ADMIN	2	USER_PRIV_ADMIN

UF

Flags for creating new users

Name	Val	Win32
SCRIPT	1	UF_SCRIPT
MNS_LOGON_ACCOUNT	131072	UF_MNS_LOGON_ACCOUNT
MACHINE_ACCOUNT_MASK	14336	UF_MACHINE_ACCOUNT_MASK
ACCOUNT_TYPE_MASK	15104	UF_ACCOUNT_TYPE_MASK
LOCKOUT	16	UF_LOCKOUT
ACCOUNTDISABLE	2	UF_ACCOUNTDISABLE
INTERDOMAIN_TRUST_ACCOUNT	2048	UF_INTERDOMAIN_TRUST_ACCOUNT
SETTABLE_BITS	211835	UF_SETTABLE_BITS
TEMP_DUPLICATE_ACCOUNT	256	UF_TEMP_DUPLICATE_ACCOUNT
PASSWD_NOTREQD	32	UF_PASSWD_NOTREQD
WORKSTATION_TRUST_ACCOUNT	4096	UF_WORKSTATION_TRUST_ACCOUNT
NORMAL_ACCOUNT	512	UF_NORMAL_ACCOUNT
PASSWD_CANT_CHANGE	64	UF_PASSWD_CANT_CHANGE
DONT_EXPIRE_PASSWD	65536	UF_DONT_EXPIRE_PASSWD
HOMEDIR_REQUIRED	8	UF_HOMEDIR_REQUIRED
SERVER_TRUST_ACCOUNT	8192	UF_SERVER_TRUST_ACCOUNT

SID_NAME_USE

Types of accounts for which SIDs exist

Name	Val	Win32
User	1	SidTypeUser
Label	10	SidTypeLabel
Group	2	SidTypeGroup
Domain	3	SidTypeDomain
Alias	4	SidTypeAlias
WellKnownGroup	5	SidTypeWellKnownGroup
DeletedAccount	6	SidTypeDeletedAccount
Invalid	7	SidTypeInvalid
Unknown	8	SidTypeUnknown
Computer	9	SidTypeComputer

FILTER

Filters when enumerating users

Name	Val	Win32
TEMP_DUPLICATE_ACCOUNT	1	FILTER_TEMP_DUPLICATE_ACCOUNT
WORKSTATION_TRUST_ACCOUNT	16	FILTER_WORKSTATION_TRUST_ACCOUNT
NORMAL_ACCOUNT	2	FILTER_NORMAL_ACCOUNT
SERVER_TRUST_ACCOUNT	32	FILTER_SERVER_TRUST_ACCOUNT
INTERDOMAIN_TRUST_ACCOUNT	8	FILTER_INTERDOMAIN_TRUST_ACCOUNT

Exceptions

exception x_accounts(errno=None, errctx=None, errmsg=None)

Base for all accounts-related exceptions

References

See also

Using the accounts module

Cookbook examples of using the accounts module

To Do

• LSA & Credentials functionality