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

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

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

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.

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:

- 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:

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

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:

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

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

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

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

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

countryCode: String or null [Country-Code].

displayName: String or null [Display-Name].

distinguishedName: String [Obj-Dist-Name].

employeeNumber: String [Employee-Number].

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

name: String or null [RDN].

objectGUID: String [Object-Guid].

objectSid: String [Object-Sid].

postalCode: String or null [Postal-Code].

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

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

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.

See more about Users here