Safewhere UserMigrator – Identify – AzureAD

Introduction


The User Migrator Identify – Azure AD application is an application that makes the export and import of users from Identify user store to Azure AD easier. The User Migrator is meant as an administrator tool – and should only be used by system administrators. The User Migrator application can be run as a command line tool and as a Windows GUI tool; the command-line option allows a system administrator to set up a daily batch job – import, export and even delete or disable users belonging to an Azure AD.

System Requirements


  • Windows Based machine with Microsoft.NET 4.6.2
  • The PC / Server needs to have network access to the Identify installation and the internet.

Installation


Run the file: SafewhereUserMigrator_Identify-AzureAD-[buildnumber].exe on the machine on which you wish to install on.

Upgrade system

Notes: If an older version than the one which will be installed, Just click Next on the removal screen to remove the old version before going to Install steps or click Cancel to stop installation. 

 2019-06-11_14-12-14

New Install

Complete the installation by clicking Next at all steps (It is recommended that user should not change the default location). The following figures show all the steps of an installation. 

Click Next on the welcome screen. 

In the License Agreement screen, ensure you read and understand the Safewhere EULA then check “I have, understand, and accept the license agreement displayed above.” and click Next. 

 2019-06-11_14-18-43

In the Destination Location screen, you can specify the folder where the User Migrator – Identify – AzureAD should install. It is recommended that you should keep the default location “C:\Program Files\Safewhere\Safewhere User Migrator – Identify – AzureAD”, just click Next to next step. 

 2019-06-11_14-25-54

In Select Start Menu Group screen, fill in the name for the application then click Next. 

 2019-06-11_14-31-37

In Start Installation screen, simply click Next to start the installation and wait until it is complete. 

 2019-06-11_14-32-36

Click Finish to close the installation. Then go to the directory C:\Program Files\Safewhere\Safewhere User Migrator – Identify – AzureAD to customize the file:Safewhere.UserMigrator.IdentifyAzureAD.Shell.exe.config before launching the Safewhere.UserMigrator.IdentifyAzureAD.Shell.exe configuration UI. 

Folders and files structure

  • Data: it contains the file storing the parameters’ value which user selects on the UI. 
  • Logfiles: all log information. 
  • Sample: it contains the csv sample for the user list as well as the mapping. 
  • LogFiles: all the log information 
  • *.config files: the current configuration files which is use for UserMigrator – Identify – AzureAD. 

Uninstallation 

To uninstall the UserMigrator – Identify -AzureAD, you can either execute the Uninstallation from the shortcut in Start menu or from Control Panel 

 2019-06-11_14-35-37 

License 

Free trial 

UserMigrator – Identify -AzureAD provides a 30 days trial period with full features enabled for a new system. 

Purchase license 

After trial days, you need to purchase a license to continue using the product. Below are the features that can be enabled for the license:

  • Expiration date: the license will enable UserMigrator – Identify – AzureAD to be used in: 
    • A period after trial days: select the expired date from the Date control 
    • Or no limit: check checkbox “Should never expire” 
License location 

The product license can be placed in “C:\Windows\System32” or “C:\Program Files\Safewhere\Safewhere User Migrator – Identify – AzureAD”. 

Configuration


The configuration of the User Migrator is explained in the UserMigrator – Identify – AzureAD – Technical reference 

For the below settings at the appSettings section: 

  • ida:ClientId 
  • ida:ClientSecret 
  • ida:Tenant

You can know more about them at the section: “Register client application to Office 365″ here

For the setting:  

  • ida:Sku 

You can know more about them at the section: “Assign a license for the newly created user” here

Besides, user must customize the following keys when using the User Migrator with the command line: 

  • azure:usageLocation: specify the default location for the new-created Azure users. 
  • azure:grant_license: specify if we grant the Azure users the license after import. 
  • azure:max_concurrent_threads: specify the number of concurrent threads which we will use to import the user
  • azure:gen_immutableid: the immutableid generation for the new Azure users.
  • identify:url: specify the Identify URI. In my sample, it’s “https://identify51.safewhere.local/”
  • identify:refresh_token: specify the Identify ‘s refresh token (refer: here ) 
  • identify:clientId: specify the Identify ‘s client ID (refer: here ) 
  • identify:clientSecret: specify the Identify ‘s client Secret (refer: here ) 
  • identify:filter_claimType: this setting is for Identify user export that allows user to filter the Identify user. When the claim type is specified, it’s required to input the value for the key identify:filter_claimValue 
  • identify:filter_claimValue: this setting is for Identify user export that allows user to filter the Identify user. When the claim value is specified, it’s required to input the value for the key identify:filter_claimType 

