Tips for finding Knowledge Articles

  • - Enter just a few key words related to your question or problem
  • - Add Key words to refine your search as necessary
  • - Do not use punctuation
  • - Search is not case sensitive
  • - Avoid non-descriptive filler words like "how", "the", "what", etc.
  • - If you do not find what you are looking for the first time,reduce the number of key words you enter and try searching again.
  • - Minimum supported Internet Explorer version is IE9
Home  >

How to use the Centrify PowerShell Module to Automate Access and Privilege Operations

Privileged Access Service ,  

11 April,19 at 11:49 AM


This article provides common AD operations (typically performed with the Access Manager MMC) using PowerShell.  We'll use a combination of the DirectManage PowerShell module commandlets and the Active Directory built-in commandlets.   You should look at this article if:


  • You want to automate some of the add/moves/change transactions to grant/revoke access to managed UNIX, Linux or Windows systems.
  • You want to front-end the operations outlined above with an IT Service Management or Workflow engine  (e.g. ServiceNow, FIM, Courion, Oracle, System Center, etc).



To simplify this post, I want to propose a two-tier model. 

  1. AD operations tier:  These are the AD transactions that relate to Centrify Zones.  This is the focus of this article and the main tool will be the Centrify DirectManage and Active Directory Powershell Modules.
  2. Managed-system tier:  These are the managed system transactions that are usually performed by your systems management or orchestration systems like Chef, Puppet, Spacewalk, Casper, System Center, etc.

 Blog - Automation and Orchestration.jpg

We'll focus on the upper part of this diagram and pick it up at the PowerShell level.


What you'll need

  • Active Directory and the rights required to write the appropriate objetcts. 
    Notes : 2003 R2 functional level to support privilege user management via RBAC and HZ
  • PowerShell 3.0 and above  (you could use lower versions, but who wants to do that?)
  • Centrify Hierarchical Zones (HZ)
  • Basic understanding of AD containers, Centrify Zones, UNIX Identities, Roles, Rights, Role Assignments and how to join Windows and UNIX systems.


What if you're new to PowerShell?

I am new to PowerShell too!  If I can do it you can too.  Believe it or not, the most powerful feature of PowerShell is that it's designed with the premise that people will learn as they go.  My advice is this, go and watch a few modules of these videos; and once you have understood the basics, just do it.  Make sure you're using PowerShell 3.0 and above.  The most powerful command that you can learn is Get-Help.  To view all Centrify PowerShell commands, type Get-Help *Cdm*   (Cdm stands for Centrify DirectManage), it should show 75 different commandlents as of Centrify Server Suite 2015.



If using the Plan-Do-Check-Adjust model, and since we don't have access to a Workflow engine at this time to cover this example end-to-end, here are some high-level tips:


Planning Tips


  • Your Identity, IT Service Management platform or Worklfow engine should be properly integrated with Active Directory.  If you have namespace disagreements, your integration may require extra work.
    E.g. Centrify has worked with ServiceNOW to provide seamless integration using our Identity Service.  Read all about it here:
  • There are cases in which you need both tiers to get something going right away.  For example, someone needs access to a server right now.  When the AD operations are complete, perhaps the orchestration side will perform an adflush in the target system and confirms that the user is ready to log in.
  • Don't forget about reporting:  When dealing with workflow and approvals, you may need to combine attestation reports generated by Centrify with references from your service desk application.  For example:  Who approved an access request?
  • Leverage the full toolset:  Centrify provides Kerberized tools for UNIX and Windows (with Centrify-enhanced PuTTY).  These tools eliminate the need to use service accounts or limit/enforce Separation of Duties.  Also, tools like the dzdo.validator can be used with REST API calls to validate reference numbers like tickets or change control numbers.  We have a post on the dzdo validator here.
  • Do not "set it and forget it" embrace "set it and improve it":  New versions are released, new best practices, new techniques.  Reviewing what's new at least every 6 monhts can make great difference.


Implementing DirectManage Operations in PowerShell


Loading Modules


