pbis programmer's guide - beyondtrust.com fileintroduction...

PowerBroker Identity ServicesProgrammer's Guide

Revision/Update Information: February 2016

Corporate Headquarters5090 N. 40th StreetPhoenix, AZ 85018Phone: 1 818-575-4000

COPYRIGHT NOTICECopyright © 2016 BeyondTrust Software, Inc. All rights reserved. Use of this software and/or document, as and whenapplicable, is also subject to the terms and conditions of the license between the licensee and BeyondTrust Software, Inc.(“BeyondTrust”) or BeyondTrust’s authorized remarketer, if and when applicable.

TRADE SECRET NOTICEThis software and/or documentation, as and when applicable, and the information and know-how they contain constitute theproprietary, confidential and valuable trade secret information of BeyondTrust and/or of the respective manufacturer orauthor, and may not be disclosed to others without the prior written permission of BeyondTrust. This software and/ordocumentation, as and when applicable, have been provided pursuant to an agreement that contains prohibitions againstand/or restrictions on copying, modification and use.

DISCLAIMERBeyondTrust makes no representations or warranties with respect to the contents hereof. Other than, any limited warrantiesexpressly provided pursuant to a license agreement, NO OTHER WARRANTY IS EXPRESSED AND NONE SHALL BE IMPLIED,INCLUDING WITHOUT LIMITATION THE WARRANTIES OF MERCHANTABILITY AND FITNESS FOR USE OR FOR A PARTICULARPURPOSE.

LIMITED RIGHTS FARS NOTICE (If Applicable)If provided pursuant to FARS, this software and/or documentation, as and when applicable, are submitted with limited rights.This software and/or documentation, as and when applicable, may be reproduced and used by the Government with theexpress limitation that it will not, without the permission of BeyondTrust, be used outside the Government for the followingpurposes: manufacture, duplication, distribution or disclosure. (FAR 52.227.14(g)(2)(Alternate II))

LIMITED RIGHTS DFARS NOTICE (If Applicable)If provided pursuant to DFARS, use, duplication, or disclosure of this software and/or documentation by the Government issubject to limited rights and other restrictions, as set forth in the Rights in Technical Data – Noncommercial Items clause atDFARS 252.227-7013.

TRADEMARK NOTICESPowerBroker, PowerPassword, and PowerKeeper are registered trademarks of BeyondTrust. PowerSeries, PowerADvantage,PowerBroker Password Safe, PowerBroker Directory Integrator, PowerBroker Management Console, PowerBroker Desktops,PowerBroker Virtualization, PowerBroker Express, PowerBroker Databases, PowerBroker Windows Servers, PowerBrokerWindows Desktops, and PowerBroker Identity Services are trademarks of BeyondTrust.ssh® is a registered trademark of SSH Communications Security Corp in the United States and in certain other jurisdictions. TheSSH logo, Tectia and tectia logo are trademarks of SSH Communications Security Corp and may be registered in certainjurisdictions.This application contains software powered by PKAIP®, the leading solution for enabling efficient and secure data storage andtransmission. PKAIP® is provided by PKWARE, the inventor and continuing innovator of the ZIP file format. Used withpermission.

OTHER NOTICESIf and when applicable the following additional provisions are so noted:The PowerBroker Identity Services Open software is free to download and use according to the terms of the Limited GPL 2.1for client libraries and the GPL 2 for daemons. The licenses for PowerBroker Identity Services Enterprise and for PowerBrokerIdentity Services UID-GID Module are different. For complete information on the software licenses and terms of use forBeyondTrust products, see www.beyondtrust.com.

Contents

Introduction 4

Overview 4

Turning On Scripting 5

Simple Scripting with VBScript 6

Programming with the PBIS API Using C# 9

Programming with PBIS Types 9

Programming with PowerBroker Types Using C# Reflection 11

ReflectedObject class 13ReflectedIdentity class 14ReflectedCell class 17Content of “CustomPathToDSUtil.txt” file 18Program class 18

Advanced Topics 21

ADSI References 21Fully Qualified Domain Names 21

Programming Reference 22