Mapping File and User File


The mapping file and user file is used by the UserMigrator – Identify – AzureAD to define what will be worked upon. 

The Mapping File contains a list of each of the user attributes that will be handled by the UserMigrator – Identify – AzureAD. Since CSV files not always have columns, the Mapping file simply defines a column index and a attributeDefinition name. 

The content of the Mapping File could look like this: 

This simply means that the first column in the userfile is supported by the attributeDefinition name displayName and will be treated by the rules there is setup for this attribute. Validation etc. 

The user file is a comma separated file which content could look something like this: 

Identify admin;admin;admin@safewhere-demo.com;53a6ba67-2687-4135-94aa-1b99e0ab5094 
Second user;abc;abc@safewhere-demo.com;7251fb37-61aa-4cf9-9a2a-42012bff9a86 
Test User;test.user;test.user@safewhere-demo.com;8aaa760f-ac73-4a15-85f1-88657630f95d 
test1;test1;test1@safewhere-demo.com;6b0f28ab-bc39-4bba-882f-05dbe2b2e7e7 
test2;test2;test2@safewhere-demo.com;da37c5d6-fdca-41a3-9715-d0f6a73009ff 

 The first column is column 0 – and it is in the mapping file defined as the displayName – this first column will then be treated in the import or export by the definitions that has been set up in the ImportExportConfiguration section of the Safewhere.UserMigrator.IdentifyAzureAD.Shell.exe.config file (See the technical reference document) 

User Interface


The GUI (Graphical User Interface) helps to configure a one time run of a specific action. E.g. the GUI can be used to analyze and verify that the setup works as it is supposed to work.

The GUI contains 4 tabs where 3 of them configures each of the 3 different actions: Import, Disable/Delete and Export. The last tab is used for the Import Users Analyze service 

 Import Users 

 image16

The UI contains a Required Fields Section and an Optional Fields section. 

Because UPN is a mandatory attribute of Azure AD, you should pay special attention to the “Username and UPN” section. 

  • When the CSV file already has a dedicated UPN attribute, you can select the None option. You can notice that the UPN claim is fixed to “userPrincipalName” to the UPN claim textbox, which mean the input CSV mapping file must contain the userPrincipalName attribute. For example:  

  • Otherwise, you can use the “Generate userPrincipalName (UPN) from username” option to generate UPN from a username attribute. That attribute must have unique values for all users. 

Finally, the “Required Azure settings” section contains a bunch of settings that are mandatory for importing users to Azure AD: 

  • Default usage location: select a location where your user base is. 
  • Grant license for all users: grant license whose value comes from the key:  ida:Sku at the config file to all imported users. 
  • Generate immutable id: all Azure AD users must have an immutable Id. You can either use Identify user’s id for this field via mapping file, or tick on this option to generate random immutable ids. 
    • Please note that when a user is deleted and moved to deleted list, its immutable id is still reserved. In other word, you can’t import a new user who has the same immutable id until the user is completely removed from the deleted list either because it exceeded 30-day period or via PowerShell script.
  • Max concurrent import threads: Since Azure AD graph API allows creating maximum 5 users per web request, sending multiple requests to Azure AD in parallel is a way to speed up the import process. On the other hand, Azure AD puts a limit on the number of requests per second that an application can call. Thus, the UI offers a drop down list with the number of concurrent threads that UserMigrator should use. 

The Import Users tab has an Analyze button that allows to run the import in an Simulation mode, the result of this Analyze action will be shown in the tab ”Import Users Simulation Mode” 

 image23

 The UI is self explanatory and will not be specified here. 

Import Disabled/Deleted Users 

 image26

The UI contains a Required Fields Section and an Optional Fields section. 

The topmost Browse button is used when selecting a user file. The userfile must contain a complete list of the users that are expected to be in the target Azure AD. This means that if the user is in the target Azure AD but not in the CSV file, the user will either be disabled or deleted (depending on which option is selected) 

The Optional Fields section has a purpose to put a filter on the user accounts being disabled or deleted.  

The Analyze button is used when the process of disabling or deleting user accounts us to be run in a simulation mode. The result of the Analyze function will be shown in the list below. 

