Difference between revisions of "Azure User Import"
Jump to navigation
Jump to search
| (14 intermediate revisions by 2 users not shown) | |||
| Line 1: | Line 1: | ||
| + | This document can now be found at its new location in the [https://docs.hornbill.com/data-imports-guide/users/azure/overview Hornbill Document Library]. | ||
| + | |||
| + | [[file:hornbill-document-library.png|Data Imports Guide|link=https://docs.hornbill.com/data-imports-guide/users/azure/overview]] | ||
| + | |||
| + | <!-- | ||
| + | |||
<div style="border:1px solid #90C0FF; background:#D0E0FF; width:99%; padding:4px; margin-bottom:10px;"> | <div style="border:1px solid #90C0FF; background:#D0E0FF; width:99%; padding:4px; margin-bottom:10px;"> | ||
{| style="width:100%" | {| style="width:100%" | ||
| Line 11: | Line 17: | ||
== About the Hornbill Azure User Import Utility == | == About the Hornbill Azure User Import Utility == | ||
The utility provides a simple, safe and secure way to create user accounts on the Hornbill platform by synchronizing with accounts held in your Azure AD. The tool is designed to run behind your corporate firewall, connect to your Azure instance, query the required account information, transform and load into the Hornbill instance. The tool connects to the Hornbill and Azure instances in the cloud over HTTPS/SSL so as long as you have standard internet access then you should be able to use tool without the need to make any firewall configuration changes. The tool supports both the initial bulk import as well as incremental adds and updates. You can schedule the tool to run periodically to perform the import/update tasks as required. | The utility provides a simple, safe and secure way to create user accounts on the Hornbill platform by synchronizing with accounts held in your Azure AD. The tool is designed to run behind your corporate firewall, connect to your Azure instance, query the required account information, transform and load into the Hornbill instance. The tool connects to the Hornbill and Azure instances in the cloud over HTTPS/SSL so as long as you have standard internet access then you should be able to use tool without the need to make any firewall configuration changes. The tool supports both the initial bulk import as well as incremental adds and updates. You can schedule the tool to run periodically to perform the import/update tasks as required. | ||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
=== Open Source === | === Open Source === | ||
| − | The Azure User Import Utility is provided open source | + | The Azure User Import Utility is no longer provided open-source, and is maintained solely by Hornbill as a closed-source, but free-to-use, tool. |
|style="width:5%"| | |style="width:5%"| | ||
| Line 43: | Line 39: | ||
=== Windows Installation === | === Windows Installation === | ||
| − | * Download the architecture specific [https://github.com/hornbill/ | + | * Download the architecture specific [https://github.com/hornbill/user-import-azure/releases/latest latest package] from GitHub |
* Extract zip into a folder you would like the application to run from e.g. '''C:\Hornbill_Import\''' | * Extract zip into a folder you would like the application to run from e.g. '''C:\Hornbill_Import\''' | ||
* Open '''conf.json''' and add in the necessary configuration | * Open '''conf.json''' and add in the necessary configuration | ||
| Line 61: | Line 57: | ||
{ | { | ||
| − | " | + | "KeysafeKeyID": 0, /* this is the Keysafe key ID, which contains your database credentials */ |
| − | |||
"AzureConf": { | "AzureConf": { | ||
| − | |||
| − | |||
| − | |||
| − | |||
"UserFilter": "startswith(displayName,'Dave')", | "UserFilter": "startswith(displayName,'Dave')", | ||
"UserProperties": [ /* list all the fields that you require from Azure */ | "UserProperties": [ /* list all the fields that you require from Azure */ | ||
| Line 216: | Line 207: | ||
} | } | ||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
# The fields are quite self-explanatory and part of the "Details"-section (as opposed to the "About"-section [5]), most can be left as-is. The mapping is done with some templating of the format {{fieldname}}. One can be a little adventurous, for instance "{{.mgrfirstname}} - {{.mgrlastname}}" puts a space, hyphen and space between the person's manager's first and last name. One can use this to prefix or suffix the values coming from the database or indeed to set a static value (as done for example with userType and Attribute under OrgLookup for the company (Type:5)). | # The fields are quite self-explanatory and part of the "Details"-section (as opposed to the "About"-section [5]), most can be left as-is. The mapping is done with some templating of the format {{fieldname}}. One can be a little adventurous, for instance "{{.mgrfirstname}} - {{.mgrlastname}}" puts a space, hyphen and space between the person's manager's first and last name. One can use this to prefix or suffix the values coming from the database or indeed to set a static value (as done for example with userType and Attribute under OrgLookup for the company (Type:5)). | ||
| − | # The same holds here as for [ | + | # The same holds here as for [1], this is regarding the "About"-section of the user's details. |
# this is a non-ordered list of the organisation structure - it allows one to associate the imported user to one or more levels within the organisation. The delivered configuration file will associate each imported user with EACH of the three discernable levels (company, department and division) - depending on your requirements regarding the availability of services and such, you will likely want to manipulate this section and perhaps only leave behind the "department" level (Type: 2) with the TasksView and TasksAction set accordingly. Please note that this import only adds and not REMOVES any association. | # this is a non-ordered list of the organisation structure - it allows one to associate the imported user to one or more levels within the organisation. The delivered configuration file will associate each imported user with EACH of the three discernable levels (company, department and division) - depending on your requirements regarding the availability of services and such, you will likely want to manipulate this section and perhaps only leave behind the "department" level (Type: 2) with the TasksView and TasksAction set accordingly. Please note that this import only adds and not REMOVES any association. | ||
# The password field should be left empty as the utility generates a secure password that adheres to the User Password Policy as specified on your Hornbill instance. This password will only be temporary as the user should use the "Forgot Password" link available on the Hornbill Login Screen to reset their password the first time they navigate to your Hornbill instance. | # The password field should be left empty as the utility generates a secure password that adheres to the User Password Policy as specified on your Hornbill instance. This password will only be temporary as the user should use the "Forgot Password" link available on the Hornbill Login Screen to reset their password the first time they navigate to your Hornbill instance. | ||
| Line 232: | Line 216: | ||
<br> | <br> | ||
<br> | <br> | ||
| + | ===Keysafe=== | ||
| + | You will need to create a [[Hornbill_KeySafe|'''KeySafe record''']] of type "Azure Imports" and set Client ID, Client Secret and Tenant ID. The KeySafeID can be obtained from looking at the URL of the KeySafe record <nowiki>https://live.hornbill.com/</nowiki>'''instanceid'''<nowiki>/security/keysafe/</nowiki>''#KeySafeID''<nowiki>/</nowiki> | ||
| + | |||
| + | '''Note:''' There are relevant Microsoft instructions online on how to obtain the ClientID and ClientSecret from within Azure - [[Azure App Registration Instructions|our quickstart version]]. We have found that the following permissions need to be granted within Azure, though these could differ for you, so please rely on your own expertise. Application permissions on: ''Group.Read.All, GroupMember.Read.All, Team.ReadBasic.All, TeamMember.Read.All, User.Read.All''. Delegated permission on ''User.Read''. The permission settings need to be confirmed. | ||
| + | |||
=== Filtering === | === Filtering === | ||
| − | There are two methods of filtering users that you can configure with this tool. They are both defined in the '''AzureConf''' section | + | There are two methods of filtering users that you can configure with this tool. They are both defined in the configuration's ''AzureConf''' section. |
To import all direct User objects within one or more Azure Groups: | To import all direct User objects within one or more Azure Groups: | ||
| Line 284: | Line 273: | ||
== Preparing to Run the Import == | == Preparing to Run the Import == | ||
| − | Ultimately, the executable will be scheduled in Windows task scheduler (see later) but to test, gain confidence, and perform the initial upload of users the utility can be executed from a command prompt window on an ad-hoc basis. The command used to execute the import can contain a number of command line parameters. | + | Ultimately, the executable will be scheduled in the Windows task scheduler (see later) but to test, gain confidence, and perform the initial upload of users the utility can be executed from a command prompt window on an ad-hoc basis. The command used to execute the import can contain a number of command line parameters. |
| − | * dryrun - Defaults to '''''false''''' - Set to True and the XMLMC for Create and Update users will not be called | + | * dryrun - Defaults to '''''false''''' - Set to True and the XMLMC for Create and Update users will not be called; instead, the XML will be dumped to the log file to aid in debugging the initial connection information. |
* file - Defaults to '''''conf.json''''' - Name of the Configuration file to load | * file - Defaults to '''''conf.json''''' - Name of the Configuration file to load | ||
* zone - Defaults to '''''eur''''' - Allows you to change the ZONE used for creating the XMLMC EndPoint URL: <nowiki>https://{ZONE}api.hornbill.com/{INSTANCE}/</nowiki> | * zone - Defaults to '''''eur''''' - Allows you to change the ZONE used for creating the XMLMC EndPoint URL: <nowiki>https://{ZONE}api.hornbill.com/{INSTANCE}/</nowiki> | ||
| − | * workers - Defaults to `3` - Allows you to change the number of worker threads used to process the import | + | * workers - Defaults to `3` - Allows you to change the number of worker threads used to process the import; this can improve performance on slow import but using too many workers have a detriment to the performance of your Hornbill instance. |
* debug - Defaults to '''''false''''' - outputs extra information to the log to help with debugging issues. | * debug - Defaults to '''''false''''' - outputs extra information to the log to help with debugging issues. | ||
| + | |||
| + | From version '''4.0.0''' of the Azure User Import Utility, when you first run the utility it will prompt you for two vital pieces of information: | ||
| + | |||
| + | * The Instance ID (also referred to as the instance name) can be found in the URL used by your organisation to access your Hornbill instance i.e. <nowiki>https://live.hornbill.com/</nowiki>'''instanceid'''/ (case sensitive). | ||
| + | * A valid API key. This needs to be created against a Hornbill user account with enough rights to create and update user accounts. Details on how to create an API key can be found [[API_keys|'''here''']]. | ||
| + | |||
| + | This information will be encrypted and stored locally on the client PC that will be running the tool. For each subsequent import run, the utility will decrypt your instance ID and API key and will use those to make the relevant API calls back into Hornbill. | ||
| + | |||
| + | NOTE - the encrypted information can only be decrypted on the computer and by the user that performed the encryption, so please keep this in mind when scheduling your imports. | ||
| + | |||
| + | Should you wish to use a different API key or Keysafe Key ID to what has been previously encrypted, delete the '''import.cfg''' file from the folder where the import binary resides, and re-run your import from the command line inputting the requested details as you would have on its first run. | ||
== Testing Overview == | == Testing Overview == | ||
| Line 373: | Line 373: | ||
=== Windows === | === Windows === | ||
| − | You can schedule .exe to run with any optional command line argument from Windows Task Scheduler. | + | You can schedule azure_user_import.exe to run with any optional command line argument from Windows Task Scheduler. |
| − | * Ensure the user account running the task has rights to | + | * Ensure the user account running the task has rights to azure_user_import.exe and the containing folder. |
| + | * Ensure the user account running the task is the one who performed the first run of the tool on this PC, as the instance details are encrypted and can only be decrypted by that user on the current Windows machine | ||
* Make sure the Start In parameter contains the folder where the executable resides in, otherwise it will not be able to pick up the correct path. eg: | * Make sure the Start In parameter contains the folder where the executable resides in, otherwise it will not be able to pick up the correct path. eg: | ||
[[File:Ldap_import_schedule.png]] | [[File:Ldap_import_schedule.png]] | ||
| + | |||
| + | --> | ||
