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

Info

See Users, Groups, & Computers for each action's inputs & outputs.

Dictionary Types

AttributePair

AttributePair Fields

name: String.

value: String, Boolean, Integer, Float, or null.

Computer

Computer Fields

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 Fields

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

Container Fields

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

Supplying Credentials

You should always use a PPA Vault integration to provide credentials to a plugin action.

Required Fields

address: Domain Controller IP or DNS address(es).

domain: FQDN of the Active Directory domain.

username: Username for authentication.

password: Password for authentication.

Optional Fields

port: The LDAPS port on the Domain Controller (defaults to 636).

Single Address

domain_controller:
  address: 1.2.3.4
  domain: example.domain.net
  port: 636
  username: [username]
  password: [password]

Multiple Addresses For Resilience

domain_controller:
  address: 1.2.3.4, 5.6.7.8
  domain: example.domain.net
  port: 636
  username: [username]
  password: [password]

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.

Group

Group Fields

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

OrganizationalUnit Fields

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

PasswordExpiry Fields

total_seconds: Integer (seconds until expiry).

timestamp: String (format: 13:26:30 30/11/2021 UTC).

days: Integer.

hours: Integer.

minutes: Integer.

seconds: Integer.

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:

- ppa.ui.output_markdown:
    doc: >
      Your password will expire in:

      **Days:** {{ expiry.days }}

      **Hours:** {{ expiry.hours }}

      **Minutes:** {{ expiry.minutes }}

As days is the largest unit, it can be used on its own to find accounts close to expiry:

1
2
3

- ppa.ui.output_error:
    text: Your password will expire in {{ expiry.days }} days.
  when: expiry.days < 7

TimePeriod

TimePeriod Fields

days: Integer.

hours: Integer.

minutes: Integer.

seconds: Integer.

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:

- ppa.ui.output_markdown:
    doc: >
      The maximum password age is:

      **Days:** {{ expiry.days }}

      **Hours:** {{ expiry.hours }}

      **Minutes:** {{ expiry.minutes }}

User

Standard User Fields

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].

msDSSupportedEncryptionTypes: Integer or null [msDS-SupportedEncryptionTypes].

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 User Fields

The following keys are created by PPA based on other Active Directory attributes:

is_disabled: Boolean.

is_enabled: Boolean.

is_expired: Boolean.

is_locked: Boolean.

password_age: Either null or a dictionary with the following fields...

- days
- hours
- minutes
- seconds

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