Last week I posted a SailPoint IdentityNow Roles Management Agent for Microsoft Identity Manager. Today I’m posting a sister for it, an IdentityNow Governance Groups Management Agent.
This Management Agent is essentially the enumeration of Governance Groups in IdentityNow via API wrapped up in a PowerShell Management Agent. You can extend the management agent for managing Governance Groups to fit your needs.
Authentication to IdentityNow for Governance Groups can leverage the v2 Authentication method. I cover enabling that in this post here. You can also use the v3 Authentication method I detail here. If you do that you will need to appropriately secure the extra credentials as I show in the Roles Management Agent.
The Management Agent leverages the Granfeldt PowerShell Management Agent. Start here to get up to speed with that. As detailed above this is an Import only MA so I’m not providing an Export Script and the Password is redundant. The script files need to be present but will be empty
Schema Script
The Schema Script below covers the core attributes associated with IdentityNow Governance Groups.
Import Script
The Import Script unlike the Roles Management Agent can use v2 Authentication. As such we don’t need to perform additional effort to provide the necessary credentials.
Your v2 IdentityNow credentials need to be provided on the Management Agent Connectivity Configuration page. The Username and Password Authentication options take the v2 API Client ID and API Client Secret respectively.
NOTE: The Import Script is also configured to page the import of Governance Groups. The Page Size is configured in your Run Profile.
Make the following update for your implementation;
Line 24 for your IdentityNow Orgname
Customisation
Depending on what you want to do with it, will depend on how you want Identity Manger to consume the data. You will likely want to;
Create a new ObjectType in the Metaverse along with the attributes associated with IdentityNow Governance Groups
Flow the information in and perform any logic
Create an Export Script that will;
create Governance Groups in IdentityNow
update Governance Groups in IdentityNow
Summary
Using this base management we can get connectivity and visibility of IdentityNow Governance Groups in Microsoft Identity Manager.
This is the first post in a series where I will provide a number of base-level Management Agents for Microsoft Identity Manager to integrate with SailPoint IdentityNow. Whilst the two products have areas of competing/equivalent functionality there are other aspects where integration of the two compliment each other. Whilst that is not the purpose of this post, through the series of upcoming posts it will be relatively easy to extrapolate how the two products can happy co-exist and orchestrate each other for certain functions.
This Management Agent is for Microsoft Identity Manager to have visibility of IdentityNow Roles (see customisation at the end for me functionality).
For more information on IdentityNow Roles see this post where I detailed Creating Roles as well as updating/managing them via API. The MA also consumes whether the Role is requestable that I covered in this post.
Notes
The Management Agent is a Full Sync only Management Agent. This is because the IdentityNow API doesn’t expose differential style requests. That is also why this is a single function Management Agent (just for Roles).
The Management Agent is configured for Paging the results back into Identity Manger. For more details on that see this post.
The Management Agent uses IdentityNow v3 Authentication. You will need to request the API Keys from your SailPoint Customer Success Manager. Details on v3 Authentication can be found in this post
The Management Agent leverages the Granfeldt PowerShell Management Agent. Start here to get up to speed with that. As detailed above this is an Import only MA so I’m not providing an Export Script and the Password is redundant. The script files need to be present but will be empty
Schema Script
The Schema Script below covers the core attributes associated with IdentityNow Roles.
Import Script
As IdentityNow v3 API Authentication requires a number of artifacts, we need to make sure we secure them all appropriately.
For the Admin Username and Password we will do that by exporting them to an XML file using Export-CLIXML and then in the Import Script, import them using Import-CLIXML. Those cmdlets respect the context by which the credentials were exported and will only be able to access them when imported under that same context. As our Management Agent will be run by the MIM Sync Server Service Account we need to create the credentials file using that login. To do that;
temporarily reconfigure the MIM Sync Service Account so that it can logon locally
On the MIM Sync Server open Local Security Policy = > Local Policies => User Rights Assignment => Deny log on locally and remove the MIM Sync Server Service Account
repeat for Deny access to this computer from the network
Logon to the MIM Sync Server using the MIM Sync Server Service Account
Run the following to create the credential file and put the credential file in the Extensions\yourRolesMA directory
IMPORTANT: Add the MIM Sync Server Service Account back into the Deny access to this computer from the network and Deny Logon Locally policies
The IdentityNow v3 API Credentials are stored on the Management Agent Connectivity Configuration page. The Username and Password Authentication options take the v3 API Client ID and API Client Secret respectively.
Make the following updates for your implementation:
Line 24 for your IdentityNow Organisation name
Line 27 for the location and name of the credentials file created above
Customisation
Depending on what you want to do with it, will depend on how you want Identity Manger to consume the data. You will likely want to;
Create a new ObjectType in the Metaverse along with the attributes associated with the Roles
Flow the information in and perform any logic
Create Roles in IdentityNow
Update Roles in IdentityNow
Summary
Using this base management we can get connectivity and visibility of IdentityNow Roles in Microsoft Identity Manager.
Recently I posted a sample Microsoft Identity Manager Management Agent for Workday HR. Subsequently I also posted about some updates I made to the WorkdayAPI PowerShell Module to enable functionality to specify the time period to return changes for. This post details updating my sample Workday Management Agent to support Delta Synchronisation.
WorkdayAPI PowerShell Module
First up you will need the updated WorkdayAPI PowerShell Module that provides the Get-WorkdayWorkerAdv cmdlet and can take a time period to return information for. Get the updated WorkdayAPI PowerShell Module from here
Update the PowerShell Module on the MIM Sync Server. The module by default will be in the C:\Program Files\WindowsPowerShell\Modules\WorkdayApi folder.
In the updated Management Agent I’m also bringing into MIM additional attributes from the other enhancements I made to the PowerShell Module for HireDate, StartDate, EndDate, Supplier and WorkdayActive. The updates to the Schema.ps1 are shown below.
With the Schema Script updated, refresh the Management Agent Schema.
You can then select the new attributes in the Workday MA under Select Attributes.
Then select Ok.
Updated Import Script
The Import Script has a number of changes to handle creating and updating a WaterMark File that is used to store the date stamp of the last run. Also updated in the Import Script is the change to use the Get-WorkdayWorkerAdv cmdlet over the Get-WorkdayWorker cmdlet so that a time period can be specified, and to retrieve the additional attributes we just added to the schema.
Update:
Line 11 for the path and name of the Watermark File you wish to use
Line 31 for the URI of your Workday Tenant
Executing the Management Agent using a Delta Import Delta Sync Run Profile
After creating a Delta Import Delta Sync Run Profile we can now run a Delta Sync. The following graphic is after seeding the WaterMark file (with the last run time in a format like this 2018-10-29T22:09:08.3628953+00:00), as by default without the WaterMark file being present a Full Import is performed by the MA as it doesn’t have a watermark to base the import time period on.
The changed records in Workday HR are then identified and those records obtained, imported and synchronised via the Management Agent.
Summary
Using Delta Synchronisation functionality from Workday HR allows for much quicker synchronsiation from Workday HR to Microsoft Identity Manager.
Before I even get started with this post, let me state that the integration I describe here is not a standalone solution. Integrating with Workday for any organisation of significant size will require multiple integration points each providing coverage for the scenarios for your implementation. I list a few in this post, but Alexander Filipin has already done an awesome job here.
You may state, that there is of course the Azure Active Directory Provisioning Service for Workday. But what if you need more granular customisation than that provides, or you have requirements to get that data to a number of other systems and you desire to have connectivity to the authoritative source? Those are requirements I had and why I built a Management Agent for Workday to consume Workday HR data directly.
As the title implies it uses the ever versatile Granfeldt PowerShell Management Agent. The other key component is a PowerShell Module that eases the integration with Workdays’ SOAP API. Specifically the Workday API PowerShell Module available here.
Enabling the Workday (Get_Workers) API
In order to access the Workday API you need to have an API account created. I pointed the Workday Support guys to this Microsoft Azure Inbound Workday Provisioning Documentation. Specifically the ‘Configure a system integration user in Workday‘ section in that link.
Once enabled they were able to give me a Service and Tenant name along with a Username and Password.
when using this information your Username is the username and the tenant. So if the username is ‘API User’ and the Tenant is ‘Identity_Corp’ then loginID for our purpose is API User@Identity_Corp
the URL you are provided will combine the Service and Tenant names. It will look something like this for the Human Resources Endpoint https://wd3-impl-services1.workday.com/ccx/service/TENANTNAME/Human_Resources/v30.2
After installing the Workday API PowerShell Module it should be located in ‘C:\Program Files\WindowsPowerShell\Modules\WorkdayApi’. You will need to unblock the module and scripts. Run the following two commands in an elevated PowerShell session.
As the PowerShell Module is unsigned you might need to do something similar to the following. The Get-ExecutionPolicy -List command will show you what the Execution Policy settings currently are.
Set-ExecutionPolicy "Unrestricted" -Scope Process -Confirm:$false
Set-ExecutionPolicy "Unrestricted" -Scope LocalMachine -Confirm:$false
Import Analytics
50k records with just the base profile (no -include work or -include personal options) takes ~7 minutes to ‘stage’ into the connector space. 50k records WITH work and personal metadata takes ~32 hours at a pretty consistent rate of ~20 mins/500 user records.
If you are retrieving just the Base record then the networking receive bandwidth consumption is ~240kbps. When retrieving the full records as a batch process the networking receive bandwidth consumption it ~3Mbps as shown below.
Why is this important?
The first “FULL” Sync depending on how many records you have in Workday will alter the approach you will need to take in order to obtain them all. I found that trying to retrieve full records in one call for anything over ~5000 records got inconsistent. I wouldn’t get the full dataset and the machine running it would start to run out of resources (processing power and memory). If you have only a few thousand records, requesting full records in one call will probably suffice.
Now I have ~100k records to return. What I found worked best is to get just the base record for all users then the full record for each user using pagination (via PSMA Paged Imports; I have my set to 500). The the PSMA Paged Imports feature will process the objects through the MA 500 at a time. That way you’re not stressing the host running the Sync Engine to the maximum and you don’t have to wait an hour+ to see any processing of objects on the MA.
Once you have completed a Full Sync and you are of any significant scale you will want to perform Delta Sync’s for the objects that have changed since your last sync. I’m not going to cover that in this post, but in a separate one in the future.
Here is a screenshot of showing the time taken for a Stage (Import) of 50k objects. Just under 33 hours.
Other Options for Scale
If you are a large organisation this solution isn’t necessary a valid one (in isolation) as I indicated in the opening paragraph. Consider it ancillary augmentation to a multi-pronged implementation (as described nicely by Alexander Filipin here). Potentially something like;
A Management Agent such as the one I describe in this post for certain aspects
and a modification or two to identify new accounts from a Base Workday discovery and only import the full object for them on workdays and a full sync on the weekends or
delta syncs using the Workday Transaction Log Criteria Data and Transaction_Date_Range_Data
I’ll cover this in a future post but essentially on every sync I store a cookie-file with the watermark of the time of the sync. On the next deltasync I retrieve the cookie-file with the timestamp and make a call to get all objects changed since the previous sync up to the current time
PSMA Workday Management Agent Script Files
Wow, what a lot of caveats and clarifications. But with all that said, below are base Schema and Import Scripts examples for the Grandfeldt PowerShell Management Agent that leverages the Workday API PowerShell module.
Schema.ps1
The schema is the base schema for my tenant. You shouldn’t have to change anything here unless you are retreiving additional attributes you want in MIM.
Import.ps1
The import script leverages AuthN creds from the MA config. Make sure the Username is in the format of UserID@TenantName. Also update;
Line 10 for the location you put your extension as well as the 8.3 format path to the MA Debug folder
Line 30 for the correct Service and Tenant info
Make sure you have Paged Imports selected on the Global Parameters screen of the MA Configuration
Export.ps1
I haven’t provided an example. The Workday API PowerShell Module has examples for updating Email, Phone and Photos. You can implement what you require.
Summary
The sample Workday MA Config in this post will give you a base integration with Workday. It is unlikely that it will give you everything you need and there isn’t a single solution that probably will, unless your organisation is quite small. There are other options as mentioned in this post and also the Workday Reports REST API. But those are topics for future posts.
Generating Schema.ps1 for the Granfeldt FIM/MIM PowerShell Management Agent
Getting started writing your first Forefront/Microsoft Identity Manager Granfeldt PowerShell Management Agent can be a bit daunting. Before you can do pretty much anything you need to define the schema for the PSMA. Likewise if you have written many, the generation of the schema file often seems to take longer than it should and can be a little tedious when all you want to do is write the logic for the Import and Export scripts.
After a few chats with Soren around enhancements for the PSMA I suggested it would be awesome if the generation of the schema.ps1 file could be (semi)automated. So here is my first stab at doing just that.
My approach is;
Using PowerShell get an object that represents an object that will be managed on the PSMA
Enumerate the Properties of the PSObject and generate the Schema script accordingly
All that is left to do afterwards is;
define your anchor
define the name of the ObjectType
combine multiples if your MA will have multiple ObjectClasses
Update $obj to $obj2 etc for any additional object classes residing in the same schema file
Below I provide four examples covering the script that generates the schema definition along with the output. The four examples cover;
Azure AD User
Azure AD Group
Workday User
Flat File CSV
Example 1: Azure Active Directory User
The example below utilises the AzureAD PowerShell Module to connect to Azure AD. It then gets a User Object (update line 7 for a user to retrieve) and enumerates the properties of the User to generate the Schema file.
Update the Anchor for the attribute you’d like to use. I recommend ObjectId and give the ObjectClass a name for how you’d like it represented on your MA (User, AADUser or similar) and save it as something like schema.ps1 in you MA folder and you can get started.
Example 2: Azure Active Directory Group
The example below utilises the AzureAD PowerShell Module to connect to Azure AD. It then gets a Group Object (update line 7 for a group to retrieve) and enumerates the properties of the Group to generate the Schema file
Update the Anchor for the attribute you’d like to use. I recommend ObjectId and give the ObjectClass a name for how you’d like it represented on your MA (Group, AADGroup or similar) and save it as something like schema.ps1 in you MA folder and you can get started.
Example 3: Workday User
The example below utilises the Workday PowerShell Module to connect to Workday. It then gets a User Object (update line 7 for a user to retrieve) and enumerates the properties of the User to generate the Schema file.
Update
Line 6 for your ServiceName and Tenant.
Line 13 for an object to retrieve
This script differs from AAD User and Group above in that the PowerShell Object returned uses NoteProperty as the type. So I updated Line 14 for that. Also the attribute when parsed by Get-Member includes a value so I had to get a substring of the result for the attribute name. That is what this change does:
Using a simple script and an example object we can quickly create the basis for a Granfeldt PSMA Schema Definition script.
As shown with the Workday example a minor tweak was required, but it was still a lot quicker than generating manually.
Hopefully this helps you get started quickly with your first, or next PSMA that you are building.
Update: Oct 30 '18
Also see this post that adds support for Microsoft's updates
to the Microsoft Graph to include additional information
about Azure AD B2B Guest users.
Introduction
Earlier this year Microsoft released the Microsoft Identity Manager Azure AD B2B Management Agent. I wrote about using it to write to Azure AD in this post here. As detailed in that post my goal was to write to Azure AD using the MA. I provided an incomplete example of doing that for Guests. This post fills in the gap and unlike the note preceding the post indicates, I’ve updated my MA to use the Graph API over the Azure AD PowerShell Module. It does though work in unison with the Microsoft Azure AD B2B Management Agent.
Overview
The process is;
Using the Microsoft Azure B2B Management Agent connect to an Azure AD Tenant that contains users that you want to invite as Guests to your Tenant. Flow in the naming information for users and their email address and any other metadata that you need to drive the logic for who you wish to invite
Use my Azure AD B2B Invitation Management Agent to automate the invitation of users to your Azure AD Tenant using Azure AD B2B
My Azure AD B2B Invitation Management Agent works in two phases;
Invitation of Users as Guests
Update of Guests with naming information (Firstname, Lastname, DisplayName)
The Azure AD B2B Invite Management Agent uses my favorite PowerShell Management Agent (the Granfeldt PSMA). I’ve posted many times on how to configure it. See these posts here if you are new to it.
Prerequisites
Setting up an Azure AD User Account for the Management Agent
In your Azure AD create a New User that will be used by the Management Agent to invite users to your Azure AD. I named mine B2B Inviter as shown below.
You then want to assign them the Guest inviter role as shown below. This will be enough permissions to invite users to the Azure AD.
However depending on how you want these invitee’s to look, you probably also want their names to be kept consistent with their home Azure AD. To also enable the Management Agent to do that you need to also assign the User administrator role as shown below.
Now log in using that account to Azure AD and change the password. The account is now ready to go.
Management Agent Scripts
The Management Agent uses the Granfeldt PowerShell Management Agent. This is a cut down version of my MIM Azure AD Management Agent.
Schema Script
I’ve kept the schema small with just enough interesting info to facilitate the functionality required. Expand it if you need additional attributes and update the import.ps1 accordingly.
Import.ps1
The Import script imports users from the Azure AD Tenant that you will be inviting remote Azure AD users too (as Guests).
Change line 10 for your file path
Change line 24 for the version of an AzureAD or AzureADPreview PowerShell Module that you have installed on the MIM Sync Server so that the AuthN Helper Lib can be used. Note if using a recent version you will also need to change the AuthN calls as well as the modules change. See this post here for details.
Change line 27 for your tenant name
Change line 47/48 for a sync watermark file
The Import script also contains an attribute from the MA Schema named AADGuestUser that is a boolean attribute. I create the corresponding attribute in the MetaVerse and MIM Service Schemas for the Person/User objectClasses. This is used to determine when a Guest has been successfully created so their naming attributes can then be updated (using a second synchronisation rule).
Export.ps1
The Export script handles the creation (invitation) of users from another azure AD Tenant as Guests as well synchronizing their naming data. It doesn’t include deletion logic, but that is simple enough include a deletion API call based on your MA Deprovisioning logic and requirements.
By default I’m not sending invitation notifications. If you want to send invitation notifications change “sendInvitationMessage“= $false to $true on Line 129. You should then also change the Invitation Reply URL on line 55 to your Tenant/Application.
Change Line 10 for the path for the debug logging
Change Line 24 as per the Import Script if you are using a different version of the help lib
Change Line 27 for your Azure AD Tenant Name
Declarative Sync Rules
I’m not going to cover import flow configurations on the MS Azure AD B2B MA here. See here for that. Below details how I’ve configured my Invitation MA for the Creation/Export functions. My join rule (configured in the Sync Engine Invitation MA Config) is email address as shown below. Not the best anchor as it isn’t immutable. But as we don’t know what the DN is going to be until after it is created this is the next best thing.
Creation Sync Rule
Here are the three attributes I’m syncing to the B2B Invite Management Agent to perform the invitation. I’m using the mail attribute for the DN as it matches the anchor for the schema. We don’t know what objectID will be assigned until the directory service does it. By using email/upn once created we will get the join and won’t end up with two objects on the MA for the same user.
For Inbound I’m flowing in the AADGuestUser boolean value. You will need to create this attribute in the MetaVerse and then the MIM Service. In the MIM Service allow the Sync Service Account to manage the attribute and change the MIM Service Filter Permissions to allow Admins to use the attribute in Sets. Also on the MIM Service MA add an Export flow from the MV to the MIM Service for AADGuestUser.
Naming Update Sync Rule
The second Sync Rule is to update the guests GivenName, Surname and DisplayName. This sync rule has a dependency on the creation sync rule and has a corresponding Set, Workflow and MPR associated with value of the AADGuestUser boolean attribute populated by the Import script. If True (which it will be after successful creation and the confirming import) the second synchronization rule will be applied.
I will trigger an export flow for the three naming attributes.
Example of Inviting Guests
In this example Rick Sanchez is a member of a guest organisation and meets the criteria of my rules to be invited as a guest to our Tenant. We then, that we get an Add for Rick on the B2B Invite MA.
On export Rick is created in our Azure AD as a Guest User
Rick appears in Azure AD as a Guest via the Azure Portal.
Following the confirming import our second sync rule fires and flows through an update to DisplayName and adds GivenName and Surname.
This naming attributes are then successfully exported.
Going to the Azure AD Portal we see that Rick has indeed been updated.
Notification Emails
If you enable notification emails a generic notification email is sent like shown below. The import.ps1 MA script has them disabled by default.
Summary
Using a combination of the Microsoft Azure AD B2B Management Agent and my Azure AD B2B Invitation Management Agent you can automate the invitation of Guest users to your Azure AD Tenant.
UPDATE: August 2018
As promised below I've finally written up my
Azure AD B2B Invitation Management Agent.
You can find it in this post here.
UPDATE: June 2018
When I originally wrote this post the intent was to test
the ability of the Graph MA to export to Azure AD.
That works.
That then extended to messing with an identity type other
than member (which works to an extent) but I detailed
guests. However that is incomplete. I do have a working
solution that utilises the Graph Invitation API via my
favourite PowerShell MA (Granfeldt PS MA) and the
PowerShell cmdlet New-AzureADMSInvitation from the
Azure AD PowerShell Module.
That solution involves the MS Graph MA connected to a
Partner tenant to get visibility of partner users and
then creating relevant users in the home tenant via a
PowerShell MA and the New-AzureADMSInvitation cmdlet.
Another MS Graph MA connected to the home tenant provides
easy visibility of additional guest user attributes for
ongoing functions such as reporting and de-provisioning.
I will write that up later in July. Stay tuned and keep
the above in mind when reading this post.
Microsoft have documented a number of scenarios for implementing the management agent. The scenarios the MA has been built for are valid and I have customers that will benefit from the new MA immediately. There is however another scenario I’m seeing from a number of customers that is possible but not detailed in the release notes. That is B2B Sync between Azure Tenants; using Microsoft Identity Manager to automate the creation of Guests in an Azure Tenant.
This could be one-way or multi-way depending on what you are looking to achieve. Essentially this is the Azure equivalent of using FIM/MIM for Global Address List Sync.
Overview
The changes are minimal to the documentation provided with the Management Agent. Essentially;
ensure you enable Write Permissions to the Application you create in the AAD Tenant you will be writing too
Enable the Invite Guest users to the organization permission on the AAD Application
Create an Outbound Sync Rule to an AAD Tenant with the necessary mandatory attributes
Configure the Management Agent for Export Sync Profiles
In the scenario I’m detailing here I’m showing taking a number of users from Org2 and provisioning them as Guests in Org1.
What I’m detailing here supplements the Microsoft documentation. For configuring the base MA definitely checkout their documentation here.
Microsoft Graph Permissions
When setting up the Graph Permissions you will need to have Write permissions to the Target Azure AD for at least Users. If you plan to also synchronize Groups or Contacts you’ll need to have Write permissions for those too.
In addition as we will be automating the invitation of users from one Tenant to another we will need to have the permission ‘Invite guest users to the organization’.
With those permissions selected and while authenticated as an Administrator select the Grant Permissions button to assign those permissions to the Application.
Repeat this in both Azure AD Tenants if you are going to do bi-directional sync. If not you only need write and invite permissions on the Tenant you will be creating Guest accounts in.
Creating the Import/Inbound Sync Rules Azure Tenants
Here is an example of my Import Sync Rules to get Members (Users) in from an Azure Tenant. I have an inbound sync rule for both Azure Tenants.
Make sure you have ‘Create Resource in FIM‘ configured on the source (or both if doing bi-directional) Graph Connector.
The attribute flow rules I’ve used are below. They are a combination of the necessary attributes to create the corresponding Guest account on the associated management agent and enough to be used as logic for scoping who gets created as a Guest in the other Tenant. I’ve also used existing attributes negating the need to create any new ones.
Creating the Export/Outbound Sync Rule to a Partner B2B Tenant
For your Export/Outbound rule make sure you have ‘Create resource in external system’ configured.
There are a number of mandatory attributes that need to be flowed out in order to create Guests in Azure AD. The key attributes are;
userType = Guest
accountEnabled = True
displayName is required
password is required (and not export_password as normally required on AD style MA’s in FIM/MIM)
mailNickname is required
for dn and id initially I’m using the id (flowed in import to employeeID) from the source tenant. This needs to be provided to the MA to get the object created. Azure will generate new values on export so we’ll see a rename come back in on the confirming import
userPrincipalName is in the format of
SOURCEUPN (with @ replaced with _ ) #EXT# DestinationUPNSuffix
e.g user1_org2.com#EXT#org1.com
Here is an example of building a UPN.
Sets, Workflows and MPR’s
I didn’t need to do anything special here. I just created a Set based on attributes coming in from the source Azure Tenant to scope who gets created in the target Tenant. An MPR that looks for transition into the Set and applies the Workflow that associates the Sync Rule.
End to End
After synchronizing in from the source (B2B Org 2) the provisioning rules trigger and created the Users as Guests on B2B Org 1.
Looking at the Pending Export we can see our rules have applied.
On Export the Guest accounts are successfully created.
On the confirming import we get the rename as Azure has generated a new CN and therefore DN for the Guest user.
Looking into Azure AD we can see one of our new Guest users.
Summary
Using the Microsoft Azure B2B Graph Management Agent we can leverage it to create users from one Tenant as Azure AD Members in another Tenant. Stay tuned for another post detailed the solution detailed in the Update in the Introduction.
Working for Kloud all our projects involve Cloud services, and all our customers have varying and unique requirements. Recently one of our customers embarked on their migration from On-Premise Exchange to Exchange Online. Nothing really groundbreaking there though, however they had a number of unique requirements including management of Litigation Hold. And that needed to be integrated with their existing Microsoft Identity Manager implementation (that currently provisions new users to their Exchange 2013 environment). They also required that management of the Exchange environment still be possible via the Exchange Management Console against a local Exchange server. This post details how I integrated the environments using MIM.
Overview
In order to integrate the Provisioning and Lifecycle management of Exchange Online Mailboxes in a Hybrid Exchange with Microsoft Identity Manager I created a custom PowerShell Management Agent simply because it was going to provide the flexibility I needed.
Provisioning is based on the following process;
MIM Creates new user in Active Directory (no changes to existing MIM provisioning process)
Azure Active Directory Connect synchronises the user to Azure Active Directory
The Exchange Online MIM Management Agent sees the corresponding AAD account for the new user
MIM Declarative Rules trigger the creation of a new Remote Mailbox for the AD/AAD user against the local Exchange 2013 On Premise Server. This allows the EMC to be used to manage mailboxes On Premise even though the mailbox resides in Office365/Exchange Online
AADC/Exchange synchronises the information as part of the Hybrid Exchange topology
MIM sees the EXO Mailbox configuration for the new user and enables Litigation Hold against the EXO Mailbox (if required)
The following diagram graphically depicts this process.
Exchange Online PowerShell MA
As always I’m using my favourite PowerShell Management Agent, the Grandfeldt PS MA now available on Github here.
Schema Script
The Schema script configures the schema required for current and future EXO management requirements. The Schema is based on a single Object Class “MailUser” but pulls the information from a combination of Azure AD User and Exchange Online Mailbox object classes for an associated account. Azure AD User objects are prefixed by ‘AAD’. Non AAD prefixed attributes are EXO Mailbox attributes.
Import Script
The Import script connects to both Azure AD and Exchange Online to retrieve Azure AD User accounts and if present the associated mailbox for a user.
It retrieves all Member AAD User Accounts and puts them into a Hash Table. Connectivity to AAD is via the AzureADPreview PowerShell module. It retrieves all Mailboxes and puts them into a Hash Table. It then processes all the mailboxes first including the associated AAD User account (utilising a join via userPrincipalName).
Following processing all mailboxes the remainder of the AAD Accounts (without mailboxes) are processed.
Export Script
The Export script performs the necessary integration against OnPremise Exchange Server 2013 for Provisioning and Exchange Online for the rest of management. Both utilise Remote Powershell. It also leverages the Lithnet MIIS Automation PowerShell Module to query the Metaverse to validate current object statuses.
Wiring it all up
The scripts above will allow you to integrate a FIM/MIM implementation with AAD/EXO for management of users EXO Mailboxes. You’ll need connectivity from the MIM Sync Server to AAD/O365 in order to manage them. Everything else I wired up using a few Sets, Workflows, Sync Rules and MPR’s.
Earlier this week I posted this blog post that showed a working example of using a custom Pwned Password FIM/MIM Management Agent to flag a boolean attribute in the MIM Service to indicate whether a users password is in the pwned password dataset or not. If you haven’t read that post this won’t make a lot of sense, so read that then come back.
The solution when receiving a new password for a user (via Microsoft Password Change Notification Service) was checking against the Have I Been Pwned API. The disclaimer at the start of the blog post detailed why this is a bad idea for production credentials. The intent was to show a working example of what could be achieved.
This update post shows a working solution that you can implement internal to a network. Essentially taking the Pwned Password Datasets available here and loading them into a local network SQL Server and then querying that from the FIM/MIM Pwned Password Management Agent rather than calling the external public API.
Creating an SQL Server Database for the Pwned Passwords
On my SQL Server using SQL Server Management Studio I right-clicked on Databases and chose New Database. I gave it the name PwnedPasswords and told it where I wanted my DB and Logs to go to.
Then in a Query window in SQL Server Management Studio I used the following script to created a table (dbo.pwnedPasswords).
use PwnedPasswords;
CREATE TABLE dbo.pwnedPasswords
( password_id int NOT IDENTITY(1,1) NULL,
passwords varchar(max) NOT NULL,
CONSTRAINT passwords_pk PRIMARY KEY (password_id)
);
Again using a query window in SQL Server Management Studio I used the following script to create an index for the passwords.
USE [PwnedPasswords]USE [PwnedPasswords]
GO
SET ANSI_PADDING ON
GO
CREATE UNIQUE NONCLUSTERED INDEX [PasswordIndex] ON [dbo].[pwnedPasswords]( [password_id] ASC)INCLUDE ( [passwords]) WITH (PAD_INDEX = OFF, STATISTICS_NORECOMPUTE = OFF, SORT_IN_TEMPDB = OFF, IGNORE_DUP_KEY = OFF, DROP_EXISTING = OFF, ONLINE = OFF, ALLOW_ROW_LOCKS = ON, ALLOW_PAGE_LOCKS = ON)
GO
The last thing I did on the DB was to take the MIM Sync Server Active Directory Service Account (that was already in the SQL Server Logins) and give that account Reader Access to my new PwnedPasswords Database. I gave this account access as I’m using Integrated Authentication for login to SQL and as the MA is initiated by the MIM Sync Service Account, that is the account that needs the access.
Getting the Pwned Password Datasets into the new Database
I’m far from a DBA. I’m an identity guy. So using tools I was most familiar with (PowerShell) I created a simple script to open the password dump files as a stream (as Get-Content wasn’t going to handle the file sizes), read in the lines, convert the format and insert the rows into SQL. I performed the inserts in batches of 1000 and I performed it locally on the SQL Server.
In order to get the content from the dump file, add another column and get it in a format quickly to insert into the SQL DB I used the Out-DataTable function available from here.
The script could probably be improved as I only spend about 20-30 minutes on it. It is opening and closing a connection to the SQL DB each time it inserts 1000 rows. That could be moved outside the Insert2DB Function and maybe the batch size increased. Either way it is a starting point and I used it to write millions of rows into the DB successfully.
This then is the only other change to the solution. The Password.ps1 script rather than querying the PwnedPasswords API queries the SQL DB and sets the pwned boolean flag accordingly.
Summary
This enhancement shows a working concept that will be more appealing to Security Officers within corporate organisations if you have an appetite to know what your potential exposure is based on your Active Directory Users Passwords.
In the last 12 months I’ve lost count of the number of PowerShell Management Agents I’ve written to integrate Microsoft Identity Manager with a plethora of environments. The majority though have not been of huge scale (<50k objects) and the import of the managed entities into the Connector Space/Metaverse runs through pretty timely.
However this week I’ve been working on a AzureAD Groups PS MA for an environment with 40k+ groups. That in itself isn’t that large, but when you start processing Group Memberships as well, the Import process can take an hour for a Full Sync. During this time before the results are passed to the Sync Engine you don’t have any visual of where the Import is up to (other than debug logging). And the ability to stop the MA requires a restart of the Sync Engine Server.
I’ve wanted to mess with Paging the Imports for sometime, but it hadn’t been a necessity. Now it is, so I looked to working out how to achieve it. The background information on Paged Imports is available at the bottom of the PSMA documentation page here. However there are no working examples. I contacted Soren and he had misplaced his demo scripts for the time being. With some time at hand (in between coats of paint on the long weekend renovation) I therefore worked it out for myself. I detail how to implement Paged Imports in this blogpost.
This post uses an almost identical Management Agent to the one described in this post. Review that post to get an understanding of the AzureAD Differential Queries. I’m not going to cover those elements in this post or setting up the MA at all.
Getting Started
There are two things you need to do in preparation for enabling Paged Imports on your PowerShell Management Agent;
Enable Paged Imports (if your Import.ps1 is checking for this setting)
Configure Page Size on your Import Run Profiles
The first is as simple as clicking the checkbox on the Global Parameters tab on your PS MA as shown below.
Identity Manager Paged Imports
The 2nd is in your Run Profile. By default this will be 100. For my “let’s figure this out” process I dropped my Run Profiles to 50 on one Run Profile and 10 on another.
Paged Imports Page Size
Import Script
With Paged Imports setup on the MA the rest of the logic goes into your Import Script. In your param section at the start of the script $usepagedimport and $pagesize are the variables that reflect the items from the two enablement components you did above.
$usepageimport is either True or False. Your Import.ps1 script can check to see if it is set and process accordingly. In this example I’m not even checking if it is set and doing Paged Imports anyway. For completeness in a production example you should check to see what the intention of the MA is.
$pagesize is the pagesize from the Run Profile (100 by default, or whatever you changed your’s too).
An important consideration to keep in mind is that the Import.ps1 will be called multiple times (ie. #of_times = #ofObjects / pagesize).
So anything that you would normally expect in any other MA to only process once when the Import.ps1 runs you need to limit to only running once.
Essentially the way I’ve approached it is, retrieve all the objects that will be processed and put them in a Global variable. If the variable does not have any values/data then it is the first run, so go and get our source data. If the Global variable has values/data in it then we must be on a subsequent loop so no need to go process that part, just page through our import.
In my example below this appears as;
if (!$global:tenantObjects) {
# Authenticate
# Search and get the users
# Do some rationalisation on the results (if required)
# setup some global variables so we know where we are with processing the data
} # Finish the one time tasks
As you’ll see in the full import.ps1 script below there are more lines that could be added into this section so they don’t get processed each time. In a production implementation I would.
For the rest of the Import.ps1 script we are expecting it to run multiple times. This is where we do our logic and process our objects to send through to the Sync Engine/Connector Space. We need to keep track of where we are up to processing the dataset and continue on from where we left off. We also need to know how many objects we have processed in relation to the ‘pagesize’ we get from the Run Profile so we know when we’ve finished.
When we reach the pagesize but know we have more objects to process we set the $global:MoreToImport to $true and break out of the foreach loop.
When we have processed all our objects we set $global:MoreToImport = $false and break out of the foreach loop to finish.
With that explanation out of the way here is a working example. I’ve left in debugging output to a log file so you can see what is going on.
You can get the associated relevant Schema.ps1 from the Management Agent described in this post. You’ll need to update your Tenant name on line 29, your directory paths on lines 10 and 47. If you are using a different version of the AzureADPreview PowerShell Module you’ll need to change line 26 as well.
Everything else is in the comments within the example script below and should make sense.
Summary
For managing a large number of objects on a PS MA we can now see progress as the import processes the objects, and we can now stop an MA if required.