ILikewiseIdentity 22ILikewiseCell 22ILikewiseUser 24ILikewiseGroup 25

Appendix A: PowerShell Example 26

Contents

Programmer's Guide 3 © 2016. BeyondTrust Software, Inc.

IntroductionPowerBroker Identity Services joins Unix, Linux, and Mac OS X computers to Active Directory so that you cancentrally manage all your computers from one source, authenticate users with the highly secure Kerberos 5protocol, control access to resources, and apply group policies to non-Windows computers. The result: Vastlysimplified account management, improved security, reduced infrastructure costs, streamlined operations, andeasier regulatory compliance.

PowerBroker Identity Services provides graphical tools to manage Linux and Unix information in Active Directory.However, it can be useful to access and modify the information programmatically. For this purpose, PowerBrokerIdentity Services provides scripting objects that can be used by any programming language that supports theMicrosoft Common Object Model, or COM. The scripting objects provide dual interfaces that can be used bylanguages that use COM early binding, such as C++ and C#, and by languages that use Idispatch, such as VBScript andJscript.

This document describes the PowerBroker Identity Services scripting objects and explains how to use them.

OverviewPowerBroker Identity Services stores Unix data for account objects within a logical structure known as a Cell. Thisstorage is a representative mapping of Unix data to a particular account object. Where this data is actually storedwithin Active Directory depends on the Cell type and mode that has been chosen for a particular implementation.

The purpose of the PowerBroker Identity Services Management Tools, including the COMmodel discussed in thisdocument is to abstract the actual location of the data to the end-user. In this way, an end-user (eitheradministrator or programmer) does not need to know exactly where to modify attributes within the Cell, butrather only needs to call upon the specific AD account objects (users or groups) directly.

The COMmodel methods will ensure that the data is read from and written to the appropriate place in thedirectory based on the Cell type and mode in use for a particular environment. In all cases users should not attemptto modify Cell objects directly (either manually or via code), but rather make modifications to the AD user andgroup account objects through the provided toolsets.

For more information on cell types, refer to the PBIS Administration Guide.

Introduction


Turning On ScriptingBefore you can use the PowerBroker Identity Services scripting objects, you must first register the PBIS DLL thatprovides this functionality. This DLL, LikewiseIdentity.dll, is placed in the PBIS installation directory, c:\programfiles\BeyondTrust\PBIS.

Register the DLL by using the Microsoft .NET regasm utility:

Regasm “c:\program files\BeyondTrust\PBIS\LikewiseIdentity.dll”

Note: If your system can not find regasm, you may need to use it from%windir%\Microsoft.NET\Framework\v2.0.50727 or to add this directory to your path.

Turning On Scripting


Simple Scripting with VBScriptTo access the PowerBroker Identity Services scripting objects from VBScript (using either cscript.exe orwscript.exe), you must first use CreateObject to create an instance of the main PBIS object:

Dim oLWIMainSet oLWIMain = CreateObject("Likewise.Identity")

Once you have this object, your first step is to connect to the Active Directory domain that you want to access.There are two ways of doing this:

Dim oLWISet oLWI = oLWIMain.InitializeoLWI.Connect "LDAP://server/dc=yourdomain,dc=com"' Alternatively

' oLWI.ConnectEx "LDAP://server/dc=yourdomain,dc=com", "username","password"

The first form of Connect uses your current login credentials whereas the second form allows you to pass in analternate set of credentials. If you need to make changes to Active Directory, it's essential that you have sufficientprivileges to do so.

Regardless of which form you use, at this point, you now have an object (oLWI) that is connected to PowerBrokerIdentity Services and is ready to access information. This object implements the ILikewiseIdentity interface.This interface allows you to access and manipulate PowerBroker cells.

You can get a list of all the cells in a domain or a particular cell in the domain as follows:

Dim listCellsDim oCellSet listCells = oLWI.GetCells()For each oCell in listCells

' Do something with oCellNext

Set oCell = oLWI.GetCell("OU=Engineering")

Note that when accessing a specific cell, you have to provide the Active Directory canonical name (cn) of the cell.Other PBIS scripting objects will follow this pattern. You will specify canonical names that PBIS will interpret relativeto the distinguished name (dn) that you specified when connecting to your domain.