Import-Module ActiveDirectory
Import-Module Centrify.DirectControl.PowerShell

 Notes:  For production-grade code, you need to have error handling and make sure you're binding to the proper forest.  That's why you want these variables to be collected from the user's environment as possible.


 Creating  Zones and Child Zones

$zone = New-CdmZone -Name "Model" -Description "Reference Zone" -Type hierarchical -Container "cn=Zones,ou=Unix,dc=example,dc=com"

If you are using the Centrify best practices, all the static data can be placed on an XML file or captured from your Service Management platform via a form.   Putting the object in a variable (E.g. $zone) allows for use later.

Frequency:  Creating a zone should be a very infrequent step.  Perhaps if you're building an access model for an environment in a public/private cloud to be used and deleted.


 Creating Computer Roles

 Because Computer Roles (groupings of systems) are contained within AD groups, this is a 2-step operation aided by the AD PowerShell commands.


$oupath = (Get-ADOrganizationalUnit -Filter 'Name -like "Demo"').DistinguishedName
New-ADGroup -Name "Centrify-Model-CR-WebServers" -Path $oupath -GroupScope Global
New-ADGroup -Name "Centrify-Model-CR-DatabaseServers" -Path $oupath -GroupScope Global
$crgroup1 = Get-ADGroup -Filter 'Name -like "Centrify-Model-CR-WebServers"'
$crgroup2 = Get-ADGroup -Filter 'Name -like "Centrify-Model-CR-DatabaseServers"'

These AD steps create (or get) the proper AD objects to build the computer roles.  Notice the naming convention for the AD group.


$crweb = New-CdmComputerRole -Zone $zone -Name "Web Servers"  -Group $crgroup1
$crdb = New-CdmComputerRole -Zone $zone -Name "Database Servers" -Group $crgroup2

The frequency of creating computer roles will be dictated by how you're grouping your systems today.  If you're using a geographical model, this is pretty much static.  If you use an application-environment model (E.g. AppX-Dev) then it will be dependent on the how frequently app environments are set up.


Defining Rights


UNIX Rights (PAM access/Commands)

# A root-like command requesting user authentication
$cmd1 = New-CdmCommandRight -Zone $zone -Name "Run any command as root" -Pattern "*" -MatchPath "*" -DzdoRunAsUser root -Authentication user 

# A simple command that allows unauthenticated access to secure log
$cmd4 = New-CdmCommandRight -Zone $zone -Name "Audit RHEL Secure Log" -Pattern "tail /var/log/secure" -DzshRunas root

# Getting  some of the Built-in PAM commands
$cmd3 = Get-CdmPamRight -Zone $zone -Name "sshd" 
$cmd5 = Get-CdmPamRight -Zone $zone -Name "login-all"

Windows Rights (Desktops/Applications)

 Windows application rights have a two-step combination.  They need the Application Criteria object and the criteria has to be used to define the Application right.

$criteria = New-CdmMatchCriteria -Description "Event Viewer" -FileType "exe" -FileName "eventvwr.exe" -Path "C:\Windows\System32\"

$cmd2 = New-CdmApplicationRight -Zone $zone -Name "Audit Windows Event Log" -MatchCriteria $criteria -RunasSelfGroups "Builtin\Administrators"

Windows Desktop Rights are much simpler.

$cmd6 = New-CdmDesktopRight -Zone $zone -Name "Admin Desktop"  -RunasSelfGroups "Builtin\Administrators"


Defining and Populating Roles


Just like in Access Manager, roles are defined and then populated with rights:

$role2 = New-CdmRole -Zone $zone -Name "UNIX Sysadmin" -UnixSysRights login, ssologin, nondzsh 

Add-CdmCommandRight -Right $cmd1 –Role $role2
Add-CdmPamRight -Right $cmd5 –Role $role2

This role allows for Password & SSO login to UNIX/Linux systems, regular shell and provides the ability to log in via any PAM protocol and run any command as root with Centrify-enhanced sudo (dzdo)


Here's an equivalent Windows role with a local Administrator Desktop

$role3 = New-CdmRole -Zone $zone -Name "Windows Admin" -WinSysRights remote, console