Export Users 

 image14

 The Export Users tab is the GUI for the export functionality of the User Migrator – Identify – AzureAD. 

 The topmost “Browse” button opens a save new file dialog where it is possible to select the location for a csv file. The csv file will be the output of the export. 

 The other “Browse” button opens a file selection dialog for the Mapping File.  

 Because UPN is a mandatory attribute of Azure AD, you should pay special attention to the “Username and UPN” section. 

  • When the Identify installation already has a dedicated UPN claim for user schema, you can select the None option and simply set the claim type to the UPN claim. Note that the claim type that you use must also appear in the mapping file. For example, the mapping below uses “http://schemas.xmlsoap.org/ws/2005/05/identity/claims/upn” as UPN at index 2: 

  • Otherwise, you can use the “Generate userPrincipalName (UPN) from username” option to generate UPN from a username claim. Any free claim that contains unique value for all users is usable here. When this option is used, the UPN claim is automatically set to “userPrincipalName”. You also need to have an attribute mapping in the mapping file set to “userPrincipalName”. For example, the mapping below uses “http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name” to generate UPN at index 2. At the same type, “http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name” is also exported at index 1. 

Finally, since you are exporting users from Identify, you need to provide necessary information that UserMigrator – Identify – AzureAD needs to query users: 

  • Identify tenant Url: base url of your Identify installation. 
  • Refresh token: you can follow instructions at http://docs.safewhere.com/rest-api-getting-started/ to generate a Refresh token. 
  • ClientId and clientsecrect: you can follow instructions at http://docs.safewhere.com/rest-api-getting-started/ to generate a Refresh token. 
  • Filter claim type and filter claim value: these optional settings provide the ability to only export users who have specific claim value. For instance, you use a “urn:department” claim to store departments of your users and you want to export only users that belong to the “Sales” department.  

The rest of the UI is self-explanatory.  

Command Line Options


we support to do the import/export user via command lines. 

Prepare 

we need to update the app keys which is used for the command lines at the Configuration section. 

Command lines 

the common syntax is:  

 where: 

– type is: I (Import) ; E (Export); D (Delete or Disable) 

 -uf: user file. It is used as exported file when action is -E 

 -us: user CSV separator 

 -mf: mapping file 

 -ms: mapping CSV separator 

Optional Parameters for Import (Only applies when using -I) 

 -fu: Filter by UPN 

 -up: Add UPN prefix 

 -rp: Remove UPN prefix 

 -ru: Replace UPN by 

 -gu: Generate UPN from samAccountName 

 -gc: Generate samAccountName from UPN 

 -du: Disable user after created 

 -pw: Specify password. If null, then auto generated. 

 -pf: Path to file to store password 

Sample with Import when using -gc / -gu parameter: 

Optional parameters for Import Disable Or Delete User (Only applies when using -D) 

 -fu: Filter by UPN 

 -up: Add UPN prefix 

 -rp: Remove UPN prefix 

 -ru: Replace UPN by 

 -type: 2 values: Delete or Disable. Default action is: Disable 

Sample with Import when using -type parameter: 

  • disable user: 

  • delete user: 

 Optional parameters for Export (Only applies when using -E) 

 -fu: Filter by UPN 

 -up: Add UPN prefix 

 -rp: Remove UPN prefix 

 -ru: Replace UPN by 

 -gu: Generate UPN from samAccountName 

 -gc: Generate samAccountName from UPN 

Sample with Import when using -gc / -gu parameter: 

  • -gu parameter

  • -gc paramter

Sample data


The application is shipped with a few useful sample data, you can find it at C:\Program Files\Safewhere\Safewhere User Migrator – Identify – AzureAD\Sample: 

  • Mapping files for Export:
    • IdentifyExportMapping-simple-upn-claim.csv: the simplest export mapping configuration when the Identify installation has a UPN claim. Data which is exported by this mapping configuration contains enough must-have attributes to import to Azure AD. Please note that this example assumes that all your users have Identify name attribute set. Usage:
      image32
    • IdentifyExportMapping-simple-generate.csv: the simplest export mapping configuration when your Identify installation doesn’t have a UPN claim and thus you choose to generate UPN from username. Data which is exported by this mapping configuration contains enough must-have attributes to import to Azure AD. Please note that this example assumes that all your users have Identify name attribute set. Usage:
      image17
    • IdentifyExportMapping.csv: the last one is a sample for a mapping configuration that has more claims. 
  • Mapping files for Import: 
    • AzureAdImportMapping-simple.csv: the simplest import mapping configuration to import data which is generated by one of the two simple export configurations above.when the Identify installation has a UPN claim. Data which is exported by this mapping configuration contains enough must-have attributes to import to Azure AD. Please note that this example assumes that all your users have Identify name attribute set. 

Logging


By default the application logs can be found in “C:\Program Files\Safewhere\Safewhere User Migrator – Identify – AzureAD\Logfiles”. There are 3 files: 

  • Log.log & infolog.log : logs all activities depends on the log level 
  • Error.log: detailed log errors  

You can change the folder and log level by editing the configuration file “C:\Program Files\Safewhere\Safewhere User Migrator – Identify – AzureAD\Logging.config”