To create or delete a cell:

Set oCell = oLWI.CreateCell("OU=Accounting")oLWI.DeleteCell aCell

Note that to delete a cell, you provide a cell object rather than its canonical name.

Cell objects implement the ILikewiseCell interface. This interface provides several properties that let youget/set information about the cell and several methods to let you access and manipulate the users and groups thathave been enabled.

Simple Scripting with VBScript


' Get various cell propertiessDisplayName = oCell.DisplayNamebIsDefaultCell = oCell.IsDefaultCellnNextUID = oCell.NextUIDnNextGID = oCell.NextGIDsDefaultHomeDir = oCell.DefaultHomeDirectorysDefaultShell = oCell.DefaultLoginShell

Dim listUsersSet listUsers = oCell.GetUsers()Dim listGroupsSet listGroups = oCell.GetGroups()

You can set these properties to make changes to a cell. Note that the PBIS objects, in a style similar to MicrosoftADSI (Active Directory Scripting Interface) objects, require that you call a method to explicitly commit yourchanges:

' Change the default login shell to use bash and the default home diroCell.DefaultLoginShell = "/bin/bash"

oCell.DefaultHomeDir = "/local/%d/%u"oCell.CommitChanges

Property changes are not written to Active Directory until you call CommitChanges. This pattern improvesperformance by delaying Active Directory LDAP write operations until requested.

As with the main object, cell objects let you request all the users and groups enabled in the cell or let you accessspecific ones. Additionally, methods are provided to let you enable and disable users and groups in a cell:

' Fetch a particular userDim oUserSet oUser = oCell.GetUser("cn=Bob Smith,cn=Users")

' Enable a new user, specifying "Domain Users" as her primary groupsDU = "cn=Domain Users,cn=Users"Set oUser = oCell.EnableUser("cn=Jane Done,cn=Users", sDU)

' Enable a new user, with an explicit UIDSet oUser = oCell.EnableUserEx("cn=Clark Kent,cn=Users", sDU, 127)

' Disable a useroCell.DisableUser oUser

' Fetch a particular groupDim oGroupSet oGroup = oCell.GetGroup(sDU)

' Enable a group letting Likewise assign a new GIDSet oGroup = oCell.EnableGroup("cn=Enterprise Admins,cn=Users")

' This time, specify an explicit GIDSet oGroup = oCell.EnableGroupEx("cn=Printer Operators,cn=Users", 444)

' Disable a groupoCell.DisableGroup oGroup



User and Group objects implement the ILikewiseUser and ILikewiseGroup interfaces (respectively).These follow similar patterns:

' Fetch some user propertiessDisplayName = oUser.DisplayNamesSID = oUser.SIDnUID = oUser.UIDnGID = oUser.GIDsLoginName = oUser.LoginName ' Actually, the *alias* namesHomeDir = oUser.HomeDirectorysLoginShell = oUser.LoginShellsGECOS = oUser.GECOS

' Change the user comment fieldoUser.GECOS = "A fine user of Likewise"oUser.CommitChanges

' Fetch some group propertiessDisplayName = oGroup.DisplayNamesSID = oGroup.SIDnGID = oGroup.GIDsGECOS = oGroup.GECOSsGroupAlias = oGroup.GroupAlias

' Change the GID for the groupoGroup.GID = 723oGroup.CommitChanges



Programming with the PBIS API Using C#To programmatically access PBIS with a .NET language, you don't need to go through the IDispatch mechanismdescribed in “Simple Scripting with VBScript,” page 6. Rather than using the LikewiseIdentity.DLL library,you can reference the Likewise DSUtil.DLL library directly. This library is found in the same PBIS installationdirectory.

Note that LWUnifiedProvider.dll should be referenced as well in order for DSUtil.dll to function properly.

The DSUtil library exposes the LikewiseIdentity class. This is the actual implementer of theILikewiseIdentity interface described earlier.

