|
|
| (63 intermediate revisions by 8 users not shown) |
| Line 1: |
Line 1: |
| − | <div style="border:1px solid #90C0FF; background:#D0E0FF; width:99%; padding:4px; margin-bottom:10px;"> | + | This document can now be found at its new location in the [https://docs.hornbill.com/data-imports-guide/users/ldap/overview/ Hornbill Document Library]. |
| | + | |
| | + | [[file:hornbill-document-library.png|Hornbill Cloud|link=https://docs.hornbill.com/data-imports-guide/users/ldap/overview/]] |
| | + | <!-- |
| | + | <div style="border:1px solid #C7004F; color: #C7004F; background:#FFFFFF; width:99%; padding:10px; margin-bottom:10px; font-size: 18px; font-weight: bold;"> |
| | {| style="width:100%" | | {| style="width:100%" |
| − | |[[Main_Page|Home]] > [[Administration]] > [[System]] > [[Data]] > Data Import Configurations > LDAP User Import
| + | This page has been deprecated, and replaced by the [https://docs.hornbill.com/data-imports-guide/users/ldap/overview Data Import Guides book] in the [https://docs.hornbill.com/ Hornbill Documentation Library]. |
| | |style="text-align:right;"| | | |style="text-align:right;"| |
| | |} | | |} |
| | </div> | | </div> |
| − |
| |
| − |
| |
| − | == About the Hornbill LDAP User Import Utility ==
| |
| − | The utility provides a simple, safe and secure way to create new Hornbill User Accounts and update existing ones by synchronizing with accounts held in your Active Directory or other industry standard LDAP capable directory service. The tool is designed to run behind your corporate firewall, connect to your LDAP service, query the required account information, transform and load into the Hornbill instance. The utility does not write back to your directory, it is purely designed to read data from the directory and use this to populate Hornbill user information during the creation of new and update of existing Hornbill User accounts.
| |
| − |
| |
| − | The tool connects to the Hornbill instance 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 utility to run periodically to perform the import/update tasks as required.
| |
| − |
| |
| − | The LDAP Utility can be used as a stand-alone alternative to, or supplement user auto-provisioning. While auto-provisioning requires Single Sign On (SSO) configuring, the LDAP import utility is completely independent of any SSO configuration.
| |
| − |
| |
| − | === Open Source ===
| |
| − |
| |
| − | The User Import Utility is provided open source under the [https://wiki.hornbill.com/index.php/The_Hornbill_Community_License_(HCL) Hornbill Community Licence] and can be found [https://github.com/hornbill/goLDAPUserImport Here] on GitHub
| |
| − |
| |
| − | == Installation Overview ==
| |
| − | Installing the LDAP utility is very simple. The biggest consideration is likely to be where you locate the utility within your environment. Here are some considerations that will help you decide:
| |
| − | # The utility will need "visibility" of your directory server and be able to access this through the appropriate port. Industry standards suggest port 389 however if you use a different port you can specify this in the conf.json file.
| |
| − | # Your Hornbill instance is located in the Cloud, a location outside of your network. The utility will communicate with your instance using HTTPS. Therefore the machine where you install the utility will need a route to the outside world. In terms of ports, industry standards dictate port 443 for HTTPS.
| |
| − |
| |
| − | === Download the Utility for Windows ===
| |
| − | # Click one of the following links to download the [https://github.com/hornbill/goLDAPUserImport/releases/download/v3.0.0/ldap_user_import_win_x64_v3_0_0.zip 64 Bit Version] or [https://github.com/hornbill/goLDAPUserImport/releases/download/v3.0.0/ldap_user_import_win_x86_v3_0_0.zip 32 Bit Version]
| |
| − | # Extract the zip into a folder you would like the application to run from e.g. '''C:\LDAP_Import\'''
| |
| − | <br>
| |
| − | Once you have done this you can then begin configuration and testing
| |
| − |
| |
| − | == HTTP Proxies ==
| |
| − |
| |
| − | If you use a proxy for all of your internet traffic, the HTTP_PROXY Environment variable needs to be set. The https_proxy environment variable holds the hostname or IP address of your proxy server. It is a standard environment variable and like any such variable, the specific steps you use to set it depends on your operating system.
| |
| − |
| |
| − | For windows machines, it can be set from the command line using the following:
| |
| − | <br>
| |
| − | <code>
| |
| − | set HTTP_PROXY=HOST:PORT
| |
| − | </code>
| |
| − | <br>
| |
| − | Where "HOST" is the IP address or host name of your Proxy Server and "PORT" is the specific port number.
| |
| − |
| |
| − | === URLs to White List ===
| |
| − |
| |
| − | Occasionally on top of setting the HTTP_PROXY variable the following URLs need to be white listed to allow access out to our network
| |
| − |
| |
| − | * https://files.hornbill.com/instances/INSTANCENAME/zoneinfo - Allows access to lookup your Instance API Endpoint
| |
| − | * https://files.hornbill.co/instances/INSTANCENAME/zoneinfo - Backup URL for when files.hornbill.com is unavailable
| |
| − | * https://eurapi.hornbill.com/INSTANCENAME/xmlmc/ - This is your Instance API Endpoint, eurapi can change so you should use the endpoint defined in the previous URL
| |
| − | * https://api.github.com/repos/hornbill/goLDAPUserImport/tags - '''Optional''' Allows access to check for the latest version of the Import Tool
| |
| − | <br>
| |
| − |
| |
| − | ==Configuration Overview==
| |
| − | While it is necessary to download an executable to be located, scheduled, and run from within your environment, the configuration is held securely in your Hornbill instance and is created and managed using Hornbill Administration. To begin creating a new configuration, login to Hornbill administration and navigate to '''Home > System > Data > Data Import Configurations'''.
| |
| − | This page relates specifically to the configuration of the LDAP User Import but in future it will be possible to manage further import configurations from this interface.
| |
| − |
| |
| − | :# Click the button located to the top right of the list to create a new import
| |
| − | :# Give your import a name
| |
| − | :# Select the type of import as "LDAP User Import"
| |
| − | :# Add a description to indicate the specific purpose of the import. It is likely that you will have at least two LDAP User Import configurations. One will be used to manage the creation of new users and changes to existing active users of Hornbill and a second configuration can be created to manage the archiving of users who have left your organisation.
| |
| − |
| |
| − | Once you have created a new LDAP User Import entry, you can begin the configuration. A brief overview can be found Here https://www.youtube.com/watch?v=qvq0TUVArqs and any existing LDAP Import configurations (version 2.0 or later) can be imported into this new interface.
| |
| − |
| |
| − |
| |
| − | The configuration is split into separate tabs and they can be approached in the following order:
| |
| − |
| |
| − | :# LDAP Server: This tab is where the information required to set up the communication link with your directory service (i.e. Active Directory) is stored.
| |
| − | :# User Account: This tab contains the mapping between the Hornbill database fields and the LDAP user object attributes. i.e. which LDAP attribute will be used to populate the Hornbill database fields. Only some of these fields are required.
| |
| − | :# User profile: In addition to the fundamental User Account Properties, Hornbill can store much more information about a user.
| |
| − | :# User Options: This tab is where the ancillary associations are managed e.g Manager, Site, Role, and Group associations.
| |
| − | :# Advanced Options: Each time the import is run, it outputs a log file. This tab allows you to set some preferences in relation to the log output.
| |
| − | :# Debug: This tab allows you to view the raw configuration which is being drawn from your selections and entries made in the previous tabs.
| |
| − |
| |
| − |
| |
| − |
| |
| − |
| |
| − |
| |
| − | each building on each other to Detailed command line options for each import configuration can be found within the Hornbill Administration UI.
| |
| − |
| |
| − |
| |
| − |
| |
| − |
| |
| − | === Connecting to your Directory Server ===
| |
| − | This section of the conf file specifies the information required to set up the communication link between your Hornbill instance and your directory service (i.e. Active Directory).
| |
| − | <br>
| |
| − | {| style="width: 100%; height: 100px" border="1" cellpadding="2"
| |
| − | ! colspan = "2" style="text-align: left;" | Connecting to your LDAP (Directory) Server
| |
| − | |-
| |
| − | | style="width: 20%; text-align=left" |
| |
| − | [[File:LDAP_Server.PNG|400px|thumb|<div align="center">''''''</div>]]
| |
| − |
| |
| − | | align="left" |
| |
| − | * "APIKey" - A Valid API Assigned to a user with enough rights to process the import
| |
| − | * "InstanceId" - This is the name of your Hornbill instance and can be found within the URL you use to navigate to it: live.hornbill.com/['''''instance name''''']/. E.g. if the URL you use to access your instance is live.hornbill.com/arescomputing/, then your instance id would be "arescomputing". Remember, this value is also case sensitive.
| |
| − | * "UpdateUserType" - If set to True then the Type of User will be updated when the user account Update is triggered
| |
| − | * "UserRoleAction" - (Both | Update | Create) - This controls when the utility will act upon the roles against a user i.e. will it assign roles only during the creation of a user account, only on Update, or Both.
| |
| − |
| |
| − | |}
| |
| − | <br>
| |
| − | {| style="width: 100%; height: 100px" border="1" cellpadding="2"
| |
| − | ! colspan = "2" style="text-align: left;" | Defining your LDAP Query
| |
| − |
| |
| − | |-
| |
| − | | style="width: 20%; text-align=left" |
| |
| − |
| |
| − | [[File:LDAP_Query.PNG|400px|thumb|<div align="center">''''''</div>]]
| |
| − |
| |
| − | | align="left" |
| |
| − | * "Server" - The address of your directory server.
| |
| − | * "UserName" - The user name needed to access the directory services.
| |
| − | * "Password" - Password for Above User Name.
| |
| − | * "Port" - LDAP Port (389 for normal connections is default, 636 for SSL / TLS connection).
| |
| − | * "ConnectionType" - Type of HTTP connection to use when communicating with the directory Server ("" = Normal HTTP, "SSL" = SSL Connection, "TLS" = TLS Connection).
| |
| − | * "InsecureSkipVerify" - Used with SSL or TLS connection types will allow the verification of SSL Certifications to be disabled.
| |
| − | * "Scope" - Search Scope (ScopeBaseObject = 0, ScopeSingleLevel = 1, ScopeWholeSubtree = 2) Default is 1.
| |
| − | * "DerefAliases" - dereference Aliases (NeverDerefAliases = 0, DerefInSearching = 1, DerefFindingBaseObj = 2, DerefAlways = 3) Default is 1.
| |
| − | * "SizeLimit" - Size Limit for query 0 will disable.
| |
| − | * "TimeLimit" - Time Limit for query 0 will disable.
| |
| − | * "TypesOnly" - Return Attribute Descriptions.
| |
| − | * "Filter" - provides the ability to target specific directory objects. As a minimum `(objectClass=user)` should be specified to ensure the utility only retrieves User Objects. Many online references are available detailing the various possibilities of LDAP filter syntax. Search the web for "''LDAP filter syntax''".
| |
| − | * "DSN" - Allows us to specify the Data Source Name. E.g. `DC=test,DC=hornbill,DC=com`. The utility can target a single OU or the entire directory from the root. The "Scope" variable can add flexibility here however it is not possible to target a selection of specific OU's in a single configuration file.
| |
| − | * "Debug" - Enable LDAP Connection Debugging, should only ever be enabled to troubleshoot connection issues.
| |
| − |
| |
| − | |}
| |
| − | <br>
| |
| − | {| style="width: 100%; height: 100px" border="1" cellpadding="2"
| |
| − | ! colspan = "2" style="text-align: left;" | Listing the LDAP Attributes
| |
| − |
| |
| − | |-
| |
| − | | style="width: 20%; text-align=left" |
| |
| − |
| |
| − | [[File:LDAP_Attributes.PNG|400px|thumb|<div align="center">''''''</div>]]
| |
| − |
| |
| − | | align="left" |
| |
| − | * Array of Attributes to query from the LDAP Server, only attributes specified here will be recognised by the utility i.e. Any LDAP attributes specified anywhere in the configuration file must be listed in this section.
| |
| − | * '''Please note:''' that "thumbnailPhoto" contains binary data for the thumbnail and is a requirement if you plan to use the ImageLink outlined. If you do NOT plan to use the ImageLink, you can leave this out and reduce the load on your AD requests. The utility must understand a definitive list of the directory attributes you have used throughout the conf.json file.
| |
| − |
| |
| − | |}
| |
| − | <br>
| |
| − | <br>
| |
| − |
| |
| − | === Mapping your Directory Attributes to Hornbill User Account Properties ===
| |
| − | This section requires us to specify what LDAP attribute will be used to populate the Hornbill database fields. Only some of these fields are required.
| |
| − | <br>
| |
| − | {| style="width: 100%; height: 100px" border="1" cellpadding="2"
| |
| − | ! colspan = "2" style="text-align: left;" | UserMapping
| |
| − |
| |
| − | |-
| |
| − | | style="width: 20%; text-align=left" |
| |
| − |
| |
| − | [[File:User_Account_Mapping.PNG|400px|thumb|<div align="center">''''''</div>]]
| |
| − |
| |
| − | | align="left" |
| |
| − | The directory attributes shown in the example to the left should be enough to get you started as they are typically where you would find this information referenced in your directory service. However, it is prudent to check that the attribute specified does actually hold the information in your directory as expected.
| |
| − | <br>
| |
| − | * Any value wrapped with [] will be treated as a directory attribute
| |
| − | * It is possible to construct a value by specifing multiple directory attributes against a Hornbill user property E.g.:
| |
| − | * "Name":"[givenName] [sn]", - Both Variables are evaluated from LDAP and set to the Name param
| |
| − | * The password field should be left empty as the utility generates a 10 character random string. 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.
| |
| − | * "Site" - Recognises a corresponding Hornbill site id. E.g.
| |
| − | * "Site":"1" - The value of Site should be numeric
| |
| − | As an alternative, the utility provides a "Site Lookup" section (see below) which can make a site association based on the contents of a directory attribute.
| |
| − | * "UserType" - This defines if a user is Co-Worker or Basic user and can have the value user or basic.
| |
| − | * "CountryCode" - expects ISO 3166 Alpha 2 two Character Country Code. (An Active Directory reference can be found here: https://msdn.microsoft.com/en-us/library/ms677987(v=vs.85).aspx)
| |
| − | * Do not try adding any new properties to this section as they will be ignored.
| |
| − | |}
| |
| − | <br>
| |
| − | <br>
| |
| − |
| |
| − |
| |
| − | === Mapping your Directory Attributes to Extended Hornbill User Account Properties ===
| |
| − | In addition to the fundamental User Account Properties, Hornbill can store much more information about a user.
| |
| − | <br>
| |
| − | {| style="width: 100%; height: 100px" border="1" cellpadding="2"
| |
| − | ! colspan = "2" style="text-align: left;" | UserProfileMapping
| |
| − |
| |
| − | |-
| |
| − | | style="width: 20%; text-align=left" |
| |
| − |
| |
| − | [[File:User_Profile_Mapping.PNG|400px|thumb|<div align="center">''''''</div>]]
| |
| − |
| |
| − | | align="left" |
| |
| − | * Works in the same way as UserMapping
| |
| − | * Do not try and add any new properties here they will be ignored
| |
| − |
| |
| − | |}
| |
| − | <br>
| |
| − | <br>
| |
| − |
| |
| − | <!--
| |
| − | === Setting the status of a Hornbill User Account ===
| |
| − | This section of the utility allows you to set the status of a Hornbill user account. This section is relevant when you wish to create a configuration file to deal with the archiving of user accounts.
| |
| − | <br>
| |
| − | {| style="width: 100%; height: 100px" border="1" cellpadding="2"
| |
| − | ! colspan = "2" style="text-align: left;" | UserAccountStatus
| |
| − |
| |
| − | |-
| |
| − | | style="width: 20%; text-align=left" |
| |
| − |
| |
| − | <code>
| |
| − | "UserAccountStatus":{
| |
| − | "Action":"Both",
| |
| − | "Enabled": false,
| |
| − | "Status":"active"
| |
| − | },
| |
| − | </code>
| |
| − |
| |
| − | | align="left" |
| |
| − | * Action - (Both | Update | Create) - When to Set the User Account Status On Create, On Update or Both
| |
| − | * Enabled - Turns on or off the Status update
| |
| − | * Status - Can be one of the following strings (active | suspended | archived)
| |
| − |
| |
| − | |}
| |
| − | <br>
| |
| − | <br>
| |
| − | === Setting a User's Manager in Hornbill ===
| |
| − | Hornbill can store a manager relationship between two users in Hornbill.
| |
| − | <br>
| |
| − | {| style="width: 100%; height: 100px" border="1" cellpadding="2"
| |
| − | ! colspan = "2" style="text-align: left;" | UserManagerMapping
| |
| − |
| |
| − | |-
| |
| − | | style="width: 20%; text-align=left" |
| |
| − |
| |
| − | <code>
| |
| − | "UserManagerMapping":{
| |
| − | "Action":"Both",
| |
| − | "Enabled":true,
| |
| − | "Attribute":"[manager]",
| |
| − | "GetIDFromName":true,
| |
| − | "Regex":"CN=(.*?)(?:,[A-Z]+=|$)",
| |
| − | "Reverse":true,
| |
| − | "ManagerSearchField":"h_name",
| |
| − | "UseDNCacheFirst":true
| |
| − | },
| |
| − | </code>
| |
| − |
| |
| − | | align="left" |
| |
| − | * Action - (Both | Update | Create) - When to Set the User Manager On Create, On Update or Both
| |
| − | * Enabled - Turns on or off the Manager Import
| |
| − | * Attribute - The LDAP Attribute to use for the name of the Manager ,Any value wrapped with [] will be treaded ad an LDAP field
| |
| − | * GetIDFromName - Lookup Hornbill User Id From Name, The Managers Name matched in the Regex must explicitly match the full name in Hornbill (true | false)
| |
| − | * Regex - Optional Regex String to Match the Name from an DSN String
| |
| − | * Reverse - Reverse the Name String Matched from the Regex (true | false)
| |
| − |
| |
| − | |}
| |
| − | <br>
| |
| − | <br>
| |
| − |
| |
| − | === Associating Roles to Hornbill User Accounts ===
| |
| − | The LDAP import utility also has the ability to associate Hornbill roles to the user accounts it creates or updates.
| |
| − | <br>
| |
| − | {| style="width: 100%; height: 100px" border="1" cellpadding="2"
| |
| − | ! colspan = "2" style="text-align: left;" | Roles
| |
| − |
| |
| − | |-
| |
| − | | style="width: 20%; text-align=left" |
| |
| − |
| |
| − | <code>
| |
| − | "Roles":[
| |
| − | "Basic User Role"
| |
| − | ],
| |
| − | </code>
| |
| − |
| |
| − | | align="left" |
| |
| − | * This should contain an array of Hornbill User Roles to be associated to a user when they are created i.e. When specifying more than one role, they should each have a comma at the end with the exception of the last role in the list.
| |
| − | * The utility understands whether to add the role on account creation or account update based on the "UserRoleAction" variable located at the top of the configuration file.
| |
| − | |}
| |
| − | <br>
| |
| − | <br>
| |
| − | === Uploading Images to Hornbill User Accounts ===
| |
| − | The "ImageLink" section of the configuration file affords the ability to upload images to User profiles in Hornbill. Only jpg/jpeg and png formats are accepted.
| |
| − | <br>
| |
| − | {| style="width: 100%; height: 100px" border="1" cellpadding="2"
| |
| − | ! colspan = "2" style="text-align: left;" | ImageLink
| |
| − |
| |
| − | |-
| |
| − | | style="width: 20%; text-align=left" |
| |
| − |
| |
| − | <code>
| |
| − | "ImageLink":{
| |
| − | "Action":"Both",
| |
| − | "Enabled": false,
| |
| − | "UploadType": "AD",
| |
| − | "InsecureSkipVerify": true,
| |
| − | "ImageType": "jpg",
| |
| − | "URI": "[thumbnailPhoto]"
| |
| − | },
| |
| − | </code>
| |
| − |
| |
| − | | align="left" |
| |
| − | * Action - (Both | Update | Create) - When to associate an Image On Create, On Update or Both
| |
| − | * Enabled - Turns on or off the Image association
| |
| − | * UploadType - (AD | URL | URI) - what TYPE of image upload sequence we are using
| |
| − | ** AD - using data stored in AD - set the "URI" as JUST the ldap field (i.e. without the square brackets; traditionally AD stores the binary in thumbnailPhoto)
| |
| − | ** URL - find the image at end of "URI" below - assuming that the URL is visible by our Hornbill servers (eg <nowiki>http://whatever.com/[userPrincipalName].jpg</nowiki>)
| |
| − | ** URI - find the image at end of "URI" below - from a LOCAL server (not fully tested; eg <nowiki>http://localserver/[userPrincipalName].jpg</nowiki>)
| |
| − | * ImageType - (jpg | png) type of image as stored in AD
| |
| − | * URI - referencing the image data
| |
| − |
| |
| − | |}
| |
| − | <br>
| |
| − | <br>
| |
| − | === Associating a Site to Hornbill User Accounts ===
| |
| − | The LDAP Import utility has the ability to associate a Hornbill Site record to a user account based on the contents of a directory attribute. This is achieved through a "Look-up". The Look up mechanism is quite simple and works in the following manner.
| |
| − | # The utility reads the attribute that is specified in the siteLookup section. In the example shown, the [physicalDeliveryOfficeName] directory attribute is used.
| |
| − | # It takes the content and tries to identify if there is an existing site record in Hornbill with a name that matches the value of the LDAP attribute. e.g. if the [physicalDeliveryOfficeName] directory attribute contained "Brussels", the utility would look for a Hornbill Site record with the name "Brussels".
| |
| − | # If a match is found, the utility will associate the user to the site.
| |
| − | # If no site record is found, the utility will move onto the next user.
| |
| − |
| |
| − | i.e. The name of the Site record in Hornbill must match the value of the Attribute in LDAP. More on Hornbill Organisational Groups can be found here: [[Sites|'''Sites''']]
| |
| − | <br>
| |
| − | {| style="width: 100%; height: 100px" border="1" cellpadding="2"
| |
| − | ! colspan = "2" style="text-align: left;" | SiteLookup
| |
| − |
| |
| − | |-
| |
| − | | style="width: 20%; text-align=left" |
| |
| − |
| |
| − | <code>
| |
| − | "SiteLookup":{
| |
| − | "Action":"Both",
| |
| − | "Enabled": false,
| |
| − | "Attribute":"[physicalDeliveryOfficeName]"
| |
| − | },
| |
| − | </code>
| |
| − |
| |
| − | | align="left" |
| |
| − | * Action - (Create | Update | Both) - When the utility should perform the siteLookup. Upon Creation of a new user account, during the updating of an existing user account, or in both situations.
| |
| − | * Enabled - Turns the Lookup of sites on or off
| |
| − | * Attribute - The directory attribute to use for the name of the Site. Any value wrapped with [] will be treated as a directory attribute.
| |
| − |
| |
| − | |}
| |
| − | <br>
| |
| − | <br>
| |
| − | === Associating a Group to Hornbill User Accounts ===
| |
| − | The LDAP Import utility has the ability to associate a Hornbill Group to a user account based on the contents of a directory attribute. This is achieved through a "Look-up". The Look up mechanism is quite simple and works in the following manner.
| |
| − | # The utility reads the attribute that is specified in the orgLookup section. In the example shown, the [department] directory attribute is used.
| |
| − | # It takes the content and tries to identify if there is a Hornbill Group that exists with a name that matches the value of the LDAP attribute. e.g. if the [department] directory attribute contained "Accounting", the utility would look for a Hornbill Group called "Accounting".
| |
| − | # If a match is found, the utility will associate the user to the group.
| |
| − | # If no Hornbill organisation is found, the utility will move onto the next user.
| |
| − |
| |
| − | i.e. The name of the Organization(Group) in Hornbill must match the value of the Attribute in LDAP. More on Hornbill Organisational Groups can be found here: [[Organisation|'''Organisation Structure (Groups)''']]
| |
| − | <br>
| |
| − | {| style="width: 100%; height: 100px" border="1" cellpadding="2"
| |
| − | ! colspan = "2" style="text-align: left;" | OrgLookup
| |
| − |
| |
| − | |-
| |
| − | | style="width: 20%; text-align=left" |
| |
| − |
| |
| − | <code>
| |
| − | "OrgLookup":{
| |
| − | "Action":"Both",
| |
| − | "Enabled":false,
| |
| − | "Attribute":"[department]",
| |
| − | "Type":2,
| |
| − | "Membership":"member",
| |
| − | "TasksView":false,
| |
| − | "TasksAction":false,
| |
| − | "OnlyOneGroupAssignment":false
| |
| − | }
| |
| − | </code>
| |
| − |
| |
| − | | align="left" |
| |
| − | * Action - (Create | Update | Both) - When the utility should perform the OrgLookup. Upon Creation of a new user account, during the updating of an existing user account, or in both situations.
| |
| − | * Enabled - Turns the Lookup of Organisations on or off
| |
| − | * Attribute - The directory attribute that contains the company or division or department name to use for the Hornbill Group Look-up. Any value wrapped with [] will be treated as an directory attribute.
| |
| − | * Type - The Hornbill Group type (0=general ,1=team ,2=department ,3=costcenter ,4=division ,5=company). This focuses the utility to only perform the look-up on Groups of a particular type (this has no relevance to the contents of your directory or the directory attribute that is used.
| |
| − | * Membership - The Hornbill Group Membership the users will be added with (values can be either member | teamLeader | manager)
| |
| − | * TasksView - If set true, then the user can view tasks assigned to this group.
| |
| − | * TasksAction - If set true, then the user can action tasks assigned to this group.
| |
| − | '''Please Note''' - A successful association of a user to a Group is dependant upon the utility finding a Hornbill Group with a name that matches the contents of the specified user attribute in your directory.
| |
| − | |}
| |
| − | <br>
| |
| − | <br>
| |
| − |
| |
| | --> | | --> |
| − | == Command Line Parameters ==
| + | [[Category:HDOC]] |
| − | | |
| − | * file - this allows us to specify the Configuration file to load when running the utility. When this argument is not used, then the utility will default to using the '''conf.json''' file provided with the utility.
| |
| − | * dryrun - Defaults to '''''false''''' - Set to True and the XMLMC for Create and Update users will not be called and instead the XML will be dumped to the log file, this is to aid in debugging the initial connection information.
| |
| − | * 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 performance of your Hornbill instance.
| |
| − | | |
| − | == Testing Overview ==
| |
| − | There is no substitute for hands-on experience when becoming familiar with the Hornbill import utilities.
| |
| − | <br>
| |
| − | The LDAP import utility accepts and understands a number of "Command Line Parameters" that can be used when running the utility from the command line. The most important one for testing is the '''-dryrun=true''' command. When this is specified, no information will be written to Hornbill and it allows you to confirm that the conf file is correctly structured and that a connection to your directory server can be established. A dryrun will also output a log file which provides you with an opportunity to review and understand any error messages that may occur.
| |
| − | <br>
| |
| − | Below are some high level steps to help you build confidence in your configuration:
| |
| − | <br>
| |
| − | <br>
| |
| − | # In the conf.json file, specify an LDAP filter to target a single user object. (Its good practice to initially test on a single, or small set of, user objects as this allows the dryruns to complete quicker and there is less log content to sift through).
| |
| − | # Perform a dryrun (by executing the utility along with the -dryrun=true command line parameter).
| |
| − | # Review cmd output and log file for errors
| |
| − | # Check against "Common Error Messages" listed on the wiki and take action to rectify where necessary.
| |
| − | # Continue with dryrun tests until you are happy that all the errors are accounted for.
| |
| − | # Perform a live import with this single user object still specified.
| |
| − | # Review user account in Hornbill and check all user properties are as expected i.e. email contains an email address etc.
| |
| − | # Adjust conf file user property mappings as necessary
| |
| − | # Loop through steps 6 - 8 as many times as is necessary until you are happy with the information being transported into the Hornbill user account properties.
| |
| − | # Amend the LDAP filter to target the user objects required for a full import.
| |
| − | # Perform a dryrun
| |
| − | # Review cmd output and log file for errors
| |
| − | # Check against "Common Error Messages" listed on the wiki and take action to rectify where necessary.
| |
| − | # Continue with dryrun tests until you are happy that all the errors are accounted for.
| |
| − | <br>
| |
| − | Example use of the dryrun command line parameter specified after the utility executable:
| |
| − | <code>
| |
| − | ldap_user_import.exe -dryrun=true
| |
| − | </code>
| |
| − | | |
| − | === What Hornbill Roles are needed for the Import to Complete Successfully? ===
| |
| − | A default role is delivered with Hornbill that is designed to be used in conjunction with our range of user import utilities. The security role is called '''User Import''' and has all the necessary rights to import / update user properties.
| |
| − | | |
| − | As you may now be aware, every action within Hornbill must be performed in the context of a user account. As well as the chosen user account possessing the "user Import" role which facilitates the importing of the user accounts and updating of the user properties, this user account must posses the roles that you are associating to imported user accounts via the import utility.
| |
| − | The above comment about roles is referring to Hornbill's security model when it comes to associating roles to user accounts, which is: ''Hornbill is designed to only allow the association of roles if the User who is performing the assignment of a particular role already possess the same system/application rights among the roles that they themselves possess.'' This security measure prevents you inflating your own rights or giving a user more rights than you have yourself.
| |
| − | | |
| − | i.e. in addition to the "User Import" role, any roles you try and assign to the user accounts being imported must be assigned to the user account logging in and running the import.
| |
| − | | |
| − | ==Trouble Shooting==
| |
| − | | |
| − | === Logging Overview ===
| |
| − | | |
| − | All Logging output is saved in the "log" directory which can be found in the same location as the executable. The file name contains the date and time the import was run '''''LDAP_User_Import_2015-11-06T14-26-13Z.log'''''
| |
| − | | |
| − | ===Common Error Messages===
| |
| − | | |
| − | Below are some common errors that you may encounter in the log file and what they mean:
| |
| − | * ''' ''[ERROR] Error Decoding Configuration File:.....'' ''' - this will be typically due to a missing quote (") or comma (,) somewhere in the configuration file. This is where an online JSON viewer/validator can come in handy rather than trawling the conf file looking for that proverbial needle in a haystack.
| |
| − | * ''' ''[ERROR] Get https:// api.github.com/repos/hornbill/goLDAPUserImport/tags: dial tcp xx.xx.xx.xx:xxx: ........'' ''' - this most likely indicates that you have a HTTP proxy server on your network between the host running the executable and your Hornbill API endpoint. Ensure the http_proxy environment variable is set (See the section on "HTTP Proxies" for more information) and that the proxy is configured to allow this communication.
| |
| − | * ''' ''[ERROR] Unable to Create User: Invalid value for parameter '[parameter name]': The text size provided (31 characters) is greater than the maximum allowable size of 20 characters for column [column name]'' ''' - the contents of your directory attribute exceed the maximum number of characters that can be placed in the Hornbill database column.
| |
| − | * ''' ''[ERROR] Unable to Create User: The value in element <userId> did not meet the required input pattern constraints. at location '/methodCall/params/userId' '' ''' - the user id contains characters that are not allowed. The User Id should be made up of alphanumeric characters. Full stops (.) and underscores (_) are also supported.
| |
| − | * ''' ''[ERROR] Unable to Update User: Invalid value for parameter '[parameter name]': Error setting value for column '[column name]'. bad lexical cast: source type value could not be interpreted as target'' ''' - this error is indicating that the contents of your directory attribute are in a format that is not compatible with the type of the Hornbill database column. For example, you will get this when trying to place text into a database field that is of type "INT" (accepts integer values only).
| |
| − | * ''' ''[ERROR] Unable to Load LDAP Attribute: '[LDAP attribute name]' For Input Param: '[Hornbill Parameter name]' '' ''' - When the import utility is unable to load a particular LDAP attribute, this means that the attribute field in your directory does not contain a value. This error will not prevent the user account being created or updated in Hornbill and can be considered more as a warning rather than an outright failure or problem.
| |
| − | * ''' ''[ERROR] Unable to Assign Role to User: You cannot create or update the role as you do not have sufficient permissions to set the system rights.'' ''' - every action within Hornbill must be performed in the context of a user account. This error is suggesting that the user account you are using to run the utility does not posses the appropriate Hornbill roles set to associate the necessary roles the imported user. See the Testing section above, specifically "What Hornbill Roles are needed for the Import to Complete Successfully?".
| |
| − | | |
| − | === Error Codes ===
| |
| − | * '''100''' - Unable to create log File
| |
| − | * '''101''' - Unable to create log folder
| |
| − | * '''102''' - Unable to Load Configuration File
| |
| − | | |
| − | == Scheduling Overview ==
| |
| − | | |
| − | === Windows ===
| |
| − | You can schedule ldap_import.exe to run with any optional command line argument from Windows Task Scheduler.
| |
| − | {| style="width: 100%; height: 100px" border="0" cellpadding="2"
| |
| − | |-
| |
| − | | align="left" |
| |
| − | [[File:Ldap_import_schedule.png|300px|thumb|centre|<div align="centre">'''Scheduling the Utility with Windows Task Scheduler'''</div>]] | |
| − | | align="left" |
| |
| − | * Ensure the user account running the task has rights to ldap_import.exe and the containing folder.
| |
| − | * Make sure the Start In parameter contains the folder where ldap_import.exe resides in otherwise it will not be able to pick up the correct path.
| |
| − | |}
| |
