Active Directory: Inputs & Outputs
Summary
Each plugin uses a set of dictionaries to store data.
These are used by plugin actions as both inputs and outputs.
This page will cover:
- The dictionaries used in this plugin
- The information each dictionary contains
Dictionary Types
AttributePair
- Contains an LDAP attribute name & value
Standard Keys
name: The name of the LDAP attribute.
value: A value to set for the attribute.
Computer
-
Contains Active Directory Computer LDAP attributes
-
Expand below to see each key and a link to the relevant Microsoft article
Standard Keys
accountExpires: Date string or null [Account-Expires].
carLicense: String or null [carLicense].
cn: String or null [Common-Name].
description: String or null [Description].
displayName: String or null [Display-Name].
distinguishedName: String [Obj-Dist-Name].
dNSHostName: String [DNS-Host-Name].
info: String or null [Comment].
lastLogoff: Date string or null [Last-Logoff].
lastLogon: Date string or null [Last-Logon].
lastLogonTimestamp: Date string or null [Last-Logon-Timestamp].
lockoutTime: Date string or null [Lockout-Time].
logonCount: Integer [Logon-Count].
mail: String or null [E-mail-Addresses].
mail: String or null [Managed-By].
memberOf: List of Group Dictionaries [Is-Member-Of-DL].
name: String or null [RDN].
objectGUID: String [Object-Guid].
objectSid: String [Object-Sid].
operatingSystem: String or null [Operating-System].
operatingSystemHotfix: String or null [Operating-System-Hotfix].
operatingSystemServicePack: String or null [Operating-System-Service-Pack].
operatingSystemVersion: String or null [Operating-System-Version].
pwdLastSet: Date string or null [Pwd-Last-Set].
sAMAccountName: String [Sam-Account-Name].
sAMAccountType: Integer [Sam-Account-Type].
userAccountControl: Integer [User-Account-Control].
userPrincipalName: String or null [User-Principal-Name].
Sensitive Keys
The following keys may contain credentials!
ms_Mcs_AdmPwd: The legacy ms-Mcs-AdmPwd attribute (if LAPS is being used).
msLAPS_Password: The msLAPS-Password (if LAPS is being used).
By default PPA will not display their values in the task interface.
Please note that logging computer records in a task may make these values visible in task log files.
See more about Computers here
Container
-
Contains Active Directory Container LDAP attributes
-
Expand below to see each key and a link to the relevant Microsoft article
Standard Keys
description: String or null [Description].
distinguishedName: String [Obj-Dist-Name].
name: String or null [RDN].
cn: String or null [Common-Name].
See more about Containers here
DomainController
-
Contains Domain Controller connection details
-
It is used as an input to many of the actions in this plugin
-
The example below shows the dictionary structure in YAML
-
See the required and optional keys underneath the example
Supplying Credentials
You should always use a PPA Vault integration to provide credentials to a plugin action.
Single Address
1 2 3 4 5 6 |
|
Multiple Addresses For Resilience
1 2 3 4 5 6 |
|
Multiple Domain Controller Addresses
Version 7.6.0 of this plugin introduced support for multiple comma-separated Domain Controller addresses.
If multiple addresses are supplied, PPA will use the first address that connects successfully.
Required Keys
address: Domain Controller IP or DNS address(es).
domain: FQDN of the Active Directory domain.
username: Username for authentication.
password: Password for authentication.
Optional Keys
port: The LDAPS port on the Domain Controller (defaults to 636
).
Group
-
Contains Active Directory Group LDAP attributes
-
Expand below to see each key and a link to the relevant Microsoft article
Standard Keys
cn: String or null [Common-Name].
description: String or null [Description].
distinguishedName: String [Obj-Dist-Name].
gidNumber: Integer or null [gidNumber].
groupType: String [Group-Type].
info: String or null [Comment].
managedBy: String or null [ManagedBy].
member: List of User, Group, or Computer distinguished names or null [Member].
memberUid: List of strings or null [memberUid].
name: String or null [RDN].
objectGUID: String [Object-Guid].
objectSid: String [Object-Sid].
sAMAccountName: String [Sam-Account-Name].
sAMAccountType: Integer [Sam-Account-Type].
Group Membership Limit
Due to an Active Directory limitation, the member key can only hold up to 1500 group members.
If the group has more than 1500 members, only members 1-1500 will be included in this key.
You can bypass this limitation by getting nested users with the get_members action.
See more about Groups here
OrganizationalUnit
-
Contains Active Directory Organizational Unit LDAP attributes
-
Expand below to see each key and a link to the relevant Microsoft article
Standard Keys
distinguishedName: String [Obj-Dist-Name].
name: String [Organizational-Unit-Name].
objectGUID: String [Object-Guid].
ou: String [Organizational-Unit-Name].
See more about Organizational Units here
PasswordExpiry
- Contains user password expiry information
PasswordExpiry Keys
total_seconds: Total number of seconds until expiry.
timestamp: Expiry date as a timestamp in the following format:
13:26:30 30/11/2021 UTC
days: Number of days.
hours: Number of hours.
minutes: Number of minutes.
seconds: Number of seconds.
Time Until Expiry
The values of days, hours, minutes, & seconds are not totals.
They are a portion of the remaining time until expiry.
For example, the value of hours is not the total number of hours until expiry.
Instead it should be used in conjunction with the other keys to display a countdown:
1 2 3 4 5 6 7 8 9 |
|
As days is the largest unit, it can be used on its own to find accounts close to expiry:
1 2 3 |
|
TimePeriod
- Describes a period of time
TimePeriod Keys
days: Number of days.
hours: Number of hours.
minutes: Number of minutes.
seconds: Number of seconds.
Using Values
The values in this dictionary are not totals, they are a portion of the time period.
For example, the value of hours is not the total number of hours.
Instead it should be used in conjunction with the other keys to display a total:
1 2 3 4 5 6 7 8 9 |
|
User
-
Contains Active Directory User LDAP attributes
-
Expand the sections below for more information
Standard Keys
accountExpires: Date string or null [Account-Expires].
badPasswordTime: Date string or null [Bad-Password-Time].
badPwdCount: Integer [Bad-Pwd-Count].
carLicense: String or null [carLicense].
cn: String or null [Common-Name].
co: String or null [Text-Country].
comment: String or null [User-Comment].
company: String or null [Company].
countryCode: String or null [Country-Code].
description: String or null [Description].
department: String or null [Department].
displayName: String or null [Display-Name].
distinguishedName: String [Obj-Dist-Name].
division: String or null [Division].
employeeID: String or null [Employee-ID].
employeeNumber: String or null [Employee-Number].
employeeType: String or null [Employee-Type].
facsimileTelephoneNumber: String or null [facsimileTelephoneNumber].
gidNumber: Integer or null [gidNumber].
givenName: String or null [Given-Name].
info: String or null [Comment].
l: String or null [Locality-Name].
lastLogoff: Date string or null [Last-Logoff].
lastLogon: Date string or null [Last-Logon].
lastLogonTimestamp: Date string or null [Last-Logon-Timestamp].
lockoutTime: Date string or null [Lockout-Time].
loginShell: String or null [loginShell].
logonCount: Integer [Logon-Count].
mail: String or null [E-mail-Addresses].
manager: String or null [Manager].
memberOf: List of Group Dictionaries [Is-Member-Of-DL].
mobile: String or null [Phone-Mobile-Primary].
name: String or null [RDN].
objectGUID: String [Object-Guid].
objectSid: String [Object-Sid].
postalCode: String or null [Postal-Code].
postOfficeBox: String or null [Post-Office-Box].
physicalDeliveryOfficeName: String or null [Physical-Delivery-Office-Name].
pwdLastSet: Date string or null [Pwd-Last-Set].
sAMAccountName: String [Sam-Account-Name].
sAMAccountType: Integer [Sam-Account-Type].
sn: String or null [Surname].
st: String or null [State-Or-Province-Name].
street: String or null [despite the name this is the Street-Address].
streetAddress: String or null [despite the name this is the Address].
telephoneNumber: String or null [Telephone-Number].
thumbnailPhoto: String or null [Picture].
title: String or null [Title].
uid: String or null [uid].
uidNumber: String or null [uidNumber].
unixHomeDirectory: String or null [unixHomeDirectory].
userAccountControl: Integer [User-Account-Control].
userPrincipalName: String or null [User-Principal-Name].
Extra Keys
The following keys are created by PPA based on other Active Directory attributes:
is_disabled: Boolean indicating whether the user is disabled.
is_enabled: Boolean indicating whether the user is enabled.
is_expired: Boolean indicating whether the user is expired.
is_locked: Boolean indicating whether the user is locked out.
password_age: Either a dictionary containing the user's password age in:
- days
- hours
- minutes
- seconds
Or `null` if no password has been set.
Exchange & Extension Attributes
The following Exchange attributes are available:
-
msExchRecipientDisplayType
-
msExchRecipientTypeDetails
-
msExchRemoteRecipientType
The following extension attributes are available for Active Directory schemas that utilise them:
extensionAttribute1
...through to...
extensionAttribute15
See more about Users here