Object Model Quick Start
- Phillip Hanegan
- Anonymous
The Workflow Studio object model or API provides you with all the tools necessary for programmatic access to organizational data, allowing you to view and manipulate each object protected by the EmpowerID Identity Warehouse. In this way, you can create your own custom applications, workflows, activities, and services to allow clients to view and manipulate that data.
Workflow Studio provides an Object Browser to allow you to view the namespaces and members of those namespaces that make up the EmpowerID object model. You can access the Object Browser in Workflow Studio by clicking the Object Browser button on the Common tab of the Workflow Studio ribbon.
Authenticating Applications to EmpowerID
As a claims-based web services platform, all communications to and from EmpowerID occurs over a web service that connects to the EmpowerID Security Token Service (ESTS). When a client attempts to access EmpowerID, the STS Location Service directs the request to the ESTS, which either issues a token based on the claims presented by the client or denies the request for access. This is true for all calls made against the EmpowerID API from all applications, including those applications that ship with the default configuration of EmpowerID.
For example, when a user launches the EmpowerID Management Console (EMC), two types of claims are presented to the EmpowerID STS—the claims of the EMC itself and any claims associated with the person launching the EMC. The first set of claims is used to determine that the EMC is a valid application authorized to be used as a vehicle for making API calls and the second set is to ensure that the person using the application is authorized to use it for making those API calls. When building applications and services on the EmpowerID platform, you must be sure that both the application user as well as the application itself can be authenticated. If one or the other is missing, the call will fail and access will be denied. This approach protects organizational data from unauthorized access.
//Authenticating an application and application user with EmpowerID credentials ... using System.IdentityModel; using System.IdentityModel.Tokens; using System.ServiceModel; using TheDotNetFactory.Framework; using TheDotNetFactory.FrameWork.Common; using TheDotNetFactory.FrameWork.Common.Shared; using TheDotNetFactory.Framework.Core; using TheDotNetFactory.Framework.RESTfulService; using TheDotNetFactory.Framework.ServiceBus; using W = TheDotNetFactory.Framework.Workflow2012; ... //Provide the STS Location Service endpoint using the FQDN of your EmpowerID web server string workflowServerURL = "https://eid.tdnfdemo.com:7080"; //Get a security token from the EmpowerID STS using the credentials of an EmpowerID person SecurityToken token = W.EIDServerContext.IssueToken(workflowServerURL,"waames","pass@word1"); //Use the token to create a trust between EmpowerID and the application EmpowerIDContext.CreateSQLOverWCFClientApplicationTrust(workflowServerURL, token);
Working with Person Objects
In EmpowerID, a person is an object in the EmpowerID SQL-based Identity Warehouse that links together the user accounts, permissions assignments, audit history, and management policies associated with an identity. The EmpowerID Person is the base identity in the EmpowerID RBAC model and is necessary for accessing resources and performing tasks in EmpowerID. The Workflow Studio object model contains two namespaces with multiple classes for working with people in EmpowerID—the People.Components namespace and the People.Entities namespace. Each of these namespaces have classes corresponding to each of the object tables in the EmpowerID Identity Warehouse. You can use the members of these classes to directly interact with the data in the Identity Warehouse. The following examples demonstrate some of the more common use cases.
Required Namespaces
When working with Person objects, minimally you should add references to the following namespaces:
using TheDotNetFactory.Framework; using TheDotNetFactory.FrameWork.Common; using TheDotNetFactory.FrameWork.Common.Shared; using TheDotNetFactory.Framework.Core; using C = TheDotNetFactory.Framework.People.Components; using E = TheDotNetFactory.Framework.People.Entities;
Get by Job Title
string columnsToSearch = "Title"; string textToSearch = "Helpdesk"; var pageLength = 500; int totalCount; E.VList<C.PersonView> p = C.PersonView.GetAllSearch(columnToSearch, textToSearch, 1, pageLength, out totalCount); //Write the results to the console foreach(var a in p) Console.WriteLine("Name: {0}, Login: {1}, PersonID: {2}", a.Name, a.Login, a.PersonID);
Create a new Person object
C.Person p = new C.Person(); p.LastName = "Simone"; p.FirstName = "John"; p.Name = "John Simone"; p.Active = true; p.AllowLogin = true; p.Login = "jSimone"; //Add the person object to the Identity Warehouse p.Insert();
Get People without Accounts
string columnsToSearch = ""; string textToSearch = ""; E.VList<C.PersonView> pView = C.PersonView.GetPeopleWithNoAccounts(columnsToSearch, textToSearch); //Write the results to the console if (pView.Count > 0) { foreach (var a in pView) Console.WriteLine("Name: {0}", a.FriendlyName); }
Execute Account RETs
string columnsToSearch = ""; string textToSearch = ""; E.VList<C.PersonView> pView = C.PersonView.GetPeopleWithNoAccounts(columnsToSearch, textToSearch); //Create a new Person Components list E.TList<C.Person> pList = new E.TList<C.Person>(); //Create a new dictionary with an empty key to pass to the method that will provision any entitlements for the people without accounts Dictionary<string, object> myDictionary = new Dictionary<string, object>(); string str = ""; object obj = null; myDictionary.Add(str, obj); //Convert all people in the pView list to Person.Component objects and add them to the Person Components list //This allows us to call the methods associated with Person objects. if (pView.Count > 0) { foreach (var p in pView) if(p.FriendlyName != "empoweriduser") { pList.Add(p.ToPerson()); } //Provision any entitlements for the people. In this case we are setting the Primary OrgRoleOrgZone for each person //without an account to an OrgRoleOrgZone with a RET that grants people in that OrgRoleOrgZone a user account foreach(var x in pList) { x.PrimaryOrgRoleOrgZoneID = 2351; x.Update(); C.ResourceEntitlement.ProvisionPersonEntitlements(x, myDictionary); x.Update(); } }
Change the primary Business Role and Location
//Pass in the PersonID C.Person p = C.Person.GetByPersonID(3174); //Pass in the new primary Business Role and Location by OrgRoleOrgZoneID p.ChangePrimaryOrgRoleOrgZone(2307);
Disable a Person
//This does not disable user accounts associated with the person C.Person p = C.Person.GetByPersonID(3174); p.Disable();
Reset a Person's Password
C.Person p = C.Person.GetByLogin("jSimone"); p.ResetPassword("myNewPass@word123");
Unlock a Person
//Pass in the Person ID C.Person p = C.Person.Unlock(3174);
Get Access Assignments
string columnsToSearch = " "; string textToSearch = " "; E.Vlist<C.RbacResourceRoleAssignment> r = C.RbacResourceRoleAssignment.GetAllAssignedDirectlyToPersonID(3150, columnsToSearch, textToSearch);
Get People in Management Role
var personInManagementRole = C.Person.GetByManagementRoleID(19); //Write the results to the console Console.WriteLine("The following people are assigned to the {0} Management Role: ", C.ManagementRole.GetByManagementRoleID(18).Name); foreach (var p in personInManagementRole) Console.WriteLine(p.FriendlyName)
Get a Person's Management Role
var p = C.ManagementRole.GetByPersonID(3150); //Write the results to the console if (p.Count > 0) { Console.WriteLine("{0} has the following Management Roles: ", C.Person.GetByPersonID(3150).FriendlyName); foreach (var a in p) Console.WriteLine(a.FriendlyName); }
Get People in Business Role and Location
string columnsToSearch = "Friendly Name"string textToSearch = "Standard Employee in Temporary Location "; E.VList<C.PersonView> p = C.PersonView.GetByOrgRoleOrgZoneID(2309, columnsToSearch, textToSearch);
Get People in a Group
var grMembers = C.Person.GetByGroupID(66); //Write the results to the console if(grMembers.Count > 0) { Console.WriteLine("{0} has {1} members.", C.Group.GetByGroupID(66).FriendlyName, p.Count.ToString()); foreach (var m in grMembers) Console.WriteLine(m.FriendlyName); }
Get a Person's Group memberships
var grMemberships = C.GroupView.GetByPersonID(3148) //Write the results to the console foreach(var gr in grMemberships) Console.WriteLine("{0} is a member of {1}", C.Person.GetByPersonID(3150).FriendlyName, gr.FriendlyName);
Check specific access to a resource
//In this example, we pass in the specific PersonID, ResourceID, and Operation string operation = "List"; int resourceID = 93; int personID = 3150; var hasAccess = C.Resource.HasAccess(personID, resourceID, operation); //Write the results to the console Console.WriteLine(hasAccess);
Check all access to a resource
//Pass in the PersonID int personID = 3148; //Pass in the ResourceID int resourceID = 953500; //Check the allowed operations var allowedOperations = C.ResourceTypeOperation.GetByPersonIDAndResourceID(personID, resourceID); //Write the results to the console Console.WriteLine("{0} has the following operations allowed for {1}: ", C.Person.GetByPersonID(3148).FriendlyName, C.Resource.GetByResourceID(953500).FriendlyName); foreach(var operation in allowedOperations) Console.WriteLine(operation.Name);
Get People able to execute an operation against a resource
//In this example, we pass in the ResourceID of the resource and the name of the Operation int resourceID = 1183422; string operation = "MoveMailbox"; var whoHasAccess = C.Resource.GetPeopleWithAccess(resourceID, operation); //Write the results to the console foreach(var person in whoHasAccess) Console.WriteLine(person.FriendlyName);
Get all operations executed by a Person
var columnsToSearch = " "; var textToSearch = " "; var operationsExecutedByPerson = C.BusinessProcessTaskSlotView.GetByPersonID(3148, columnsToSearch, textToSearch); //Write the results to the console foreach (var operation in operationsExecutedByPerson) Console.WriteLine(operation.BusinessProcessTaskFriendlyName);
Working with User Accounts
In EmpowerID, user accounts are Identity Warehouse objects that represent the user accounts in external account stores, such as Active Directory or Office 365. User accounts are generally linked to EmpowerID Person objects, and as such, any actions performed against an account can affect the Person objects to which they are linked and vice-versa. As with the EmpowerID Person, the Workflow Studio object model contains two namespaces with multiple classes for working with accounts in EmpowerID—the People.Components namespace and the People.Entities namespace.
Required Namespaces
When working with Account objects, minimally you should add references to the following namespaces:
using TheDotNetFactory.Framework; using TheDotNetFactory.FrameWork.Common; using TheDotNetFactory.FrameWork.Common.Shared; using TheDotNetFactory.Framework.Core; using C = TheDotNetFactory.Framework.People.Components; using E = TheDotNetFactory.Framework.People.Entities;
Create an account and a Person linked to the account
//Create a new account, add it to an account store, and set some properties for it C.AccountStore accStore = C.AccountStore.GetByAccountStoreID(259); C.Account acc = new C.Account(); acc.AccountStoreID = 259; acc.Name = "Jacques Clouseay"; acc.LogonName = "jClouseay"; acc.CreatedDate = DateTime.UtcNow; acc.DistinguishedName = "CN=Jacques Clouseay,OU=Sydney,OU=Offices,DC=tdnfdemo,DC=com"; //Create the account and set the password for it acc.Create(acc, "pass@word1"); //Create an EmpowerID Person for the account C.Person per = new C.Person(); per.FirstName = acc.FirstName; per.LastName = acc.LastName; per.Name = acc.Name; per.Login = acc.LogonName; acc.PersonID = per.PersonID; //Write the results to the console Console.WriteLine("New Person: {0} created from Account: {1}", per.Name, acc.Name);
Move an account
//Get the account you wish to move by AccountID var acc = C.Account.GetByAccountID(3120); //Move the account, passing in the new OU path acc.Move("OU=New Mexico,OU=Offices,DC=tdnfdemo,DC=com"); //Write the results to the console Console.WriteLine(acc.ResourceIDSource.ParentOU); //Verify the move occurred in the Account Store Console.WriteLine(acc.AccountStoreIdentityEntry.Path);
Add an account to a group
//Create a new Group TList and add a group to the list var groupList = new TList<C.Group>(); groupList.Add(C.Group.GetByGroupID(66)); //Add the account to the groups in the list var account = C.Account.GetByAccountID(26471).AddToGroups(groupList); //Write the results to the console var acc = C.AccountView.GetByGroupID(66, columnsToSearch: "", textToSearch: ""); foreach (var a in acc) if (a.AccountID == 26471) Console.WriteLine(a.Name);
Restore deleted accounts
//Retrieve deleted accounts var deletedAccounts = C.Account.GetByDeleted(true); //Restore each account in the list of deleted accounts foreach(var acc in deletedAccounts) acc.RestoreDeletedAccount();
Join an account to a Person
//Call JoinAccountToPerson(), passing in the AccountID and PersonID //Person cannot currently have an account var person = C.Person.JoinAccountToPerson(7824, 3194);
Remove an account from a Person
//Call UnJoinAccountToPerson(), passing in the AccountID var person = C.Person.UnJoinAccountToPerson(7824);
Unlock all locked accounts
//Return a list of locked out accounts var account = C.Account.GetByLockedOut(true); //Unlock each account in the list foreach(var acc in account) acc.Unlock();
Create mailbox for user
//Add reference for TheDotNetFactory.Framework.People.Common.Enum to your project for access to the ExchangeMailboxTypeList enum //Return an account without a mailbox var accountCollection = C.AccountView.GetNonMailboxAccountsByAccountStoreID("LogonName", "jclouseay"); //Get the account store var accStore = C.AccountStore.GetByFQN("exchange.com"); //Configure the mailbox you are creating foreach (var acc in accountCollection) { var mailboxConfig = new C.MailBoxConfig(); mailboxConfig.AccountStore = accStore; mailboxConfig.Alias = acc.LogonName; mailboxConfig.cn = acc.Name; mailboxConfig.MasterAccountID = acc.DistinguishedName; //Set the MailboxContainer var mailboxContainer = C.ExchangeMailboxObjectContainer.GetByMostAvailableSpace(); foreach (var mBC in mailboxContainer) mailboxConfig.MailboxContainer = mBC; mailboxConfig.AccountStore = accStore; mailboxConfig.Path = acc.DistinguishedName; //Person linked with the account var owner = C.Person.GetByLogin(acc.LogonName); //Set the account var targetAccount = C.Account.GetByAccountID(acc.AccountID); //Create the mailbox, passing in owner, targetAccount, and mailboxConfig //Also set the type of mailbox and process it immediately var createMailbox = C.ExchangeMailbox.CreateMailbox(owner, targetAccount, mailboxConfig, ExchangeMailboxTypeList.UserMailbox, refreshRbac: true, sendToQueue: false); //Write the results to the console Console.WriteLine("Mailbox with MailboxID: {0} has been created for Account: {1}", createMailbox.ExchangeMailboxID, CreateteMailbox.AccountIDSource.FriendlyName); }