Add-CdmCommandRight -Right $cmd6 –Role $role3

Note that this role can only be used in platforms that support the Desktop Right.  This type of role can be created with Windows app rights as well.


A mixed Windows/UNIX Role example  (Auditor)


$role1 = New-CdmRole -Zone $zone -Name "Mixed Auditor" -UnixSysRights login, ssologin, nondzsh -WinSysRights remote

Add-CdmCommandRight -Right $cmd4 –Role $role1 
Add-CdmApplicationRight -Right $cmd2 –Role $role1 
Add-CdmPamRight  -Right $cmd3 –Role $role1

Access Manager - Mixed Auditor Role.jpg


This role when granted, allows SSH and RDP/Citrix access and in UNIX systems allows to read the secure log unauthenticated.  In windows, the user can open the full event viewer (including the Security log) since it's running as a local Administrator.


Common Operations (Add/Moves/Changes)

These operations are most likely to be front-ended by your Service Management or Workflow Engines.


UNIX-enabling Users:


# Clean enablement (SAM as login, UID/GID generated from SID)
New-CdmUserProfile -Zone $zone –User -login marge.simpson -UseAutoUid -AutoPrivateGroup –HomeDir "%{home}/%{user}" –Gecos "%{u:displayName}" –Shell "%{shell}"

# Overriding the login name
New-CdmUserProfile -Zone $zone –User -login bart -UseAutoUid -AutoPrivateGroup –HomeDir "%{home}/%{user}" –Gecos "%{u:displayName}" –Shell "%{shell}"

# Overriding UID and Primary Group
New-CdmUserProfile -Zone $zone –User –login maggie.simpson -Uid 5024 -PrimaryGroup 200 –HomeDir "%{home}/%{user}" –Gecos "%{u:displayName}" –Shell "%{shell}"

# Overriding Home and GECOS
New-CdmUserProfile -Zone $zone –User–login homer -UseAutoUid -AutoPrivateGroup –HomeDir "/export/home/%{user}" –Gecos "Homer the King" –Shell "%{shell}"

Notes:  Use overrides very very sporadically.


Assigning Roles

Recap:  In UNIX, users need an Identity and a role that allows them to log in to access a UNIX system.  On Windows, all they need is a role.  Although you can assign these roles directly to user principals, in a large enterprise roles will be assigned to AD groups.  This means that this can be automated using the AD PowerShell commands or any other ADSI interface.  Here are some examples with individual assignments:


Assign a role at the zone level (infrequent)

$role1 = Get-CdmRole -Zone $zone -Name "UNIX SysAdmin"  
New-CdmRoleAssignment -Zone $zone -Role $role1 -ADTrustee

I would add some logic to make sure the target user is UNIX-enabled.


Assign a role at the Computer Role level (should be the majority)

$role2 = Get-CdmRole -Zone $zone -Name "Mixed Auditor" 
$crweb = Get-CdmComputerRole -Zone $zone -Name "Web Servers" 

New-CdmRoleAssignment -ComputerRole $crweb  -Role $role2 -ADTrustee

Notice how the parameters can be potentially selected with a Form.


Assign a "Break Glass" or Emergency access to an individual system for an hour

$role3 = Get-CdmRole -Zone $zone -Name "UNIX login"  
$comp = Get-CdmManagedComputer -Zone $zone -Name "your-zone-enabled-system" 

New-CdmRoleAssignment -Computer $comp -Role $role3 -ADTrustee -StartTime (Get-Date) -EndTime (Get-Date).AddMinutes(60)






  • The Access Control and Privilege Management Scripting Guide contains the manual for the PowerShell commandlets, and can be obtained from the Documentation Center.
  • Centrify Enterprise Edition (DirectAudit) also debuted a PowerShell module with version 2015.
  • The \Centrify\PowerShell\Centrify.DirectControl.PowerShell folder contains sample code that can be reused for different tasks.  There are samples for reporting as well.
  • Prefer to do everything via the UNIX CLI?  Remember, adedit has been around for a long time and it uses the same APIs.