Programming with PBIS Typesusing System.Text;using Centeris.Likewise.Auth;namespace ScriptTest{

class Program{

static void Main(string[] args)

{

// create an instance of LikewiseIdentityLikewiseIdentity lwi = new LikewiseIdentity();

lwi.Connect("LDAP://dc=yourdomai,dc=com");

ILikewiseCell Cell = lwi.GetCell("OU=test");

// relative DN of group of interest (object in AD - not within acell)

string sRelativeDN_ofGroup = "CN=Domain Users,CN=Users";

// Not "CN=Domain Users,CN=Groups,CN=$LikewiseIdentityCell,OU=test";ILikewiseGroup Group = Cell.GetGroup(sRelativeDN_ofGroup);Console.WriteLine(Group.DisplayName);

// relative DN of user of interest (object in AD - not within a cell)string sRelativeDN_ofUser = "CN=test name,OU=test";

// Not "CN=testname,CN=Users,CN=$LikewiseIdentityCell,OU=test";ILikewiseUser User = Cell.GetUser(sRelativeDN_ofUser);Console.WriteLine(User.DisplayName);

. . .

Programming with the PBIS API Using C#


NoteA relative DN to objects outlined by blue line shall be provided instead of relative DN to objects highlighted withyellow.

Programming with the PBIS API Using C#


Programming with PowerBroker Types Using C# ReflectionIn custom projects where it is not desirable to have a direct reference to PowerBroker Identity Serviceslibraries,you can program against PBIS libraries using C# Reflection with an option to provide custom path to location whereDSUtil.dll and LWUnifiedProvider.dll reside.

Below is an example of code and files for custom library that uses Reflection to use the PowerBroker IdentityServices API without direct references to the libraries.

Location of PowerBroker Identity Services cell in Active Directory:

Programming with PowerBroker Types Using C#


Solution Files tree

ReflectedObjectsPBIS project provides base class for custom objects that “reflect” PowerBroker Identity Servicestypes.

In the Derived folder are two examples of “reflected” types. More types or more functionality to the providedones can be added by browsing PBIS types through the Object Browser or Class View in Visual Studio, choosingnames of types and/or methods and properties and implementing them as shown in classes from theReflectedObjects folder.

The “CustomPathToDSUtil.txt” file is an optional configuration (which is implemented the way it is for simplicity) toprovide custom location from which PowerBroker Identity Services libraries will be loaded.

The code in ReflectedIdentity class will look for this file and a path within it.

In case file is not found – the default PowerBroker Identity Services installation location will be used to find thelibraries to load.

The “Test” project is a Console application that shows how “reflected” objects are used in custom code.

Below is content from files shown in Solution above.



ReflectedObject class

using System;

using System.Collections.Generic;

using System.Text;

using System.Reflection;

namespace ReflectedObjectsPBIS

{

/// <summary>

/// Base class for objects that will serve as a wrapper around objects reflected from PBIS DSUtil.dll

/// </summary>

public abstract class ReflectedObject

{

protected Type _objectType;

protected object _objectInstance;

public ReflectedObject(Type objectType)

{

_objectType = objectType;

_objectInstance = Activator.CreateInstance(objectType);

}

public ReflectedObject(object instance)

{

_objectInstance = instance;

_objectType = instance.GetType();

}

protected object Invoke(string methodName)

{

return Invoke(methodName, new object[] { });

}

protected object Invoke(string methodName, object[] arguments)

{

BindingFlags flags = BindingFlags.InvokeMethod |

BindingFlags.Instance |

BindingFlags.Public |



BindingFlags.GetProperty |

BindingFlags.Static;

return _objectType.InvokeMember(methodName, flags, null, _objectInstance, arguments);

}

}

}

ReflectedIdentity classusing System;


using System.Text;

using System.Collections;

using System.Reflection;

using System.IO;


{

/// <summary>

/// Wrapper around LikewiseIdentity from DSUtil.

/// Serves as a mean to code against in custom projects

/// </summary>

public class ReflectedIdentity : ReflectedObject

{

private ReflectedIdentity(Type objectType)

: base(objectType) { }

public void ConnectEx(string LDAP_Path, string AD_UserName, string AD_Password)

{

Invoke("ConnectEx", new object[] { LDAP_Path, AD_UserName, AD_Password });

}

public ArrayList GetCells()

{

return (ArrayList)Invoke("GetCells");

}



public ReflectedCell GetCell(string Cell_OU_Path)

{

object cell = Invoke("GetCell", new object[] { Cell_OU_Path });

return new ReflectedCell(cell);

}

// Implement other methods (and/or properties) below as needed //

// .....

// -------- ReflectedIdentity Instance creation -------------

public static ReflectedIdentity GetInstance()

{

Assembly a = LoadAssembly();

Type[] atyp = a.GetTypes();

foreach (Type t in atyp)

{

if (t.FullName == "Centeris.Likewise.Auth.LikewiseIdentity")

return new ReflectedIdentity(t);

}

throw new ApplicationException("Can't get Centeris.Likewise.Auth.LikewiseIdentity type");

}

private static Assembly LoadAssembly()

{

string PBIS_path = GetPBISdllsLocationPath();

return Assembly.LoadFrom(PBIS_path);

}

/// <summary>

/// !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!

/// The LWUnifiedProvider.dll MUST be present in the same location with DSUtil.dll !!!

/// !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!

/// </summary>

/// <returns></returns>

private static string GetPBISdllsLocationPath()



{

string pathTo_PBIS_DSUtil;

if (NotFoundInConfig(out pathTo_PBIS_DSUtil))

pathTo_PBIS_DSUtil = Environment.ExpandEnvironmentVariables(@"%systemdrive%\ProgramFiles\BeyondTrust\PBIS\Enterprise\dsutil.dll");

if(!File.Exists(pathTo_PBIS_DSUtil))

throw new ApplicationException(String.Format("DSUtil.dll is not found in {0} or path to it is not a validpath.", pathTo_PBIS_DSUtil));

return pathTo_PBIS_DSUtil;

}

private static bool NotFoundInConfig(out string pathTo_PBIS_DSUtil)

{

string nameOfFileWithCustomPath = "CustomPathToDSUtil.txt";

pathTo_PBIS_DSUtil = null;

if (!File.Exists(nameOfFileWithCustomPath))

return true;

using (StreamReader reader = new StreamReader("CustomPathToDSUtil.txt"))

{

pathTo_PBIS_DSUtil = reader.ReadLine();

}

if (String.IsNullOrEmpty(pathTo_PBIS_DSUtil))

throw new ApplicationException("pathTo_PBIS_DSUtil is not found");

if (!pathTo_PBIS_DSUtil.ToLower().EndsWith("dsutil.dll"))

throw new ApplicationException("pathTo_PBIS_DSUtil does not point to DSUtil.dll");

return false;

}

}



}

ReflectedCell class

using System;


using System.Text;



{

/// <summary>

/// Wrapper around ILikewiseCell from DSUtil.

/// Serves as a mean to code against in custom projects

/// </summary>

public class ReflectedCell : ReflectedObject

{

public ReflectedCell(object instance)

: base(instance) { }

public ArrayList GetGroups()

{

return (ArrayList)Invoke("GetGroups");

}

public ArrayList GetUsers()

{

return (ArrayList)Invoke("GetUsers");

}

public string DisplayName

{

get { return (string)Invoke("DisplayName"); }

}

// Implement other methods (and/or properties) below as needed //



// .....

}

}

Content of “CustomPathToDSUtil.txt” file

“C:\Program Files\BeyondTrust\PBIS\Enterprise\DSUtil.dll”

Program class

using System;


using System.Text;


using ReflectedObjectsPBIS;

namespace Test

{

class Program

{

static void Main(string[] args)

{

string LDAP_Path = "LDAP://MyDomain.com/dc=MyDomain,dc=com";

string Cell_OU_Path = "OU=test";

string AD_UserName = null; // "<USERNAME>";

string AD_Password = null; // "<PASSWORD>";

ArrayList cells = new ArrayList();

ArrayList users = new ArrayList();

ArrayList groups = new ArrayList();

try

{

// listing variables...

Console.WriteLine("Variables:");



Console.WriteLine("LDAP_Path:" + LDAP_Path);

Console.WriteLine("Cell_OU_Path:" + Cell_OU_Path);

Console.WriteLine("AD_UserName: " + AD_UserName);

Console.WriteLine("AD_Password: " + AD_Password);

Console.WriteLine();

ReflectedIdentity identity = ReflectedIdentity.GetInstance(); // - instead of: //ILikewiseIdentity lwi = newLikewiseIdentity();

// executing connection...

Console.WriteLine("Executing ConnectEx(\"{0}\", \"{1}\", \"{2}\") ...", LDAP_Path, AD_UserName, AD_Password);

identity.ConnectEx(LDAP_Path, AD_UserName, AD_Password);


// enumerating all cells...

Console.WriteLine("Getting Cells... ");

cells = identity.GetCells();

Console.WriteLine("Cells count: " + cells.Count);


// getting one particular cell...

Console.WriteLine("Geting cell \"{0}\"", Cell_OU_Path);

ReflectedCell cell = identity.GetCell(Cell_OU_Path);

string message = (null == cell) ? "Cell is not found" : String.Format("cell name: {0}", cell.DisplayName);

Console.WriteLine(message);


// getting groups...

Console.WriteLine("Getting Groups...");

groups = cell.GetGroups();

Console.WriteLine("Found {0} group{1}", groups.Count, groups.Count == 1? "": "s");


// getting users...

Console.WriteLine("Getting Users...");

users = cell.GetUsers();

Console.WriteLine("Found {0} user{1}", users.Count, users.Count == 1 ? "" : "s");




}

catch (Exception ex)

{

Console.WriteLine("Operation failed");

Console.WriteLine("Exception is: ");

Console.WriteLine(ex);

}

Console.ReadLine();

}

}

}



Advanced TopicsIt is important to keep in mind that the PBIS objects are associated with other objects in Active Directory.

• A PBIS cell object is associated with an AD organizational unit.

• PBIS user and group objects are associated with Active Directory objects of the same name.

Note that the PBIS objects are not the same as the AD objects with which they are associated. Identity objects existin parallel with the actual AD objects.

Occasionally, it might be necessary to access the AD objects associated with Identity objects. Each Identityobject provides a property that lets you do this:

' Access the AD user object associated with the Identity user objectDim oADSIUserSet oADSIUser = oUser.User

' Access the AD group object associated with the Identity group objectDim oADSIGroupSet oADSIGroup = oGroup.Group

' Access the AD organizational unit object associated with the Identity cellobjectDim oADSIOUSet oADSIOU = oCell.OU

ADSI ReferencesWith access to the associated AD objects, you can now use ADSI properties and methods to manipulate the objects.The specifics of these operations are not described in this guide.

Refer to Microsoft documentation and such books as the O'Reilly series on Active Directory:

• Richards, Joe, Robbie Allen, Alistair G. Lowe-Norris, and Brian Desmond. Active Directory. Sebastopol, CA:O'Reilly, 2013.

• Allen, Robbie and Brian Svidergol. Active Directory Cookbook. Sebastopol, CA: O'Reilly, 2013.

Visit the following web site for more information on ADSI programming:

www.selfadsi.org

Fully Qualified Domain NamesUse Fully qualified domain names instead of IP addresses whenever you need to specify a server.

This ensures that the DNS can be resolved. Issues might occur with DNS resolution if you use only the IP address inyour script.

Advanced Topics


http://www.selfadsi.org/

Programming ReferenceThis section describes the objects and interfaces that are provided by PBIS.

ILikewiseIdentity

Properties(none)

Methodsvoid Connect(string sLDAPPath)

void ConnectEx(string sLDAPPath, string sUsername, string sPassword)These methods connect the Likewise object to a particular Active Directory domain. The first form uses thecurrent login credentials whereas the second form specifies explicit credentials. In both forms, sLDAPPath isa full LDAP distinguished name (dn) identifying the directory to which the object should connect (for example,"LDAP://mydc/dc=mydomain,dc=com").

IEnumerable GetCells()This method retrieves a collection of all the cells defined in a domain. The collection can be traversed by usingan interator (such as For Each in VBScript). Each returned cell object implements the ILikewiseCellinterface.

ILikewiseCell GetCell(string sOUPath)Retrieves an ILikewiseCell object for a particular cell identified by sOUPath. sOUPath is the canonicalname of the organizational unit with which the cell is associated (for example,"ou=Accounting,ou=Western Region").

ILikewiseCell CreateCell(string sOUPath);ILikewiseCell CreateCellEx(string sOUPath,uint nNextUID,uint nNextGID,string sDefaultShell,string sDefaultHomeDirectory)These methods create a new cell in a domain. In both forms, the sOUPath is the canonical name of theorganizational unit with which the cell is to be associated. In the first form, PBIS will automatically set theNextUID, NetGID, DefaultShell, and DefaultHomeDirectory properties of the new cell as perthe defaults. In the second form, these properties are set explicitly.

bool DeleteCell(ILikewiseCell lwc)Deletes a cell from a domain. The cell to be deleted is identified by the lwc argument. Note that this is not acanonical name – a cell must first be "gotten" with GetCell before it can be deleted.

ILikewiseCell

Propertiesstring DisplayName (Read only)

Contains the displayable name of the cell. This is actually the displayName attribute of the organizationalunit with which the cell is associated.

object OU (Read only)

Programming Reference


Returns ADSI object of the organizational unit with which the cell is associated.

string GuidOU (Read only)

Returns the GUID of the organizational unit with which the cell is associated.

uint NextUID (Read/write)

uint NextGID (Read/write)

These properties contain the next user ID and group ID that will be automatically allocated to users and groups(respectively) enabled in the cell.

bool IsDefaultCell (Read only)

This read-only property is set to true if the cell is default cell for the domain. The default cell is associated withthe top-most domain object rather than with any particular organizational unit.

string DefaultHomeDirectory (Read/write)

Contains the default home directory that will be applied to any new users enabled in the cell. The value of thisproperty should use "%D" and "%U" as placeholders for the user's domain and user name. For example,setting this property to "/home/%d/%u" (its default value) means that the user [email protected] willhave his home directory set to "/home/mydomain/joe".

string DefaultLoginShell (Read/write)

Contains the default shell program that will be applied to any new users enabled in the cell. By default, this isset to "/bin/bash".

List<string> LinkedCells (Read)

Returns the list of cells to which this one is linked. The PBIS Agent searches linked cells for UID, GID and otherinformation after searching the current cell. The cells are searched in order with a match stopping the searchoperation. This implies that linked cells that appear earlier in the list take precedence over ones later in the list.

The list contains the GUIDs for the linked cells. Although the property is read-only, the returned list can bemodified.

Methodsbool CommitChanges()

Writes any modified property values out to Active Directory. If you changed any property settings, you mustcall this method to make those changes permanent.

IEnumerable GetUsers()Returns a collection of all the users enabled in the cell. Each of the objects in the enumeration implements theILikewiseUser interface.

ILikewiseUser GetUser(string sCNUser)Returns an ILikewiseUser object for the object identified by the sCNUser argument. This argument shouldbe the AD canonical name of the user, for example, "cn=Joe Smith,cn=Users".

ILikewiseUser EnableUser(string sCNUser, string sCNPrimaryGroup)ILikewiseUser EnableUserEx(string sCNUser, string sCNPrimaryGroup, uint nUID)

These methods enable a user to access computers in the cell. The user is identified by the AD canonical namein the sCNUser argument. The sCNPrimaryGroup argument identifies an AD group that has beenpreviously enabled in the cell. The user's Linux/Unix primary group ID will be set to the GID of this enabledgroup. The first form of this method lets PBIS automatically assign a UID in the cell to the user. The second formspecifies an explicit UID.



bool DisableUser(ILikewiseUser lwu)This method disables a user in a cell, disallowing access to Linux/Unix computers in the organizational unit withwhich the cell is associated. The lwu argument specifies an ILikewiseUser object previously obtainedwith GetUsers or GetUser.

ArrayList GetGroups()Returns a collection of all the groups enabled in the cell. Each of the objects in the enumeration implementsthe ILikewiseGroup interface.

ILikewiseGroup GetGroup(string sCNGroup)Returns an ILikewiseGroup object for the object identified by the sCNGroup argument. This argumentshould be the AD canonical name of the group, for example, "cn=Domain Admins,cn=Users".

ILikewiseGroup EnableGroup(string sCNGroup)ILikewiseGroup EnableGroupEx(string sCNGroup, uint nGID)

These methods enable the use of an AD group within a PowerBroker cell. Enabling a group assigns it a group IDin that cell. The first form of this method lets PBIS automatically assign a GID. The second form specifies the GIDexplicitly. In both forms, the sCNGroup argument should be set to the canonical name of the AD group that isto be enabled in the cell (for example, "cn=Enterprise Admins,cn=Users"). Note that enabling agroup in a cell does not automatically enable the users that are members of the group.

bool DisableGroup(ILikewiseGroup lwg)This method disables a group in a cell. The lwg argument specifies an ILikewiseGroup object previouslyobtained with GetGroups or GetGroup.

ILikewiseUser


Contains the displayable name of the user. This is actually the displayName attribute of the AD user objectwith which the ILikewiseUser object is associated.

object User (Read only)

Returns ADSI object of the AD user object with which this ILikewiseUser object is associated.

string SID (Read only)

Returns the SID of the AD user object with which this ILikewiseUser object is associated.

uint UID (Read/write)

uint GID (Read/write)

These properties contain the UID and GID of the user as assigned within the cell from which thisILikewiseUser object was obtained.

string LoginName (Read/write)

This property contains the Linux/UNIX login name of the user as set within the cell from which thisILikewiseUser object was obtained. If this is left blank, the login name will be the same as thesAMAccountName of the user which which this ILikewiseUser object is associated. If it is not blank, theLoginName is considered an "alias" for the user.

string HomeDirectory (Read/write)



Contains the home directory for the user as set within the cell from which this IlikewiseUser object wasobtained. Note that this property must not contain any spaces (even if the user's name contains them).

string LoginShell (Read/write)

Contains the Linux/Unix shell that will be started initially when the user logs on to a Linux/Unix computer inthe cell.

string GECOS (Read/write)

Contains the GECOS "comment" field associated with the user within the current cell.


Writes any modified property values out to Active Directory. If you have changed any property settings, youmust call this method to make those changes permanent.

ILikewiseGroup


Contains the displayable name of the group. This is actually the displayName attribute of the AD groupobject with which the ILikewiseGroup object is associated.

object Group (Read only)

Returns ADSI object of the AD group object with which this ILikewiseGroup object is associated.

string SID (Read only)

Returns the SID of the AD group object with which this ILikewiseGroup object is associated.

uint GID (Read/write)

This properties contains the GID of the group as assigned within the cell from which this ILikewiseGroupobject was obtained.

string GECOS (Read/write)

Contains the GECOS "comment" field associated with the group within the current cell.

string GroupAlias (Read/write)

Contains the group alias of the group. Group aliases are when mapping an AD group to a different group nameon UNIX/Linux.


Writes any modified property values out to Active Directory. If you have changed any property settings, youmust call this method to make those changes permanent.



Appendix A: PowerShell ExampleInstantiates COM object, connects to cell, gets cell user, binds to user’s corresponding ADSI object:

$objLWIMain = New-Object -ComObject "Likewise.Identity"$objLWI = $objLWIMain.Initialize().WrappedObject$objLWI.Connect("LDAP://dc=wingtiptoys,dc=com")$objCell = $objLWI.GetCell("")write-host $objCell.DisplayName$oADSICell = [ADSI]$objCell.OUwrite-host $oADSICell.distinguishedName$objUser = $objCell.GetUser("cn=Joe Smith,ou=Users,ou=PBIS") write-host

$objUser.DisplayName $oADSIUser = [ADSI]$objUser.User $oADSIUser | Get-Member write-host $oADSIUser.distinguishedName

Appendix A: PowerShell Example


pbis programmer's guide - beyondtrust.com fileintroduction...

Documents