diff --git a/midpoint/methodology/first-steps/assessment.adoc b/midpoint/methodology/first-steps/assessment.adoc deleted file mode 100644 index dba433c8f..000000000 --- a/midpoint/methodology/first-steps/assessment.adoc +++ /dev/null @@ -1,453 +0,0 @@ -= First Steps With MidPoint: Assessment -:page-nav-title: 'Assessment' -:page-display-order: 110 -:page-toc: top -:experimental: - -.Goal -TIP: Asses the _real_ data quality, determine practical next steps. -At this point we know what we _really_ have, what we can build on, what needs to be improved. -We can identify the most severe security risks, such as orphaned accounts. -Now we can improve our plan, adding more details based on the _real_ data. - -You have some kind of HR data now. -In theory, you should use the HR data to create and manage accounts in target system, such as your Active Directory. -However, in practice, this is not entirely straightforward. - -Firstly, it is almost certain that there are errors and inaccuracies in the HR data. -The data were maintained manually for a long time, with no way for automatic validation. -Mistakes in the data might be buried deep, surviving undetected for decades. -Having nothing to compare the data with, there is no telling how good or bad the data are. - -Secondly, the data in your target systems (especially Active Directory) certainly leave a lot to be desired. -These were managed manually for years, with no automatic way to make sure they are correct. -There will be account belonging to people that left your organizations years ago. -There will be accounts using maiden names of women that are married now. -There will be strange accounts and identifiers that originated ages ago when your organization was still small and system administration was fun. -There may be all kinds of weirdness and historical baggage frozen in time because nobody remembers what it does and everybody is scared to touch it. - -In general, when deploying identity management system to an existing environment, we need to take extra care of the following: - -. *usernames*: midPoint usernames should be the same as for the principal authentication system. In this methodology, we assume that company's Active Directory or LDAP which will be connected as the first target system is used as the source of usernames. -. *accounts*: we should not harm any existing accounts in an unexpected way -. *passwords*: we should not alter (e.g. re-generate) any existing account password - -Taking HR data and simply forcing them to Active Directory will never work. -We need much smarter approach. - -// TODO: short summary of the process - -This is what you have to do: - -== Connect HR System - -*Connect HR* data source to midPoint. -Set up your HR identity resource in midPoint, using CSV or DatabaseTable connector. - -.Please refer to the following documentation: - -* xref:/midpoint/reference/admin-gui/resource-wizard/[] - -You can see this step in action in the First Steps Methodology webinar video: - -video::suo775ym_PE[youtube,title="Step 2: Connect Source System (HR)",start="1216"] - -Deal with just the very basic data items for now: - -* Names (given name, family name) -* Employee number, student number or similar identifier -* Status (active, former employee, alumni, etc.) and/or validity date/time (based on contract etc.) - -You can ignore other fields for now. -We can get back to them later. - -The resource is created in `Proposed` lifecycle status by default. -Keep it that way at this stage. - -We recommend to use resource capabilities to disable `Create`, `Update` and `Delete` operations on the resource. - -Create a new object type for HR accounts to allow creation of users in midPoint with `Person` archetype assigned. - -.Please refer to the following documentation: - -* xref:/midpoint/reference/admin-gui/resource-wizard/#object-type-configuration[Resource wizard - part Object type configuration] - -WARNING: Make sure you select the proper archetype before importing the users. Change of archetype is not supposed to be a straightforward process as archetypes are expected to work as object classes in the future. - -Preview your HR records which will be imported to see if you want to import all of them, or you want to import only a subset of them using a classification filter (e.g. if you want to ignore non-IT personnel). -While the resource is in `Proposed` lifecycle state, you can redefine classification filters and reclassify your HR accounts as many times as you wish. - -[#import-users-from-hr] -== Import Users From HR To MidPoint - -*Import users* to midPoint, using HR data. -For simplicity, use HR person identifier (e.g. employee number) as the midPoint username. -We will import the usernames from AD/LDAP later. - -.Please refer to the following documentation: - -* xref:/midpoint/reference/admin-gui/resource-wizard/#wizard-for-task-creation[Resource wizard - part Wizard for task creation] - -You can see this step in action in the First Steps Methodology webinar video: - -video::suo775ym_PE[youtube,title="Step 3: Import from HR",start="1541"] - -//Select appropriate algorithm for midPoint username. -//You surely have some username convention (such as `jsmith`) in place. - -Start with importing a single HR account with preview option to see how the user would be created in midPoint. -Then you can xref:/midpoint/reference/simulation/[simulate] the import of all HR accounts using a simulated import task running with _Development_ configuration to see how all the users would be created in midPoint. - -You can continually improve your imported data by adding more attribute mappings. - -When finished, switch the HR resource to `Active` lifecycle state. - -.Please refer to the following documentation: - -* xref:/midpoint/reference/admin-gui/resource-wizard/#how-to-use-lifecycle-state[Resource wizard - part How to use lifecycle state] - -WARNING: Make sure you have selected the proper archetype for users before importing them. Change of archetype is not supposed to be a straightforward process as archetypes are expected to work as object classes in the future. - -Now you can import the HR data, creating user objects in midPoint. -As we are working with simple data for now, the import should go well. - -.User lifecycle -[NOTE] -==== -This is where user lifecycle management starts. - -We need at least some basic framework for user lifecycle management at this point. - -If we can identify inactive (former) HR persons, we can utilize this information when checking for accounts in target systems that should not be there (if we do not import inactive users from HR, we will see their accounts in target systems as simply orphaned). -==== - -Instead of setting user's `administrativeStatus`, we recommend to set midPoint user's `lifecycleState` property based on HR data as either: - -* active -* suspended (e.g. temporarily inactive employees - parental leave, long-term sickness etc.) -* archived (e.g. former employees) - -.If you have imported users with incorrect archetype -[NOTE] -==== -If you have managed to import users from source system with an incorrect archetype, please do the following: - -. Delete all imported users from midPoint (make sure you do not delete `administrator` user) -.. midPoint will attempt to delete the source accounts in HR as well, if you have disabled `Create`, `Update` and `Delete` operations in resource capabilities, errors will be displayed (this is expected) -. Re-configure HR resource to use a correct archetype for user creation. -. Re-run the import task from HR resource. -==== - -[#connect-active-directory] -== Connect Active Directory - -*Set up your Active Directory (or LDAP) identity resource* in midPoint and keep it in `Proposed` lifecycle state. -Create Object type definition for AD accounts and keep it in `Proposed` lifecycle state as well. - -.Please refer to the following documentation: - -* xref:/midpoint/reference/admin-gui/resource-wizard/[] - -TIP: You can see this step in action in https://youtu.be/suo775ym_PE?t=1898&si=In5OAmPHUM9p7YdW[Step 4: Connect Target System in the First Steps Methodology Webinar] video. - -You can see this step in action in the First Steps Methodology webinar video: - -video::suo775ym_PE[youtube,title="Step 4: Connect Target System",start="1898"] - -Set up outbound mappings for the small data set that you have (given name, username and so on) and keep them in `Draft` lifecycle state (effectively disabled). - -Configure correlation rules for AD accounts. - -Configure synchronization configuration in `Proposed` lifecycle state. - -We do not want to change any data in Active Directory yet. - -.Please refer to the following documentation: - -* xref:/midpoint/reference/admin-gui/resource-wizard/#synchronization[Resource wizard - part Synchronization] -* xref:/midpoint/reference/admin-gui/resource-wizard/#correlation[Resource wizard - part Correlation] -* xref:/midpoint/reference/admin-gui/resource-wizard/#mappings[Resource wizard - part Mappings] - -.Resource templates -[NOTE] -==== -Resource templates can be prepared in advance. - -Creating a new resource based on resource template instead of creating it from scratch can save your time as the basic configuration would be pre-defined, and you can enable/update it as necessary. -==== - -TIP: Please refer to our https://github.com/Evolveum/midpoint-samples/tree/master/samples/resources/ad-ldap/AD[Active Directory resource sample] for more information. This sample was tested with our First Steps Methodology. - - -== Correlate Active Directory Accounts - -*Correlate Active Directory accounts* with midPoint users. -If you have employee numbers (or similar unique attributes from HR) stored in your Active Directory, then use that for correlation. -As an alternative if no such data can be used or if data is unreliable, you may want to use several attributes for _approximate_ correlation such as names, locality, department etc. -Manual confirmation using midPoint correlation cases can be used to specify midPoint user who should own the Active Directory account if the match is ambiguous. - -.Please refer to the following documentation: -* xref:/midpoint/reference/admin-gui/resource-wizard/#synchronization[Resource wizard - part Synchronization] -* xref:/midpoint/reference/admin-gui/resource-wizard/#correlation[Resource wizard - part Correlation] -* xref:/midpoint/reference/admin-gui/resource-wizard/#wizard-for-task-creation[Resource wizard - part Wizard for task creation] - - -You can see this step in action in the First Steps Methodology webinar video: - -video::suo775ym_PE[youtube,title="Step 5: Target System Integration",start="2027"] - - -After configuring correlation and synchronization (while the resource, object type and synchronization configuration is in `Proposed` lifecycle state): - -//Otherwise, use the generated midPoint usernames (e.g. `jsmith` convention) as the correlation identifier to match //(assumed) majority of the accounts to their corresponding owners in midPoint: - -. Run the simulated _reconciliation_ task on AD resource using _Development_ configuration. -. Then have a look at the task and simulation results in midPoint GUI (interactively). - -If you maintained your identifier assignment conventions reasonably well, most identities should correlate well. -MidPoint will show you correlation statistics for your accounts. - -Of course, if the correlation is not able to use the personal/employee numbers, just users' names, there will be problems of `John Smith` and `Josh Smith` with their `jsmith` and `jsmith42` accounts. -Let's leave that for later. -For now just focus on correlating the bulk of users. - -If you get 80-90% users to correlate well, you are done here. - -There will be also orphaned accounts (`Unmatched` synchronization situation). -Based on your resource configuration, midPoint may report they will be deactivated (but we are still in `Proposed` lifecycle state - just simulating). - -We will analyze the accounts here, but we will take final decision later in <> to not stop us from progressing. - -TIP: You can analyze/clean up the data in several iterations. - -The orphaned accounts generally fall into the following categories: - -. *Obviously orphaned accounts*: -Review the list of orphaned accounts (the accounts in Active Directory not having an owner in midPoint which should mean they are not related to HR data on which midPoint data is based) one by one and make sure these are _not_ system accounts (see the _System (service) accounts_ category). -+ -Be careful if your HR system does not contain/export former employees data; in such situation you will not have the former employees in midPoint as users and their Active Directory accounts will be also considered orphaned. -+ -If you are absolutely sure the accounts should be deactivated, you do not need to mark them and leave them to their (later) fate. - -. *Orphaned accounts of unclear origin*: -Review the list of orphaned accounts (the accounts in Active Directory not having an owner in midPoint which should mean they are not related to HR data on which midPoint data is based) one by one and make sure these are _not_ system accounts (see the _System (service) accounts_ category). -+ -xref:/midpoint/reference/concepts/mark/[_Mark_ the undesired ones as Decommission later] to be deactivated eventually (but not yet). - -. *System (service) accounts*: -For all accounts that are crucial for Active Directory, we need a different decision. -+ -xref:/midpoint/reference/concepts/mark/[_Mark_ the system accounts as Protected in midPoint] to keep track of them, but ignore them otherwise by midPoint. - -. *Accounts unmatched because of data inconsistencies.* -Review the rest of accounts which have not been matched or decided in the previous steps. -This is the time to take care of the Smiths, Johnsons and Browns if no reasonably unique attribute could have been used for their correlation. -If possible, update your correlation configuration to use more attributes to find matching users (e.g. Given name, Family name, Location, ...). -+ -You can also try to figure out which account belongs to which user and correlate them manually. -+ -Or you can mark specific accounts as "Correlate later" to ignore them now and resolve them in later iteration. -+ -If you did the previous steps well, there should be just a handful of them. -+ -Sometimes there are several accounts (or groups of accounts) which need to be reviewed in more detail and remedied. -To avoid getting stuck in this phase, you may simply mark these accounts for later review ("Do not touch") and ignore any provisioning for them fow now. -(This is actually similar to the concepts of protected accounts, but having a different mark allows us to differentiate the accounts. We want them marked only temporarily, and they will be reported.) - -TIP: We recommend to *review the accounts marked in previous iterations* to avoid a constant increase of their numbers. - -After you have finished marking of your accounts, you can run the simulated _reconciliation_ task with _Development_ configuration again. -Your marked accounts should not be reported to be deactivated anymore. -Orphaned accounts which are not marked should be still reported as to be deactivated. - -Switch the resource, object type configuration and all synchronization actions except for `Unmatched` situation to `Active` lifecycle state. -Switch the synchronization action for `Unmatched` situation to `Draft` lifecycle state (to keep the reaction temporarily disabled), and: - -. Run the simulated _reconciliation_ task on AD resource using _Production_ configuration. -. Then have a look at the simulation results in midPoint GUI (interactively). Orphaned accounts should not be touched anymore - we will resolve them later, the synchronization configuration for them won't be used now (just in simulations). - -Correlate the majority of your accounts now: - -. Run the _reconciliation_ task on AD resource. -. Check the correlation statistics (watch for *Linked* situation) -. Majority of your accounts should be linked to their midPoint owners. - - -Of course, you are doing this for the first time. -Chances are that you have not got all your configuration exactly right at the first try. -You may even need to update your HR resource configuration (e.g. if you forgot to import employee number) and reimport HR data. -Therefore, we assume you will work in iterations. -Simulations will guide you all the way. - -== Import Active Directory usernames - -Until now, users in midPoint have been created with employee number (or similar) attribute from HR. -But your users already have Active Directory usernames. -We can reuse them also for midPoint users - the advantage will be more obvious later, if we switch the midPoint authentication mechanism to use Active Directory. - -.Please refer to the following documentation: -* xref:/midpoint/reference/admin-gui/resource-wizard/#mappings[Resource wizard - part Mappings] -* xref:/midpoint/reference/admin-gui/resource-wizard/#wizard-for-task-creation[Resource wizard - part Wizard for task creation] - - -You can see this step in action in the First Steps Methodology webinar video: - -video::suo775ym_PE[youtube,title="Step 6: Import Usernames from Target System",start="2461"] - - -Re-configure the original HR inbound mapping for midPoint username: set its strength to _weak_. -This allows to still create midPoint users who have no Active Directory account, but AD username will have higher priority. - -Re-configure your Active Directory resource: add a new _inbound_ mapping from AD's login attribute to midPoint username. -The mapping will be created as _strong_ by default, to take precedence over HR, but keep the mapping lifecycle state `Proposed` (simulation) for now. - -Simulate the username import: - -. Run the simulated or _reconciliation_ task on AD resource using _Development_ configuration (as the mapping we're interested in is in `Proposed` lifecycle state). -. Then have a look at the simulation results in midPoint GUI (interactively). - -For all users with Active Directory account, midPoint will indicate username change. -Inspect the changes and fix the username mapping in Active Directory if needed. - -Re-configure your Active Directory inbound mapping: set it to `Active` lifecycle state. - -.Optional step: -[TIP] -==== - -Simulate the username import once again: - -. Run the simulated _reconciliation_ task on AD resource using _Production_ configuration. -. Then have a look at the simulation results in midPoint GUI (interactively). - -Inspect the changes and fix the username mapping in Active Directory if needed, before you turn import them for real. -==== - -Import the usernames now: - -. Run the _reconciliation_ task on AD resource. -. Majority of your midPoint users should be renamed according to their Active Directory usernames. -. Users without accounts in Active Directory (e.g. still uncorrelated) will keep their original usernames from HR (based on e.g. employee number). Such users (without Active Directory accounts) can be easily found in midPoint using GUI. - -== Clean Up The Accounts - -After the majority of the accounts have been correlated and usernames imported, we can handle the orphaned accounts (in situation `Unmatched`). -You have already marked your accounts (and intentionally not marked some of them). - -.Please refer to the following documentation: - -* xref:/midpoint/reference/admin-gui/resource-wizard/#synchronization[Resource wizard - part Synchronization] - -You can see this step in action in the First Steps Methodology webinar video: - -video::suo775ym_PE[youtube,title="Step 6.1: Clean Up Orphaned Accounts",start="2723"] - - -You are ready for clean up procedure: - -. re-configure synchronization action for `Unmatched` situation: set it to `Active` lifecycle state. -. run _reconciliation_ task with Active Directory with _Production_ configuration to see what would happen one last time. If the simulation results correspond to what you have seen earlier with _Development_ configuration, continue. -. run _reconciliation_ task with Active Directory -. unmarked orphaned accounts should be deactivated -. additionally, the policy for orphaned accounts is set from now on, but the marked accounts will not be harmed. - -During the clean up part (now or in one of the later iterations), you should check if there are any uncorrelatable accounts that can be correlated using additional correlation rules and/or operator intervention. - -You can see this step in action in the First Steps Methodology webinar video: - -video::suo775ym_PE[youtube,title="Step 6.2: Correlation with Operator Confirmation",start="2833"] - -You should periodically review your xref:/midpoint/reference/concepts/mark/[marked accounts], especially those "temporary" states such as "To be decommissioned", "Do not update" and "Correlate later". - -You should also periodically run reconciliation task with your Active Directory to detect and deactivate any future orphaned accounts. -Unmarking those accounts and running _reconciliation_ task with Active Directory will remove them. - -This phase may seem as pointless phase. -Why not just go directly to automation? -That is what we really want! -However, assessment is all but pointless. -Automation can be done only after the assessment phase is done. -Attempts to automate processes with unreliable data are futile, they invariably lead to failures, usually a very expensive failures. -Speaking from a couple of decades of identity management experience, there is no such thing as reliable data, unless the data are cleaned up and systematically maintained with an assistance of identity management platform. -Simply speaking: you may think that your data is good, but it is not. - -== Prepare Active Directory for Provisioning - -Before turning on automation, we need to ensure the provisioning configuration for Active Directory resource is correct. -Especially if you are preparing the configuration in iterations, you need to make sure you are going right direction. -Simulations will guide you all the way. - -.Please refer to the following documentation: - -* xref:/midpoint/reference/admin-gui/resource-wizard/#mappings[Resource wizard - part Mappings] -* xref:/midpoint/reference/admin-gui/resource-wizard/#activation[Resource wizard - part Activation] -* xref:/midpoint/reference/admin-gui/resource-wizard/#credentials[Resource wizard - part Credentials] -* xref:/midpoint/reference/admin-gui/resource-wizard/#wizard-for-task-creation[Resource wizard - part Wizard for task creation] - - -You can see this step in action in the First Steps Methodology webinar video: - -video::suo775ym_PE[youtube,title="Step 7: Enable Provisioning to Target System",start="3088"] - -Prepare / update outbound attribute mappings for your Active Directory attributes that you wish to provision. -If you want to force midPoint policy for attributes, you would need to make your mappings strong (this is default if you use GUI to create the mappings). -Set your mappings' lifecycle state attributes to `Proposed` to allow simulations. - -Prepare / update outbound password mapping(s) for your Active Directory: - -. to generate _initial_ (strength: weak) random password for any _new_ Active Directory account from now on. -The password will be forgotten; users need to cooperate with AD administrators or Helpdesk to gain their first credentials. -. to allow passing midPoint password changes to Active Directory (if you wish to use midPoint for AD password changes). -. set your credentials mappings' lifecycle state to `Proposed` to allow simulations. - -Passwords may be also changed via Active Directory as usual (or both). - -Prepare / update outbound activation mapping(s) for your Active Directory: - -. to enable/disable Active Directory accounts based on midPoint user's Lifecycle state -. (optional) xref:/midpoint/reference/resources/resource-configuration/schema-handling/activation/#predefined-activation-mapping[configuration] for Disable instead of delete, Delayed delete etc. - if needed -. set your activation mappings(s') lifecycle state to `Proposed` to allow simulations. - -NOTE: midPoint authentication against Active Directory (or LDAP) is assumed for later steps. - -Then you can start your simulations: - -. Run the simulated _reconciliation_ task on AD resource using _Development_ configuration. -. Then have a look at the simulation results in midPoint GUI (interactively). -. Inspect the results: if midPoint would change existing attributes, states or even passwords in Active Directory or add new values, there should be a reason for, e.g.: policy vs data inconsistency, such as: -.. Active Directory attributes are incorrect/missing, midPoint attributes based on HR data are correct. -.. Active Directory attributes are correct, midPoint attributes based on HR data are incorrect -.. mappings have errors (you need to correct them) -. Fix data vs policy inconsistency by using one or several mechanisms: -.. let midPoint to override data in Active Directory -.. fix data in HR/midPoint and reimport the user(s) -.. adjust midPoint policies (e.g. outbound attribute mappings) -.. define exceptions for specific accounts (e.g. using marks) -.. escalate the situation to let someone help (or decide) -. Repeat the process until all simulated changes make sense and can be executed for real - -*When all the inconsistencies are resolved, you are prepared.* -You can turn on the provisioning: - -. Set all required outbound mappings including the mappings for activation and credentials to `Active` lifecycle state -. Run the simulated _reconciliation_ task on AD resource using _Production_ configuration -. Then have a look at the simulation results in midPoint GUI (interactively) one last time. -. Run the _reconciliation_ task on AD resource - -Your Active Directory resource is now configured. -Data inconsistency has been fixed. -Policy is defined, applied and will be followed from now on. -There is no automation between HR and midPoint yet, but we are already prepared for it. - -.Simulation notes -[NOTE] -==== -. When switching from `Proposed` to `Active` lifecycle state, use also simulation with _Production_ configuration before using the feature in real execution, if possible (usually when the real execution task is not yet running) - this is as close to the real task execution as possible. - -. When switching the configuration from `Proposed` to `Active` lifecycle state, be sure to switch all relevant configuration. Otherwise, you might see different behaviour when simulating with _Development_ configuration and _Production_ configuration / real task execution. - -. Try not to simulate several unrelated scenarios at the same time, otherwise switching just parts of the configuration from `Proposed` to `Active` lifecycle state may be challenging. You might see different behaviour when simulating with _Development_ configuration and _Production_ configuration / real task execution. - -==== - -You can continue to xref:automation/[Automation] step or return to xref:kick-off/[Kick-off] step. diff --git a/midpoint/methodology/first-steps/audience.adoc b/midpoint/methodology/first-steps/audience.adoc deleted file mode 100644 index 22807867b..000000000 --- a/midpoint/methodology/first-steps/audience.adoc +++ /dev/null @@ -1,68 +0,0 @@ -= First Steps With MidPoint: Audience -:page-nav-title: Audience -:page-display-order: 300 -//:page-toc: top -:experimental: - -This guide is targeted at an organization that fits following description: - -* Managing hundreds to thousands of identities. - -* Existing identity processes are mostly manual, possibly with some simple (home-brewed) automation (e.g. scripts or ancient identity management systems). - -* There is no dedicated identity management team. -Identity management tasks are executed by general IT staff, as part of their day-to-day responsibilities. -However, there is some basic understanding of identity management concepts in IT team. - -* No strict regulation compliance requirements. -Alternatively, there may be compliance requirements, yet addressing them is not immediate priority. - -* There is a motivation to improve identity management, with some support from the management and reasonable budget. - -* Typical organizations: mid-size enterprise, smaller government or academic institution, municipality - -This concept can be used also for other organizations and institutions, but its implementation may require more time and effort. - - -IT environment of the organization: - -* There is a feasible source of identity data, such as human resources (HR) system. -This source has authoritative data on most of the identities. -(There is no requirement for the data to be complete or 100% exact). -There is a simple way to get the data out of the system, such as structured text export (CSV), or a database view. - -* There is one "main" system that need to be managed, such as Active Directory. -Automatic management of identities in this system will provide significant benefits for the organization. -Also, there may be several such systems in the organization. - -* There are some operational procedures and conventions in place, such as a convention to systematically generate a username and e-mail address. -However, there are likely exceptions, e.g. e-mail address of top management, usernames generated before the convention was in place and so on. - -Which means that: - -* Quality of identity data is probably low. -The HR system was maintained manually, without any automated validation of the data. -There will be typos, outdated and incomplete data. -The accounts in Active Directory (or equivalent system) were managed manually, without any regular and automated checks. -There will be accounts that belonged to employees that left several years ago. -There will be accounts still using maiden names of women that got married years ago. -There will be non-conventional usernames and account names. - -* There are limited human resources that can be dedicated for identity management. -The implementation must proceed in parallel to the usual IT operation routines, requiring only a reasonable amount of effort. - -* The management will want to see tangible results quite soon. -Identity management deployment cannot be executed in a "big bang" way, spending years on analysis and implementation. - -* The ideal plan would be to proceed in iterations, providing value in small steps. -Each step taking several months, at most. - -.No free lunch -TIP: We live in a material world. -Money are needed to do almost anything. -Identity management is no exception. -Even though midPoint is an open source _platform_ and there are no licence costs or any other costs directly associated with use of midPoint, the identity management _deployment_ is not free. -You will need money to pay your staff, pay for trainings, assistance and support. -Reasonably-sized budget is needed to get tangible results. - -//Please see also xref:current-situation.adoc[] for more notes on the environment and assumption for which is this guide designed. diff --git a/midpoint/methodology/first-steps/automate-target-system-integration/automate-group-membership/hris-import-simul-devel-projection-entitlement-changed-luis-callahan.webp b/midpoint/methodology/first-steps/automate-target-system-integration/automate-group-membership/hris-import-simul-devel-projection-entitlement-changed-luis-callahan.webp new file mode 100644 index 000000000..49e1a2f6c Binary files /dev/null and b/midpoint/methodology/first-steps/automate-target-system-integration/automate-group-membership/hris-import-simul-devel-projection-entitlement-changed-luis-callahan.webp differ diff --git a/midpoint/methodology/first-steps/automate-target-system-integration/automate-group-membership/hris-import-simul-devel-projection-entitlement-changed-overview.webp b/midpoint/methodology/first-steps/automate-target-system-integration/automate-group-membership/hris-import-simul-devel-projection-entitlement-changed-overview.webp new file mode 100644 index 000000000..f38d9d518 Binary files /dev/null and b/midpoint/methodology/first-steps/automate-target-system-integration/automate-group-membership/hris-import-simul-devel-projection-entitlement-changed-overview.webp differ diff --git a/midpoint/methodology/first-steps/automate-target-system-integration/automate-group-membership/index.adoc b/midpoint/methodology/first-steps/automate-target-system-integration/automate-group-membership/index.adoc new file mode 100644 index 000000000..ecc961cb7 --- /dev/null +++ b/midpoint/methodology/first-steps/automate-target-system-integration/automate-group-membership/index.adoc @@ -0,0 +1,195 @@ += Automate target resource group membership +:page-nav-title: Automate group membership +:page-display-order: 430 +:page-toc: top +:experimental: +:icons: font +:page-description: Configure the Person archetype to induce AD group membership entitlement for all users coming from the HRIS. + +Usually, users of a certain category, such as employees, contractors, etc., are assigned to certain groups by default. +In this guide, we do not really work with roles and have users of only one category (_Person_ archetype), but all users are in the _all-users_ group in Active Directory. +You have already automated username creation and Active Directory provisioning for new users. +It is time now to make sure new users also get assigned to the universal group in which all users should be. + +== What awaits you in this module + +To assign new users to a group automatically, you will take these steps: + +. Create an _AD Group_ resource object type in the Active Directory resource. +. Create an association between the _AD Group_ and AD resource accounts. +. Create an association construction in the _Person_ archetype to grant the group membership to the users of the _Person_ archetype. +. Reconcile the HRIS resource accounts so that users get recomputed and all are assigned to the group automatically. + +[NOTE] +==== +If you use the Docker images prepared for this guide, most of the settings are already preconfigured. +Follow the steps in this module and review the settings to understand how the group assignment works. +==== + +:sectnums: + +== Create object type for user groups + +In midPoint, groups of users (or any other identities, such as printers) are represented by object types of the _entitlement_ kind. +When a user is added to a group, it means the account of the user is _associated_ with the entitlement object type. + +Firstly, you need to create the group entitlement object type in the AD resource schema handling. + +. In [.nowrap]#icon:database[] *Resources*# > [.nowrap]#icon:database[] *All resources*#, open the AD resource. +. In [.nowrap]#icon:exchange-alt[] *Schema handling*#, click [.nowrap]#icon:circle-plus[] btn:[Add object type]#. +. *Basic information about the object type* screen: + ** *Display name*: e.g., _AD Group_ + ** *Kind*: _Entitlement_ + ** *Intent*: e.g., _adgroup_ + ** *Default*: _True_ +. *Specify the resource data* screen: + ** *Object class*: _groupOfNames_ +. *Specify the midPoint data* screen: + ** Leave unchanged +. Click [.nowrap]#icon:check[] btn:[Save settings]# +. Click btn:[Back to object types]. + +[NOTE] +==== +The new object type is in the _Active_ lifecycle state by default. +You can leave it at that because you will create the association part of the configuration in the _Proposed_ state, +meaning the xref:/midpoint/methodology/first-steps/automate-target-system-integration/generate-usernames-in-midpoint/#automate-importing-users-to-midpoint[recurring HRIS import task] you have set up earlier will not pick up your new configuration until you _activate_ the association. +==== + +== Associate AD accounts with the group + +With the entitlement for the group ready, you need create an association between the entitlement and user accounts. +In short, the association definition tells midPoint the following: + +* With what to associate the resource accounts (the group). +* In which direction the association works (object to subject, i.e., the group contains list of accounts belonging to the group). +* Which entitlement object attribute (i.e., which attribute of the group) holds the list of subjects, i.e., the accounts. +* Which subject attribute (i.e., which attribute of the account) to use in the list of subjects belonging to the group—in our case, it is the distinguished name (`dn`). + +[TIP] +==== +It is worth noting that when you associate accounts to an entitlement, nothing is written neither into the account shadows, nor their respective focal objects. +It is the entitlement resource object that holds the membership information and midPoint pulls this information from the remote system (e.g., Active Directory) whenever needed (and caches the information if configured to do so). + +Learn more: xref:/midpoint/reference/resources/entitlements/[] +==== + +To add the association: + +. In the target resource, go to [.nowrap]#icon:male[] *Accounts*#. +. Click [.nowrap]#icon:cog[] btn:[Configure]# and select [.nowrap]#icon:shield[] *Associations*#. +. Click [.nowrap]#icon:circle-plus[] btn:[Add association]#. +. Fill in the form fields to define the association: + ** *ref*: The name of the entitlement object you have created earlier: _adGroup_ + ** *Display name* A human-friendly for the association: e.g., _AD Group Membership_ + ** *Kind*: _Entitlement_ + ** *Intent*: _adGroup_ + ** *Direction*: _Object to subject_ + *** In this case, the entitlement object holds a list of members, i.e., subjects. + ** *Association attribute*: : _member_ + *** Declares which attribute in the entitlement object holds the member list. + *** This value depends on the remote resource attribute naming. + ** *Value attribute*: _dn_ + *** Declares which account attribute to store in the association attribute of the entitlement object + *** This value depends on the remote resource attribute naming. + ** *Lifecycle state*: _Proposed_ +. Click [.nowrap]#icon:check[] btn:[Save association settings]# to save your changes. + +.Association of AD accounts with the all-users group +image::ldap-adgroup-association.webp["Association of AD account with the all-users group"] + +== Grant all _Persons_ membership in the group + +In this guide, we do not use roles; however, it is necessary to have some key to determine which accounts are entitled to the group membership. +Normally, user roles would be the key. +Here, instead of roles, we can use archetypes for the classification: +Only accounts of the _Person_ archetype are eligible for the group membership. + +To achieve this, you need to induce the entitlement in the _Person_ archetype: + +. In [.nowrap]#++++++ *Archetypes*# > [.nowrap]#++++++ *All archetypes*#, open the _Person_ archetype for editing. + ** You can filter archetypes by *Name*. +. In [.nowrap]#icon:circle[] *Inducements*# > [.nowrap]#icon:database[] *Resource*#, select the *Construction Associations* tab. +. Click [.nowrap]#icon:plus[] btn:[New]# to add a new association. +. In the modal that appears, select the group entitlement: _cn=all-users,ou=groups,dc=example,dc=com_. + ** You may need to click [.nowrap]#icon:rotate-right[] btn:[Reload]# to refresh the list if you do not see the desired entitlement. +. Click btn:[Done] to save the settings. +. Click btn:[Done] in the Construction Associations tab to save the settings. +. Click [.nowrap]#icon:save[] btn:[Save]# in the top toolbar to save the archetype configuration. + +.Select the group to entitle the Person archetype-related accounts to the group membership +image::ldap-person-archetype-association-grant-entitlement.webp["Select the group to entitle the Person archetype-related accounts to the group membership"] + +== Verify your configuration + +To test the new configuration, you need to reconcile the accounts. +You can either reconcile the source HRIS accounts or the target AD ones, the simulation results will be the same regardless, because the induced entitlement comes from the _Person_ archetype which is "above" the resources. +We suggest simulating on the HRIS, though, because it is the HRIS application from which you import users to midPoint. + +Firstly, xref:/midpoint/reference/tasks/synchronization-tasks/import-and-reconciliation/gui/#simulate-import-of-a-single-object[import preview] a single user with `empnum` 90XX (those are the xref:/midpoint/methodology/first-steps/automate-target-system-integration/generate-usernames-in-midpoint/#add-new-users-to-hris-to-test-username-generation[new users you have added to HRIS] when testing the Active Directory provisioning). +After the import preview finishes, inspect the results and verify the results are as expected. + +.Import preview of Luise Callahan in the HRIS resource, showing the projection entitlement would change for the resource object +image::hris-import-simul-devel-projection-entitlement-changed-luis-callahan.webp["Import preview in HRIS of Luise Callahan, showing the projection entitlement would change for the resource object"] + +Once you verify the configuration works as expected on one user, create and run a simulated reconciliation task in the HRIS resource. + +*Follow this guide: xref:/midpoint/reference/tasks/synchronization-tasks/import-and-reconciliation/gui/[]* + +. In the HRIS resource, create a new *reconciliation* task with the *simulation* toggle on. +. Name it, e.g., _HR Reconciliation - development simulation_. +. Select the _Preview_ mode with the _Development_ configuration in the Execution screen. +. Save the task and run it. + +When the reconciliation simulation task finishes, review its results: +Only the 90XX-series accounts you have added earlier should be affected. +The only change should be the addition of entitlements on the AD resource objects. + +.The HRIS resource import simulation task results overview shows five resource objects would be changed due to the group membership assignment +image::hris-import-simul-devel-projection-entitlement-changed-overview.webp["HRIS resource import simulation task results overview"] + +== Put the configuration to production + +Once you verify the group is assigned to the new 90XX-series users and nothing else changes (as it should not), you can _activate_ the configuration. + +To activate the configuration on production, trace back your steps and make sure every new piece you have added is in the _Production_ lifecycle state: + +. The new AD resource object type for entitlements. + ** Go to the AD resource > [.nowrap]#icon:exchange[] *Schema handling*# and ensure the _AD Group_ entitlement is _active_. +. The association between the entitlement and user accounts. + ** In the AD resource > [.nowrap]#icon:male[] *Accounts*# > [.nowrap]#icon:cog[] btn:[Configure]# > [.nowrap]#icon:shield[] *Associations*#, ensure the association is _active_. +. The construction association in the _Person_ archetype resource inducement. + ** You do not need to do anything here because the archetype is already _active_ and the association construction does not have its own lifecycle. + +Once all is _active_, wait for the xref:/midpoint/methodology/first-steps/automate-target-system-integration/generate-usernames-in-midpoint/#automate-importing-users-to-midpoint[recurring HRIS reconciliation task] to pick up the accounts and process them. +After it finishes, you can verify the results in two places: + +. In the link:http://localhost/phpldapadmin/[AD server web UI]. ++ +.The all-users group member list in the AD user interface. The new users are shown at the bottom. +image::ldap-ui-all-users-group.webp["The all-users group member list in the AD user interface. The new users are shown at the bottom."] + +. In [.nowrap]#icon:user[] *Users*# > [.nowrap]#icon:user[] *Persons*#, + where you open one of the new users for inspection, go to [.nowrap]#icon:male[] *Projections*#, select the AD projection, and look into the *Associations* section. + ++ +.The projections screen in Luise Callahan's user profile in midPoint showing the user is a member of the all-users group on AD +image::ldap-user-lcallahan-association-ad-group-membership.webp["The projections screen in Luise Callahan's user profile in midPoint showing the user is a member of the all-users group in AD"] + +:sectnums!: + +== Next steps + +Now that you have a complete target resource provisioning configuration, it is time to think about consistency management. +In the beginning, you have decided that the HR information system is your single source of truth (SSoT). +That means the data in all midPoint-managed applications should be consistent with what is in the HRIS. + +You have configured your midPoint deployment with that in mind and gradually took steps to harmonize the HRIS and AD data. +It is now the time to confirm that the setup enforces data consistency across the connected applications even in case of nefarious changes and considers the HRIS as the SSoT. + +[.nowrap]#icon:arrow-right[] *xref:/midpoint/methodology/first-steps/verify-configuration-behavior/rectify-unauthorized-changes-on-target-resource/[]*# + +.When you are through the basics… +[TIP] +==== +Should you want to pursue more complex group membership configurations, take the link:https://evolveum.com/training-and-certification/midpoint-deployment-group-synchronization-self-paced/#evo_training_description[MidPoint Deployment: Group Synchronization] group after you finish this First steps guide. +==== \ No newline at end of file diff --git a/midpoint/methodology/first-steps/automate-target-system-integration/automate-group-membership/ldap-adgroup-association.webp b/midpoint/methodology/first-steps/automate-target-system-integration/automate-group-membership/ldap-adgroup-association.webp new file mode 100644 index 000000000..b470ba675 Binary files /dev/null and b/midpoint/methodology/first-steps/automate-target-system-integration/automate-group-membership/ldap-adgroup-association.webp differ diff --git a/midpoint/methodology/first-steps/automate-target-system-integration/automate-group-membership/ldap-person-archetype-association-grant-entitlement.webp b/midpoint/methodology/first-steps/automate-target-system-integration/automate-group-membership/ldap-person-archetype-association-grant-entitlement.webp new file mode 100644 index 000000000..3387178fe Binary files /dev/null and b/midpoint/methodology/first-steps/automate-target-system-integration/automate-group-membership/ldap-person-archetype-association-grant-entitlement.webp differ diff --git a/midpoint/methodology/first-steps/automate-target-system-integration/automate-group-membership/ldap-ui-all-users-group.webp b/midpoint/methodology/first-steps/automate-target-system-integration/automate-group-membership/ldap-ui-all-users-group.webp new file mode 100644 index 000000000..6c9a203be Binary files /dev/null and b/midpoint/methodology/first-steps/automate-target-system-integration/automate-group-membership/ldap-ui-all-users-group.webp differ diff --git a/midpoint/methodology/first-steps/automate-target-system-integration/automate-group-membership/ldap-user-lcallahan-association-ad-group-membership.webp b/midpoint/methodology/first-steps/automate-target-system-integration/automate-group-membership/ldap-user-lcallahan-association-ad-group-membership.webp new file mode 100644 index 000000000..453b6acb0 Binary files /dev/null and b/midpoint/methodology/first-steps/automate-target-system-integration/automate-group-membership/ldap-user-lcallahan-association-ad-group-membership.webp differ diff --git a/midpoint/methodology/first-steps/automate-target-system-integration/automate-target-resource-account-creation/index.adoc b/midpoint/methodology/first-steps/automate-target-system-integration/automate-target-resource-account-creation/index.adoc new file mode 100644 index 000000000..9e7166a83 --- /dev/null +++ b/midpoint/methodology/first-steps/automate-target-system-integration/automate-target-resource-account-creation/index.adoc @@ -0,0 +1,72 @@ += Automate target resource account creation +:page-nav-title: Automate account creation +:page-display-order: 420 +:page-toc: top +:experimental: +:icons: font +:page-description: Ensure every user gets an AD account automatically by creating an inducement in the Person archetype. + +At this point of your journey, your midPoint configuration can automatically generate usernames and passwords, +and source HRIS accounts are automatically synchronized into midPoint. +In the setup we use in this guide, every _Person_ should have an account in Active Directory. +However, there is no automation for that yet, so the new users you have added in the previous module do not have an AD account. +You are going to address that in this module. + +== What awaits you in this module + +You will configure midPoint so that every user of the _Person_ archetype automatically gets an Active Directory account. + +Typically, resource provisioning is based on roles or organizations user has or belongs to. +But since you do not manage any of that in midPoint yet, you have to make use of something else: +Every HRIS user account is of the _Person_ archetype. +You will use the _Person_ archetype to _induce_ AD accounts as a *birthright* of every user imported from the HRIS. + +To give users of the _Person_ archetype this birthright, you will *add a new inducement to the _Person_ archetype* that will _cause_ creation and ownership of an AD account. + +[TIP] +==== +Learn more about inducements, how they work and how they differ from other similar concepts in midPoint: xref:/midpoint/architecture/concepts/inducement-assignment-entitlement/[] +==== + +:sectnums: + +== Add inducement to the Person archetype + +. In [.nowrap]#++++++ *Archetypes*# > [.nowrap]#++++++ *All archetypes*#, open the _Person_ archetype for editing. + ** You can filter archetypes by *Name*. +. In [.nowrap]#icon:circle[] *Inducements*# > [.nowrap]#icon:database[] *Resource*#, click [.nowrap]#++++++ btn:[New]#. +. Select your target resource. +. Click btn:[Next: Resource object type]. +. Keep the selected *Default for kind: Account* and click btn:[Next: Entitlements]. +. Do not make any changes and click btn:[Next: Mappings] to continue. +. Do not add any mappings. +. Click [.nowrap]#icon:check[] btn:[Save settings]# to save the configuration. + +.Active Directory account inducement in the Person archetype +image::person-archetype-ldap-inducement.webp["Active Directory account inducement in the Person archetype"] + +== Let scheduled HRIS reconciliation ensure provisioning + +You have added an entitlement to the _Person_ archetype ensuring all _Person_-archetype users have an AD account. + +Wait until the next run of the xref:/midpoint/methodology/first-steps/automate-target-system-integration/generate-usernames-in-midpoint/#automate-importing-users-to-midpoint[scheduled HRIS reconciliation task] finishes and check the results. +The new users of the 900X series you have added in the previous module now should have their AD accounts active. +Verify that in the link:http://localhost/phpldapadmin/[AD server web UI]. + +.List of AD accounts including the new accounts created in HRIS +image::ldap-new-accounts-created-from-hris.webp["List of AD accounts on the AD server including the new accounts created in HRIS"] + +You can also check the result when you open one of the new users in [.nowrap]#icon:male[] *Users*# > [.nowrap]#icon:male[] *Persons*# and see their [.nowrap]#icon:male[] *Projections*#. + +.The new user Andreas Baker has both the HRIS and AD projections +image::person-with-HRIS-and-AD-projections.webp["The new user Andreas Baker has both the HRIS and AD projections"] + +:sectnums!: + +== Next steps + +With the steps above completed, you have automated provisioning target resource accounts for all people you manage in midPoint. + +The next step is to have all new accounts automatically assigned to the group in which all users are. + +[.nowrap]#icon:arrow-right[] *xref:/midpoint/methodology/first-steps/automate-target-system-integration/automate-group-membership/[]*# \ No newline at end of file diff --git a/midpoint/methodology/first-steps/automate-target-system-integration/automate-target-resource-account-creation/ldap-new-accounts-created-from-hris.webp b/midpoint/methodology/first-steps/automate-target-system-integration/automate-target-resource-account-creation/ldap-new-accounts-created-from-hris.webp new file mode 100644 index 000000000..1b9e64bd6 Binary files /dev/null and b/midpoint/methodology/first-steps/automate-target-system-integration/automate-target-resource-account-creation/ldap-new-accounts-created-from-hris.webp differ diff --git a/midpoint/methodology/first-steps/automate-target-system-integration/automate-target-resource-account-creation/person-archetype-ldap-inducement.webp b/midpoint/methodology/first-steps/automate-target-system-integration/automate-target-resource-account-creation/person-archetype-ldap-inducement.webp new file mode 100644 index 000000000..08a9d4d42 Binary files /dev/null and b/midpoint/methodology/first-steps/automate-target-system-integration/automate-target-resource-account-creation/person-archetype-ldap-inducement.webp differ diff --git a/midpoint/methodology/first-steps/automate-target-system-integration/automate-target-resource-account-creation/person-with-HRIS-and-AD-projections.webp b/midpoint/methodology/first-steps/automate-target-system-integration/automate-target-resource-account-creation/person-with-HRIS-and-AD-projections.webp new file mode 100644 index 000000000..ed10fb45c Binary files /dev/null and b/midpoint/methodology/first-steps/automate-target-system-integration/automate-target-resource-account-creation/person-with-HRIS-and-AD-projections.webp differ diff --git a/midpoint/methodology/first-steps/automate-target-system-integration/generate-usernames-in-midpoint/hris-persons-with-jsmith82-usernames.webp b/midpoint/methodology/first-steps/automate-target-system-integration/generate-usernames-in-midpoint/hris-persons-with-jsmith82-usernames.webp new file mode 100644 index 000000000..c3023432c Binary files /dev/null and b/midpoint/methodology/first-steps/automate-target-system-integration/generate-usernames-in-midpoint/hris-persons-with-jsmith82-usernames.webp differ diff --git a/midpoint/methodology/first-steps/automate-target-system-integration/generate-usernames-in-midpoint/hris-preview-import-with-jsmith82-username.webp b/midpoint/methodology/first-steps/automate-target-system-integration/generate-usernames-in-midpoint/hris-preview-import-with-jsmith82-username.webp new file mode 100644 index 000000000..fd135e4a3 Binary files /dev/null and b/midpoint/methodology/first-steps/automate-target-system-integration/generate-usernames-in-midpoint/hris-preview-import-with-jsmith82-username.webp differ diff --git a/midpoint/methodology/first-steps/automate-target-system-integration/generate-usernames-in-midpoint/index.adoc b/midpoint/methodology/first-steps/automate-target-system-integration/generate-usernames-in-midpoint/index.adoc new file mode 100644 index 000000000..b35e239ec --- /dev/null +++ b/midpoint/methodology/first-steps/automate-target-system-integration/generate-usernames-in-midpoint/index.adoc @@ -0,0 +1,188 @@ += Generate usernames in midPoint for new users +:page-nav-title: Generate usernames in midPoint +:page-display-order: 410 +:page-toc: top +:experimental: +:icons: font +:page-description: Configure midPoint to generate jsmith82 usernames automatically and automate HRIS reconciliation. +// This redirect is here to move visitors directly to the first child of the section +:page-moved-from: /midpoint/methodology/first-steps/automate-target-system-integration/ + +Up until now, you sourced usernames from the target Active Directory application. +This approach works well for existing accounts that already have the username populated in Active Directory. +But what about new users? +Once the HR department registers a new user in the HRIS, the account arrives to midPoint, but it has no place from which to obtain the username. + +Let us change that. +Similarly to passwords, midPoint can generate usernames as well. +The difference here is that passwords are random strings, while usernames consist, typically, of the first and last names and possibly some numbers. +For this reason, you are going to use a script for this task. + +== What awaits you in this module + +To generate usernames, you will: + +. Archive both the HRIS and AD inbound mappings for the `name` attribute as they will not be needed any longer. +. Use the Person object template to define a new mapping for username generation. + The mapping will be _weak_ so that it does not overwrite existing values. +. Create new users in the source HRIS resource. +. Use a simulated import to check whether the username generation works correctly. +. Create a recurring HRIS reconciliation task to import new users automatically on regular basis. + +When you are done, you will have automated generation of usernames that are link:https://learn.microsoft.com/en-us/windows/win32/adschema/a-samaccountname[sAMAccountName]-compatible, and set up an interval-based recurring reconciliation task to import the HRIS accounts without a human operator like you needing to import the users manually. + +:sectnums: + +== Archive obsolete mappings + +In the beginning, you have used the `empnum` containing employee number from the HR source system as a unique value for the _name_ attribute (which needs to be unique as per midPoint requirements). +Later on, after you have connected Active Directory, you have replaced it with `uid` which contains usernames, at least in our example training data. + +However, you have already reconciled all the pre-existing users so there is no need for either of the mappings because they would be useless for new users. +This means you can archive them. + +To archive the HRIS mapping: + +. Go to the source HRIS resource > [.nowrap]#icon:male[] *Accounts*# > mapping configuration. +. In [.nowrap]#icon:arrow-right-to-bracket[] *Inbound*# mappings, find the _empnum-to-name_ mapping that copies the `empnum` attribute from the HRIS to the focal object `name` attribute. +. Set its *Lifecycle state* to _Archived_. + +When done, do exactly the same with the _inbound-uid-username-to-name_ AD mapping you used to copy the AD usernames in `uid` to the `name` focus attribute in midPoint. + +[TIP] +==== +We use the _Archived_ lifecycle state here to indicate that the mapping is unlikely to be active again. +For temporary mapping deactivation, you could use the _Suspended_ state. +All _Archived_, _Suspended_, and _Draft_ states represent deactivation and configurations in these states are not used, +but midPoint has those three states to express different reasons for deactivation. +Refer to xref:/midpoint/reference/concepts/object-lifecycle/[] for more information on the topic. +==== + +== Add username mapping to Person object template + +Object template is a configuration object in midPoint you can use to run mappings whenever a focal object, such as a user, is created or updated in midPoint. + +Refer to xref:/midpoint/reference/expressions/object-template/[] and xref:/midpoint/reference/schema/archetypes/person/[] for more details. + +The Person object template already contains out-of-the-box a mapping to generate a full name. +You have seen it in action when you assigned the Person archetype to users imported from the HRIS. + +What you are after now is a mapping that would take the given name and surname, and generate a username in the _jsmith82_ format that conforms to the Active Directory sAMAccountName restrictions. +Such a username consists of the first letter from the given name, concatenates it with the surname, and takes 8 characters from the result. +Moreover, if the result is not unique in the system (e.g., _Alice Baker_ and _Andrew Baker_ result both in _abaker_), the username is to contain up to two digits to become unique. +It is a usual to start with the number iterator at _2_ to make the usernames more human friendly and intuitive: _abaker_, _abaker2_, _abaker3_, … + +.Person object template mapping to generate jsmith82-style usernames +image::person-object-template-mapping-generate-jsmith82-username.webp["Person object template mapping to generate jsmith82-style usernames"] + +To add a new mapping to generate the _jsmith82_ usernames: + +. In [.nowrap]#icon:file-alt[] *Object templates*# > [.nowrap]#icon:file-alt[] *All object templates*#, select *Person Object Template*. +. In [.nowrap]#icon:circle[] *Mappings*#, click [.nowrap]#icon:plus[] btn:[New]# to create a new mapping. + ** If you use the preconfigured Docker images for this guide, the username mapping is already there. + Inspect it to see how it works. +. *Name* the mapping, e.g., _generate-name-jsmith-8-2_. +. Set *Strength* to _weak_ so that the mapping does not overwrite existing usernames. +. Set *Lifecycle state* to _Active_. + ** You can safely activate the mapping for it is _weak_ and will never overwrite existing values. +. Select _givenName_ and _familyName_ from _Focus_ in *Source*. +. Set the *expression* to _Script_. + ** See the script below. +. Set *Target* to _name_ as that is the uniquely identifying attribute for focal objects (users). +. Click btn:[Done] in the mapping details and [.nowrap]#icon:save[] btn:[Save]# in the overview screen to save your settings. + +.The script to use for generating jsmith82 usernames +[source,groovy] +---- +tmpGivenName = basic.trim(basic.norm(basic.stringify(givenName))) <1> +tmpFamilyName = basic.trim(basic.norm(basic.stringify(familyName))) <1> +tmpGivenNameInitial = tmpGivenName?.take(1) <2> +return (tmpGivenNameInitial + tmpFamilyName?.replaceAll(" ", ""))?.take(8) + iterationToken <3> +---- +<1> Take the xref:/midpoint/reference/schema/polystring-normalization/[normalized version of the name string] and remove leading and trailing white characters using `trim()`. +<2> Truncate the first name only to one character. This is safe even if `firstName` is empty, but it cannot be null. +<3> Concatenate the first name initial with the surname, shorten the result to 8 characters if needed, remove white spaces, and add the xref:/midpoint/reference/concepts/iteration/[iteration token]. + +== Add new users to HRIS to test username generation + +With the object template mapping ready, it is time to put it to test. +Create new users in your source HR information system and import them to midPoint. + +If you use the training Docker images prepared for this guide, use the link:http://localhost/hr/[Demo HR app web interface]. +Otherwise, register new users to your own source system; you can use the data from below for inspiration. +The instructions below are for the Demo HR app. + +. In the Demo HR app, click btn:[Register user] at the top of the screen. +. Fill in the values according to the table below. +. Add each user by clicking btn:[Register user] beneath the form. +. Once you add all users, click btn:[Export users to CSV file] at the bottom of the user list screen to export the users. + +.Users to be added +[cols="h,5*"] +|======================================================================================================= +| First name | Louise | Andreas | Clara | Clara | Jacques +| Surname | Callahan | Baker | Whiteherring | Whiteherring | Smith +| Employee number | 9000 | 9001 | 9002 | 9003 | 9004 +| Locality 5+^| White Stone City +| Job 5+^| 222#Export/Import Coordinator +| EmpType 5+^| FTE +| Status 5+^| In +|======================================================================================================= + +== Simulate importing new users to midPoint + +Before you put the new configuration to production, verify it works using simulations. + +Perform an import preview of a single user. +You can repeat the preview import for multiple new users. + +*Follow this guide: xref:/midpoint/reference/tasks/synchronization-tasks/import-and-reconciliation/gui/#simulate-import-of-a-single-object[]* + +Once the import finishes, observe the _name_ attribute being filled in with a proper username instead of the employee number. + +.Result of preview import operation showing successfully generated username +image::hris-preview-import-with-jsmith82-username.webp["Result of preview import operation showing successfully generated username"] + +== Automate importing users to midPoint + +After you verify generating the usernames works, import the users to midPoint for real. +You will create a recurring reconciliation task in order to automate the whole process. +A reconciliation task is more suitable than import because it is going to handle removed users as well. + +*Follow this guide: xref:/midpoint/reference/tasks/synchronization-tasks/import-and-reconciliation/gui/[]* + +. In the HRIS resource, create a new *reconciliation* task with the *simulation* toggle off. +. Name it, e.g., _HR Reconciliation_. +. Set the schedule interval to, e.g., 60 seconds. + ** This makes the task automated, running every 60 seconds. + Every time new accounts appear in the source CSV, they get automatically imported to midPoint. + In a real scenario, you would probably set the interval to minutes or hours, depending on the amount of identities you would be managing. +. Save the task and run it. + +Wait until the task finishes its first run and head over to [.nowrap]#icon:user[] *Users*# > [.nowrap]#icon:user[] *Persons*# +to see the newly added users and their generated jsmith82-style usernames. + +You can filter them out, e.g., by the employee number (mapped to `personalNumber`) using the advanced filter like this: + +.Query to filter users by their `personalNumber` attribute +[source, groovy] +---- +personalNumber startsWith '900' +---- + +.Newly imported users in the HRIS resource with jsmith82-style usernames generated by midPoint +image::hris-persons-with-jsmith82-usernames.webp["Users newly imported to the HRIS resource with jsmith82-style usernames generated by midPoint"] + +// Lab 8-1 also mentions looking into the audit log viewer to see what midPoint did. This could be covered in an article on reading audit logs. @dakle 2025-11-12 + +:sectnums!: + +== Next steps + +You have automated sAMAccountName-compatible username generation. +You have also automated reconciliation of the source HR application with midPoint, +which means that every time a user is created in and exported from the HRIS, the account is imported to midPoint as well. + +The next step is to ensure that every person in midPoint has an account in Active Directory provisioned automatically. + +[.nowrap]#icon:arrow-right[] *xref:/midpoint/methodology/first-steps/automate-target-system-integration/automate-target-resource-account-creation/[]*# \ No newline at end of file diff --git a/midpoint/methodology/first-steps/automate-target-system-integration/generate-usernames-in-midpoint/person-object-template-mapping-generate-jsmith82-username.webp b/midpoint/methodology/first-steps/automate-target-system-integration/generate-usernames-in-midpoint/person-object-template-mapping-generate-jsmith82-username.webp new file mode 100644 index 000000000..9496c34d2 Binary files /dev/null and b/midpoint/methodology/first-steps/automate-target-system-integration/generate-usernames-in-midpoint/person-object-template-mapping-generate-jsmith82-username.webp differ diff --git a/midpoint/methodology/first-steps/automate-target-system-integration/index.adoc b/midpoint/methodology/first-steps/automate-target-system-integration/index.adoc new file mode 100644 index 000000000..480759e86 --- /dev/null +++ b/midpoint/methodology/first-steps/automate-target-system-integration/index.adoc @@ -0,0 +1,7 @@ += Automate target system provisioning +:page-nav-title: 5. Automate provisioning +:page-display-order: 400 +:experimental: +:icons: font + +This is a placeholder page immediately redirected to the first article in the section. \ No newline at end of file diff --git a/midpoint/methodology/first-steps/automation.adoc b/midpoint/methodology/first-steps/automation.adoc deleted file mode 100644 index 69a76e0c6..000000000 --- a/midpoint/methodology/first-steps/automation.adoc +++ /dev/null @@ -1,134 +0,0 @@ -= Methodology: First Steps With MidPoint: Automation -:page-nav-title: 'Automation' -:page-display-order: 120 -:page-toc: top -:experimental: - - - -.Goal -TIP: Make on-boarding and off-boarding processes more efficient and reliable. -Save some money and improve efficiency by speeding up the processes. -However, the most important goal is enabled by _reliability_ of the automated processes. -Accounts belonging to off-boarded people are automatically disabled. -Orphaned accounts are reliably detected. -The most severe identity-related risks are addressed. - - -Finally, we have reliable data to build on. -What are we waiting for? - -.User lifecycle -NOTE: We have user lifecycle figured, and partially implemented/pre-configured at this step. -The lifecycle management starts with HR import. -But this is the point where it has to work well. - -== Username Generation - -We have previously imported all existing Active Directory usernames which became midPoint usernames. -Now it's time to prepare automation for this step. - -You can see this step in action in the First Steps Methodology webinar video: - -video::suo775ym_PE[youtube,title="Step 8: Automate Integration",start="3626"] - -. Disable (or remove) the inbound mapping in HR resource which populates midPoint username -. Disable (or remove) the inbound mapping in Active Directory resource which populates midPoint username -. Choose and activate (or create your own) username mapping in `Person Object Template` (object template for `Person` archetype) which will generate username based on given name and family name (e.g. `jsmith`, resolving duplicate usernames with suffixes, e.g. `jsmith2`) -+ -TIP: The mapping can be used for `sAMAccountName` as it keeps the username under 20 characters (actually 8 + 2 digits for iterator) -. Keep this mapping _weak_. Usernames should never automatically change. - -The new username policy is active from now on: for all new users created in the future. - -.Naming convention notes -[NOTE] -==== -Make sure your naming convention is good enough to not collide with existing AD/LDAP accounts (or other objects) that won't be imported to midPoint. -These include orphaned accounts that won't be imported (but still exist), system accounts etc. - -In case of collision, you may want to rename such accounts in AD/LDAP or the colliding users in midPoint manually. - -In case you would like to have more automated solution, you may want to create your own naming convention that avoids duplicate usernames in midPoint as well as in AD/LDAP by doing an additional check against AD/LDAP when generating midPoint username. -==== - -If your HR source already contains new records which have not yet been imported to midPoint, you can use the following mechanisms to double-check the username generator before going live: - -* single HR account Import with preview action (_Production_ configuration) -* simulated HR import task (_Production_ configuration) - -== On-Boarding Automation (Provisioning) - -In this step, turn on the on-boarding automation for the joiners and automatic account updates for existing users. - -*This is the right time to suspend your legacy on-boarding/provisioning process (e.g. scripts or manual processes).* -If the accounts will be also updated by system other-than-midPoint, the behaviour in midPoint can be set as "tolerant" for the account attributes which may be still managed by other solution(s), e.g. access rights managed by request/approve process using tickets etc. -After the access right management is moved to midPoint, this tolerance should be turned off. - -Until any roles are created and conditions for their automatic assignment are defined, the on-boarding automation may simply create accounts in Active Directory for all people from HR with the help of `Person` archetype we assign to everyone upon import from HR: - -. Edit *Person* archetype -. Add inducement for Active Directory resource account for all users with Person archetype -. Create scheduled reconciliation task for HR resource - -TIP: We can also add Active Directory accounts to pre-existing groups, e.g. general "all users" group using the same *Person* archetype and group association for AD account to implement the concept of _birthrights_ in midPoint. - -== Off-Boarding Automation (Deprovisioning) - -The automation between HR and midPoint covers on-boarding as well as off-boarding as data is transferred from HR to midPoint and then from midPoint to Active Directory. - -Temporarily inactive HR persons (their xref:/midpoint/reference/concepts/object-lifecycle/[Lifecycle state] in midPoint is `suspended`) will be disabled in Active Directory. - -Former employees will be disabled in midPoint and their Active Directory (possibly other in the future) accounts will be deleted after a defined time (e.g. 6 months). -Former employees will be kept in midPoint indefinitely (their xref:/midpoint/reference/concepts/object-lifecycle/[Lifecycle state] in midPoint is `archived`). - -== Incorrect Data Overrides - -HR data is usually authoritative, but not ideal. -There might be mistakes in data (typos) or even in person states. -Such errors are usually spotted by end users or target system administrators and should be fixed in the source system. -Sometimes, however, the fix must be done in the provisioning system - either because we need the fix _fast_ or because some data is constructed by midPoint _based_ on data in HR that will not change just because the end user requires it - this is for example how username is generated. - -The data overrides fall into the following categories: - -. *source system user status is incorrect - user must be disabled*: -this happens in case of malicious employees. We need to disable user's access _now_, without waiting for data in HR to be updated and synchronized. MidPoint computes its `lifecycleState` from HR data (and all target system accounts states based from midPoint `lifecycleState`). We need to disable user by using special midPoint property: *Administrative status: Disabled*. User and his/her accounts will be immediately disabled. If the user is cleared from all suspicions, administrator may revert to the original xref:/midpoint/reference/concepts/object-lifecycle/[lifecycle state] by removing the Administrative status override. - -. *source system user status is incorrect - user must be enabled*: -this happens in case that HR incorrectly stores user's status as inactive, but the user should be working normally. Administrative status override cannot be currently used for the _positive_ override; we need to use something else. We will xref:/midpoint/reference/concepts/mark/[mark] user's HR account as "Invalid data" and then change user's xref:/midpoint/reference/concepts/object-lifecycle/[Lifecycle state] in midPoint. From now on, the HR data are no more synchronized for the user. After HR fixes their data, administrator may revert these steps. - -. *source system data is incorrect*: -this is a simpler version of the previous. Data in HR is incorrect, so administrator can xref:/midpoint/reference/concepts/mark/[mark] user's HR account as "Invalid data" and fix data directly in midPoint. From now on, the HR data are no more synchronized for the user. After HR fixes their data, administrator may revert these steps. - -. *username change*: -usually the username is never automatically changed, in some environments, it is actually _never_ changed. -But there might be situations when user _insists_ on username change, e.g. because the generated username is inappropriate or even offensive. This cannot be influenced by HR data as username is generated in midPoint. So the quick action is simply to change the username property of midPoint user. Such a change will be automatically propagated to the target systems (so the Active Directory username will change too). -+ -TIP: We recommend to use username change with extreme care. - -== Follow-Up Steps - -Your follow-up steps can differ based on your requirements and their priorities. -They can include: - -* link:https://docs.evolveum.com/midpoint/methodology/first-steps/multiple-sources/[*Add additional source system*] e.g. for additional populations - -* *Add additional target system* using this methodology (without username import) - -* *Automate scans* for orphaned accounts in Active Directory with automatic reaction (or reporting/notification). - -* *Import existing Active Directory groups as roles and assign these roles* to midPoint users corresponding to the AD group members. -** We plan to concentrate on this topic in the follow-up for First steps methodology. - -* *Start provisioning Active Directory groups and their membership via midPoint* (after they have been initially imported). -** We plan to concentrate on this topic in the follow-up for First steps methodology. - -* *Start moving self-service (password change/reset) to midPoint.* Probably makes more sense after more target systems accounts with different passwords are provisioned by midPoint. - -* *Switch from batch mode to event-driven synchronization (Live synchronization) from HR*. - -* *Start creating roles* for request/approvals (based on existing roles in the organization). Move request/approval process to midPoint. -** We plan to concentrate on this topic in the follow-up for First steps methodology. - -* *Start creating roles* for automatic/conditional assignment. Use role auto-assignment expressions. -** We plan to concentrate on this topic in the follow-up for First steps methodology. diff --git a/midpoint/methodology/first-steps/bonus-points/index.adoc b/midpoint/methodology/first-steps/bonus-points/index.adoc new file mode 100644 index 000000000..1544c467d --- /dev/null +++ b/midpoint/methodology/first-steps/bonus-points/index.adoc @@ -0,0 +1,9 @@ += MidPoint first steps methodology bonus points +:page-nav-title: Bonus points +:page-display-order: 700 + +This section contains some additional resources that are not tightly bound to the First steps guide but you may find them useful. + +++++ +{% children %} +++++ \ No newline at end of file diff --git a/midpoint/methodology/first-steps/bonus-points/multiple-sources.adoc b/midpoint/methodology/first-steps/bonus-points/multiple-sources.adoc new file mode 100644 index 000000000..e1241bcda --- /dev/null +++ b/midpoint/methodology/first-steps/bonus-points/multiple-sources.adoc @@ -0,0 +1,92 @@ += How to handle multiple source systems +:page-nav-title: Handling multiple sources +:page-display-order: 710 +:page-toc: top +:experimental: +:page-description: How to handle multiple source systems in midPoint + +In real deployment, we often need to connect multiple source systems to get all necessary data to midPoint. +Here, we cover a few scenarios you may face, and outline possible solutions. + +== Additional source with different users + +For example, you can have source systems for employees and another system for external employees. + +This scenario is very simple. +Connect new source system in the same way you have connected the very first one. +Since there are no overlaps, each system will be responsible for own set of user objects and their properties. + +Most likely you will not have the exact same attributes in both system, therefore you need to count with that when you define your outbound mappings. +Either you are fine with empty values (and expect it during simulations evaluation), or you have a mapping script handling that. +Otherwise, there is no difference compared to scenario with only a single source system. + +== Additional source with same users but different attributes + +For example, you have a primary HR source with all users and their basic attributes. +You also have an address book source containing the same users with their email and telephone numbers which the HR system does not contain. + +In this scenario you want to correlate accounts from both system to the same focal objects (typically users) in midPoint. +Make sure you have correct correlation rules for both source systems. +In practice, it might be hard to guarantee that a user is first created in the primary source system, synchronized to midPoint, and only then created in (and synchronized to) the secondary source. + +This can be handled in two ways: + +. Do not synchronize accounts to the secondary source system until they are imported from the primary one. +** Do not set any reaction for the _unmatched_ situation in the secondary source resource synchronization settings. +** Set _unlinked_ situation reaction to _link_ to ensure the accounts for existing midPoint users will be linked. +** Set up both liveSync and reconciliation tasks for the secondary resource. ++ +LiveSync will skip account that cannot be linked at the moment (because midPoint user do not exist yet) and will not process them again unless there is a change on that account. Therefore, reconciliation running with reasonable period is needed. ++ +TIP: It is possible to configure synchronization from the primary source system to trigger import of a particular account from the secondary source during creation of the new user. +This is complex configuration far beyond The First Steps methodology. ++ +** Note that users in midPoint will be initially created without the data from the secondary source system. + The data from the secondary system will be added later by liveSync or reconciliation task. + Keep that in mind when evaluating simulations and designing your mappings and data flows. ++ +CAUTION: It might be complicated to automatically decide whether an _unmatched_ account is only waiting for synchronization from the primary source and will get a focal object to match to, or if this account is truly orphaned. + +. If the account in the secondary system is synchronized to midPoint first, create a user with minimal information in the _draft_ lifecycle state. +** Set _unmatched_ situation reaction to _add focus_ to create a new midPoint users if they do not exist yet. +** Set _unlinked_ situation reaction to _link_ to ensure the accounts for existing midPoint users will be linked. +** Set the mappings as _weak_ and the lifecycle state to _draft_. + This mapping will be overridden by _strong_ mappings in the primary source system. +** Add mappings for necessary attributes. + Do not forget to add mappings that will be used for correlation from the primary source system (e.g., a mapping for personal number). + +NOTE: If a user will stay in draft state for too long and synchronization from primary source system is running, it is probably an orphaned account that should be handled. + +== Both source systems contain identical user information + +For example, a university scenario with sources for employees and students where one person can be both a student and employee. + +NOTE: This scenario is beyond the First steps methodology. +Even tough midPoint supports it, it requires complex configuration to handle it in its full complexity. +This section describes several approaches, but it might require detailed study of relevant features and configuration options. + +* Make sure you have correct correlation rules for both source systems. +* It is recommended to use a single archetype (e.g., Person) for users from both systems. + You can use *auxiliary archetypes* to differentiate between them. + User might be created first with any of them and later needs to be properly correlated when he/she is created in the other source system. +* Set _unmatched_ situation reaction to _add focus_ to create a new midPoint users if they do not exist yet. +* Set _unlinked_ situation reaction to _link_ to ensure the accounts for existing midPoint users will be linked. +* You need to solve problem of merging same attributes (e.g., given name and family name) from source systems to midPoint properties. This is the most difficult part with several options: +. Set mapping strength for such attributes to _normal_. + In that case the last change will overwrite the old one. + Even though this might seem as a simple solution there might be some practical problems, such as the lack of control over the results or the fact that reconciliation process does not touch _normal_ strength mappings. + Nevertheless, in some cases, this might be practical solution to start with and you can replace it by a more robust solution later. + See xref:/midpoint/reference/expressions/mappings/#_mapping_strength[mapping strength documentation] for details. +. Create xref:/midpoint/reference/schema/custom-schema-extension/[a custom schema extension] where you can store attributes from both source systems. + For example, you will have attributes like _studentGivenName_, _employeeGivenName_. + Then, you will add mappings to your object template that will convert these extended attribute to standard midPoint schema base on your requirements. + For example, you might decide that data from the employee source system, if exists, will be preferred over data from the student system. +. Use experimental feature for xref:/midpoint/reference/correlation/multiple-identity-data-sources/[multiple identity data sources]. + The principle it the same as the schema extension approach, but the configuration is more straightforward. + Read about xref:/midpoint/versioning/experimental/[experimental features] before using this approach. +. There are other options, like using conditional mappings with dynamic ranges that might be preferred in certain situations. + Such options are situational and complex to be described specifically. Contact our support if you need help with such case. +* Do not forget the *lifecycle state* user property needs to be merged base on state from both systems too. +* Note that it is impossible to simulate import from two sources at the same time. + You need to connect them one by one at least to correlate users. + When you have users correlated, you can simulate mappings from both sources by running simulated *recomputation* of users. \ No newline at end of file diff --git a/midpoint/methodology/first-steps/bonus-points/reset-training-environment.adoc b/midpoint/methodology/first-steps/bonus-points/reset-training-environment.adoc new file mode 100644 index 000000000..5afe20a2f --- /dev/null +++ b/midpoint/methodology/first-steps/bonus-points/reset-training-environment.adoc @@ -0,0 +1,15 @@ += Reset the training environment +:page-nav-title: Reset training environment +:page-display-order: 720 +:page-description: Guide on resetting your training environment when you wish to repeat the course and begin with a blank slate + +Should you decide to go through the whole First steps guide again, you may want to reset the training environment. +This is only applicable if you used the preconfigured Docker images we provide as part of the link:https://evolveum.com/training-and-certification/midpoint-deployment-first-steps-self-paced/[MID-301 First steps training course]. + +. Go to the directory into which you have unpacked the `firststeps.zip` with the Docker images. +. Stop and remove the Docker container: `docker compose down -v` + ** The `-v` parameter instructs Docker to delete the containers, volumes, and networks. + Without the parameter, Docker only stops the containers and you can resume them as you left them. +. Start the whole training environment anew: `docker compse up -d` + +In a few moments, you can connect to the training applications. \ No newline at end of file diff --git a/midpoint/methodology/first-steps/connect-source-system/connect-hris.adoc b/midpoint/methodology/first-steps/connect-source-system/connect-hris.adoc new file mode 100644 index 000000000..316424b07 --- /dev/null +++ b/midpoint/methodology/first-steps/connect-source-system/connect-hris.adoc @@ -0,0 +1,91 @@ += Connect the HR system +:page-nav-title: Connect HR system +:page-display-order: 110 +:page-toc: top +:experimental: +:icons: font + +When starting an IGA deployment project, having covered the planning part, the first practical thing to do is to connect the authoritative source system to midPoint. +When you are done with this step, you are going to have the user accounts in midPoint and can move forth with connecting a target system, such as an Active Directory. + +In this guide, we are using an HR information system as the authoritative system. + +== What awaits you in this module + +Connect the HR application to midPoint by creating a new resource, +define an object type as the blueprint for HRIS user accounts, +and filter out any HRIS accounts you do not wish to manage in midPoint. + +:sectnums: + +== Create a resource for the HR system + +Our HR system exports accounts to CSV files. +A CSV file can be a resource like any other. +To get users from the CSV to midPoint, use the CSV connector and configure it according to the structure of the CSV file. + +*Follow this configuration guide: xref:/midpoint/reference/admin-gui/resource-wizard/create-resource-using-wizard/[]* + +. Create a new resource from scratch. +. Use the CSV connector. +. Keep the lifecycle state set to _Proposed_ until you finish the whole configuration of the resource. +. Get back here when you are done. + +[NOTE] +==== +For the MID-301 training Docker containers, use: + +* `/opt/midpoint/var/resources/export.csv` as the CSV file path +* `empnum` as the unique attribute name +==== + +== Configure the HR resource object type + +The next step is to configure the CSV resource object type. +In the case of HR system, each resource object represents a user account in the system. + +*Follow this configuration guide: xref:/midpoint/reference/admin-gui/resource-wizard/object-type/[]* + +. Name the object type _HR Person_, for example. +. Make the object type of the _Account_ kind, _default_ (or empty) intent, and with the _Default_ attribute set to _True_. +. Keep the rest of the settings to defaults. +. In the last screen, select the _User_ type, and the _Person_ archetype. +. Get back here when you are done. + +.Object type configuration screen with the type set to _User_ and the archetype to _Person_ +image::hris-object-type-midpoint-data.webp["Object type configuration screen with the type set to User and the archetype to Person"] + +After you save your object type, you can xref:/midpoint/reference/admin-gui/resource-wizard/object-type/#further-object-type-configuration[preview the resource data] to see what you are getting from the resource. + +== Filter out irrelevant HR entries + +When you preview the resource objects, you may realize that there are some accounts which you do not want or need to manage using midPoint. + +These may be AC technicians or people who manage your office greenery. +While their work is indispensable, they simply have no IT accounts to manage. + +To prevent these accounts from being imported to midPoint: + +. Find a common pattern these entries have in the HR system. + + It may be that their employee numbers start with a different digit or their employment type is different from others… + +. xref:/midpoint/reference/admin-gui/resource-wizard/object-type[Go back to the object type configuration] and select the icon:circle[] *Basic attributes* tile. + +. Edit the object type you've created for the accounts and xref:/midpoint/reference/admin-gui/resource-wizard/object-type#filter-resource-objects[set up a filtering query]. + + For instance, to exclude employees whose number (`empnum`) starts with `8`: `attributes/empnum not startsWith "8"`. + ** If you are using the MID-301 training data, use exactly that filtering formula. + +. Save the object. + ** Note that previewing will always list _all_ the objects on the resource regardless of the object type filtering you set up. + +. xref:/midpoint/reference/tasks/shadow-reclassification-task/[Reclassify the resource object shadows] to reflect your changes in the account list. + +The excluded accounts no longer appear among the accounts. MidPoint is aware of them but they are no longer considered an _HR Person_ (they are of an undefined kind and intent, and not managed by midPoint). + +:sectnums!: + +== Next steps + +Now, you are ready to proceed further with preparations to import your HRIS users to midPoint. + +[.nowrap]#icon:arrow-right[] *xref:/midpoint/methodology/first-steps/connect-source-system/define-mapping-and-synchronization-rules/[]*# \ No newline at end of file diff --git a/midpoint/methodology/first-steps/connect-source-system/define-mapping-and-synchronization-rules.adoc b/midpoint/methodology/first-steps/connect-source-system/define-mapping-and-synchronization-rules.adoc new file mode 100644 index 000000000..fbe82e437 --- /dev/null +++ b/midpoint/methodology/first-steps/connect-source-system/define-mapping-and-synchronization-rules.adoc @@ -0,0 +1,201 @@ += Define mapping and synchronization rules +:page-nav-title: Define mapping and synchronization rules +:page-display-order: 120 +:page-toc: top +:experimental: +:icons: font + +Before you can import any user accounts, you need to define user data handling rules, +as well as specify synchronization rules on how to behave when users are discovered, updated, deleted, and so on. + +== What awaits you in this module + +You are about to create two sets of rules telling midPoint how to manage the HRIS application data. +Firstly, you need to define synchronization rules. + +Synchronization situation is what happens when midPoint correlates (synchronizes) its object repository with a remote resource, such as the HRIS. +Newly discovered accounts not yet seen by midPoint are unmatched, accounts removed from the resource are deleted, etc. +Read more on the topic: + +* xref:/midpoint/reference/synchronization/introduction/[] +* xref:/midpoint/reference/synchronization/situations/[] + +Each synchronization situation can have some reaction from midPoint, such as linking a new xref:/midpoint/reference/schema/focus-and-projections/[focal object] to a discovered account. +You are now about to define reactions to synchronization situations. + +Secondly, you will create mapping rules, telling midPoint which source attribute maps to which focal object attribute. +Mapping rules are basically a mapping table telling midPoint which "external" (application resource) attribute (e.g., `surname`) corresponds to which "internal" (focus) attribute (e.g., `familyName`). + +See xref:/midpoint/features/current/mapping/[] to learn more about the topic. + +Lastly, you will configure midPoint so that it can only read from the HRIS application, not write to it. +This is an additional data protection layer should you make a mistake when you deploy the configuration to production. + +:sectnums: + +== Set synchronization rules + +Firstly, tell midPoint what to do in what synchronization situation. + +*Follow this configuration guide: xref:/midpoint/reference/admin-gui/resource-wizard/object-type/synchronization/[]* + +Define these rules: + +[cols="2,1,1,1,4"] +|==== +| Name | Situation | Reaction | Lifecycle state | Comments + +| add-focus-for-unmatched +| Unmatched +| Add focus +| Active +| The account from CSV does not exist in midPoint yet, so create the user (focus) in midPoint. + +// technically not needed in clean MP but they need to add it later anyway so I'm putting it here already @dakle +| link-unlinked +| Unlinked +| Link +| Active +| There is a focus for the account but it is not linked to the shadow of the account yet, let us link it. This is not used during the first import, but it is necessary for later when the account shadows are in midPoint already. + +| synchronize-linked +| Linked +| Synchronize +| Active +| Synchronize the data between the remote account and the focus based on mappings. + +|==== + +[TIP] +==== +At this point, both the synchronization and mapping rules can be set as _Active_ because the whole resource is still in the _Proposed_ lifecycle state. +You can consider lifecycle states as hierarchical. +Refer to xref:/midpoint/reference/concepts/object-lifecycle/[] for more details about lifecycle states. +==== + +== Map user data + +Secondly, you need to map the resource-side account attributes to the attributes of user focal objects in midPoint. + +*Follow this configuration guide: xref:/midpoint/reference/admin-gui/resource-wizard/object-type/mapping/[]* + +Use *inbound mappings* because you are pulling attributes _from_ the HRIS application _to_ midPoint. + +Below are the rules to define. + +[NOTE] +==== +The resource-side attribute names (ie., Source) match those used in the xref:/midpoint/methodology/first-steps/connect-source-system/#playground-data-used-in-this-guide[MID-301 course training data]. +If you use your own systems, adjust the source names as needed. +==== + +.Mappings for HRIS accounts data manipulation +[cols="2,1,1,1,1,5"] +|==== +| Name | Source | Expression | Target | Lifecycle state | Comments + +| empnum-to-name +| `empnum` +| As is +| `name` +| Active +| The `name` attribute values must be unique, hence the employee number is the best choice now. + Later, you will generate unique usernames. + +| empnum-to-personalNumber +| `empnum` +| As is +| `personalNumber` +| Active +| `empnum` is also important for employee identification, so we map it to a dedicated attribute. It will stay there even after you create unique usernames. + +| firstName-to-givenName +| `firstName` +| As is +| `givenName` +| Active +.2+<.^| First and last names are used to construct a full name. + +| surname-to-familyName +| `surname` +| As is +| `familyName` +| Active + + +| locality-to-locality +| `locality` +| As is +| `locality` +| Active +| User location will be later used with the full name for a last-resort correlation. + +| status-to-lifecycleState +| `status` +| Script +| `lifecycleState` +| Active +| Translate textual status to midPoint user lifecycle state. + Find the script to use beneath the table. + Click btn:[Show script] to edit the script. + +|==== + +[[mapping-script]] +.The status-to-lifecycleState mapping conversion script +[source,groovy] +---- +switch (input) { + case 'In': <1> + 'active' + break + + case 'Long-term leave': <1> + 'suspended' + break + + case 'Former employee': <1> + 'archived' + break +} +---- +<1> Adjust to the corresponding values of the attribute in your system. + These values are used in the MID-301 training data. + +.Inbound mappings for the HR resource +image::hris-inbound-mappings.webp["Inbound mappings for the HR resource"] + +.Naming conventions for mapping names +[NOTE] +==== +You may be curious about why we name the mappings as shown above. +At first glance, it seems unnecessary to name the mapping _surname-to-familyName_ +since it is evident that it takes _surname_ as input and outputs its content to _familyName_. + +You are correct, but the rationale behind this naming convention is that *mapping names must be unique within the object type*. +This approach helps to ensure that. + +As for spaces vs. dashes—you can use either, but dash signs are generally the saver option. +Treat mapping names as filenames. +==== + +== Make the resource read-only + +If you are dealing with a resource the data of which you do not want to change, it is best to adjust the xref:/midpoint/reference/resources/resource-configuration/capabilities/[configured capabilities] of the resource so that mistakes cannot happen. + +. In your HR resource, go to icon:info[] *Details*. +. Disable the *Create*, *Update*, and *Delete* capabilites. + ** You can disable Create and Delete by clicking their respective buttons. + As for the Update capability, you need to select *Enabled*: _False_ in the modal that appears after clicking the capability button. +. Click [.nowrap]#icon:save[] btn:[Save]# at the top left. + +.Resource capabilities screen with the Create, Update, and Delete capabilities highlighted and disabled as per the instructions above +image::hris-resource-capabilities.webp["Resource capabilities screen with the Create, Update, and Delete capabilities highlighted and disabled as per the instructions above"] + +:sectnums!: + +== Next steps + +With this configuration finished, you are now ready to import users to midPoint. + +[.nowrap]#icon:arrow-right[] *xref:/midpoint/methodology/first-steps/connect-source-system/import-accounts-from-hris/[]*# \ No newline at end of file diff --git a/midpoint/methodology/first-steps/connect-source-system/hris-inbound-mappings.webp b/midpoint/methodology/first-steps/connect-source-system/hris-inbound-mappings.webp new file mode 100644 index 000000000..0f52058a6 Binary files /dev/null and b/midpoint/methodology/first-steps/connect-source-system/hris-inbound-mappings.webp differ diff --git a/midpoint/methodology/first-steps/connect-source-system/hris-object-type-midpoint-data.webp b/midpoint/methodology/first-steps/connect-source-system/hris-object-type-midpoint-data.webp new file mode 100644 index 000000000..bed09618e Binary files /dev/null and b/midpoint/methodology/first-steps/connect-source-system/hris-object-type-midpoint-data.webp differ diff --git a/midpoint/methodology/first-steps/connect-source-system/hris-people-imported.webp b/midpoint/methodology/first-steps/connect-source-system/hris-people-imported.webp new file mode 100644 index 000000000..4002ef1d7 Binary files /dev/null and b/midpoint/methodology/first-steps/connect-source-system/hris-people-imported.webp differ diff --git a/midpoint/methodology/first-steps/connect-source-system/hris-resource-capabilities.webp b/midpoint/methodology/first-steps/connect-source-system/hris-resource-capabilities.webp new file mode 100644 index 000000000..5f902b297 Binary files /dev/null and b/midpoint/methodology/first-steps/connect-source-system/hris-resource-capabilities.webp differ diff --git a/midpoint/methodology/first-steps/connect-source-system/import-accounts-from-hris.adoc b/midpoint/methodology/first-steps/connect-source-system/import-accounts-from-hris.adoc new file mode 100644 index 000000000..2f037ae51 --- /dev/null +++ b/midpoint/methodology/first-steps/connect-source-system/import-accounts-from-hris.adoc @@ -0,0 +1,120 @@ += Import users from the HR system +:page-nav-title: Import users from HRIS +:page-display-order: 130 +:page-toc: top +:experimental: +:icons: font + +With the mapping and synchronization configuration from the previous module finished, you are now ready to import users from the source HRIS application to midPoint. + +== What awaits you in this module + +Your goal in this module is to import accounts from the HRIS application to midPoint. +Before the actual import, you will verify that your midPoint configuration behaves as expected, and then import the accounts. + +First, you will simulate import of one user to do the basic check of mapping and synchronization rules behavior. + +After that, you will simulate importing all user accounts. +This time, you will see the number of user accounts imported and what data would be pulled from the HRIS appliaction to midPoint. +If need be, you will amend the configuration of the HRIS resource in midPoint and run the simulation again. + +Having confirmed the correctness of the configuration, you will then import the user accounts to midPoint for real. + +[TIP] +==== +We strongly suggest you *never skip simulations*. +It is the best way to make sure your resource configuration behaves as expected, and fix it if needed. +==== + +:sectnums: + +== Simulate a single account import + +You first simulate importing one account. +This is useful for catching the most basic configuration errors, and it is fast because midPoint does not have to fetch _all_ the users from the source application. + +*Follow this guide: xref:/midpoint/reference/tasks/synchronization-tasks/import-and-reconciliation/gui/#simulate-import-of-a-single-object[Simulate import of a single object]* + +Once the simulation is done, inspect the results and verify the source application user attributes are mapped correctly to midPoint. +If not, adjust the mapping configuration. +Once everything looks good, proceed to the full import simulation. + +== Simulate importing all users + +The next step is to simulate importing all users. + +*Follow this guide: xref:/midpoint/reference/tasks/synchronization-tasks/import-and-reconciliation/gui/[]* + +. Select [.nowrap]#icon:upload[] btn:[Import task]#. +. Switch on the *Simulate task* toggle to activate simulation mode. +. Select the _Preview_ mode with the _Development_ configuration in the xref:/midpoint/reference/tasks/synchronization-tasks/import-and-reconciliation/gui#execution[execution setup screen]. +. Run the task. +. xref:/midpoint/reference/tasks/synchronization-tasks/import-and-reconciliation/gui/#read-simulation-results[Inspect the simulation results] +. Rectify the mapping and synchronization rules configuration if needed. + +Refer to xref:/midpoint/reference/simulation/[] for more details on simulations. + +[NOTE] +==== +You may notice a discrepancy between the number of activated focal objects (users) and the total number of added accounts. +That is expected if xref:/midpoint/methodology/first-steps/connect-source-system/define-mapping-and-synchronization-rules/#map-user-data[your _status-to-lifecycleState_ mapping sets some people as inactive]. + +All HRIS application accounts (with xref:/midpoint/methodology/first-steps/connect-source-system/connect-hris/#filter-out-irrelevant-hr-entries[some exceptions]) get shadows and focal objects in midPoint, but only the current employees are activated as per the mapping. + +In the simulation results screen: + + * Click btn:[More info] in the *Focus activated* tile to see all users that would be activated (current employees). + * Click the number in the *Added objects* row in the [.nowrap]#icon:flask[] *Simulation task details*# sidebar to view all accounts that would be added. +==== + +== Import users for real + +Once you confirm you get the expected results during the simulations, you can import the HRIS user accounts for real. + +=== Activate your configuration + +Make sure you have all the relevant items in the _Active_ lifecycle state because you are not simulating anymore: + +* The whole resource +* The object type for accounts +* The mapping rules +* The synchronization rules + +*Follow this guide: xref:/midpoint/reference/admin-gui/resource-wizard/create-resource-using-wizard/#activate-proposed-resource[Activate proposed resource]* + +=== Create production import task + +Create an import task similar to the simulation one, but this time for production—do not switch on the simulation toggle. + +*Follow this guide: xref:/midpoint/reference/tasks/synchronization-tasks/import-and-reconciliation/gui/[]* + +=== Check the import results + +Once you run the production import task and it finishes, you can check the results in two places in midPoint: + +. [.nowrap]#icon:male[] *Accounts*# section in the HRIS resource contains the accounts imported from your HRIS application. +. [.nowrap]#icon:user[] *Users*# > [.nowrap]#icon:user[] *Persons*# lists focal objects (i.e., users) created based on the accounts in the HRIS application. + +.List of focal objects (users) with the Person archetype +image::hris-people-imported.webp["List of focal objects (users) with the Person archetype"] + +If you see a list similar to the one above―congratulations, you have imported your users to midPoint and you are ready to connect a target system to midPoint. +If not, revisit the mapping and synchronization settings to investigate possible misconfiguration. + +.Do you really suggest using numbers as usernames? +[TIP] +==== +Good and timely question. +Technically, it is fine to use employee numbers as usernames, but you are right. +It is better to use actual names for user identifiers. +You will learn how to do that later in the guide. +==== + +:sectnums!: + +== Next steps + +Accounts from the source application are imported. +It is time to integrate the target system. + +[.nowrap]#icon:arrow-right[] *xref:/midpoint/methodology/first-steps/integrate-target-system/[]*# \ No newline at end of file diff --git a/midpoint/methodology/first-steps/connect-source-system/index.adoc b/midpoint/methodology/first-steps/connect-source-system/index.adoc new file mode 100644 index 000000000..dbdaa3971 --- /dev/null +++ b/midpoint/methodology/first-steps/connect-source-system/index.adoc @@ -0,0 +1,65 @@ += Connect source system +:page-nav-title: 2. Connect source system +:page-display-order: 100 +:page-toc: top +:experimental: +:icons: font + +With your target systems identified, the next step is to connect the first source system (HRIS in the case here) to midPoint and evaluate the quality and structure of the data it contains. +Use the findings to refine your deployment plan based on real, actionable data. + +== Considerations before you connect the source system + +In theory, you should give the data in your _source_ HR system absolute authority and use it to fix any inconsistencies in other _target_ systems, such as an Active Directory or other resources. + +Reality is not so straightforward, though. + +* Firstly, there are almost certainly errors in the HR data. + They are managed manually with no automatic validation. + Having nothing to compare the data with makes it impossible to assess their quality. + +* Secondly, target systems like Active Directory are managed by different people and also manually. + There may be outdated information, such as old names of people who changed their names (typically through marriage). + More serious issues like orphaned accounts of former employees are usual as well. + These issues are fairly easy to fix through the synchronization with the HR resource, though. + +* Thirdly, not all Active Directory accounts need to exist in the HR system. + Your AD admins may have created some service accounts. + These are not employees and therefore are not in the HR system. + That means an HR-based synchronization without proper planning would delete these potentially business-critical accounts. + +[TIP] +==== +However complex these concerns may sound to you now, they are fairly easy to tackle in midPoint and you will learn to address them properly one by one. +==== + +Overall, when integrating an IGA solution on top of existing account data, *you need to be vigilant*: + +* You cannot change *usernames* carelessly. + Many systems in your organization may use them as the primary ID of accounts. + +* You must not delete any *accounts* unless you are absolutely sure it is the desired action. + +* You have to keep *passwords* as they are. + Otherwise, you would lock people out of the systems across your organization. + +== Playground data used in this guide + +For this guide, we use HRIS and LDAP systems provided as Docker images originally for the link:https://evolveum.com/training-and-certification/midpoint-deployment-first-steps-self-paced/[MID-301 First steps training]. + +The training is freely accessible and you may use it to obtain the same playground environment as we use here. +Once you enroll, complete the module called _Technical prerequisites_ to set up the environment, and return back here. + +You may also go through the MID-301 training instead of following this guide should you find it more comfortable, as the content is nearly identical. + +In this guide, we use the HRIS as an authoritative source system and Active Directory (simulated by LDAP) as a target system. + +You can follow this guide with your own systems. +The concepts in this guide are universal; only implementation details such as attribute names and resource configuration will need adjustment for your environment. + +== Next steps + +This has been the last piece of the theory. +Now, let us get into action and connect the first system to midPoint: + +[.nowrap]#icon:arrow-right[] *xref:/midpoint/methodology/first-steps/connect-source-system/connect-hris/[]*# \ No newline at end of file diff --git a/midpoint/methodology/first-steps/enable-target-system-provisioning/credential-mapping-overview.webp b/midpoint/methodology/first-steps/enable-target-system-provisioning/credential-mapping-overview.webp new file mode 100644 index 000000000..acef38689 Binary files /dev/null and b/midpoint/methodology/first-steps/enable-target-system-provisioning/credential-mapping-overview.webp differ diff --git a/midpoint/methodology/first-steps/enable-target-system-provisioning/index.adoc b/midpoint/methodology/first-steps/enable-target-system-provisioning/index.adoc new file mode 100644 index 000000000..c4deca25b --- /dev/null +++ b/midpoint/methodology/first-steps/enable-target-system-provisioning/index.adoc @@ -0,0 +1,254 @@ += Enable target system provisioning +:page-nav-title: 4. Provision to target system +:page-display-order: 300 +:page-toc: top +:experimental: +:icons: font +:page-description: Enable data delivery to the target Active Directory application to move forth with the automation of your midPoint IGA setup. + +Enable data delivery to the target Active Directory application to move forth with the automation of your midPoint IGA setup. +Target application provisioning enables automation of account creation for new users, updating existing users, as well as disabling former employee accounts without undue delay. +This is also known as the joiner-mover-leaver (JML) process management. + +== What awaits you in this module + +You will configure midPoint so that it creates new accounts in AD after it fetches them from the HRIS, +corrects mistakes in AD based on the _truth_ in the HRIS, +and manages AD account activation based on the midPoint user status. +Last but not least, you will configure midPoint to handle Active Directory passwords for both new and existing users. + +Here is the outline of the action points in this module: + +. Configure outbound AD mappings. +. Create outbound activation rules to enable central account activation management and create a safety cushion in case of an unintended account deactivation. +. Set up outbound credential mappings to enable new AD account creation, as well as let users manage their AD passwords in midPoint. +. Validate the new setup using simulations and put the configuration to production. + +Aside the introduction of the ability to populate AD with the accounts created in the HR source system, the configuration has one pleasant "side effect". +That is, once deployed on production, midPoint will fix typos and other mistakes in existing AD accounts. + +:sectnums: + +== Create outbound Active Directory mappings + +The first step is to tell midPoint which user attributes map to which AD attributes. + +If you follow this guide along with the preconfigured training Docker images, you do not need to set the rules up from scratch; the midPoint Docker image is preconfigured with these rules in the _Draft_ lifecycle state. +Their names may differ. + +If you use your own data sources, you need to inspect them and devise the data flow on your own. +Should your resource be an LDAP or similar, you can use the mapping scripts beneath the table for inspiration on how to transform the data appropriately. + +.Inbound vs. outbound mappings +[NOTE] +==== +So far, you have used only _inbound_ mappings. +Even the Active Director resource had, so far, used only inbound mappings for usernames and correlation, despite being a target system. +Now, the data flows not _to_ midPoint (_indbound_), but _from_ midPoint. +Hence, the mappings need to be _outbound_. +==== + +Set the mapping rules according to the table below. + +*Follow this guide: xref:/midpoint/reference/admin-gui/resource-wizard/object-type/mapping/#outbound_mappings[]* + +.Proposed outbound mappings for the Active Directory provisioning +[cols="5*", options="header"] +|==== +| Name | Source | Expression | Target | Lifecycle state +| out-name-fullname-to-dn | `name`, `fullName` | Script | `dn` | Proposed +| out-name-fullname-to-cn-weak | `name`, `fullName` | Script | `cn` | Proposed +| out-full-name-to-displayName | `fullName` | As is | `displayName` | Proposed +| out-familyName-to-sn | `familyName` | As is | `sn` | Proposed +| out-givenName-to-givenName | `givenName` | As is | `givenName` | Proposed +| out-name-to-uid | `name` | As is | `uid` | Proposed +| out-locality-to-l | `locality` | As is | `l` | Proposed +| out-personalNumber-to-employeeNumber | `personalNumber` | As is | `employeeNumber` | Proposed +|==== + +.Script for _out-name-fullname-to-dn_ mapping +[source,groovy] +---- +def cn + if (iteration == 0) { + cn = fullName + } else { + cn = fullName + ' (' + name + ')' + } + return basic.composeDnWithSuffix('cn', cn, + 'ou=users,' + basic.getResourceIcfConfigurationPropertyValue(resource, 'baseContext') + ) +---- + +.Script for _out-name-fullname-to-cn_ mapping +[source,groovy] +---- +def cn + if (iteration == 0) { + cn = fullName + } else { + cn = fullName + ' (' + name + ')' + } + return cn +---- + +.Proposed vs. active configuration items +[TIP] +==== +In the previous modules, you may have gotten used to creating mapping and other configuration items in the _Active_ lifecycle state. +It was fine as long as you had the whole resource _proposed_. +However, that is not the case anymore. +Your Active Directory resource is _active_ now which means you need to _propose_ any new configurations before you validate and _activate_ them. +==== + +== Handle AD accounts activation from midPoint + +When provisioning to Active Directory (or any other target system), you want to equip midPoint with the ability to enable and disable AD accounts based on their respective owner's status in midPoint. + +This is the purpose of the outbound administrative status activation mapping. + +*Follow this guide: xref:/midpoint/reference/admin-gui/resource-wizard/object-type/activation/[]* + +. Create an outbound activation rule. +. Select [.nowrap]#icon:id-card-clip[] btn:[Administrative status]#. +. *Name* the rule descriptively, such as _set-account-status-based-on-midpoint-user_. +. Set *Strength* to _Strong_ to ensure midPoint has full control over the value in the target system. +. Leave other settings at their default. + +The *Source* can be left empty because midPoint infers it should use the effective status _As is_ which is exactly what you want here. +If you ever need to override the default behavior, you can specify a source using path expression to reference user (`$focus`) or shadow (`$shadow`) attributes (e.g., `$focus/activation/effectiveStatus`). +You could also use a Groovy script expression to compute the value dynamically. + +.Technical advice on disabling accounts in AD/LDAP +[TIP] +==== +Since there is no native way to disable AD or LDAP accounts, you need to write the user's effective status to an arbitrary AD/LDAP account attribute. +In the this guide, we use the `roomNumber` attribute. +This needs to be configured in the definition of the resource which is why xref:/midpoint/methodology/first-steps/integrate-target-system/connect-ad/#create-a-new-resource-for-the-target-application[you copied the AD resource from template]. +See this link:https://github.com/Evolveum/midpoint-samples/blob/b7565d9eab1cd702b2ae662f8d2e8b571cf51901/samples/group-synchronization/2024-11-07-webinar/objects/210-resource-ad.xml#L1063[configuration example] for details. +==== + +== Delete AD accounts with a grace period + +You have already cleaned the "illegal" accounts from your AD. +However, when you are done setting up the joiner-mover-leaver process, midPoint will delete accounts that lose their raison d'être; for instance, when an employee leaves the company, he no longer has a reason to have an AD account. +Deleting accounts is, however, not to be taken lightly. +Mistakes can happen and it is a good practice to avoid hard-deleting accounts right away without any grace period. + +For this reason, you will set up two outbound activation mappings: + +. Disable instead of delete +. Delayed delete + +The former disables accounts instead of having them deleted right away, the latter deletes the disabled accounts after a configured period of time. + +*Follow this guide: xref:/midpoint/reference/admin-gui/resource-wizard/object-type/activation/[]* + +. Create a new outbound activation rule. +. Select [.nowrap]#icon:user-slash[] btn:[Disable instead of delete]#. + ** This mapping has no configurable settings. +. Create a new outbound activation rule. +. Select [.nowrap]#icon:clock[] btn:[Delayed delete]# +. Choose a period of time after which accounts should be deleted. + ** For testing, it makes sense to set this as short as a few minutes. + On production, reasonable values would be between days and weeks. + +.Active Directory outbound activation mappings +image::ldap-outbound-activation-mappings.webp["Active Directory outbound activation mappings"] + +== Generate initial password for new AD users + +The accounts created in the HR information system do not have any credentials (passwords) associated with them +because the HRIS is simply a database of people, it does not deal with accesses. +AD accounts, however, cannot be created _passwordless_. + +For this reason, you need to configure midPoint to create a random password for each user that arrives from HRIS and is to be pushed to AD. +In this guide, we use simplified approach where users do not know their initial AD password and, in the real world, would be expected to reset via the company help desk, for example. + +*Follow this guide: xref:/midpoint/reference/admin-gui/resource-wizard/object-type/credentials/[]* + +. Create a new [.nowrap]#icon:arrow-right-from-bracket[] *outbound*# credential mapping. +. *Name* it _generate-initial-password_, for instance. +. Set *Strength* to _Weak_. +. Set *Expression* to _Generate_. +. Set the lifecycle state of the mapping to _Proposed_. +. Keep other options to their default. + +This mapping populates the password attribute with a random generated password only if the attribute is empty. +Under any other circumstance, the mapping does not change the password because you set it as _weak_. + +== Let users change their AD password in midPoint + +Unless you manage authentication and credentials using SSO or other midPoint-unrelated system, +your users may find it useful to have the option to self-manage their AD password directly in midPoint, provided you can somehow supply them with access to midPoint in the first place. +More so if a new user comes, has the initial AD password auto-generated, and needs to reset it to be able to actually access the AD server. + +. Create a new [.nowrap]#icon:arrow-right-from-bracket[] *outbound*# credential mapping. +. *Name* it _change-password_, for instance. +. Set *Strength* to _Normal_. +. Set *Expression* to _As is_. +. Set the lifecycle state of the mapping to _Proposed_. +. Keep other options to their default. + +The strength of this mapping dictates that it updates the target value when the source changes (i.e., user changes the value in midPoint), +but leaves it be in case the source stays the same but the target value is updated externally (user changed it directly in Active Directory, for example). + +.Credential mappings overview +image::credential-mapping-overview.webp["Credential mappings overview"] + +== Test your new configuration + +With mappings and credential handling set up, you are ready to test the new configuration. + +This is the stage when you are about to correct mistakes on the target system, such as incorrectly filled in names, wrong employee numbers (remember the xref:/midpoint/methodology/first-steps/integrate-target-system/reconcile-ad-accounts/#resolve-correlation-cases[correlation cases]?), and so on. +The amount of changes depends on the quality of the data in your systems. + +Reuse the _Reconcile AD - development simulation_ reconciliation task you have used before: xref:/midpoint/methodology/first-steps/integrate-target-system/reconcile-ad-accounts/#simulate-ad-reconciliation[] + +If you follow this guide along with the preconfigured training Docker images, you can expect results similar to this: + +.Simulated reconciliation task results overview +image::ldap-provisioning-reconcile-simul-devel.webp["Simulated reconciliation task results overview"] + +And should you open one of the accounts under *Projection renamed*, you would see the data on AD would be corrected based on the HRIS data. +Nothing was changed yet because this was a simulation. + +.Simulated correction of data on AD based on HRIS data +image::ldap-provisioning-reconcile-simul-devel-data-correction.webp["Projection renamed showing simulated changes on an AD account"] + +Review the simulation results. +If all looks as expected, proceed to the next section. + +If you see some unexpected or unwanted changes, now is the time to investigate: + +* Which one of your resources holds correct data? +* Do your mappings point to correct attributes? +* Are lifecycle states of all required configurations (mappings, credentials) set to _Proposed_ instead of _Draft_? + +Usually, you would either let midPoint change the data in the target system (AD), or fix them in the source system (HRIS) manually. +You could also mark some AD accounts as _Do not touch_ to resolve their situation later. + +== Put the provisioning configuration to production + +After you verify everything works as expected, the last step is to put the configuration to production. + +Put everything that is in the _Proposed_ lifecycle state to the _Active_ state: + +* Mapping rules +* Activation rules +* Credential rules + +Use the reconciliation tasks you have used before: xref:/midpoint/methodology/first-steps/integrate-target-system/reconcile-ad-accounts/#reconcile-your-ad-accounts[] + +After the production reconciliation task finishes, check that your Active Directory data are consistent with what you have in the HRIS. +All users now have their misspelled names corrected, employee numbers fixed, and so on. + +:sectnums!: + +== Next steps + +Now that you have data between HRIS and AD systems synchronized and consistent, +it is time to automate some processes. +In the next modules, you will learn how to generate usernames for new accounts, ensure all users have an Active Directory account, and are members of the right group. + +[.nowrap]#icon:arrow-right[] *xref:/midpoint/methodology/first-steps/automate-target-system-integration/[]*# \ No newline at end of file diff --git a/midpoint/methodology/first-steps/enable-target-system-provisioning/ldap-outbound-activation-mappings.webp b/midpoint/methodology/first-steps/enable-target-system-provisioning/ldap-outbound-activation-mappings.webp new file mode 100644 index 000000000..731bbbcbf Binary files /dev/null and b/midpoint/methodology/first-steps/enable-target-system-provisioning/ldap-outbound-activation-mappings.webp differ diff --git a/midpoint/methodology/first-steps/enable-target-system-provisioning/ldap-provisioning-reconcile-simul-devel-data-correction.webp b/midpoint/methodology/first-steps/enable-target-system-provisioning/ldap-provisioning-reconcile-simul-devel-data-correction.webp new file mode 100644 index 000000000..30ea7047a Binary files /dev/null and b/midpoint/methodology/first-steps/enable-target-system-provisioning/ldap-provisioning-reconcile-simul-devel-data-correction.webp differ diff --git a/midpoint/methodology/first-steps/enable-target-system-provisioning/ldap-provisioning-reconcile-simul-devel.webp b/midpoint/methodology/first-steps/enable-target-system-provisioning/ldap-provisioning-reconcile-simul-devel.webp new file mode 100644 index 000000000..93a8e59ae Binary files /dev/null and b/midpoint/methodology/first-steps/enable-target-system-provisioning/ldap-provisioning-reconcile-simul-devel.webp differ diff --git a/midpoint/methodology/first-steps/hris-export-sample.csv b/midpoint/methodology/first-steps/hris-export-sample.csv new file mode 100644 index 000000000..6dbc9b43e --- /dev/null +++ b/midpoint/methodology/first-steps/hris-export-sample.csv @@ -0,0 +1,45 @@ +id,employeenumber,firstname,surname,status,locality,country,emptype,job +1,"1001","Geena","Green","In","Small Red Rock City","_loc:Rocky State","FTE","124#CEO" +2,"1002","Ana","Lopez","In","Hot Lava City","_lcl:Lava State","FTE","125#CFO" +3,"1003","Jimmy","Taylor","Former employee","Small Red Rock City","_loc:Rocky State","FTE","107#Junior Consultant" +4,"1004","Peter","Hunter","In","White Stone City","_ilo:Stone State","FTE","910#HR Consultant" +5,"1005","Emanuel","Young","Former employee","Hot Lava City","_lcl:Lava State","FTE","120#Senior Specialist" +6,"1006","Martin","Knight","In","Hot Lava City","_lcl:Lava State","FTE","121#Junior Specialist" +7,"1007","Diane","Davis","In","Hot Lava City","_lcl:Lava State","FTE","107#Junior Consultant" +8,"1008","Elisabeth","Mason","In","Small Red Rock City","_loc:rocky state","FTE","191#Accountant" +9,"1009","Josef","Zimmer","In","Hot Lava City","_lcl:Lava State","FTE","113#Sales Representative" +10,"1010","Alexander","Freeman","In","Fast River City","_rlc:two river state","FTE","113#Sales Representative" +11,"1011","Victoria","Violet","In","White Stone City","_ilo:stone State","FTE","111#Sales Director" +12,"1012","Robert","Nelson","In","Fast River City","_rlc:Two River State","FTE","199#Service Development Specialist" +13,"1013","Olaf","Peterson","In","Hot Lava City","_lcl:Lava State","FTE","102#CTO" +14,"1014","Tom","Walker","In","White Stone City","_ilo:Stone State","FTE","107#Junior Consultant" +15,"1015","Lucy","Rider","In","Hot Lava City","_lcl:Lava State","FTE","331#HR Director" +16,"1016","Jane","Anderson","Long-term leave","Hot Lava City","_lcl:Lava State","FTE","107#Junior Consultant" +17,"1017","Frank","Usher","In","White Stone City","_ilo:Stone State","FTE","106#Agent Recruitment Specialist" +18,"1018","Sam","Brown","In","White Stone City","_ilo:Stone State","FTE","106#Agent Recruitment Specialist" +19,"1019","John","Smith","In","Hot Lava City","_lcl:Lava State","FTE","667#International Intervention Coordinator" +20,"1020","Olivia","Xander","Long-term leave","Hot Lava City","_lcl:Lava State","FTE","106#Agent Recruitment Specialist" +21,"1021","Alice","Baker","In","White Stone City","_ilo:Stone State","FTE","139#Chief Recruiting Officer" +22,"1022","David","Iverson","Long-term leave","Small Red Rock City","_loc:Rocky State","FTE","199#Service Development Specialist" +23,"1023","Ellen","Jones","In","Small Red Rock City","_loc:Rocky State","FTE","331#Contract Termination Specialist" +24,"1024","Brad","Carpenter","In","Fast River City","_rlc:Two River State","FTE","906#Airborne Unit Coordinator" +25,"1025","Robert","Riley","In","Fast River City","_rlc:Two River State","FTE","222#Careers Advisor" +26,"1026","Joseph","Smith","In","White Stone City","_ilo:Stone State","FTE","146#Expert Specialist" +27,"1027","Emma","Jones","In","Fast River City","_rlc:Two River State","FTE","222#Careers Advisor" +28,"1028","Jonathan","Taylor","In","Fast River City","_rlc:Two River State","FTE","665#Domestic Intervention Coordinator" +29,"1029","Ashley","Jackson","In","Hot Lava City","_lcl:Lava State","FTE","331#Contract Termination Specialist" +30,"1030","Amanda","de Wries","In","Small Red Rock City","_loc:Rocky State","FTE","209#Senior Consultant" +31,"1031","Jennifer","Jameson","In","Hot Lava City","_lcl:Lava State","FTE","209#Senior Consultant" +32,"1032","Patrick","Anderson","In","Hot Lava City","_lcl:Lava State","FTE","113#Negotiation Specialist" +33,"1033","Scott","Hoover","In","Fast River City","_rlc:Two River State","FTE","113#Negotiation Specialist" +34,"1034","Laura","Shepherd","Long-term leave","Hot Lava City","_lcl:Lava State","FTE","113#Sales Representative" +35,"1035","John","Smith-Walker","In","White Stone City","_ilo:Stone State","FTE","113#Sales Representative" +36,"1036","Maria","Schmitt","In","Hot Lava City","_lcl:Lava State","FTE","107#Junior Consultant" +37,"1037","Eva","Mendez","Long-term leave","Hot Lava City","_lcl:Lava State","FTE","107#Junior Consultant" +38,"1038","Ricardo","Pedroso","In","Hot Lava City","_lcl:Lava State","FTE","190#Expert Accountant" +39,"1039","Charles","Whitehead","In","Hot Lava City","_lcl:Lava State","FTE","400#Environment Adaptation Specialis" +40,"1040","Frederick","Smith","In","Hot Lava City","_lcl:Lava State","FTE","400#Environment Adaptation Specialis" +41,"8000","Janet","Garner","In","Hot Lava City","_lcl:Lava State","PTE","899#Cleaning & Maintenance Specialist" +42,"8001","Ben","Goosehead","In","Hot Lava City","_lcl:Lava State","PTE","899#Cleaning & Maintenance Specialist" +43,"8002","Maria","Alvarez","In","Small Red Rock City","_loc:Rocky State","PTE","899#Cleaning & Maintenance Specialist" +44,"8003","Monica","Mendez","In","Fast River City","_rlc:Two River State","PTE","899#Cleaning & Maintenance Specialist" \ No newline at end of file diff --git a/midpoint/methodology/first-steps/import-preview.webp b/midpoint/methodology/first-steps/import-preview.webp new file mode 100644 index 000000000..b5043ada4 Binary files /dev/null and b/midpoint/methodology/first-steps/import-preview.webp differ diff --git a/midpoint/methodology/first-steps/index.adoc b/midpoint/methodology/first-steps/index.adoc index 3695cdb44..952516694 100644 --- a/midpoint/methodology/first-steps/index.adoc +++ b/midpoint/methodology/first-steps/index.adoc @@ -1,216 +1,81 @@ -= Methodology: First Steps With MidPoint -:page-nav-title: First Steps With MidPoint += First steps with midPoint +:page-nav-title: First steps with midPoint :page-toc: top :experimental: -== Introduction +This is a guide to a simplified midPoint deployment +to help you grasp the basics and get tangible results in days instead of months. -Evolveum has created a simplified midPoint deployment methodology, which will guide you through the quick deployment of simple midPoint configurations in three steps. +This guide is a blueprint to the initial identity management deployment modelling a common organization. +Its scope is limited to identities and their accounts with the ability to cover birthright permissions in target systems. -The methodology aims to start an _iterative_ identity governance program providing value early, in a series of small steps of connecting new systems, cleaning up data, and automating processes. -At the same time, the methodology ensures a _safe_ midPoint deployment by preventing unexpected changes or deletions of existing identity data, thanks to the simulations. -This combination makes it ideal for fast and safe midPoint deployment even in environments where data quality suffers. +The series of tutorials in this guide includes the following key points of deploying midPoint: -This document is a blueprint to the initial identity management deployment modelling a common organization. -The methodology includes: +* Some theory to help you understand common pitfalls and start your new IGA project off on the right foot. +* Adapt the midPoint deployment to your existing IT environment. +* Integrate the first source and target systems using correlation. +* Map the system account attributes. +* Detect and handle orphaned accounts. +* Automate the identity lifecycle and joiner-mover-leaver (JML) process. +* Override incorrect source system data. -* adaptation of the midPoint deployment to your existing IT applications environment -* connecting and integrating first source and target systems using smart correlation -* account attribute mappings -* orphaned accounts detection and handling -* identity lifecycle management -* automation of Joiner-Mover-Leaver (JML) processes -* identity management with scope limited to identities and their accounts with ability to cover _birthright_ permissions in target systems -* data override capability for incorrect source system data +== Methodology behind this guide -This methodology will guide you on your identity management journey towards identity governance. +We believe the best way to get started is to use an _iterative cyclic approach_. +Start with a series of *small steps that deliver the value early on*, and then repeat those steps to refine your solution. +The steps consist of connecting new systems, cleaning up the data, and automating the processes. +Each cycle should take a few days at most. +Of course, every deployment velocity depends on many factors, such as cooperation speed within the company, +but the iterative approach generally allows for manageable effort and budget allocation. +More on the methodology concept in a bit. -Evolveum introduced the First Steps methodology also in https://www.youtube.com/watch?v=suo775ym_PE[First Steps Methodology Webinar] video, feel free to watch the recording to familiarize yourself with the approach and see live demonstration. +== For whom is this guide? -video::suo775ym_PE[youtube,title="First Steps Methodology Webinar Video",width="852",height="480"] +This guide is meant to help small and mid-size organizations. +Typically, such organizations handle hundreds or lower thousands of identities, most of the processes are manual, and the IT staff doesn't have a lot of knowledge about identity governance and administration (IGA). +We expect that there's an HR system serving as a source of the identity data, as is usual for medium-sized businesses, smaller government offices, or academic institutions. +Nonetheless, most concepts in this guide are applicable to organizations of any size and type. +Even if your organization manages a considerably larger number of identities, the deployment process is the same. +It will probably cost more time and money, but that's it. +=== Key challenges and requirements -== Audience +These are the usual challenges you may be facing: -This guide is targeted at small and mid-size organizations that are starting with identity management. -Most concepts, however, can be applied also for other organizations, given more time and effort. +* Your identity data is of low quality because it's maintained manually without automatic validation. +* You need more people to manage identities. +* You want to improve your IGA and get tangible results quickly. +* The implementation can't be a "big bang" effort because your IT staff must also continue performing their regular duties. -Please see xref:audience.adoc[] for more detailed information. +By going through this guide, you'll learn how to deploy midPoint iteratively and get first results in a matter of weeks, even if you face all the challenges mentioned above. -== The Idea +== Why midPoint? -The idea is to start an iterative _identity management program_. -The program allows you to reach your desired solution in a series of small steps. -Each step bringing value, improving the solution. +Here are some pointers as to why midPoint is worth your attention when looking for an IGA solution: -Simply speaking, the program repeats three steps: Connect -> Clean-up -> Automate. +- MidPoint is an open-source software (OSS) that requires a minimum initial investment and no licensing fees before the project begins. -image::first-steps-idea.png[] +- The software and documentation are open, meaning they're freely available. +You don't have to spend money on consulting services to get started. +You can do the first steps (like prototyping) yourself. -Each of the steps have a slightly different goal: +- MidPoint is available now. +No paperwork, contracts, or registration required. +Just https://evolveum.com/download/[download midPoint] and try it out. -* *Connect* step is aimed at connecting new systems to the solution. -MidPoint platform will be able to _read_ the data from the system and analyze them. +- MidPoint is an OSS product with a dedicated team of professionals ready to provide support. +https://evolveum.com/services/[Contact us] to discover more about our services and benefits. -* *Clean-up* step is aimed at improving data quality. -Data in disconnected systems are often in quite a poor state. -Accounts have to be correlated, orphaned accounts have to be disabled, data errors have to be corrected. -MidPoint can help with that. +- link:https://evolveum.com/partners/find-a-partner/[Evolveum has a network of official partners] that are ready to deliver dedicated professional support for your project as well. -* *Automate* step is aimed at speeding up the processes and improving efficiency. -Manual work can be automated, making the process faster, cheaper and more reliable. -On-boarding (_joiners_) and off-boarding (_leavers_) processes are the usual candidates for automation. +While learning to use midPoint, you can *feel safe thanks to xref:/midpoint/reference/simulation/[simulations]*. +Before making any changes that could potentially damage your data, you can test them to see if you get the expected results. -The steps are repeated as long as they bring tangible value. +However, no matter how safe midPoint is, it is still a good practice to *back up your data regularly*. -When it comes to identity management, one size does *not* fit all. -Some organizations need strict policies, perfect visibility or high degree of automation. -Yet other organizations can be perfectly happy with just basic integration and automation, as long as the cost is reasonable. -It is almost impossible to plan an ideal identity management project beforehand, in all its width and depth. -Hence the iterative approach. -Series of small steps is iterated, focusing on areas that need to be improved at that particular point. -This is the way to satisfy the requirements, while keeping the costs reasonable. +== Next steps -== Big Picture +Proceed to the outline to discover what awaits you in the roadmap of this guide. -The _Connect -> Clean-up -> Automate_ approach outlined above is a useful abstraction. -It illustrates the overall approach quite well. -However, practical projects and programs are slightly more complex. -They have to _start_ somewhere, set up the team, there should be checkpoints, stop/go decisions and so on. -Therefore, we propose a series of very practical steps to bootstrap the iterative approach. - -We propose to proceed in following steps: - -. *xref:kick-off/[Kick-off]*: Start the project. -Set goals. -Identify crucial data sources and targets. -Make a plan. -Secure budget. -+ -xref:kick-off/[Read more about kick-off step] - -. *xref:assessment/[Assessment]*: Set up midPoint. -Load data from the source. -Compare the data with the target. -Assess data quality. -Decide next steps. -+ -xref:assessment/[Read more about assessment step] - -. *xref:automation/[Automation]*: Automate management of identities (to a reasonable degree). -Speed up on-boarding processes. -Make off-boarding process more reliable, improving security. -Keep data up to date. -+ -xref:automation/[Read more about automation step] - -These three steps start up a *program*, a never-ending process to maintain and expand the solution. -The progress of the program may be as fast or as slow as you need. -It is an endless iteration of several on-demand activities, executed as needed: - -* *Connect* new systems. -Add more systems to your solution, much like you did in the _assessment_ step before. -This is increasing _breadth_ (scope) of your solution. - -* *Clean-up* the data. -Your data were created and maintained manually. -They often do really match exactly between systems, the data are often out of date, there are inaccuracies and errors. -Manual processes can often tolerate quite a high degree of data disorganization. -However, increased automation heavily relies on accurate data. -There is a constant need to monitor and improved data quality, correct errors, resolve inaccuracies and inconsistencies. -This is increasing _quality_ of your solution. - -* *Automate*. -Add automated data mappings, processes and basic policies. -Your processes will run faster, more reliably, with less manual steps. -This is increasing _depth_ of your solution. - -The iterations can be repeated as many times as needed, with as big or as small scope as needed. -The overall goal of the program is to bring convergence: convergence of the data, processes and policies. - -image::first-steps-big-picture.png[Process big picture] - -There is no pre-determined number of iterations. -The iterations should be executed as long as they bring sufficient value. -However, as the business and IT environment is ever-changing, it is very likely that at least some part of the program will become part of ordinary operational routine. - -Once the first steps are complete, data are reasonably reliable, important systems are covered and processes are automated to appropriate degree, it is time to move to the next steps. -The next logical step is to focus on identity _governance_, managing entitlements, identity-related policies and business processes. - -=== Iterations - -You can use as many iterations as you need; while the iterations bring you sufficient value. -You need to take into account that a complete perfection cannot be always achieved, or it would be too expensive. -After all, you are deploying a real project with limited scope and budget, not an academic exercise. - -This does not mean that the iterations would ever stop. -New systems are added all the time, they have to be connected. -Yet, not all systems have to be necessarily connected to identity management. -Data are changing all the time, they have to cleaned up. -Yet, the data quality does not need to be perfect. -Most important of all, the amount of automation should be very reasonable. -Automation may be expensive to set up, yet it is even more expensive to maintain. - -Organizational complexity has its cost, cost that is reflected in all the systems and applications. -The combined cost of organizational complexity on the entire IT infrastructure is enormous. -Try to reduce organizational complexity as much as you can. -However, chances are that this not in your hands. -Maybe all you can do is to handle the complexity. -Once again, iterations will help you to manage effort, time and costs. - -== Why MidPoint? - -Why we think midPoint is the best tool for this kind of approach? - -* MidPoint is open source platform. -There is a very little up-front investment. -There are no licence costs that need to be paid before project starts. - -* MidPoint is completely open. -All the software is publicly available as well as all the documentation. -The very first steps (e.g. prototyping) can be done by internal staff, without a need for expensive consulting services. - -* MidPoint is available immediately. -Just https://evolveum.com/download/[download it] and try it out. -No need to do any paperwork, no need to sign any contracts, no need to request access to software. -You do not even have to register, or agree to unintelligible terms of use. -Just go ahead, click the link and try it now. - -* Professional support. MidPoint is an OSS product with a dedicated team of professional developers and engineers ready to provide support whenever you need it. -https://evolveum.com/services/[Contact us] to discover more about our services and the exclusive benefits available to our subscribers. -+ -Evolveum's network of https://evolveum.com/partners/find-a-partner/[official partners] is ready to deliver dedicated local support to your project as well. - - -== How to Use This Methodology - -Before midPoint 4.8, we recommended our users and customers to review our samples and base their midPoint configuration on them. -These samples represented a sample _final_ configuration. -They were written in midPoint XML language and any customization required our users to understand the midPoint language. - -Since midPoint 4.8, the recommended way of starting with midPoint is using GUI wizards and following this methodology. -The advantage of this approach is obvious: administrators can configure midPoint features and try them without learning another language such as midPoint XML object language. -*One significant burden is removed.* -New features such as xref:/midpoint/reference/admin-gui/simulations/[] can be used right from the beginning. -Exceptions using xref:/midpoint/reference/concepts/mark/[] can be defined directly in GUI. -This all helps to achieve a safe environment to try midPoint and avoid any unexpected modifications or even deletes in the target systems. - -But there is also a small disadvantage: when using interactive wizards such as resource wizard, it's hard to prepare _complete_ examples for learning purposes. -Having a ready-to-use example in _final state_ or even for each step of the interactive process would not be efficient and would beat the purposes of the interaction entirely. - -As the initial state for this methodology is basically an empty midPoint, we have decided to document the methodology by following the interactive wizards. -Therefore, be prepared that connecting and configuring a new system is an iterative and interactive _process_. -If you get lost, do not hesitate to watch the video mentioned in the <> chapter. - -== What's Next - -This program can continue for as long as needed. -It is not limited only to identity management. -Once the solution is mature enough, it will also cover Identity Governance and Administration, by setting up roles and policies, managing applications, xref:/midpoint/methodology/group-synchronization/[entitlements], organizational structure, etc. - -//Where does it lead? -> IGA (Set up roles and policies, manage applications, entitlements, organizational structure, etc.) ... once the solution is mature enough - -*Begin your IGA journey today and start a free self-paced First Steps Training*. -Learn how to carry out go-live regardless of data quality from HR, automate the Joiner-Mover-Leaver (JML) processes, manage birthright permissions, and use the latest features, such as simulations and smart correlation. -Please follow the instructions on how to https://evolveum.com/accessing-the-learning-portal/[access our learning platform]. \ No newline at end of file +[.nowrap]#icon:arrow-right[] *xref:/midpoint/methodology/first-steps/outline-and-concept/outline/[]*# \ No newline at end of file diff --git a/midpoint/methodology/first-steps/integrate-target-system/connect-ad.adoc b/midpoint/methodology/first-steps/integrate-target-system/connect-ad.adoc new file mode 100644 index 000000000..43b4de406 --- /dev/null +++ b/midpoint/methodology/first-steps/integrate-target-system/connect-ad.adoc @@ -0,0 +1,74 @@ += Connect your target Active Directory +:page-nav-title: Connect AD system +:page-display-order: 210 +:page-toc: top +:experimental: +:icons: font +:page-description: Integrate your target AD server with midPoint to centralize identity governance and administration across platforms. + +Integrate your target Active Directory with midPoint to establish the groundwork for centralized identity governance and administration across the HRIS and AD platforms. + +== What awaits you in this module + +As you have created the midPoint resource for the HR information system, you will create a second resource for your target Active Directory system. +After you establish connection to the AD server, +you will set up an object type for the accounts and groups in AD. + +Since we follow here the original xref:/midpoint/methodology/first-steps/connect-source-system/#playground-data-used-in-this-guide[MID-301 training course] footsteps, you will create the Active Directory resource from a preconfigured template. +This guide uses an LDAP server to simulate Active Directory server. + +If you are configuring everything on your own, +you need configure the resource so that midPoint can connect to the target application. +This is out of the scope of this guide. +If you are unsure how to fill in the connection details in midPoint, ask your system administrators for help. +The xref:/connectors/connectors/com.evolveum.polygon.connector.ldap.LdapConnector/#resource-examples[LDAP resource examples] and the xref:/connectors/connectors/com.evolveum.polygon.connector.ldap.ad.AdLdapConnector/[documentation of the connector for AD servers based on the LDAP protocol] may also help. + +:sectnums: + +== Create a new resource for the target application + +Create a new resource and copy the configuration from the template that is preconfigured in the training Docker image. +This simplified deployment is used in this guide mainly to save your time and spare you learning system management details that are potentially out of your real-life duties scope. + +*Follow this guide: xref:/midpoint/reference/admin-gui/resource-wizard/create-resource-using-wizard/[]* + +. Create a new resource and use the *Copy From Template* option. +. In the *Resource catalog* screen, select the *Training Active Directory Resource Template* template (it uses the xref:/connectors/connectors/com.evolveum.polygon.connector.ldap.LdapConnector/[LDAP connector]). +. Name the resource, e.g., _AD_. +. Keep the lifecycle state set to _Proposed_ until you finish the whole configuration of the resource. +. Configure connection to the AD (LDAP) server. + + These are the connection details for the MID-301 training Docker images: + ** Host: `ad` + ** Port: `389` + ** Bind DN: `cn=idm,ou=Administrators,dc=example,dc=com` + ** Bind password: `secret` +. Keep the rest of the settings as preconfigured in the template. + +Optionally, after you create the resource, click btn:[Preview Resource Data] and select the _inetOrgPerson_ to view the accounts in the AD application. + +== Configure the AD resource object type + +Similarly to the HRIS, AD also needs a resource object type for the accounts stored in it. +In addition to the accounts, AD contains groups. +You need to define a resource object for groups as well. + +Both object types are preconfigured in the MID-301 training template, meaning you can skip this section if you use the template. + +If you need to define the object types on your own: + +* The account object type should be of the _Account_ kind, _inetOrgPerson_ class, and _User_ type. +* The group type should be of the _Entitlement_ kind, custom-defined intent, _groupOfNames_ class, and undefined type. +* Neither should use an archetype. + +*Use this guide for xref:/midpoint/reference/admin-gui/resource-wizard/object-type/[instructions on object type configuration].* + +.AD resource object types for users and groups. +image::ldap-resource-object-types.webp["AD resource object types for users and groups"] + +:sectnums!: + +== Next steps + +With the target application connected, you are ready to proceed with preparations to reconcile the AD and HRIS accounts. + +[.nowrap]#icon:arrow-right[] *xref:/midpoint/methodology/first-steps/integrate-target-system/define-rules-for-data-handling/[]*# \ No newline at end of file diff --git a/midpoint/methodology/first-steps/integrate-target-system/define-rules-for-data-handling.adoc b/midpoint/methodology/first-steps/integrate-target-system/define-rules-for-data-handling.adoc new file mode 100644 index 000000000..25e7844c3 --- /dev/null +++ b/midpoint/methodology/first-steps/integrate-target-system/define-rules-for-data-handling.adoc @@ -0,0 +1,175 @@ += Define Active Directory rules for mapping, synchronization, and correlation +:page-nav-title: Define AD data handling rules +:page-display-order: 220 +:page-toc: top +:experimental: +:icons: font +:page-description: Create rules to enable midPoint find accounts in the target Active Directory application and match them with accounts it already knows from HRIS. + +Create rules to enable midPoint find accounts in the target Active Directory application and match them with accounts it already knows from HRIS. + +== What awaits you in this module + +You are about to create mapping, synchronization, and correlation rules to ensure midPoint can match the accounts it finds in the Active Directory with the accounts it already knows from HRIS. +The process is similar to what you have done in xref:/midpoint/methodology/first-steps/connect-source-system/define-mapping-and-synchronization-rules/[] but since the AD is a target application, you need to tailor the settings accordingly; most notably, you will learn to create inbound mapping rules limited only to correlation. + +:sectnums: + +== Define synchronization rules + +Define the synchronization rules for the AD resource. +You can safely use the _Active_ lifecycle state even during testing as long as the whole AD resource is _proposed_. + +*Follow this guide: xref:/midpoint/reference/admin-gui/resource-wizard/object-type/synchronization/[]* + +[cols="2,1,1,1,4"] +|==== +| Name | Situation | Reaction | Lifecycle state | Comments + +| link-unlinked +| Unlinked +| Link +| Active +| There is a focus for the account but it is not linked to the shadow of the account yet, let us link it. + This is not used during the first import, but it is necessary for later when the account shadows are in midPoint already. + +| synchronize-linked +| Linked +| Synchronize +| Active +| Synchronize the data between the remote account and the focus based on mappings. + +| synchronize-deleted +| Deleted +| Synchronize +| Active +| Restore "illegally" deleted accounts on the resource using the shadow in midPoint. + +| delete-unmatched-resource-object +| Unmatched +| Delete resource object +| Draft +| Delete orphaned ("illegal") resource objects, i.e., those not present in HRIS and thus not having shadow in midPoint. + This is potentially destructive in case of misconfiguration. + + Keep in _Draft_ (effectively disabled) for now. + +| create-correlation-case-for-disputed +| Disputed +| Create correlation case +| Active +| In case a candidate owner is not found with 100% certainty, create a correlation case to let a human operator resolve the situation. + You will learn more about cases in a bit. + +|==== + +Refer to xref:/midpoint/reference/synchronization/introduction/[] for more details on the topic. + +== Create inbound mappings for correlation + +With inbound ("target") resources like the one for the Active Directory application we have here, you face a new challenge when you need to correlate accounts. +To successfully correlate accounts, you need _inbound_ mappings for the AD resource, i.e., _from_ the resource _to_ midPoint. +But the "regular" inbound mappings are not the best fit because you do not want to actually write the data from the resource to midPoint. + +That is why you are going to define a *new kind of mappings*: inbound mappings limited to correlation purposes. +MidPoint will use these mapping rules only to know which resource attribute to correlate with which _internal_ (focus) user attribute. + +*Follow these guides:* + +* xref:/midpoint/reference/admin-gui/resource-wizard/object-type/mapping/[]. +* xref:/midpoint/reference/admin-gui/resource-wizard/object-type/mapping/advanced-mappings/#advanced_inbound_mappings[] + +Use *inbound mappings* and set them to be *used for correlation only*. + +Define these mapping rules: + +[cols="2,1,1,1,1,5"] +|==== +| Name | Source | Expression | Target | Lifecycle state | Comments + +| inbound-employeeNumber-for-correlation +| `employeenumber` +| As is +| `personalNumber` +| Active +| Used for correlating employee number in the resource with the personal number in midPoint. + +| inbound-surname-for-correlation +| `sn` +| As is +| `familyName` +| Active +| Used for the second correlation rule when the default employee number correlation fails. + +| inbound-givenName-for-correlation +| `givenname` +| As is +| `givenName` +| Active +| Used for the second correlation. + +| inbound-locality-for-correlation +| `l` +| As is +| `locality` +| Active +| Used for the second correlation. + +|==== + +.Correlation-only inbound mappings for AD. Note the yellow icon:code-branch[role="yellow"] icons left of the rule names signifying the *Use for* limitation. +image::ldap-inbound-correlation-mappings.webp["Correlation-only inbound mappings for the AD resource"] + +== Define correlation rules + +Correlation in midPoint is a mechanism used to identify the owner of a resource object, such as an account. +It involves finding the right xref:/glossary/#focus[focal object] for a particular resource object. +This process essentially binds the xref:/glossary/#shadow[shadows] of the resource objects to their appropriate midPoint focal objects. + +Refer to xref:/midpoint/features/current/correlation/[] for more details on the topic. + +In general, to correlate objects from various resources, you need to *find a common identifier*. +In this guide, we use the employee numbers as the common identifier. +If an AD server entry has the same employee number as a user in midPoint, they are surely a match. + +For the cases when this bullet-proof matching fails due to erroneous data, +you can set up a *fallback correlation rule using an attribute combination*, such as first name + surname + locality. + +Fallback rules should not have as high *confidence* because there may be cases when two people of the same name are in the same place, for instance. +Lower-confidence correlation rules can be set to create produce *correlation cases*, +meaning they can only suggest which focus should be bound to which shadow, but a human operator needs to confirm the match. + +In the suggested setup below, the fallback rule using names and locality has the confidence of only 0.5. +That means that even if all the three attributes agree, the match would be only 50% sure and a correlation case would be created. + +*Follow this guide: xref:/midpoint/reference/admin-gui/resource-wizard/object-type/correlation/[]* + +Define these correlation rules: + +[cols="~,~,1,1,1,~"] +|==== +| Rule name | Description | Weight | Tier | Enabled | xref:/midpoint/reference/admin-gui/resource-wizard/object-type/correlation/#set-up-correlators[Correlators] (Item : Search method) + +| personalNumber-correlation +| Correlation using `personalNumber`. Does not require human intervention. +| +| 1 +| True +| `personalNumber` : Exact match + +| last-resort-correlation +| Correlation using givenName, familyName and locality. Trusted only by 50%, human intervention is needed. +| 0.5 +| 10 +| False +| `givenName` : Exact match + + `familyName` : Exact match + + `locality`: Exact match +|==== + +:sectnums!: + +== Next steps + +Having all the essential rules in place, you can now continue to reconcile the AD application accounts with what you already have in midPoint. + +[.nowrap]#icon:arrow-right[] *xref:/midpoint/methodology/first-steps/integrate-target-system/reconcile-ad-accounts/[]*# \ No newline at end of file diff --git a/midpoint/methodology/first-steps/integrate-target-system/delete-orphaned-accounts.adoc b/midpoint/methodology/first-steps/integrate-target-system/delete-orphaned-accounts.adoc new file mode 100644 index 000000000..2b554ab0e --- /dev/null +++ b/midpoint/methodology/first-steps/integrate-target-system/delete-orphaned-accounts.adoc @@ -0,0 +1,72 @@ += Delete orphaned Active Directory accounts +:page-nav-title: Delete orphaned AD accounts +:page-display-order: 250 +:page-toc: top +:experimental: +:icons: font +:page-description: Configure midPoint to eradicate orphaned and malicious target system accounts from the target AD application. + +When integrating the AD application into your new midPoint ecosystem, you found some AD accounts that are either leftovers of unknown purpose from the past or even obviously malicious attack attempts. +You have marked some of them for later resolution, but you kept the obviously malicious one unmarked because it should be removed from Active Directory for security reasons. + +== What awaits you in this module + +Previously, you have prepared but kept inactive a synchronization rule to delete orphaned accounts from the AD server. +In this module, you will activate this rule and eradicate any unmatched accounts without marks. + +You will, of course, simulate the effects of the change before activating the rule on production to see if it does not do anything destructive. +You need to be extra careful with these rules that delete objects on remote systems because, if misconfigured, they can be irreversibly destructive. + +In the future, when a similar "illegal" account without a counterpart in HRIS appears, midPoint will delete it during reconciliation. +And any legitimate accounts that are not in HRIS will need to be protected with marks. + +:sectnums: + +== Prepare resource-side account deletion for testing + +In xref:/midpoint/methodology/first-steps/integrate-target-system/define-rules-for-data-handling/#define-synchronization-rules[], you have created an AD synchronization rule called _delete-unmatched-resource-object_ to delete unmatched accounts. +You kept this rule in the _Draft_ lifecycle state to avoid deleting legitimate accounts before you ensure their preservation by marking them accordingly. + +Now that the marks are in place, you can safely activate the synchronization rule. +First, put it to the _Proposed_ lifecycle state to test it. + +*Follow this guide: xref:/midpoint/reference/admin-gui/resource-wizard/object-type/synchronization/[]* + +. In the AD resource synchronization rules, find the _delete-unmatched-resource-object_ rule. + ** It is the _Delete resource object_ reaction to the _Unmatched_ situation +. Set its lifecycle state to _Proposed_. + +.List of target AD resource synchronization rules with the delete-unmatched-resource-object now in the Proposed state +image::ldap-delete-unmatched-account-proposed-synchro-rule.webp[List of target AD resource synchronization rules with the delete-unmatched-resource-object now in the Proposed state] + +== Simulate behavior of the new configuration + +You are now ready to simulate the behavior the updated configuration before you put it to production. + +. Use the _Reconcile AD - development simulation_ reconciliation task you have set up and used in xref:/midpoint/methodology/first-steps/integrate-target-system/reconcile-ad-accounts/[]. +. Inspect the simulation results to see if the configuration behaves as expected. + +If you changed nothing else on the resource or in midPoint in the meantime, only the unmatched & unmarked accounts you need to get rid of are affected. +Verify the affected accounts are really the ones you want deleted. + +.Synchronization simulation results showing that one account would be deleted from the resource. +image::ldap-delete-unmatched-accounts-simulation-result.webp["Synchronization simulation results showing that one account would be deleted from the resource"] + +== Delete unwanted accounts from Active Directory + +Once tested and verified, activate the whole configuration on production. + +. Switch the lifecycle state of the _delete-unmatched-resource-object_ synchronization rule to _Active_. +. Run the _Reconcile AD - real production_ reconciliation task you have set up and used in xref:/midpoint/methodology/first-steps/integrate-target-system/reconcile-ad-accounts/[]. + +After the task finishes, check the accounts on the AD resource in midPoint—the unmatched & unmarked accounts, such as the malicious `cn=Secret Admin`, are no longer in the list. +You can also navigate to the link:http://localhost/phpldapadmin[training AD application user interface] (i.e., the LDAP server) and check the results there because for the first time now, you are making changes to the data in the target application. + +:sectnums!: + +== Next steps + +With the unwanted accounts evicted from Active Directory, you are one step closer to the clean and secure IGA setup you are striving for. +The next logical step is to enable data delivery to the target system which will then seamlessly lead you to automating your setup. + +[.nowrap]#icon:arrow-right[] *xref:/midpoint/methodology/first-steps/enable-target-system-provisioning/[]*# \ No newline at end of file diff --git a/midpoint/methodology/first-steps/integrate-target-system/import-usernames-from-ad.adoc b/midpoint/methodology/first-steps/integrate-target-system/import-usernames-from-ad.adoc new file mode 100644 index 000000000..e73bd2cfb --- /dev/null +++ b/midpoint/methodology/first-steps/integrate-target-system/import-usernames-from-ad.adoc @@ -0,0 +1,107 @@ += Import usernames from Active Directory +:page-nav-title: Import usernames from AD +:page-display-order: 240 +:page-toc: top +:experimental: +:icons: font +:page-description: Stop using the unfriendly employee numbers as usernames and import the AD usernames to make your deployment more accessible. + +When setting up the HRIS resource, you used employee numbers (`empnum`) for account names in midPoint +because the HR system does not have any better unique identifier. +Now that you have Active Directory connected, midPoint has access to more human-friendly usernames that are in AD. + +== What awaits you in this module + +In this module, you will use the AD usernames as new identifiers for the focal objects (users) in midPoint. + +. You will set the original HRIS mapping that fills the `name` attribute in midPoint focal objects with employee numbers as _weak_ to prevent it from overwriting the new usernames. +. You will create a new inbound mapping for AD that will copy the AD usernames to the `name` attribute. + You will make the new mapping strong to overwrite the original employee numbers in the attribute. +. As always, you will simulate reconciliation to verify the setup before you _activate_ it. + +[NOTE] +==== +In general, we use Active Directory in this guide as a target application, meaning we (will) write data to it rather than use it a data source. +In this particular case, though, Active Directory serves as a data source. +As we mentioned before, xref:/midpoint/methodology/first-steps/integrate-target-system/#every-coin-has-two-sides[no coin is one-sided]. +==== + +:sectnums: + +== Adjust the mappings to prepare for username import + +To use the AD usernames as the primary identifier for users in midPoint, you need to adjust mappings for both the HRIS and AD resources. + +=== Make the old HRIS name mapping weak + +Firstly, adjust the strenght of the HR resource _name_ mapping so that it does not overwrite non-empty values. +Refer to xref:/midpoint/reference/expressions/mappings/#_mapping_strength[] for details on mapping strength options. + +*Follow this guide: xref:/midpoint/reference/admin-gui/resource-wizard/object-type/mapping/advanced-mappings/#advanced_inbound_mappings[]* + +. In your HR resource, open inbound mapping settings. +. Locate the mapping populating the `name` attribute with the value of the source `empnum` attribute. + In this guide, it is called _empnum-to-name_. +. In advanced settings of the mapping, change its *strength* to _weak_. + +=== Add new mapping to AD for usernames + +Secondly, add a new inbound mapping for the `name` attribute in the AD resource. +Leave this mapping set as _strong_ so that it can overwrite existing values. +This is the default. + +. Look into your AD data and locate the name of the attribute that holds usernames. They have to be unique across all accounts. + + In the training data used in this guide, the name of the attribute is `uid`. +. In your AD resource, open inbound mapping settings. +. Add a new mapping according to the table below. + +[cols="3,1,1,1,2,4", options="header"] +.Strong inbound mapping to copy _uid_ parameter with usernames to _name_ parameter +|==== +| Name | Source | Expression | Target | Lifecycle state | Comments +| inbound-uid-username-to-name | `uid` | As is | `name` | Proposed | Keep the mapping *Strength* set to _Strong_ and the *Use for* option to _Undefined_. +|==== + +.AD resource inbound mappings, the proposed one being the one for importing usernames +image::ldap-username-import-inbound-mapping.webp["AD resource inbound mappings"] + +== Test the configuration update + +To check the behavior of your new configuration, use reconciliation tasks. +Since you have already reconciled the AD accounts earlier in this guide, you have the reconciliation tasks defined and available for reuse. + +* Refer to the xref:/midpoint/methodology/first-steps/integrate-target-system/reconcile-ad-accounts/[] module for a refresher on reconciliation tasks. + ** When you view the results of the simulation, you should see the _focus renamed_ note. +* Use the xref:/midpoint/reference/tasks/synchronization-tasks/import-and-reconciliation/gui/#simulate-import-of-a-single-object[import preview] functionality to simulate the effects of your configuration changes on a single account. +* Refer to xref:/midpoint/reference/tasks/synchronization-tasks/import-and-reconciliation/gui/[] for the guide on working with tasks in the graphical user interface. + +[NOTE] +==== +Make sure you run the reconciliation tasks on the AD resource. +==== + +.A single user import preview result showing that the username would be imported successfully and the focus object would be renamed +image::ldap-import-username-simulation-focus-renamed.webp["A single user import preview result showing that the username would be imported successfully and the focus object would be renamed"] + +== Rename users to AD usernames on production + +Once you confirm the simulation yields expected results, reconcile the accounts in production: + +. In AD mappings, change the lifecycle state for the _inbound-uid-username-to-name_ mapping from _Proposed_ to _Active_. +. Run the real production reconciliation task which you used to reconcile the AD accounts in xref:/midpoint/methodology/first-steps/integrate-target-system/reconcile-ad-accounts/[]. + +.List of midPoint users before the import of usernames from AD +image::ldap-username-import-before-rename.webp["List of midPoint users before the import of usernames from AD"] + +.List of midPoint users before and after the import of usernames from AD. Notice that their primary identifier (`name`) has changed to their respective AD usernames. +image::ldap-username-import-after-rename.webp["List of midPoint users after the import of usernames from AD. Notice that their primary identifier (`name`) has changed to their respective AD usernames."] + +:sectnums!: + +== Next steps + +You enabled importing nice usernames to midPoint thanks to the dynamic approach to resources midPoint can take when needed. +The next step to take in the journey of integrating the target system is to automatically remove orphaned and malicious accounts. +After that, you will learn how to provision data to Active Directory to fix wrong attribute values or tackle the joiner-mover-leaver process, for instance. + +[.nowrap]#icon:arrow-right[] *xref:/midpoint/methodology/first-steps/integrate-target-system/delete-orphaned-accounts/[]*# \ No newline at end of file diff --git a/midpoint/methodology/first-steps/integrate-target-system/index.adoc b/midpoint/methodology/first-steps/integrate-target-system/index.adoc new file mode 100644 index 000000000..f2ad12800 --- /dev/null +++ b/midpoint/methodology/first-steps/integrate-target-system/index.adoc @@ -0,0 +1,37 @@ += Integrate target system +:page-nav-title: 3. Integrate target system +:page-display-order: 200 +:experimental: +:icons: font + +After connecting the source application to midPoint, you can move on to a target application or system. +A target application is a resource that acts as a recipient of data _from_ midPoint. +It is not authoritative, yet it has data on the same accounts that you have imported _to_ midPoint from the source system. + +When a resource is not authoritative, it means that it cannot overwrite data in midPoint. +Moreover, midPoint is supposed to overwrite (read: rectify) the data on the resource if they happen to mismatch the data in midPoint. +This is useful in cases when someone creates an unauthorized ("illegal") account on the target system, for example. +Such an account needs to be deleted and midPoint does so as soon as it finds it, if instructed to do so. + +The target system in this guide is an LDAP server that mimics Active Directory. +We will refer to this system as Active Directory or AD henceforth. + +[[every-coin-has-two-sides]] +.No coin is one-sided +[TIP] +==== +Target systems may not be authoritative in general, +yet they sometimes contain data we do not have in other systems and need to pull them _into_ midPoint +rather than delete them on the resource as superfluous. + +In the case of this guide, it is be the situation with usernames. +We will read the usernames from the otherwise write-only non-authoritative AD application. +More on that in the modules about mappings and correlation rules. +==== + +== Next steps + +The initial steps to integrate a target system are the same as with the source system. +You will define the resource for the application to enable connection between midPoint and the remote system the application runs on. + +[.nowrap]#icon:arrow-right[] *xref:/midpoint/methodology/first-steps/integrate-target-system/connect-ad/[]*# \ No newline at end of file diff --git a/midpoint/methodology/first-steps/integrate-target-system/ldap-accounts-disputed-after-simulation.webp b/midpoint/methodology/first-steps/integrate-target-system/ldap-accounts-disputed-after-simulation.webp new file mode 100644 index 000000000..160119888 Binary files /dev/null and b/midpoint/methodology/first-steps/integrate-target-system/ldap-accounts-disputed-after-simulation.webp differ diff --git a/midpoint/methodology/first-steps/integrate-target-system/ldap-correlation-simulation-result-operational-statistics.webp b/midpoint/methodology/first-steps/integrate-target-system/ldap-correlation-simulation-result-operational-statistics.webp new file mode 100644 index 000000000..73479990d Binary files /dev/null and b/midpoint/methodology/first-steps/integrate-target-system/ldap-correlation-simulation-result-operational-statistics.webp differ diff --git a/midpoint/methodology/first-steps/integrate-target-system/ldap-delete-unmatched-account-proposed-synchro-rule.webp b/midpoint/methodology/first-steps/integrate-target-system/ldap-delete-unmatched-account-proposed-synchro-rule.webp new file mode 100644 index 000000000..2f0959bcc Binary files /dev/null and b/midpoint/methodology/first-steps/integrate-target-system/ldap-delete-unmatched-account-proposed-synchro-rule.webp differ diff --git a/midpoint/methodology/first-steps/integrate-target-system/ldap-delete-unmatched-accounts-simulation-result.webp b/midpoint/methodology/first-steps/integrate-target-system/ldap-delete-unmatched-accounts-simulation-result.webp new file mode 100644 index 000000000..ec103a0ff Binary files /dev/null and b/midpoint/methodology/first-steps/integrate-target-system/ldap-delete-unmatched-accounts-simulation-result.webp differ diff --git a/midpoint/methodology/first-steps/integrate-target-system/ldap-hris-correlation-case-workitem-resolution.webp b/midpoint/methodology/first-steps/integrate-target-system/ldap-hris-correlation-case-workitem-resolution.webp new file mode 100644 index 000000000..1ba1dc5a3 Binary files /dev/null and b/midpoint/methodology/first-steps/integrate-target-system/ldap-hris-correlation-case-workitem-resolution.webp differ diff --git a/midpoint/methodology/first-steps/integrate-target-system/ldap-import-username-simulation-focus-renamed-with-iteration.webp b/midpoint/methodology/first-steps/integrate-target-system/ldap-import-username-simulation-focus-renamed-with-iteration.webp new file mode 100644 index 000000000..defe0c9f4 Binary files /dev/null and b/midpoint/methodology/first-steps/integrate-target-system/ldap-import-username-simulation-focus-renamed-with-iteration.webp differ diff --git a/midpoint/methodology/first-steps/integrate-target-system/ldap-import-username-simulation-focus-renamed.webp b/midpoint/methodology/first-steps/integrate-target-system/ldap-import-username-simulation-focus-renamed.webp new file mode 100644 index 000000000..a559a58e4 Binary files /dev/null and b/midpoint/methodology/first-steps/integrate-target-system/ldap-import-username-simulation-focus-renamed.webp differ diff --git a/midpoint/methodology/first-steps/integrate-target-system/ldap-inbound-correlation-mappings.webp b/midpoint/methodology/first-steps/integrate-target-system/ldap-inbound-correlation-mappings.webp new file mode 100644 index 000000000..26308543d Binary files /dev/null and b/midpoint/methodology/first-steps/integrate-target-system/ldap-inbound-correlation-mappings.webp differ diff --git a/midpoint/methodology/first-steps/integrate-target-system/ldap-marked-accounts.webp b/midpoint/methodology/first-steps/integrate-target-system/ldap-marked-accounts.webp new file mode 100644 index 000000000..b1c2203b3 Binary files /dev/null and b/midpoint/methodology/first-steps/integrate-target-system/ldap-marked-accounts.webp differ diff --git a/midpoint/methodology/first-steps/integrate-target-system/ldap-outbound-activation-mappings-delayed-delete.webp b/midpoint/methodology/first-steps/integrate-target-system/ldap-outbound-activation-mappings-delayed-delete.webp new file mode 100644 index 000000000..1c745b427 Binary files /dev/null and b/midpoint/methodology/first-steps/integrate-target-system/ldap-outbound-activation-mappings-delayed-delete.webp differ diff --git a/midpoint/methodology/first-steps/integrate-target-system/ldap-resource-object-types.webp b/midpoint/methodology/first-steps/integrate-target-system/ldap-resource-object-types.webp new file mode 100644 index 000000000..add291900 Binary files /dev/null and b/midpoint/methodology/first-steps/integrate-target-system/ldap-resource-object-types.webp differ diff --git a/midpoint/methodology/first-steps/integrate-target-system/ldap-username-import-after-rename.webp b/midpoint/methodology/first-steps/integrate-target-system/ldap-username-import-after-rename.webp new file mode 100644 index 000000000..6974818ee Binary files /dev/null and b/midpoint/methodology/first-steps/integrate-target-system/ldap-username-import-after-rename.webp differ diff --git a/midpoint/methodology/first-steps/integrate-target-system/ldap-username-import-before-rename.webp b/midpoint/methodology/first-steps/integrate-target-system/ldap-username-import-before-rename.webp new file mode 100644 index 000000000..5319e09a6 Binary files /dev/null and b/midpoint/methodology/first-steps/integrate-target-system/ldap-username-import-before-rename.webp differ diff --git a/midpoint/methodology/first-steps/integrate-target-system/ldap-username-import-inbound-mapping.webp b/midpoint/methodology/first-steps/integrate-target-system/ldap-username-import-inbound-mapping.webp new file mode 100644 index 000000000..ffd40e48d Binary files /dev/null and b/midpoint/methodology/first-steps/integrate-target-system/ldap-username-import-inbound-mapping.webp differ diff --git a/midpoint/methodology/first-steps/integrate-target-system/reconcile-ad-accounts.adoc b/midpoint/methodology/first-steps/integrate-target-system/reconcile-ad-accounts.adoc new file mode 100644 index 000000000..6b4e6f359 --- /dev/null +++ b/midpoint/methodology/first-steps/integrate-target-system/reconcile-ad-accounts.adoc @@ -0,0 +1,207 @@ += Reconcile the Active Directory accounts +:page-nav-title: Reconcile AD accounts +:page-display-order: 230 +:page-toc: top +:experimental: +:icons: font +:page-description: Reconcile the Active Directory accounts with the data midPoint has from the HRIS to align AD with the HRIS. + +Reconcile the Active Directory accounts with the data midPoint has imported from HRIS to align AD accounts with their HRIS counterparts. +Use marks to label accounts that cannot be processed automatically, and resolve correction cases created where midPoint could not determine the account owners reliably. + +== What awaits you in this module + +You will bring your AD as close to the HRIS as possible. +You will first simulate reconciliation to test your configuration and see how close are your Active Directory data to what your HRIS claims to be true. + +When you analyze the simulation results, you will use account marks to prevent midPoint from deleting some accounts, such as service accounts that have no counterpart in HRIS. + +Once all valid accounts are either marked or correlated, you will reconcile AD on production and resolve the correlation cases that arise when midPoint cannot match some HRIS and AD accounts with 100% certainty. + +The production reconciliation will not delete any orphaned and malicious accounts because you have not yet activated the xref:/midpoint/methodology/first-steps/integrate-target-system/define-rules-for-data-handling/#define-synchronization-rules[synchronization rule] for that. + +:sectnums: + +== Simulate AD reconciliation + +To test your configuration, run a simulated reconciliation task on the development environment. + +*Follow this guide: xref:/midpoint/reference/tasks/synchronization-tasks/import-and-reconciliation/gui/[]* + +. In your AD resource, create a *Reconciliation Task*. +. Switch on the *simulation toggle*. +. Name the task, e.g., _Reconcile AD - development simulation_. +. On the *Execution* screen, select the _preview_ *mode* with the _development_ *configuration*. +. After you create the simulated reconciliation task, + run it and xref:/midpoint/reference/tasks/synchronization-tasks/import-and-reconciliation/gui/#read-simulation-results[inspect the simulation results] to see how your data handling rules work. + +When reviewing the simulation results in [.nowrap]#icon:chart-line[] *Operational statistics*#, you will see a result similar to the example below. + + +.Synchronization situation transitions +[cols="8*", options="header"] +|==== +| Original state | Synchronization start | Synchronization end | Exclusion reason | Succeeded | Failed | Skipped | Total +| No record | Unlinked | Linked | | 47 | 0 | 0 | 47 +| No record | Disputed | Disputed | | 3 | 0 | 0 | 5 +| No record | Unmatched | Unmatched | | 5 | 0 | 0 | 7 +|==== + +// Image not needed thanks to the tables, I think @dakle 2025-10-16 +// image::../ldap-correlation-simulation-result-operational-statistics.webp[title="Operational statistics of the simulated AD reconciliation task"] + +The numbers above say the following: + +* 47 accounts that were found on the resource are unlinked and would be linked, i.e., the account shadows would be linked to their respective focal objects (users in midPoint). +* 3 accounts cannot be correlated reliably (the `empnum` did not match, but the first name, surname, and locality did), so they are disputed and correlation case would be created. +* 5 accounts would stay unmatched because no focus object was found for them. + After you activate the xref:/midpoint/methodology/first-steps/integrate-target-system/define-rules-for-data-handling/#define-synchronization-rules[_delete-unmatched-resource-object_ synchronization rule], these accounts would be deleted from the AD resource. + +This was simulation so none of the reactions actually happened. + +[NOTE] +==== +The original state of accounts that midPoint has not yet ever seen is always _No record_. +Should you run the task again without changing anything, the original state will match the synchronization start from the previous reconciliation. +This only means that midPoint already knows about the accounts, so their original state is not _No record_ anymore. +The numbers stay the same. +==== + +== Mark unmatched accounts to prevent deletion + +Pay now closer attention to the *unmatched accounts*. +They are safe now because you have not yet activated the synchronization rule that would delete them, but you will, eventually, because that is the desired course of action for such accounts. + +The unmatched accounts can be service accounts with no HRIS counterpart, +legitimate normal accounts that contain multiple errors (e.g., wrong employee number and one of the names or the locality), +or they can be malicious or orphaned accounts that you actually want deleted. +You need to decide what to do with them individually, and that is what marking is for. + +Refer to xref:/midpoint/reference/concepts/mark/[] for more details on the topic. + +Here is a possible marking strategy to take: + +* No mark means the account will be deleted. +* _Correlate later_ mark is for valid accounts that cannot be correlated now due to erroneous data and you want to handle them later. +* _Do not touch_ mark is for accounts of unknown purpose or origin and need to investigate them. +* _Protected_ mark is for legitimate service accounts you need to keep with no HRIS counterpart. + +The point here is to mark the accounts you want to keep and move on with your deployment even if there are inconsistencies and unknowns in your data. +This way you get tangible results soon without having to wait for a solution to every obstacle. + +*Follow this guide: xref:/midpoint/reference/admin-gui/resource-wizard/object-type/policies/#simulations[Mark accounts after simulation]* + +Here are the marks to use on accounts in the MID-301 training data: + +[cols="5,2,4", options="header"] +|==== +| Account | Mark | Note +| `cn=Mail Service Account,ou=users,dc=example,dc=com` | Protected | Service account +| `cn=Secret Admin,ou=users,dc=example,dc=com` | _none_ | Malicious account to be deleted +| `cn=Spam Assassin Service Account,ou=users,dc=example,dc=com` | Protected | Service account +| `cn=Test123,ou=users,dc=example,dc=com` | Do not touch | Account of unknown purpose or origin; resolve later +|==== + +[TIP] +==== +Be careful if your HR system does not contain or export former employees data your target Active Directory system has data on. +In such situation, you would not have the former employees in midPoint and their AD accounts would appear as orphaned. +To keep such accounts, mark them. +==== + +Now, if you run the simulated reconciliation task again, +you would see a new entry in the [.nowrap]#icon:chart-line[] *Operational statistics*# table telling you how many unmatched accounts are _excluded_ and for what reason (you marked them). + +[cols="8*"", options="header"] +.Synchronization situation transitions +|==== +| Original state | Synchronization start | Synchronization end | Exclusion reason | Succeeded | Failed | Skipped | Total +| Unlinked | Unlinked | Linked | | 47 | 0 | 0 | 47 +| Disputed | Disputed | Disputed | | 3 | 0 | 0 | 3 +| Unmatched | No record | No record | Protected | 0 | 0 | 4 | 4 +| Unmatched | Unmatched | Unmatched | | 1 | 0 | 0 | 1 +|==== + +// https://youtu.be/GIlr7xYi8UI?t=326 +// TODO: improve the object marking GUIde + +=== Use filters to check account status and marks + +Aside viewing the task simulation results, you can use the resource account list to confirm your setup behaves as expected. +Even when you simulate reconciliation, the situations of the accounts in the list reflect the results of the simulation. + +. Under the AD resource, go to *icon:male[] Accounts*. +. Use the *Situation* menu above the account list to select an account state you wish to filter. +. Click icon:search[] btn:[Basic] to confirm the selected search criterion. + +The list also shows the marks on the accounts. +Using the menu at the far right of the account row, you can modify the marks. + +Use the btn:[×] button next to the *Situation* menu to clear the filter. + +.Account list showing unmatched accounts with marks +image::ldap-marked-accounts.webp["Account list showing unmatched accounts with marks"] + +== Reconcile your AD accounts + +Once you confirm that your AD configuration works as expected and you mark accounts as needed, +run the _real_ AD reconciliation. + +. Switch the *lifecycle state* of the AD resource to _Active_. + ** Ensure all the configurations are _active_ as well: + *** Mapping rules + *** Synchronization rules + **** Keep the _delete-unmatched-resource-object_ rule in _Draft_ until later. + *** Correlation rules + *** Object types +. Create a new reconciliation task, link:#simulate-ad-reconciliation[same as you did before]. + ** Switch on the *simulation toggle*. + ** Name the task, e.g., _Reconcile AD - production simulation_. + ** On the *Execution* screen, select the _preview_ *mode* with the _production_ *configuration*. + *** This production simulation is the last check as close to production as possible before you deploy. + ** Run the task and xref:/midpoint/reference/tasks/synchronization-tasks/import-and-reconciliation/gui/#read-simulation-results[inspect the results]. +. Lastly, create a new reconciliation task; this time, for production. + ** Keep the *simulation toggle* off. + ** Name the task, e.g., _Reconcile AD - real production_. + ** Run the production reconciliation task. + +The expected result of running the production reconciliation task is that: + +* All accounts that match "cleanly" between HRIS and AD are linked and their focal objects (users) have two projections now. +* MidPoint creates correlation cases for accounts it cannot reconcile with 100% certainty (e.g., when `empnum` differs in HRIS and AD). +* The accounts you need to get rid of (e.g., the hacker account in our data) are not yet deleted from the AD server. + +.User with two projections to the HRIS and AD systems +image::user-projections-hris-ad.webp["User with two projections to HRIS and AD systems"] + +== Resolve correlation cases + +As per your synchronization rules, if midPoint cannot reliably determine an AD account owner (focus), it sets the account as _disputed_ and creates a correlation case. + +In the case of this guide, when the `employeeNumber` AD attribute does not match the `empnum` HRIS attribute for an account, midPoint uses the _last-resort-correlation_ rule you have set up earlier and correlates the two connected with a lower certainty. +Accounts correlated like this are not linked automatically but are, according to the _create-correlation-case-for-disputed_ synchronization rule, rather presented in a correlation case to a human operator for a manual resolution. + +A correlation case is the way for you to efficiently find an owner for disputed accounts, particularly thanks to the suggestions from which you can select. + +*Follow this guide: xref:/midpoint/reference/correlation/correlation-cases/[]* + +.A correlation case workitems screen showing a suggested resource object owner candidate +image::ldap-hris-correlation-case-workitem-resolution.webp["A correlation case workitems screen showing a suggested resource object owner candidate"] + +.Resolving a correlation case does not correct the wrong data +[NOTE] +==== +In our training data, it is the CFO Anna Lopez with the employee number `1002`, who has a wrong number in Active Directory and, hence, does not get correlated automatically. +After you resolve her correlation case, her accounts are assigned correctly, yet her employee number does not get magically fixed in AD. +That will have to wait until later modules where you learn how to enable Active Directory provisioning. +==== + +:sectnums!: + +== Next steps + +You have reached another important milestone in your IGA journey and, should this be a real-world project for you in your organization, you have the next batch of tangible results to present to your peers. + +The next step is to move away from using employee numbers as usernames and introduce something more human-friendly. + +[.nowrap]#icon:arrow-right[] *xref:/midpoint/methodology/first-steps/integrate-target-system/import-usernames-from-ad/[]*# \ No newline at end of file diff --git a/midpoint/methodology/first-steps/integrate-target-system/user-projections-hris-ad.webp b/midpoint/methodology/first-steps/integrate-target-system/user-projections-hris-ad.webp new file mode 100644 index 000000000..a17b7b690 Binary files /dev/null and b/midpoint/methodology/first-steps/integrate-target-system/user-projections-hris-ad.webp differ diff --git a/midpoint/methodology/first-steps/kick-off.adoc b/midpoint/methodology/first-steps/kick-off.adoc deleted file mode 100644 index 49837100b..000000000 --- a/midpoint/methodology/first-steps/kick-off.adoc +++ /dev/null @@ -1,172 +0,0 @@ -= Methodology: First Steps With MidPoint: Kick-Off -:page-nav-title: 'Kick-Off' -:page-display-order: 100 -:page-toc: top -:experimental: - -.Goal -TIP: Assess your resources, capabilities and goals. -Set your target. -Decide whether the project is feasible. -Make a rough plan. -Get long-term support from management. -Secure budget. - -You have to start somewhere. -At this point, you probably have a very rough idea what you want to achieve. -However, all the details are missing. -The goal of this step is to fill some details in, make a plan, set up project structure and secure necessary resources. - -Start with a brainstorming or "kick-off" meeting. -Gather all the people in your organization interested in identity management. -This does not have to be a formal team. -The project is not formally established anyway. -Gather all the people that have something to say. - -You will probably need to engage following persons: - -* Senior IT engineer or an architect. -Identity management is touching many things, you want someone with broad perspective and IT experience. - -* Active Directory administrator, or an administrator of a critical IT systems that you want to manage. - -* Someone from HR, or any person that is somehow familiar with HR practices. -HR is going to be your information source, you need someone that can help you assess impact of HR practices on your project. - -* Security professional. -Identity management is intimately related to information security. -There may be policies, constraints and goals given by company security policy, which you should definitely consider in your plans. - -In fact, especially in smaller organizations, this can a "meeting" of just a couple of people over the cup of coffee. -This can be a series of meetings. -Do whatever suits your organizational culture the best. - -[TIP] -==== -The paragraphs below contain a lot of questions. -It is not an exhaustive list; there may be others. -You do not need to know all the answers before starting the project. -The questions are provided as starting points for discussion. -Yet, you need to know there will be questions that need to be answered eventually, in one of the iterations. -The answers to the questions (or lack of them) may influence the speed and quality of the project. -==== - -// TODO: should these questions be in Kick-off step or in Assessment? Or perhaps between them? When we iterate, we need to get back to the questions and try again, but the Big Picture does not go back to Kick-off step... - -// TODO: maybe we could provide explanation WHY we ask these questions. -// E.g. We ask about the situation with returning former employees so that we know if they are considered as complete new entities or if they should be "resurrected". - -The results of the initial meeting/kickoff/brainstorming should be: - -* Identify *data source*, which will probably be HR system. -Discuss the data the HR has, their scope and quality. -Do they have data on all employees? -Do they have also a data on contractors? -How and how often are the data updated and maintained. -E.g. how are records of new employees enrolled? -How are data of former employees handled? -Are the records deleted, marked as inactive, set a lay-off date or something else? -What is the unique identifier of HR record? -Is its uniqueness guaranteed? -What happens if former employees return to the organization again? Are they considered new record with new identifiers or are their original HR records reused? - -+ -You will probably get CSV export of HR data, or perhaps a database table/view. -Both are perfectly fine, at least for now. -Request a sample data from the HR people, to make sure data formats will work for you. -If possible, request several sample data exports from HR (e.g. daily, weekly) to see the trends in data (e.g. if it contains also former employees, approximate number of changes etc.) - -* Identify *data target*, which will probably be Active Directory (AD). -Discuss the structure of AD users with the administrator. -Are all the users in a single organizational unit in the AD? -Are there several organizational units? -How is the AD username created? -Are there any conventions to generate username? -Are there exceptions to these conventions? -Is there a reliable identifier stored somewhere in the user account? -Maybe an employee number is conveniently stored in `employeeNumber` attribute? -Have a look at live AD data, selecting few examples (such as your own account), roughly assessing the situation. -Compare that with the HR data sample. This may help you to see how much HR data is actually part of AD attributes, and you should have at least some data transformation ideas. -+ -Discuss the practices of creating an AD account. -Are there any special procedures or manual steps that take place? -How is the initial password set, how is it delivered to the user? -Is there a need to create a home directory, file share, mailbox? -What is the procedure to delete/archive account? -Discuss which steps would be nice to automate, and which are best left for manual action. - -* Discuss *security*. -Discuss the limitations, requirements and wishes given by the information security policies. -+ -Do not overdo it. -This is very important. -Security professionals tend to provide long lists of non-negotiable security requirements that need to be satisfied right now. -Do not get distracted to theoretical discussions of information security. -Discuss the practice, the current state, the day-to-day reality. -Be honest to yourself. -Do not pretend that you have perfect security while the reality is vastly different. -+ -Goal of identity management is to _improve real security_, not to pretend that the security is perfect while it is not. -Do not try to satisfy all the security requirements and requests immediately. -Make a plan to address the requirements in iterations. -It is too early to focus solely on security at this point. -Basing security on wrong data is no security anyway, it is just false sense of security. -You need to put your data back in line first, then built up from there. - -* Discuss other data targets (optional). -What other systems would you like to connect to your identity management deployment in the future? -Consider just the big picture for now. -You do not need to go to all the details. -Just roughly set the scope, listing and prioritizing the systems. -Although this kind of perspective is completely optional, it is a huge benefit for planning and budgeting. - -* Discuss *resources, timing and rough plan*. -Keep you plan realistic. -Identity management requires systematic approach, time and a lot of patience. -Too many projects have failed due to unrealistic plans and expectations. -Plan modest results, delivered in few weeks. -*Start with connecting your first source and target system(s) to achieve first results in days.* -Then proceed in iterations, delivering improvements every few weeks. -Prepare for a long run. -This is not a project, with a specific start and end. -This is a _program_. -It starts now, yet it has no end. -Discuss who will lead the program, what people will need to be involved, other resource that you will need. - -* Discuss *money*. -You will need money, even if you plan to do most of the work internally. -You will need training, assistance and support. -Plan a recurring budget, sustainable funding for many years to come. -Having a modest budget every year can lead to a successful identity management program. -Having a generous budget for year one and no budget after that is a certain way to an expensive failure. - -As we mentioned, you do not need to have all the answers to all the questions at this point. -We will get to that later. -What you need is an _overview_ of your situation. -It is perfectly OK to leave a lot of blank spaces in your plan now. -The important thing is to know that you have a lot of black spaces that need to be filled in later. - -Maybe you will need some time to get your plan straight. -Take your time. -Learn and explore in the meantime. -Do some read-up on identity management. -Watch videos. -Download midPoint and have some fun. -If you are a hands-on type, create a small prototype. -All of that will help you better understand your problems, and also the tools that you have at hand. -Gather your collaborators again, update your plan as necessary. - -Now comes the most important step. -*Talk to your management*. -Make sure that the management understands importance of identity management for your organization. -As identity management touches many parts of the IT infrastructure as well as business processes and organizational procedures, support from your management is critical for success. -You will also need time and money. -Make sure there are human resources and appropriate budget allocated for your project. -Do not exaggerate, do not oversell. -Provide honest plan and estimates, set realistic expectations. -Identity management is a long run, any kind of hype or exaggeration is very likely to backfire in the future. -Get a green light - for a long program, not just for a short project. - -Now, you are ready to go. - -You can continue to xref:assessment/[Assessment] step. \ No newline at end of file diff --git a/midpoint/methodology/first-steps/ldap-hris-correlation-case-list.webp b/midpoint/methodology/first-steps/ldap-hris-correlation-case-list.webp new file mode 100644 index 000000000..ff7a1bdf0 Binary files /dev/null and b/midpoint/methodology/first-steps/ldap-hris-correlation-case-list.webp differ diff --git a/midpoint/methodology/first-steps/ldap-outbound-activation-mappings.webp b/midpoint/methodology/first-steps/ldap-outbound-activation-mappings.webp new file mode 100644 index 000000000..02e8f4705 Binary files /dev/null and b/midpoint/methodology/first-steps/ldap-outbound-activation-mappings.webp differ diff --git a/midpoint/methodology/first-steps/ldap-outbound-mappings.webp b/midpoint/methodology/first-steps/ldap-outbound-mappings.webp new file mode 100644 index 000000000..9fb946b34 Binary files /dev/null and b/midpoint/methodology/first-steps/ldap-outbound-mappings.webp differ diff --git a/midpoint/methodology/first-steps/ldap-users-sample.csv b/midpoint/methodology/first-steps/ldap-users-sample.csv new file mode 100644 index 000000000..c3f88aa71 --- /dev/null +++ b/midpoint/methodology/first-steps/ldap-users-sample.csv @@ -0,0 +1,56 @@ +"dn","objectclass","ou","cn","displayname","employeenumber","givenname","initials","l","sn","title","uid","userpassword","st","roomnumber" +"ou=users,dc=example,dc=com","top | organizationalUnit","people | users","","","","","","","","","","","","" +"cn=Alexander Freeman,ou=users,dc=example,dc=com","inetOrgPerson","","Alexander Freeman","Alexander Freeman","1010","Alexander","AF","Fast River City","Freeman","Sales Representative","afreeman","{SSHA}7oe49dqK/ccuPILNCs2LFnAY9IdgV0vqjljCXw==","","" +"cn=Alice Baker,ou=users,dc=example,dc=com","inetOrgPerson","","Alice Baker","Alice Baker","1021","Alice","AB","White Stone City","Baker","Chief Recruiting Officer","abaker","{SSHA}nbiCSFRf7D89b9wZYLqzOKT6PBVHd4YY","Stone state","" +"cn=Amanda de Wries,ou=users,dc=example,dc=com","inetOrgPerson","","Amanda de Wries","Amanda de Wries","1030","Amanda","AD","Small Red Rock City","de Wries","Senior Consultant","adewries","{SSHA}nbiCSFRf7D89b9wZYLqzOKT6PBVHd4YY","Rocky State","" +"cn=Ana Lopez,ou=users,dc=example,dc=com","inetOrgPerson","","Ana Lopez","Ana Lopez","1002","Ana","AL","Hot Lava City","Lopez","CFO","alopez","{SSHA}nbiCSFRf7D89b9wZYLqzOKT6PBVHd4YY","Lava State","" +"cn=Andreas Baker,ou=users,dc=example,dc=com","inetOrgPerson","","Andreas Baker","Andreas Baker","9001","Andreas","AB","White Stone City","Baker","Export/Import Coordinator","abaker2","{SSHA}WnenEQBj0PTlEE9lJcpUzhD3X35QpX2i3DS1qA==","","" +"cn=Ashley Jackson,ou=users,dc=example,dc=com","inetOrgPerson","","Ashley Jackson","Ashley Jackson","1029","Ashley","AJ","Hot Lava City","Jackson","Contract Termination Specialist","ajackson","{SSHA}nbiCSFRf7D89b9wZYLqzOKT6PBVHd4YY","Lava State","" +"cn=Brad Carpenter,ou=users,dc=example,dc=com","inetOrgPerson","","Brad Carpenter","Brad Carpenter","102451","Brad","BC","Fast River City","Carpenter","Airborne Unit Coordinator","bcarpenter","{SSHA}nbiCSFRf7D89b9wZYLqzOKT6PBVHd4YY","Two River State","" +"cn=Brad Carpenter (bcarpent),ou=users,dc=example,dc=com","inetOrgPerson","","Brad Carpenter (bcarpent)","Brad Carpenter","1024","Brad","","Fast River City","Carpenter","Airborne Unit Coordinator","bcarpent","{SSHA}9BXy7Mji4dvRArGvprUKJWEj+j/oj1frkLyHZw==","","" +"cn=Brad Carpenter (bcarpent2),ou=users,dc=example,dc=com","inetOrgPerson","","Brad Carpenter (bcarpent2)","Brad Carpenter","1024","Brad","","Fast River City","Carpenter","Airborne Unit Coordinator","bcarpent2","{SSHA}xQqm+Xhh1HQ/VyoNHnq7/4kRafKy7s5ppqT51A==","","" +"cn=Brenda Itchy,ou=users,dc=example,dc=com","inetOrgPerson","","Brenda Itchy","Brenda Itchy","9007","Brenda","","Fat River City","Itchy","Accountant","britchy","{SSHA}jx1Dg6LTTwyhNZbFhNUQW+Mbtr06+f5E7ODJ1Q==","","" +"cn=Charles Whitehead,ou=users,dc=example,dc=com","inetOrgPerson","","Charles Whitehead","Charles Whitehead","1039","Charles","CW","Hot Lava City","Whitehead","Environment Adaptation Specialis","cwhitehe","{SSHA}nbiCSFRf7D89b9wZYLqzOKT6PBVHd4YY","Lava State","" +"cn=Clara Whiteherring,ou=users,dc=example,dc=com","inetOrgPerson","","Clara Whiteherring","Clara Whiteherring","9002","Clara","CW","White Stone City","Whiteherring","Export/Import Coordinator","cwhitehe2","{SSHA}hcKLJcYRRi+54CDJqkVzsYujIs0Y8qGlQbw1zQ==","","" +"cn=Clara Whiteherring (cwhitehe3),ou=users,dc=example,dc=com","inetOrgPerson","","Clara Whiteherring (cwhitehe3)","Clara Whiteherring","9003","Clara","CW","White Stone City","Whiteherring","Export/Import Coordinator","cwhitehe3","{SSHA}rD+TLke8azMmENBlpu3vaw97QqbARoKk3zXz+w==","","" +"cn=David Iverson,ou=users,dc=example,dc=com","inetOrgPerson","","David Iverson","David Iverson","1022","David","DI","Small Red Rock City","Iverson","Service Development Specialist","diverson","{SSHA}nbiCSFRf7D89b9wZYLqzOKT6PBVHd4YY","Rocky State","disabled" +"cn=Diane Davis,ou=users,dc=example,dc=com","inetOrgPerson","","Diane Davis","Diane Davis","1007","Diane","DD","Hot Lava City","Davis","Junior Consultant","ddavis","{SSHA}nbiCSFRf7D89b9wZYLqzOKT6PBVHd4YY","Lava State","" +"cn=Elisabeth Mason,ou=users,dc=example,dc=com","inetOrgPerson","","Elisabeth Mason","Elisabeth Mason","1008","Elisabeth","EM","Small Red Rock City","Mason","Accountant","emason","{SSHA}nbiCSFRf7D89b9wZYLqzOKT6PBVHd4YY","Rocky State","" +"cn=Ellen Jones,ou=users,dc=example,dc=com","inetOrgPerson","","Ellen Jones","Ellen Jones","1023","Ellen","EJ","Small Red Rock City","Jones","Contract Termination Specialist","ejones","{SSHA}nbiCSFRf7D89b9wZYLqzOKT6PBVHd4YY","Rocky State","" +"cn=Emanuel Young,ou=users,dc=example,dc=com","inetOrgPerson","","Emanuel Young","Emanuel Young","1005","Emanuel","EY","Hot Lava City","Young","Senior Specialist","eyoung","{SSHA}nbiCSFRf7D89b9wZYLqzOKT6PBVHd4YY","Lava State","disabled" +"cn=Emma Jones,ou=users,dc=example,dc=com","inetOrgPerson","","Emma Jones","Emma Jones","1027","Emma","EJ","Fast River City","Jones","Careers Advisor","ejones27","{SSHA}nbiCSFRf7D89b9wZYLqzOKT6PBVHd4YY","Two river State","" +"cn=Eva Mendez,ou=users,dc=example,dc=com","inetOrgPerson","","Eva Mendez","Eva Mendez","1037","Eva","EM","Hot Lava City","Mendez","Junior Consultant","emendez","{SSHA}nbiCSFRf7D89b9wZYLqzOKT6PBVHd4YY","Lava State","disabled" +"cn=Frank Usher,ou=users,dc=example,dc=com","inetOrgPerson","","Frank Usher","Frank Usher","1017","Frank","FU","White Stone City","Usher","Agent Recruitment Specialist","fusher","{SSHA}nbiCSFRf7D89b9wZYLqzOKT6PBVHd4YY","Stone State","" +"cn=Frederick Smith,ou=users,dc=example,dc=com","inetOrgPerson","","Frederick Smith","Frederick Smith","1040","Frederick","FS","Hot Lava City","Smith","Environment Adaptation Specialis","fsmith","{SSHA}nbiCSFRf7D89b9wZYLqzOKT6PBVHd4YY","Lava State","" +"cn=Geena Green,ou=users,dc=example,dc=com","inetOrgPerson","","Geena Green","Geena Green","31001","Geena","GG","Hot Lava City","Green","CEO","geena","{SSHA}nbiCSFRf7D89b9wZYLqzOKT6PBVHd4YY","Rocky State","" +"cn=Geena Green (ggreen),ou=users,dc=example,dc=com","inetOrgPerson","","Geena Green (ggreen)","Geena Green","1001","Geena","","Hot Lava City","Green","CEO","ggreen","{SSHA}RBfeOOPdPGkK/feavFd4dNT/8u8B1nMGEcRXXQ==","","" +"cn=Jacques Smith,ou=users,dc=example,dc=com","inetOrgPerson","","Jacques Smith","Jacques Smith","9004","Jacques","JS","White Stone City","Smith","Export/Import Coordinator","jsmith3","{SSHA}tGbaP2JujE6TWRLerUwJSFhDiZ8g9ACpZ0/9QA==","","" +"cn=Jane Anderson,ou=users,dc=example,dc=com","inetOrgPerson","","Jane Anderson","Jane Anderson","1016","Jane","JA","Hot Lava City","Anderson","Junior Consultant","janderso","{SSHA}nbiCSFRf7D89b9wZYLqzOKT6PBVHd4YY","Lava State","disabled" +"cn=Jennifer Jameson,ou=users,dc=example,dc=com","inetOrgPerson","","Jennifer Jameson","Jennifer Jameson","1031","Jennifer","JJ","Hot Lava City","Jameson","Senior Consultant","jjameson","{SSHA}nbiCSFRf7D89b9wZYLqzOKT6PBVHd4YY","Lava State","" +"cn=Jimmy Taylor,ou=users,dc=example,dc=com","inetOrgPerson","","Jimmy Taylor","Jimmy Taylor","1003","Jimmy","JT","Small Red Rock City","Taylor","Junior Consultant","jtaylor","{SSHA}nbiCSFRf7D89b9wZYLqzOKT6PBVHd4YY","Rockky State","disabled" +"cn=John Doe,ou=users,dc=example,dc=com","inetOrgPerson","","John Doe","John Doe","9006","John","","Fast River City","Doe","CXO","jdoe","{SSHA}jJCyY5PSB7Hvd0wQ+fSHiDfJGwuYJRmnAWkDAw==","","" +"cn=John Newman,ou=users,dc=example,dc=com","inetOrgPerson","","John Newman","John Newman","9005","John","","Fast River City","Newman","Junior Consultant","jnewman","{SSHA}XiADnSWpzoFvimtXI0iRPi9wrJhjQYOj2jioXw==","","disabled" +"cn=John Smith,ou=users,dc=example,dc=com","inetOrgPerson","","John Smith","John Smith","1019","John","JS","Hot Lava City","Smith","International Intervention Coordinator","jsmith","{SSHA}nbiCSFRf7D89b9wZYLqzOKT6PBVHd4YY","Lava State","" +"cn=John Smith-Walker,ou=users,dc=example,dc=com","inetOrgPerson","","John Smith-Walker","John Smith-Walker","1035","John","JS","White Stone City","Smith-Walker","Sales Representative","jsmithwa","{SSHA}nbiCSFRf7D89b9wZYLqzOKT6PBVHd4YY","Stone tate","" +"cn=Jonathan Taylor,ou=users,dc=example,dc=com","inetOrgPerson","","Jonathan Taylor","Jonathan Taylor","1028","Jonathan","JT","Fast River City","Taylor","Domestic Intervention Coordinator","jtaylor2","{SSHA}nbiCSFRf7D89b9wZYLqzOKT6PBVHd4YY","Two River State","" +"cn=Josef Zimmer,ou=users,dc=example,dc=com","inetOrgPerson","","Josef Zimmer","Josef Zimmer","1009","Josef","JZ","Hot Lava City","Zimmer","Sales Representative","jzimmer","{SSHA}nbiCSFRf7D89b9wZYLqzOKT6PBVHd4YY","Lava State","" +"cn=Joseph Smith,ou=users,dc=example,dc=com","inetOrgPerson","","Joseph Smith","Joseph Smith","1026","Joseph","JS","White Stone City","Smith","Expert Specialist","jsmith2","{SSHA}nbiCSFRf7D89b9wZYLqzOKT6PBVHd4YY","Stone State","" +"cn=Laura Shepherd,ou=users,dc=example,dc=com","inetOrgPerson","","Laura Shepherd","Laura Shepherd","1034","Laura","LS","Hot Lava City","Shepherd","Sales Representative","lshepher","{SSHA}nbiCSFRf7D89b9wZYLqzOKT6PBVHd4YY","Lava State","disabled" +"cn=Lucy Rider,ou=users,dc=example,dc=com","inetOrgPerson","","Lucy Rider","Lucy Rider","1015","Lucy","LR","Hot Lava City","Rider","HR Director","lrider","{SSHA}nbiCSFRf7D89b9wZYLqzOKT6PBVHd4YY","","" +"cn=Luise Callahan,ou=users,dc=example,dc=com","inetOrgPerson","","Luise Callahan","Luise Callahan","9000","Luise","LC","White Stone City","Callahan","Export/Import Coordinator","lcallaha","{SSHA}zdiGkJ8pPTIqLHq9qGRMVVgGmuxAUdKe1XhEtA==","","" +"cn=Mail Service Account,ou=users,dc=example,dc=com","inetOrgPerson","","Mail Service Account","","","Mail","","","Service Account","","mail-svc","{SSHA}nbiCSFRf7D89b9wZYLqzOKT6PBVHd4YY","","" +"cn=Maria Schmitt,ou=users,dc=example,dc=com","inetOrgPerson","","Maria Schmitt","Maria Schmitt","1036","Maria","MS","Hot Lava City","Schmitt","Junior Consultant","mschmitt","{SSHA}nbiCSFRf7D89b9wZYLqzOKT6PBVHd4YY","Lava State","" +"cn=Olaf Peterson,ou=users,dc=example,dc=com","inetOrgPerson","","Olaf Peterson","Olaf Peterson","1013","Olaf","OP","Hot Lava City","Peterson","CTO","opeterso","{SSHA}nbiCSFRf7D89b9wZYLqzOKT6PBVHd4YY","Lava State","" +"cn=Olivia Xander,ou=users,dc=example,dc=com","inetOrgPerson","","Olivia Xander","Olivia Xander","1020","Olivia","OX","Hot Lava City","Xander","Agent Recruitment Specialist","oxander","{SSHA}nbiCSFRf7D89b9wZYLqzOKT6PBVHd4YY","Lava State","disabled" +"cn=Patrick Anderson,ou=users,dc=example,dc=com","inetOrgPerson","","Patrick Anderson","Patrick Anderson","1032","Patrick","PA","Hot Lava City","Anderson","Negotiation Specialist","panderson","{SSHA}nbiCSFRf7D89b9wZYLqzOKT6PBVHd4YY","Lava State","" +"cn=Peter Hunter,ou=users,dc=example,dc=com","inetOrgPerson","","Peter Hunter","Peter Hunter","1004","Peter","PH","White Stone City","Hunter","HR Consultant","hunter","{SSHA}nbiCSFRf7D89b9wZYLqzOKT6PBVHd4YY","Stone State","" +"cn=Ricardo Pedroso,ou=users,dc=example,dc=com","inetOrgPerson","","Ricardo Pedroso","Ricardo Pedroso","1038","Ricardo","RP","Hot Lava City","Pedroso","Expert Accountant","rpedroso","{SSHA}nbiCSFRf7D89b9wZYLqzOKT6PBVHd4YY","Lava State","" +"cn=Robert Nelson,ou=users,dc=example,dc=com","inetOrgPerson","","Robert Nelson","Robert Nelson","1012","Robert","RN","Fast River City","Nelson","Service Development Specialist","rnelson","{SSHA}nbiCSFRf7D89b9wZYLqzOKT6PBVHd4YY","Two Rivrr State","" +"cn=Robert Riley,ou=users,dc=example,dc=com","inetOrgPerson","","Robert Riley","Robert Riley","1025","Robert","RR","Fast River City","Riley","Careers Advisor","rriley","{SSHA}nbiCSFRf7D89b9wZYLqzOKT6PBVHd4YY","Two River State","" +"cn=Sam Brown,ou=users,dc=example,dc=com","inetOrgPerson","","Sam Brown","Sam Brown","1018","Sam","SB","White Stone City","Brown","Agent Recruitment Specialist","sbrown","{SSHA}nbiCSFRf7D89b9wZYLqzOKT6PBVHd4YY","Stone State","" +"cn=Scott Hoover,ou=users,dc=example,dc=com","inetOrgPerson","","Scott Hoover","Scott Hoover","1033","Scott","SH","Fast River City","Hoover","Negotiation Specialist","shoover","{SSHA}nbiCSFRf7D89b9wZYLqzOKT6PBVHd4YY","Two River State","" +"cn=Spam Assassin Service Account,ou=users,dc=example,dc=com","inetOrgPerson","","Spam Assassin Service Account","","","Spam","","","Assassin","","spam-svc","{SSHA}nbiCSFRf7D89b9wZYLqzOKT6PBVHd4YY","","" +"cn=Test123,ou=users,dc=example,dc=com","inetOrgPerson","","Test123","Test123","","Test123","","","Test123","","test123","{SSHA}nbiCSFRf7D89b9wZYLqzOKT6PBVHd4YY","","" +"cn=Tom Walker,ou=users,dc=example,dc=com","inetOrgPerson","","Tom Walker","Tom Walker","1014","Tom","TW","White Stone City","Walker","Junior Consultant","twalker","{SSHA}nbiCSFRf7D89b9wZYLqzOKT6PBVHd4YY","Stone State","" +"cn=Victoria Violet,ou=users,dc=example,dc=com","inetOrgPerson","","Victoria Violet","Victoria Violet","1011","Victoria","VV","White Stone City","Violet","Sales Director","vviolet","{SSHA}nbiCSFRf7D89b9wZYLqzOKT6PBVHd4YY","Stone State","" +"cn=WWW Service Account,ou=users,dc=example,dc=com","inetOrgPerson","","WWW Service Account","","","WWW","","","Service Account","","www-svc","{SSHA}nbiCSFRf7D89b9wZYLqzOKT6PBVHd4YY","","" diff --git a/midpoint/methodology/first-steps/make-plan.adoc b/midpoint/methodology/first-steps/make-plan.adoc new file mode 100644 index 000000000..e6b6181ab --- /dev/null +++ b/midpoint/methodology/first-steps/make-plan.adoc @@ -0,0 +1,205 @@ += Make a deployment plan +:page-nav-title: 1. Plan your deployment +:page-display-order: 70 +:page-toc: top +:experimental: + +Now that you have a rough idea of what is an IGA project about, it is time to make a plan. + +Before you involve a broader spectrum of people in your organization, devise a rough idea of what you want to achieve and how it helps your organization. + +* Assess your resources, capabilities and goals. +* Set your target. +* Determine whether the project is feasible. +* Make a rough plan. +* Get long-term support from management. +* Secure budget. + +[TIP] +==== +Prepare a pitch-talk to explain clearly why it is a good idea to implement an IGA solution and why midPoint is your solution of choice. +==== + +The sections below contain guidance on how to select your advisory team, what questions to ask, and what to take care of. + +== Pick the team members + +Start with a brainstorming kick-off meeting. +Bring together all the people in your organization who are interested in identity management. +This does not have to be a formal team. +The project is not yet formally established anyway. + +Here are some tips on whom to invite: + +* A *senior IT engineer* or architect. +Identity management is related to many different areas. +You need someone who can see the big picture and understands IT. + +* *Administrator of a critical IT systems* with which you want to integrate midPoint. + +* A *member of HR* familiar with HR practices. +Usually, HR information system is to be your information source, so you need someone who can help you assess the impact of the HR practices on the IGA project. + +* A *security professional*. +Identity management and governance is closely related to information security. +There may be policies, limits, and goals given by company security policy you need to consider in your plans. + +In smaller organizations, this can be a meeting of just a couple of people over coffee. +It could be a series of meetings. +Do whatever suits the culture of your organization the best. + +== Topics for discussion + +Here is a list of topics you should discuss with your team. +You probably will not have all the answers after the first session. +That is OK. +It is important to know that these questions are there to be answered eventually. +The sooner you find the answers, the faster you will progress. + +=== What are your data sources? + +A data source is a system you can consider authoritative and from which you can pull data _into_ midPoint. + +You probably have many systems with identity data, but only some can be considered authoritative. +The HR information system (HRIS) is likely your first choice because its data usually are mostly correct and authoritative. + +In this guide, we use a simple resource that exports CSV files to act as an HR system. + +[CAUTION] +==== +*Do you have other reliable source systems?* +If so, could their data be in conflict? + +For example, one system might say that an employee's name is "John," while another system says it is "Johannes." + +In that case, which system do you trust? +==== + +==== Questions regarding data handling + +* How do you add records about new employees? + +* What happens with data of former employees? + ** Are the records deleted? + ** Do you keep them marked as inactive? + ** Do you only set a layoff date? + +* What is the unique identifier of each HR record? + ** Is it guaranteed to be unique? + ** Do all your systems share the identifier? + +* What happens if a former employee comes back to the organization? +Do you start over with a new ID or can you reuse the old records? + +Ask the HR department for some sample data to ensure the data formats work for you. + +If you can, request a few sample data exports (like daily or weekly) to see trends in the data: +For example, whether the exports include former employees, what's the approximate number of changes per period, etc. + +=== What are your data targets? + +As opposed to data sources, data targets are systems that hold identity data but are not authoritative. +Your goal is to _push_ data _from_ midPoint _to_ the target systems to ensure identity data consistency. + +The usual setup is that you mostly write to target systems and use the authoritative source systems to overwrite any conflicting data on targets. +Of course, this depends on your situation. +A *system may be both source and target*. +You will see further down the lane how to temporarily use a target system as a source for select attributes. + +[NOTE] +==== +In this guide, we simulate an Active Directory (AD) server using an LDAP server and use that as a target resource. +==== + +Whatever target systems you have, discuss their internal data structure with their administrators so that you know what you are going to work with in midPoint. + +For example, in the case of an Active Directory or LDAP server: + +* How are users distributed among *organizational units*? +* How are *usernames* created? + ** What is the convention for generating usernames? + ** Any exceptions to this convention? +* Is there a reliable *unique identifier* of user accounts? + ** Maybe an employee number, the same as in the source system? + +Look at the live target resource data, select a few samples (such as your own account), and assess the situation. +Then, compare the sample with the same account in the HRIS. +This will help you see the common attributes and figure out how to connect the accounts. + +Discuss *other data targets*. +What other systems would you like to connect to your identity management deployment in the future? +Consider just the big picture for now. +You don’t need to go into all the details. +Just roughly set the scope, listing and prioritizing the systems. +Although this step is completely optional, it helps a lot with planning and budgeting. + +=== How much security do you require? + +What security measures do you need to implement? +Discuss the limitations, requirements, and wishes given by your information security authorities. + +It is important to distinguish _requirements_ and _wishes_. + +Your security official will likely give you a long list of _hard requirements_ that _must_ be implemented _right now_. +That is understandable and all right. +However, in this phase, it is important that you do not get distracted by theoretical discussions of information security. + +You are undergoing this IGA project to improve _real_ security, clean up your data, and automate processes. +Not to implement false sense of security on data that are wrong and insecure anyway. +Discuss the practice, the current state, the day-to-day reality. +Be honest with yourself. + +Hear the long-term requirements, make a plan to address them, and focus on what's non-negotiable and _possible to implement_ right now. +The rest comes later. + +=== Plan your budget + +Discuss *resources, timing, and rough plan*. + +Keep your plan realistic. +Identity management requires: + +* Systematic approach +* Time +* Money +* A lot of patience + +Too many projects have failed due to unrealistic plans and expectations. + +Set modest goals that you can achieve in a few weeks. +*Start by connecting your first source and target systems to get first results in days.* +Then proceed in iterations, delivering improvements every few weeks. + +Discuss who will lead the project, who needs to be involved, what other resources you need. + +And most importantly, *prepare for a long run*. +This project does not have specific start and end dates. +It will be with you *from now to eternity*. + +Last but certainly not least, *discuss money*. + +You will need money, even if you plan to do most of the work internally. +You will need training, assistance and support. + +.Plan for recurring budget +[TIP] +==== +Having a modest budget every year can lead to a successful IGA program. +Having a generous budget for the first year and no budget after that is a certain way to an expensive failure. +==== + +== Get a buy-in from your management + +Once you develop a rough plan and estimates regarding required money and time, *go talk to your management*. +It is crucial to get their buy-in, get them to believe that your IGA mission is meaningful and that it makes sense to invest money in it. + +Do not oversell and exaggerate. +Provide honest plan and estimates, set realistic expectations. +Identity management is a long run, any kind of hype or exaggeration is very likely to backfire in the future. +Get a green light—for a long program, not just for a short project. + +And with that, you are ready to go. + +== Next steps + +[.nowrap]#icon:arrow-right[] *xref:/midpoint/methodology/first-steps/connect-source-system/[]*# \ No newline at end of file diff --git a/midpoint/methodology/first-steps/multiple-sources.adoc b/midpoint/methodology/first-steps/multiple-sources.adoc deleted file mode 100644 index 8617b9549..000000000 --- a/midpoint/methodology/first-steps/multiple-sources.adoc +++ /dev/null @@ -1,87 +0,0 @@ -= Methodology: First Steps With MidPoint: Handling multiple sources -:page-nav-title: 'Handling multiple sources' -:page-display-order: 130 -:page-toc: top -:experimental: - -In real deployment we often need to connect multiple source systems to get all necessary data to midPoint. - -Scenarios: - -== Additional source with no object (e.g. users) overlaps with other sources. -_For example, you can have source systems for employees and another system for external employees._ - -This scenario is very simple. -Just connect new source system in a same way as you have connected the very first one. -Since there are no overlaps, each system will be responsible for own set of objects and their properties. -Most likely you won't have the exact same attributes in both system, therefore you need to count with that when you are defining your outbound mappings. -Either you are fine with empty values (and expecting it during simulations evaluation), or you have a mapping script handling that. -Otherwise, there is no difference compared to scenario with only a single source system. - -== Source with same objects but containing additional attributes. -_For example, you have primary HR source with all users and their basic attributes and an addressbook source containing the same users and their email and telephone numbers.)_ - -In this scenario we want to correlate account from both system to the same object (typically user) in midPoint. -Make sure you have correct correlation rules for both source systems. -In practice, it might be hard to guarantee that user is first created in primary source systems, synchronized to midPoint and then created (and synchronized) in the secondary source. - -This can be handled in two ways: - -. Do not synchronize account from secondary source system until is will be synchronized from the primary one. -** Do not set any reaction for the *unmatched* situation in the resource synchronization settings. -** Set *unlinked* situation reaction to *link* to ensure the accounts for existing midPoint users will be linked. -** Set up both liveSync and reconciliation task for secondary resource. -LiveSync will skip account that cannot be linked at the moment (because midPoint user don't exist yet) and won't process them again unless there is a change on that account. Therefore, reconciliation running with reasonable period is needed. -+ -TIP: It's possible to configure synchronization from primary source system to trigger import of particular account from the secondary source during creation of the new user. -This is complex configuration far beyond The First Steps methodology. -+ -** _Note that users in midPoint will be initially created without the data from the secondary source system. -The data from secondary system will be added later by liveSync or reconciliation task. -Keep that in mind when evaluating simulations and designing your mappings and data flows._ - -+ -CAUTION: It might be complicated to automatically decide if *unmatched* account is only waiting for synchronization from primary source to create and user in midPoint to which this unmatched account will be linked or if this account is orphaned. - -. If the account in the secondary system is synchronized first, create user with minimal information in *draft* lifecycle state. -** Set *unmatched* situation reaction to *add focus* to create a new midPoint users if they don't exist yet. -** Set *unlinked* situation reaction to *link* to ensure the accounts for existing midPoint users will be linked. -** Set *weak* mapping for lifecycle state to set *draft* value. -This mapping will be overridden by strong lifecycle mapping in the primary source system. -** Add mappings for necessary attributes. -Don't forget to add mapping that will be used from correlation from the primary source system (e.g. mapping for personal number). - -+ -CAUTION: If a user will stay in draft state for too long and synchronization from primary source system is running, it's probably an orphaned account that should be handled. - -== Same objects are present in both source systems. -_For example a university scenario with source for employees and students where one person an be both student and employee._ - -CAUTION: This scenario is beyond The First Steps Methodology. -Even tough midPoint supports it, it requires complex configuration to handle it in its full complexity. -This section describes several approaches, but it might require detailed study of relevant features configuration options. - -* Make sure you have correct correlation rules for both source systems. -* It's recommended to use a single archetype (e.g. Person) for users from both systems. -You can use _Auxiliary archetypes_ to differentiate between them. -User might be created first with any of them and later needs to be properly correlated when he/she is created in the other source system. -* Set *unmatched* situation reaction to *add focus* to create a new midPoint users if they don't exist yet. -* Set *unlinked* situation reaction to *link* to ensure the accounts for existing midPoint users will be linked. -* You need to solve problem of merging same attributes (e.g. given name and family name) from source systems to midPoint properties. This is the most difficult part with several options: -. Set mapping strength for such attributes to *normal*. -In that case the last change will overwrite the old one. -Even though this might seem as a simple solution there might be some practical problem like lack of control on the result including reconciliation processes which are skipping such values. -Nevertheless, in some cases this might be practical solution for start and replace it by robust solution later. -See xref:/midpoint/reference/expressions/mappings/#_mapping_strength[mapping strength documentation] for details. -. Create xref:/midpoint/reference/schema/custom-schema-extension/[a custom schema extension] where you can store attributes from both source systems. -For example, you will have attributes like _studentGivenName_, _employeeGivenName_. Then, you will add mapping to your object template that will convert these extended attribute to standard midPoint schema base on your requirements. -For example, you might decide that data from the employee source system, if exists, will be preferred over data from the student system. -. Use experimental feature for xref:/midpoint/reference/correlation/multiple-identity-data-sources/[multiple identity data source]. -The principle it the same as the schema extension approach, but the configuration is more straightforward. -Read about xref:/midpoint/versioning/experimental/[experimental features] before using this approach. -. There are other options, like using conditional mappings with dynamic ranges, that might be preferred in certain situations. -Such options are situational and complex to be described specifically. Contact our support if you need help with such case. -* Don't forget the _lifecycle state_ user property needs to be merged base on state from both systems too. -* Note that it's impossible to simulate import from two sources at the same time. -You need to connect them one by one at least to correlate users. -When you have users correlated, you can simulate mappings from both sources by running simulated *recomputation* of users. diff --git a/midpoint/methodology/first-steps/outline-and-concept/adopt-midpoint.drawio.svg b/midpoint/methodology/first-steps/outline-and-concept/adopt-midpoint.drawio.svg new file mode 120000 index 000000000..671e765e3 --- /dev/null +++ b/midpoint/methodology/first-steps/outline-and-concept/adopt-midpoint.drawio.svg @@ -0,0 +1 @@ +../../../../why-evolveum/adopt-midpoint.drawio.svg \ No newline at end of file diff --git a/midpoint/methodology/first-steps/first-steps-idea.drawio b/midpoint/methodology/first-steps/outline-and-concept/first-steps-idea.drawio similarity index 100% rename from midpoint/methodology/first-steps/first-steps-idea.drawio rename to midpoint/methodology/first-steps/outline-and-concept/first-steps-idea.drawio diff --git a/midpoint/methodology/first-steps/first-steps-idea.png b/midpoint/methodology/first-steps/outline-and-concept/first-steps-idea.png similarity index 100% rename from midpoint/methodology/first-steps/first-steps-idea.png rename to midpoint/methodology/first-steps/outline-and-concept/first-steps-idea.png diff --git a/midpoint/methodology/first-steps/outline-and-concept/index.adoc b/midpoint/methodology/first-steps/outline-and-concept/index.adoc new file mode 100644 index 000000000..b5969ce93 --- /dev/null +++ b/midpoint/methodology/first-steps/outline-and-concept/index.adoc @@ -0,0 +1,5 @@ += Outline of the first steps guide and iterative approach concept +:page-nav-title: Outline & iterative concept +:page-display-order: 50 + +This is a placeholder page immediately redirected to the first article in the section. \ No newline at end of file diff --git a/midpoint/methodology/first-steps/outline-and-concept/iterative-concept.adoc b/midpoint/methodology/first-steps/outline-and-concept/iterative-concept.adoc new file mode 100644 index 000000000..9eb42c93e --- /dev/null +++ b/midpoint/methodology/first-steps/outline-and-concept/iterative-concept.adoc @@ -0,0 +1,57 @@ += Cyclic iterative approach concept +:page-nav-title: Iterative concept +:page-display-order: 57 +:experimental: +:icons: font + +The main concept behind this whole guide is the iterative cyclic approach. +It is about reaching your desired solution in a series of small steps. +Each step brings new value and improves the overal solution iteratively moving you toward your goal. + +image::first-steps-idea.png[steps in the iterative cyclic IGA implementation approach] + +* *Connect* a new system to midPoint. +At this step, you give midPoint the option to _read_ the data from the system and analyze them, possibly comparing them to what midPoint already has its database. + +* The *clean-up* step is aimed at improving data quality. +Data in disconnected systems may often be in a poor state. +Accounts have to be correlated, orphaned accounts disabled, data errors corrected. +MidPoint is built to help with that. + +* The *automate* step focuses on speeding up processes and improving efficiency. +Manual work can be automated, making the process faster, cheaper, and more reliable. +Onboarding (_joiners_) and offboarding (_leavers_) employees are the usual candidates for automation. + +Repeat these steps as long as they bring you tangible value. +In every loop, you connect more systems with more data, align the data, automate the process, and thus make your organization more resilient to usual human errors. + +You can repeat the iterations as many times as you need, with as big or small a scope as you need. +The goal is to bring together the data, processes, and policies. + +The number of iterations you perform during the first deployment is finite because your time and budget are finite. +However, the first go-live is not the end. +Your policies evolve, you implement new systems, your IT ecosystem develops. +That means the connect—clean-up—automate cycles will repeat over and over, endlessly. +But, on the bright side, their cost is going to decrease significantly over time. + +.Iterative approach to midPoint deployment +image::adopt-midpoint.drawio.svg[Diagram of the iterative approach to midPoint deployment] + +When it comes to identity management, *one size does not fit all*. +Some organizations need strict policies, perfect visibility, or high degree of automation. +Others are perfectly happy with just basic integration and automation, focusing rather on low cost of the solution. + +It is virtually impossible to plan an ideal identity management project right of the bat in all its breadth and depth. +Hence, the iterative approach. +You repeat a series of small steps, focusing on areas that need to be improved at that particular point. +This is the way to satisfy the requirements while keeping the costs reasonable. + +You can also watch this webinar to familiarize yourself with the approach and see a live demonstration: + +video::suo775ym_PE[youtube,title="First steps methodology webinar video"] + +== Next steps + +Now that you know what to expect, it is time to kick off your IGA project by making a deployment plan. + +[.nowrap]#icon:arrow-right[] *xref:/midpoint/methodology/first-steps/make-plan/[]*# \ No newline at end of file diff --git a/midpoint/methodology/first-steps/outline-and-concept/outline.adoc b/midpoint/methodology/first-steps/outline-and-concept/outline.adoc new file mode 100644 index 000000000..6a367dad6 --- /dev/null +++ b/midpoint/methodology/first-steps/outline-and-concept/outline.adoc @@ -0,0 +1,24 @@ += Outline of the first steps guide +:page-nav-title: Outline +:page-display-order: 54 +:experimental: +:icons: font +:page-moved-from: /midpoint/methodology/first-steps/outline-and-concept/ + +To go from greenfield to a functional midPoint deployment, you will go through the following steps: + +. Decide what is it exactly that you need. + ** Which systems do you need to connect to identity management (IDM)? + ** What level of security do you need? + ** Consider your budget for long-term IDM expenses. +. Connect and integrate your first source and target systems. +. Map account attributes. +. Clean up the data by fixing inconsistencies and handling orphaned accounts. +. Automate some processes, such as the joiner-mover-leaver (JML) process. + +== Next steps + +Before you get into the action, one important module remains: +Get acquainted with the iterative approach on which this guide builds. + +[.nowrap]#icon:arrow-right[] *xref:/midpoint/methodology/first-steps/outline-and-concept/iterative-concept/[]*# \ No newline at end of file diff --git a/midpoint/methodology/first-steps/override-incorrect-source-data/index.adoc b/midpoint/methodology/first-steps/override-incorrect-source-data/index.adoc new file mode 100644 index 000000000..c55a2d2cf --- /dev/null +++ b/midpoint/methodology/first-steps/override-incorrect-source-data/index.adoc @@ -0,0 +1,26 @@ += Override incorrect source data +:page-nav-title: 7. Rectify source data +:page-display-order: 600 +:experimental: +:icons: font +:page-description: Sometimes, you may need to manually take over the target systems and overwrite the data coming from the source system. This sections explains how to go about it. + +In the beginning, there was the Single Source of Truth… + +[quote] +One source to rule them all, + +one source to find them, + +once source to bring them all, + +and in the truthfulness bind them. + +You have configured midPoint so that all data incongruent with the source system are overwritten and rectified to establish all-encompassing consistency. + +But one day, you have found yourself in need of denying the source system the power over all, take the situation into your own hands, and rewrite attributes in a target system to values different than the _Truth_ coming from the Single Source of Truth. + +On that day—it was a rainy Friday evening—an employee went rogue. +The malicious user had to be deactivated right away. +It was out of question to wait till Monday when the people from HR would come to work and deactivate him in the HR system properly. +It had to be done _now_. +Fortunately, an IT admin was still on duty to handle the situation. + +Head over to the module on xref:/midpoint/methodology/first-steps/override-incorrect-source-data/override-user-status/[overriding malicious user status] to learn how the story develops. \ No newline at end of file diff --git a/midpoint/methodology/first-steps/override-incorrect-source-data/ldap-account-disabled-attribute-roomnumber.webp b/midpoint/methodology/first-steps/override-incorrect-source-data/ldap-account-disabled-attribute-roomnumber.webp new file mode 100644 index 000000000..eb8f16dfb Binary files /dev/null and b/midpoint/methodology/first-steps/override-incorrect-source-data/ldap-account-disabled-attribute-roomnumber.webp differ diff --git a/midpoint/methodology/first-steps/override-incorrect-source-data/midpoint-account-with-wrong-source-data-marked-invalid-data.webp b/midpoint/methodology/first-steps/override-incorrect-source-data/midpoint-account-with-wrong-source-data-marked-invalid-data.webp new file mode 100644 index 000000000..c81f533e1 Binary files /dev/null and b/midpoint/methodology/first-steps/override-incorrect-source-data/midpoint-account-with-wrong-source-data-marked-invalid-data.webp differ diff --git a/midpoint/methodology/first-steps/override-incorrect-source-data/midpoint-account-with-wrong-source-data-set-marks.webp b/midpoint/methodology/first-steps/override-incorrect-source-data/midpoint-account-with-wrong-source-data-set-marks.webp new file mode 100644 index 000000000..3cf216a12 Binary files /dev/null and b/midpoint/methodology/first-steps/override-incorrect-source-data/midpoint-account-with-wrong-source-data-set-marks.webp differ diff --git a/midpoint/methodology/first-steps/override-incorrect-source-data/midpoint-audit-log-administrative-status-change-triggers-ldap-attribute-provisioning-detail.webp b/midpoint/methodology/first-steps/override-incorrect-source-data/midpoint-audit-log-administrative-status-change-triggers-ldap-attribute-provisioning-detail.webp new file mode 100644 index 000000000..a2401deb1 Binary files /dev/null and b/midpoint/methodology/first-steps/override-incorrect-source-data/midpoint-audit-log-administrative-status-change-triggers-ldap-attribute-provisioning-detail.webp differ diff --git a/midpoint/methodology/first-steps/override-incorrect-source-data/midpoint-audit-log-administrative-status-change-triggers-ldap-attribute-provisioning.webp b/midpoint/methodology/first-steps/override-incorrect-source-data/midpoint-audit-log-administrative-status-change-triggers-ldap-attribute-provisioning.webp new file mode 100644 index 000000000..ae36c1556 Binary files /dev/null and b/midpoint/methodology/first-steps/override-incorrect-source-data/midpoint-audit-log-administrative-status-change-triggers-ldap-attribute-provisioning.webp differ diff --git a/midpoint/methodology/first-steps/override-incorrect-source-data/midpoint-dashboard-object-marks.webp b/midpoint/methodology/first-steps/override-incorrect-source-data/midpoint-dashboard-object-marks.webp new file mode 100644 index 000000000..81be40edf Binary files /dev/null and b/midpoint/methodology/first-steps/override-incorrect-source-data/midpoint-dashboard-object-marks.webp differ diff --git a/midpoint/methodology/first-steps/override-incorrect-source-data/midpoint-inappropriate-username.webp b/midpoint/methodology/first-steps/override-incorrect-source-data/midpoint-inappropriate-username.webp new file mode 100644 index 000000000..69bd1c7c5 Binary files /dev/null and b/midpoint/methodology/first-steps/override-incorrect-source-data/midpoint-inappropriate-username.webp differ diff --git a/midpoint/methodology/first-steps/override-incorrect-source-data/midpoint-preview-change-username.webp b/midpoint/methodology/first-steps/override-incorrect-source-data/midpoint-preview-change-username.webp new file mode 100644 index 000000000..c5f59f951 Binary files /dev/null and b/midpoint/methodology/first-steps/override-incorrect-source-data/midpoint-preview-change-username.webp differ diff --git a/midpoint/methodology/first-steps/override-incorrect-source-data/midpoint-user-set-administrative-status-to-disabled.webp b/midpoint/methodology/first-steps/override-incorrect-source-data/midpoint-user-set-administrative-status-to-disabled.webp new file mode 100644 index 000000000..8ccc8fbb1 Binary files /dev/null and b/midpoint/methodology/first-steps/override-incorrect-source-data/midpoint-user-set-administrative-status-to-disabled.webp differ diff --git a/midpoint/methodology/first-steps/override-incorrect-source-data/midpoint-user-with-wrong-source-data-inactive.webp b/midpoint/methodology/first-steps/override-incorrect-source-data/midpoint-user-with-wrong-source-data-inactive.webp new file mode 100644 index 000000000..fd13dfd9d Binary files /dev/null and b/midpoint/methodology/first-steps/override-incorrect-source-data/midpoint-user-with-wrong-source-data-inactive.webp differ diff --git a/midpoint/methodology/first-steps/override-incorrect-source-data/override-incorrect-source-attribute-values.adoc b/midpoint/methodology/first-steps/override-incorrect-source-data/override-incorrect-source-attribute-values.adoc new file mode 100644 index 000000000..bfdf43862 --- /dev/null +++ b/midpoint/methodology/first-steps/override-incorrect-source-data/override-incorrect-source-attribute-values.adoc @@ -0,0 +1,157 @@ += Temporarily rectify incorrect source data +:page-nav-title: Rectify source data +:page-display-order: 620 +:page-toc: top +:experimental: +:icons: font +:page-description: Amend source system data temporarily in midPoint and enable incorrectly disabled user accounts + +In this module, you will use midPoint to amend source system data temporarily and enable incorrectly disabled user accounts. + +Imagine the following situation: The HR department creates a user in the HRIS with some errors, e.g., incorrect locality and status. +You cannot wait until the user is fixed in the HRIS. +The user is a new member of high management who needs to work, which he cannot because his account is kept inactive due to those errors. + +== What awaits you in this module + +You will first act as an inattentive HR person adding a new employee with wrong data in the HR system. +Then, as an administrator, you will take steps to rectify the mistakes and let the employee to use his accounts. +Lastly, you are going to fix the data issues in the HRIS and have the user reconcile "as usual". + +In this exercise, you will learn how to use account marks when you need to amend data coming from an authoritative resource and prevent the scheduled reconciliation task from reverting your edits. + +:sectnums: + +== Register new user in HRIS + +First, you need to register the new hire in HRIS. +You are going to make a few mistakes there, acting as the inattentive HR person. + +. In the link:http://localhost/hr/[HRIS user interface], click btn:[Register user] in the top bar. +. Fill in the form: + ** *First name*: _John_ + ** *Surname*: _Doe_ + ** *Employee number*: _9006_ + ** *Locality*: _Fat Rover City_ + ** *Job*: _999#CXO_ + ** *EmpType*: _FTE_ + ** *Status*: _Long-term leave_ +. Click btn:[Register user] +. Click btn:[Export users to csv file] at the bottom of the user list. + +== Check the new user in midPoint + +After the recurring HRIS reconciliation task runs: + +. In [.nowrap]#icon:user[] *Users*# > [.nowrap]#icon:user[] *Personas*#, open _John Doe_ (user _jdoe_) for editing. +. Check the user's *Lifecycle state*: It is _Disabled_. +. Check the user's AD account in [.nowrap]#icon:male[] *Projections*#: It is disabled. + +Obviously, this man cannot do his job when all his accounts are disabled. + +.User with wrong source data in midPoint +image::midpoint-user-with-wrong-source-data-inactive.webp["User profile screen in midpoint showing with wrong source data"] + +== How to fix it? + +Changing the *administrative status* would not work in this case because currently, the administrative status can only be used to _deactivate_ an active user. +You cannot use it to force activation. + +An attempt to blindly overwrite the lifecycle state would not work either. +It would be reverted during the next scheduled HRIS reconciliation task run. + +That means you need to create an exception. +But how? + +Use marks. + +== Mark the account as an exception + +Similarly to what you did when reconciling the HRIS accounts with the AD accounts, you can use marks to "protect" an account in this case as well. + +. In [.nowrap]#icon:database[] *Resources*# > [.nowrap]#icon:database[] *All resources*#, select the source HRIS resource. +. In [.nowrap]#icon:male[] *Accounts*#, find the user in question: _John Doe_ (_jdoe_) in our case. +. Click the drop-down menu button btn:[▼] at the far right of the row and select *Add Marks*. ++ +.Set marks on the account for which you need to correct data manually in midPoint +image::midpoint-account-with-wrong-source-data-set-marks.webp["Set marks on the account for which you need to correct data manually in midPoint"] + +. In the modal dialog that appears, select *Invalid data*. +. Click btn:[Add]. + +The account is now "protected", i.e., the recurring HRIS reconciliation task will not touch it and you can edit it manually in midPoint. + +.Account with invalid data marked for protection +image::midpoint-account-with-wrong-source-data-marked-invalid-data.webp["Account with invalid data marked for protection"] + +== Correct the data manually + +Still in the [.nowrap]#icon:male[] *Accounts*# screen, click _jdoe_ in the owner column to open the corresponding focal object of the account for editing. + +Edit the following properties to correct the mistakes the HR department made: + +. *Locality*: _Fast River City_ +. *Lifecycle state*: _Active_ +. Click [.nowrap]#icon:save[] btn:[Save]#. + +The focal object (user) has now correct attribute values and the AD account is enabled immediately. + +Wait for the next scheduled HRIS reconciliation task to see that your changes are not reverted. +You can also verify that any updates of the HR data for the employee number 9006 are ignored + +=== Use reports to get a quick overview of marked accounts + +Dashboards and reports are very useful in larger deployments to get an overview of irregularities, such as marked accounts, quickly. +If you follow this guide along with the Docker images preconfigured for the guide, there is a dashboard ready for this situation. + +In the main navigation menu, select [.nowrap]#icon:tachometer-alt[] *Dashboards*# > *Account marks*: + +.Dashboard showing numbers of accounts with various object marks +image::midpoint-dashboard-object-marks.webp["Dashboard showing numbers of accounts with various object marks"] + +If you prefer a report you can save on your computer: + +. Select [.nowrap]#icon:chart-pie[] *Reports*# in the main navigation menu. +. On the *Account Marks Dashboard Report* entry, click [.nowrap]#icon:play[] btn:[Run]# button at the far right. + ** This is a report directly connected to the dashboard. +. Click *Show task* in the notification that appears at top of the screen. +. Click btn:[Download report] to save the HTML report to your computer. + +You can access created reports at a later time via [.nowrap]#icon:chart-pie[] *Reports*# > [.nowrap]#icon:circle[] *Created reports*#. + +Refer to xref:/midpoint/reference/admin-gui/dashboards/[] to learn more about dashboards and their relation to reports. + +== Correct the HRIS data to put the situation back to normal + +You used emergency means to correct the incorrect attributes in midPoint while preventing the recurring HRIS reconciliation task from overwriting your adjustments. +At some point, the HR personnel obtains the complaint regarding their mistake, and rectify the incorrect HRIS data. +Additionally, they realize the correct locality is completely different than what they put there in the first place. + +Fix the data in HRIS: + +. In the HRIS user interface, find the user _John Doe_, employee number _9006_. +. Click btn:[Modify] at the right side of their row. +. Adjust the attributes of the user: + ** *Locality*: _White Stone River_ + ** *Status*: _In_ +. Click btn:[Modify user]. +. Click btn:[Export users to csv file] at the bottom of the user list. + +The updates from HR are ignored for this user until you remove the _Invalid data_ mark. + +. In [.nowrap]#icon:database[] *Resources*# > [.nowrap]#icon:database[] *All resources*#, select the source HRIS resource. +. In [.nowrap]#icon:male[] *Accounts*#, find the user in question: _John Doe_ (_jdoe_). +. Click the drop-down menu button btn:[▼] at the far right of the row and select *Remove Marks*. +. Select the *Invalid data* mark. +. Click btn:[Remove Marks]. + +In John Doe's profile and his AD account, you can observe the locality changes to _White Stone City_ after the scheduled reconciliation task runs, meaning the account can be managed by the usual means from now on. + +:sectnums!: + +== Next steps + +The last module in the series on overwriting incorrect source data focuses on the automatically generated usernames. +You will learn why you might want to override the automation and how to do it correctly. + +[.nowrap]#icon:arrow-right[] *xref:/midpoint/methodology/first-steps/override-incorrect-source-data/override-usernames/[]*# \ No newline at end of file diff --git a/midpoint/methodology/first-steps/override-incorrect-source-data/override-user-status.adoc b/midpoint/methodology/first-steps/override-incorrect-source-data/override-user-status.adoc new file mode 100644 index 000000000..3bf656922 --- /dev/null +++ b/midpoint/methodology/first-steps/override-incorrect-source-data/override-user-status.adoc @@ -0,0 +1,80 @@ += Override malicious user status +:page-nav-title: Override user status +:page-display-order: 610 +:page-toc: top +:experimental: +:icons: font +:page-description: Override the source system user status to force-disable the user's AD account + +The first task in the series of overriding source data is to force-disable a user's account regardless of the user's status in the source HR system. +The goal is to prevent the user from accessing target systems—in the case of this guide, Active Directory. + +== What awaits you in this module + +. Pick an active user, i.e., a user whose `status` in the HRIS equals to `In`. +. Find the user in midPoint and set the user's *administrative status* to _Disabled_. +. Verify the effect of you action on the user's AD account. + +== About administrative status + +The xref:/midpoint/reference/concepts/activation/#administrative-status[administrative status] defines an explicit decision of midPoint administrator about the status of a user. +As such, it overrides all other constraints on activation, including the lifecycle state we use in this guide to determine who is eligible to an AD account. +For this reason, the administrative status is the go to property for disabling a user under an emergency situation because it does not get overwritten by any mapping like the xref:/midpoint/methodology/first-steps/connect-source-system/define-mapping-and-synchronization-rules/#map-user-data[lifecycle state would] in our case. + +.Effective status vs. administrative status +[TIP] +==== +xref:/midpoint/reference/concepts/activation/#effective-status[ Effective status ] is a virtual status, a computed combination of all constraints on an object activation. +It cannot be set directly, it depends on the `validFrom` and `validTo` attributes, the lifecycle state, or administrative status. +If any of the constraints affecting the effective status says the account should be disabled, the effective status changes to _Disabled_. +That is what you see in the GUI at top of the user profile. +The administrative status is, under normal circumstances, _Undefined_, meaning it does not affect the effective status anyhow. +==== + +:sectnums: + +== Set administrative status for a user + +For this exercise, let us say that the contract termination specialist Ashley Jackson is the user you need to disarm immediately. + +. In [.nowrap]#icon:user[] *Users*# > [.nowrap]#icon:user[] *Persons*#, open _Ashley Jackson_ (user _ajackson_) for editing. +. Select [.nowrap]#icon:recycle[] *Activation*# on the left. +. Click *Show empty fields* if you do not see any fields to edit. +. In *Administrative status*, select _Disabled_. +. Click [.nowrap]#icon:save[] btn:[Save]#. + +.Set administrative status for Ashley Jackson +image::midpoint-user-set-administrative-status-to-disabled.webp["Set administrative status for Ashley Jackson"] + +The effect of this action is immediate. +Changing the administrative status of a user triggers update according to the policies and rules you have set all across the ecosystem, meaning the update propagates to the AD server without having to wait for the next scheduled reconciliation. + +== Verify the effect of administrative status change + +To confirm the effect of you setting the administrative status, select [.nowrap]#icon:magnifying-glass-chart[] *Audit Log Viewer*# to head over to the audit log, and see the three related events there (request, resource, execution). + +.Changing the administrative status to Disabled triggers disabling the user in the target AD application +image::midpoint-audit-log-administrative-status-change-triggers-ldap-attribute-provisioning.webp["Audit log screen with events showing the effects of changing the administrative status to Disabled which triggers disabling the user in the target AD application"] + +Click the time stamp on the *Resource* entry in the audit log to see the exact change your action caused: + +.The mapping rules in effect translate effective status _Disabled_ to the `roomNumber` resource attribute value `disabled` +image::midpoint-audit-log-administrative-status-change-triggers-ldap-attribute-provisioning-detail.webp["Audit log screen showing the effects of the administrative status change - the mapping rules in effect translate effective status Disabled to the roomNumber resource attribute Disabled"] + +You can check directly on the AD resource that your change of the administrative status provisioned Ashley Jackson the `disabled` value into the `roomNumber` attribute, effectively barring her from accessing Active Directory. + +.The attribute `roomNumber` with the value `disabled` has been provisioned to the AD account of the user disabled by the administrative status +image::ldap-account-disabled-attribute-roomnumber.webp["Attribute roomNumber with the value disabled has been provisioned to the account of the user disabled by the administrative status"] + +:sectnums!: + +== How to revert the changes made by administrative status + +Should you need to enable the user and take all the disabling action back, change the *Administrative status* attribute back to _Undefined_. +The effective status then gets calculated based on all the "usual" policies and rules, and re-enables the user's account if nothing else says it should not be enabled. + +== Next steps + +In the next module, you will learn how to manage the situation when the information in the HRIS is wrong and you need to address the issue before the HR personnel can handle it the standard way. + +[.nowrap]#icon:arrow-right[] *xref:/midpoint/methodology/first-steps/override-incorrect-source-data/override-incorrect-source-attribute-values/[]*# \ No newline at end of file diff --git a/midpoint/methodology/first-steps/override-incorrect-source-data/override-usernames.adoc b/midpoint/methodology/first-steps/override-incorrect-source-data/override-usernames.adoc new file mode 100644 index 000000000..4ed5b967b --- /dev/null +++ b/midpoint/methodology/first-steps/override-incorrect-source-data/override-usernames.adoc @@ -0,0 +1,92 @@ += Override usernames +:page-nav-title: Override usernames +:page-display-order: 630 +:page-toc: top +:experimental: +:icons: font +:page-description: Replace automatically generated username when automation creates it offensive + +Imagine a situation where the automated username generator creates a username that is inappropriate. +That can happen because the generator takes the first given name letter and combines it with (a part of) the surname. +The result may be or resemble an insulting or offensive word. +That is the situation you are about to face and learn handling in this module. + +== What awaits you in this module + +You will create a user with a "problematic" name-surname combination in the HRIS. +Once the HRIS reconciliation task synchronizes the user into midPoint, the _Person Object Template_ mapping script creates a username for the user in the `jsmith82` format. +You will promptly see that the user cannot go by the automatically generated username. +Thus, you will override it manually and see how your configuration is prepared for such an intervention. + +:sectnums: + +== Create new user to test with + +We do not have an "inappropriate" names combination in the sample data prepared for this guide. +Thus, you need to first create a new user: + +. In the link:http://localhost/hr[HRIS user interface], click btn:[Register user] in the top bar. +. Fill in the form: + ** *First name*: _Samuel_ + ** *Surname*: _Hits_ + ** *Employee number*: _9007_ + ** *Locality*: _Fast River City_ + ** *Job*: _191#Accountant_ + ** *EmpType*: _FTE_ + ** *Status*: _In_ +. Click btn:[Register user] +. Click btn:[Export users to csv file] at the bottom of the user list. + +== Check the new user in midPoint + +After the recurring HRIS reconciliation task runs, check the new user in midPoint. + +.User Samuel Hits receives an inappropriate username generated by the mapping script +image::midpoint-inappropriate-username.webp["User Samuel Hits receives an inappropriate username generated by the mapping script"] + +Obviously, this person cannot go by this username. + +You can also head over to the link:http://localhost/phpldapadmin[AD resource UI] directly and check the username there. + +== Fix the username manually + +The fix for the situation is, in this case, surprisingly easy. +You can manually alter the username value in midPoint without fearing that midPoint will overwrite it. +That is because the mapping in the object template which generates usernames is _weak_. +It touches the attribute only if it is empty. +In no other case does it alter the value of the attribute. + +[TIP] +==== +Be careful to not use a username that already exists; +in such a situation, midPoint would show an error message on changes preview or saving the user. +==== + +. In [.nowrap]#icon:user[] *Users*# > [.nowrap]#icon:user[] *Persons*#, open the user _Samuel Hits_ for editing. +. Rewrite *Name* to, e.g., _sahits_. +. Click [.nowrap]#icon:eye[] btn:[Preview changes]# to see what will be saved to midPoint and the target system. + ** You can see that midPoint would immediately provision the new username to the target AD resource. ++ +.Preview what happens when you change the username +image::midpoint-preview-change-username.webp["Preview screen with display of what happens when you manually change the user's username"] + +. Click btn:[Save] to actually make the change. + ** You can also btn:[Continue editing] and then [.nowrap]#icon:save[] btn:[Save]# your changes in the main user profile screen. + +With this done, you have successfully mitigated an HR crisis of a user having an unacceptable username. + +[TIP] +==== +If you ever use such an automatic username generation system in a larger organization, +we strongly advise to use an automatic system to check against a database of known offensive and inappropriate words the generator might produce. +==== + +:sectnums!: + +== Conclusion + +In this module, you have learned how to manage precarious situations when automation fails you. +The solution is not universal but throughout the course, you have learned to notice and work with mapping strengths and lifecycle states, giving you the power to efficiently solve such issues that may arise during the IGA solution deployment in your organization. + +This is the last module in the First steps methodology. +We hereby congratulate you on finishing the course. \ No newline at end of file diff --git a/midpoint/methodology/first-steps/verify-configuration-behavior/handle-source-system-data-updates.adoc b/midpoint/methodology/first-steps/verify-configuration-behavior/handle-source-system-data-updates.adoc new file mode 100644 index 000000000..e91bdc475 --- /dev/null +++ b/midpoint/methodology/first-steps/verify-configuration-behavior/handle-source-system-data-updates.adoc @@ -0,0 +1,81 @@ += Verify handling source system data updates +:page-nav-title: Handle source data updates +:page-display-order: 520 +:page-toc: top +:experimental: +:icons: font +:page-description: Verify that changes to user accounts in the source system propagate correctly through midPoint to the target system. + +You have already confirmed that creating new users works. +In this module, you will verify that you can actually change data in the source HR information system and that these changes are picked up by midPoint correctly. + +== What awaits you this module + +This exercise is short: + +. Update an attribute of a user in the HRIS. +. Wait for the recurring reconciliation task to run. +. Inspect how midPoint handled the change across the systems. + +:sectnums: +== Update user in HRIS + +. Navigate to the link:http://localhost/hr/[HR demo app web UI]. +. Click btn:[Show users] in the top navigation bar. +. Pick whichever user you like, e.g., _Geena Green_. +. Click btn:[Modify] in right-most column of the listing table. +. In the form that appears, rewrite *Locality* to _Hot Lava City_. +. Click btn:[Modify user]. +. Click btn:[Export users to csv file] at the bottom of the user listing page. + +== Let automation handle the updates + +Wait for the xref:/midpoint/methodology/first-steps/automate-target-system-integration/generate-usernames-in-midpoint/#automate-importing-users-to-midpoint[recurring HRIS reconciliation task] you have already up and running to pick up the changes. + +== Inspect the results + +To verify that the change has propagated to both midPoint and Active Directory: + +. In [.nowrap]#icon:user[] *Users*# > [.nowrap]#icon:user[] *Persons*#, search for _geena_ and click the name to open Geena Green's profile. +. Select [.nowrap]#icon:history[] *History*# in Geena's profile on the left. + ++ +.You can see here that the user has been modified through the reconciliation xref:/midpoint/reference/concepts/channel/[channel]. +image::midpoint-geena-user-history-modified-by-reconciliation.webp[] + +. Click the time stamp of the last change in the [.nowrap]#icon:history[] *History*# screen to open the audit log entry with the details of the change. ++ +.On the right, you can see that both the focus and the AD account of Geena have been modified. +image::midpoint-geena-user-audit-log.webp[] + +. You can check the data on the target AD system by two means: + ** In Geena's midPoint user profile, go to [.nowrap]#icon:male[] *Projections*#, select the AD resource, and inspect the attribute values. + ** Go directly to the link:http://localhost/phpldapadmin[target AD server administration interface], open Geena's account details, and confirm the changes there. + +=== Audit log: Canonical approach to keeping track of changes + +Finding out what the scheduled reconciliation task did was easy this time, because you knew exactly on which user to expect changes. +In case you do not know which user to inspect and want to review what is happening in your IGA ecosystem, *use the audit log*: + +. Select [.nowrap]#icon:magnifying-glass-chart[] *Audit Log Viewer*# in the main midPoint navigation menu. +. Inspect entries with an appropriate value in the *xref:/midpoint/reference/concepts/channel/[Channel]* column. + ** In the case of this module, it is _Reconciliation_. +. There are always multiple *stages* for events—open the _Execution_ or _Resource_ stage entries as those show most clearly what has actually been done. + +.Audit log entries +image::midpoint-audit-log-geena-reconciled.webp["Audit log entries"] + +:sectnums!: + +== Summary + +This experiment has proven beyond doubt that your setup works as expected. +The changes you made in the source system propagate to midPoint and then to the target system. + +== Next steps + +Having successfully covered two out of the three basic IGA transitions (*join*, *move,* leave), you have yet left to confirm your configuration performs correctly for *leavers.* +In the next module, you will do exactly that. + +[.nowrap]#icon:arrow-right[] *xref:/midpoint/methodology/first-steps/verify-configuration-behavior/manage-former-employees/[]*# + +You may also find it interesting to read a related IAM myth: xref:/iam/myths/iga-means-accounts/[] \ No newline at end of file diff --git a/midpoint/methodology/first-steps/verify-configuration-behavior/hris-import-simul-devel-provision-job-title.webp b/midpoint/methodology/first-steps/verify-configuration-behavior/hris-import-simul-devel-provision-job-title.webp new file mode 100644 index 000000000..ab507b6f7 Binary files /dev/null and b/midpoint/methodology/first-steps/verify-configuration-behavior/hris-import-simul-devel-provision-job-title.webp differ diff --git a/midpoint/methodology/first-steps/verify-configuration-behavior/hris-inbound-mapping-job-to-title-archived-job-to-title-nice-active.webp.webp b/midpoint/methodology/first-steps/verify-configuration-behavior/hris-inbound-mapping-job-to-title-archived-job-to-title-nice-active.webp.webp new file mode 100644 index 000000000..d522f2620 Binary files /dev/null and b/midpoint/methodology/first-steps/verify-configuration-behavior/hris-inbound-mapping-job-to-title-archived-job-to-title-nice-active.webp.webp differ diff --git a/midpoint/methodology/first-steps/verify-configuration-behavior/hris-inbound-mapping-job-to-title-deprecated-job-to-title-nice-proposed.webp.webp b/midpoint/methodology/first-steps/verify-configuration-behavior/hris-inbound-mapping-job-to-title-deprecated-job-to-title-nice-proposed.webp.webp new file mode 100644 index 000000000..c4898a53f Binary files /dev/null and b/midpoint/methodology/first-steps/verify-configuration-behavior/hris-inbound-mapping-job-to-title-deprecated-job-to-title-nice-proposed.webp.webp differ diff --git a/midpoint/methodology/first-steps/verify-configuration-behavior/hris-inbound-mapping-job-to-title.webp b/midpoint/methodology/first-steps/verify-configuration-behavior/hris-inbound-mapping-job-to-title.webp new file mode 100644 index 000000000..ec8063491 Binary files /dev/null and b/midpoint/methodology/first-steps/verify-configuration-behavior/hris-inbound-mapping-job-to-title.webp differ diff --git a/midpoint/methodology/first-steps/verify-configuration-behavior/hris-reconcile-simul-devel-improved-job-titles.webp b/midpoint/methodology/first-steps/verify-configuration-behavior/hris-reconcile-simul-devel-improved-job-titles.webp new file mode 100644 index 000000000..8056cbc6f Binary files /dev/null and b/midpoint/methodology/first-steps/verify-configuration-behavior/hris-reconcile-simul-devel-improved-job-titles.webp differ diff --git a/midpoint/methodology/first-steps/verify-configuration-behavior/hris-reconcile-simul-prod-fixed-malevolent-ldap-changes.webp b/midpoint/methodology/first-steps/verify-configuration-behavior/hris-reconcile-simul-prod-fixed-malevolent-ldap-changes.webp new file mode 100644 index 000000000..3bbd7d1c1 Binary files /dev/null and b/midpoint/methodology/first-steps/verify-configuration-behavior/hris-reconcile-simul-prod-fixed-malevolent-ldap-changes.webp differ diff --git a/midpoint/methodology/first-steps/verify-configuration-behavior/hris-resume-hris-reconciliation-task.webp b/midpoint/methodology/first-steps/verify-configuration-behavior/hris-resume-hris-reconciliation-task.webp new file mode 100644 index 000000000..b402d5977 Binary files /dev/null and b/midpoint/methodology/first-steps/verify-configuration-behavior/hris-resume-hris-reconciliation-task.webp differ diff --git a/midpoint/methodology/first-steps/verify-configuration-behavior/hris-suspend-hris-reconciliation-task.webp b/midpoint/methodology/first-steps/verify-configuration-behavior/hris-suspend-hris-reconciliation-task.webp new file mode 100644 index 000000000..7c92a4a24 Binary files /dev/null and b/midpoint/methodology/first-steps/verify-configuration-behavior/hris-suspend-hris-reconciliation-task.webp differ diff --git a/midpoint/methodology/first-steps/verify-configuration-behavior/index.adoc b/midpoint/methodology/first-steps/verify-configuration-behavior/index.adoc new file mode 100644 index 000000000..7eccba143 --- /dev/null +++ b/midpoint/methodology/first-steps/verify-configuration-behavior/index.adoc @@ -0,0 +1,5 @@ += Verify the whole configuration behaves as expected +:page-nav-title: 6. Verify configuration behavior +:page-display-order: 500 + +This is a placeholder page immediately redirected to the first article in the section. \ No newline at end of file diff --git a/midpoint/methodology/first-steps/verify-configuration-behavior/ldap-corrected-job-title.webp b/midpoint/methodology/first-steps/verify-configuration-behavior/ldap-corrected-job-title.webp new file mode 100644 index 000000000..db94d8214 Binary files /dev/null and b/midpoint/methodology/first-steps/verify-configuration-behavior/ldap-corrected-job-title.webp differ diff --git a/midpoint/methodology/first-steps/verify-configuration-behavior/ldap-delete-user-in-ldap-ui.webp b/midpoint/methodology/first-steps/verify-configuration-behavior/ldap-delete-user-in-ldap-ui.webp new file mode 100644 index 000000000..6435e5d60 Binary files /dev/null and b/midpoint/methodology/first-steps/verify-configuration-behavior/ldap-delete-user-in-ldap-ui.webp differ diff --git a/midpoint/methodology/first-steps/verify-configuration-behavior/ldap-remove-user-from-group-in-ldap-ui.webp b/midpoint/methodology/first-steps/verify-configuration-behavior/ldap-remove-user-from-group-in-ldap-ui.webp new file mode 100644 index 000000000..6ec68cada Binary files /dev/null and b/midpoint/methodology/first-steps/verify-configuration-behavior/ldap-remove-user-from-group-in-ldap-ui.webp differ diff --git a/midpoint/methodology/first-steps/verify-configuration-behavior/ldap-user-job-title-nicer.webp b/midpoint/methodology/first-steps/verify-configuration-behavior/ldap-user-job-title-nicer.webp new file mode 100644 index 000000000..23d1719a4 Binary files /dev/null and b/midpoint/methodology/first-steps/verify-configuration-behavior/ldap-user-job-title-nicer.webp differ diff --git a/midpoint/methodology/first-steps/verify-configuration-behavior/manage-former-employees.adoc b/midpoint/methodology/first-steps/verify-configuration-behavior/manage-former-employees.adoc new file mode 100644 index 000000000..930d769a4 --- /dev/null +++ b/midpoint/methodology/first-steps/verify-configuration-behavior/manage-former-employees.adoc @@ -0,0 +1,207 @@ += Handle long-term leaves and former employees safely +:page-nav-title: Inactivate employee accounts +:page-display-order: 530 +:page-toc: top +:experimental: +:icons: font +:page-description: Test behavior of your midPoint configuration regarding leavers—be it people on long-term leave or former employees. + +Test behavior of your midPoint configuration regarding leavers—be it people on long-term leave or former employees. + +== What awaits you in this module + +In this guide, long-term leave stands for cases like parental leave. +Such users and their accounts should be disabled. +It is important, though, to avoid deleting their accounts, because the employees are expected to return and use continue using their accounts thereafter. + +You will confirm that focal objects (users) and their Active Directory projections (accounts) are disabled as required when the HRIS user status changes to _Long-term leave_. +Subsequently, you will check that the users have their accounts reactivated when they return from the long-term leave. + +In the second part of the module, you will test your midPoint configuration for former employee handling (i.e., true _leavers_). +Accounts of former employees need to be disabled and then deleted after a defined period of time automatically. +For this delayed delete, midPoint uses the _disabled instead of delete_ and _delayed delete_ xref:/midpoint/methodology/first-steps/enable-target-system-provisioning/#delete-ad-accounts-with-a-grace-period[activation rules you have set up earlier]. + +:sectnums: + +== Employee goes on long-term leave + +The first case we are to cover is when employees leave on long-term leave. +You will update the leaving employee in the HR information system and observe how midPoint handles the case. + +=== Update the user in HRIS + +As always, all changes are initiated in the HRIS. +To update a user in the HRIS, use the same steps as in xref:/midpoint/methodology/first-steps/verify-configuration-behavior/handle-source-system-data-updates/[]. + +. Pick a user to update, e.g., _Martin Knight_ (employee number: 1006). +. Update their *Status* to _Long-term leave_. +. Export HRIS users to CSV. + +=== Let automation handle the updates + +Wait for the xref:/midpoint/methodology/first-steps/automate-target-system-integration/generate-usernames-in-midpoint/#automate-importing-users-to-midpoint[recurring HRIS reconciliation task] you have already up and running to pick up the changes. + +=== Check the results + +Verify how the change was handled using the same steps as in xref:/midpoint/methodology/first-steps/verify-configuration-behavior/handle-source-system-data-updates/#inspect-the-results[]. + +These should be the results: + +* The *Lifecycle state* of the user Martin Knight is set to _Suspended_. +* The user's *Effective status* is _Disabled_ (displayed in the top-right corner of the screen). +* In the user's profile, go to [.nowrap]#icon:male[] *Projections*#, select the AD projection, and check that the *Administrative status* is set to _Disabled_. +* You can also check the user directly on the AD server. + The disabled status is mapped there to the `roomNumber` user attribute because AD does not support user activation natively. + +.User Martin Knight has been suspended due to going on long-term leave +image::midpoint-knight-user-suspended-long-term-leave.webp["User Martin Knight is suspended due to his long-term leave"] + +Users who are on the long-term leave in the HRIS are suspended in midPoint. +Users inactive in midPoint, in turn, have their AD accounts disabled. +That is because they should not have access to the accounts, but you cannot delete them because the users are expected to return back to work at a later time. + +=== After the employee returns + +When their long-term leave ends, employees are about to return to work. +They need their accounts back as they were before they left. + +. Update the returning user in HRIS—set their *Status* back to _In_. +. Export HRIS users to CSV. +. Wait for the recurring reconciliation task to run. +. Check the particular user's *Lifecycle state* and *Effective status*, and the *Administrative status* of their AD projection. + They should be _Active_ and _Enabled_. + +== Employee leaves for good + +The second exercise in this module is similar to the first but with some added points. +Pick a user on which to simulate leaving the employment. +In examples herein, we use _Martin Knight_ (employee number: 1006) again. + +=== Update the user status in HRIS + +. In the HRIS user interface, modify the user's *Status* to _Former employee_. +. Export HRIS users to CSV. +. Wait for the recurring HRIS reconciliation task to pick up the change. + +=== Verify the user is deactivated and waiting for deletion in AD + +Once the reconciliation task picks up the changed employment status of the user, you have configured midPoint to: + +* Set the user's *Lifecycle state* to _Archived_. +* Set the user's *Effective status* to _Disabled_ (displayed in the top-right corner of the screen). +* Disable the account on the AD resource (mapped to the `roomNumber` user attribute). +* Set up the trigger for delayed deletion of the AD resource account. + +[NOTE] +==== +When you are on the user profile screen, it is not enough to refresh the page to see the updates made by the reconciliation task to the user (such as changed lifecycle state). +You need to go [.nowrap]#icon:arrow-left[] btn:[Back]# to the user list, and open the user profile again. +==== + +=== Check the delayed delete trigger + +The delayed delete activation rule places a trigger on accounts that are to be deleted instead of having them deleted right away. +In laymen terms, the trigger says, for instance, "delete this AD account on 2026-04-23 07:57:19". + +To act on triggers, there is a trigger scanner task which periodically scans objects with triggers. +Once it discovers an object with a trigger the time of which is in the past, it performs the action specified in the trigger. + +[NOTE] +==== +For a trigger to be fired, its time stamp must be in the past. +That means triggers are never fired earlier than at the time specified by their time stamp. +On the other side, the action may be delayed depending on the schedule of the trigger scanner task. +==== + +By default, the trigger scanner task is scheduled to run every 5 minutes. +In the Docker image prepared for this guide, it is set to 1 minute. +You can check and change the schedule in [.nowrap]#icon:tasks[] *Server tasks*# > [.nowrap]#icon:save[] *System tasks*# > Trigger scanner > [.nowrap]#icon:calendar[] *Schedule*#. +You can also use the [.nowrap]#icon:play[] btn:[Run now]# button there if you do not want to wait for the next scheduled run. +// TODO: We're missing an article on triggers and trigger scanners @dakle 2025-11-23 + +.Trigger scanner schedule configuration screen +image::trigger-scaner-task-edit-schedule.webp["Trigger scanner schedule configuration screen"] + +[TIP] +==== +The trigger is stored in the midPoint xref:/midpoint/architecture/concepts/shadow/[shadow object] corresponding to the resource account. +It is not stored in the user's focal object nor in the actual account on the remote resource. +==== + +Once the trigger is in place: + +. Go to the user's profile in midPoint. +. Click [.nowrap]#icon:male[] *Projections*#. +. Select the AD resource. +. Hover your mouse over the account icon to see the timer. + +.The AD account for user Martin Knight pending delete +image::midpoint-knight-ldap-projection-pending-delete.webp["The AD account for user Martin Knight is pending deletion"] + +If you are on the Docker images prepared for this guide, you can check accounts with triggers using the *AD account notices dashboard*: + +. Under [.nowrap]#icon:tachometer-alt[] *Dashboards*#, select *AD account notices*. +. Click [.nowrap]#*More info* icon:arrow-circle-right[]# on the *Users with accounts with triggers* tile to list *users* with triggers on any of their accounts. +. Click [.nowrap]#*More info* icon:arrow-circle-right[]# on the *Accounts with triggers* tile to list *accounts* with triggers. +. Click [.nowrap]#*More info* icon:arrow-circle-right[]# on the *Users without AD accounts* to list users without an AD account. + ** This number will grow by one once the grace period for Martin Knight's AD account expires. + +.AD notices dashboard showing one account is pending delete +image::midpoint-dashboard-ad-notices-one-pending-delete.webp["AD notices dashboard showing one account is pending delete"] + +.If you have renamed your AD resource… +[NOTE] +==== +The dashboard widget for showing the number of accounts without an AD account depends on the resource name. +If you have renamed the AD resource to anything other than `AD`, the dashboard would wrongly show that all users in midPoint are without an AD account. + +Should that be your case, either rename your AD resource to `AD`, or adjust the object collection used in the dashboard as follows: + +. In [.nowrap]#icon:filter[] *Object collections*#, find and open for editing the collection _Users without AD accounts_. +. Click [.nowrap]#icon:edit[] btn:[Edit raw]#. +. Edit the filter part of the collection: ++ +[source,XML] +---- + + + linkRef/@ not matches ( + . type ShadowType + and resourceRef/@/name = "AD" + and kind = "account" ) + + +---- +<1> Rewrite the quoted string so that it matches exactly the name of your target (AD/LDAP) resource. ++ +. Click btn:[Save] and go back to dashboards. + The dashboard should show accurate data now. + +Refer to xref:/midpoint/reference/admin-gui/dashboards/[] to learn more about dashboards. +==== + +=== Confirm the AD account has been deleted + +After the grace period elapses, the trigger scanner task catches the trigger and midPoint deletes the AD account projection for Martin Knight who is no longer entitled to have one because he left the company. +For the account to be _actually_ deleted on the resource, the recurring HRIS reconciliation task must run as well. + +To verify the AD account has been deleted, check [.nowrap]#icon:male[] *Projections*# for user _knight_ in midPoint. +He should have only the one for the HRIS; the AD projection should be deleted. + +.User Martin Knight's projections contain only the HRIS now +image::midpoint-knight-ldap-projections-only-hris.webp["User Martin Knight's projections contain only the HRIS now"] + +You can also use the *AD account notices* dashboard—the *Users without AD accounts* tile should now show one more account than before. + +Finally, you can also link:http://localhost/phpldapadmin[access the AD/LDAP server directly] to verify the account is not there anymore. + +The user _knight_ remains in midPoint because in the setup we use in this guide, we keep track of all users who have ever been part of the company, +similarly to how a university keeps track of all students who have ever enrolled at the university. + +:sectnums!: + +== Next steps + +In the next module, you will test how the existing configuration copes with adding a new outbound mapping to the target resource. + +[.nowrap]#icon:arrow-right[] *xref:/midpoint/methodology/first-steps/verify-configuration-behavior/provision-new-attributes-to-target-resource/[]*# \ No newline at end of file diff --git a/midpoint/methodology/first-steps/verify-configuration-behavior/midpoint-audit-log-geena-reconciled.webp b/midpoint/methodology/first-steps/verify-configuration-behavior/midpoint-audit-log-geena-reconciled.webp new file mode 100644 index 000000000..e36e15698 Binary files /dev/null and b/midpoint/methodology/first-steps/verify-configuration-behavior/midpoint-audit-log-geena-reconciled.webp differ diff --git a/midpoint/methodology/first-steps/verify-configuration-behavior/midpoint-dashboard-ad-notices-one-pending-delete.webp b/midpoint/methodology/first-steps/verify-configuration-behavior/midpoint-dashboard-ad-notices-one-pending-delete.webp new file mode 100644 index 000000000..a3f591586 Binary files /dev/null and b/midpoint/methodology/first-steps/verify-configuration-behavior/midpoint-dashboard-ad-notices-one-pending-delete.webp differ diff --git a/midpoint/methodology/first-steps/verify-configuration-behavior/midpoint-geena-user-audit-log.webp b/midpoint/methodology/first-steps/verify-configuration-behavior/midpoint-geena-user-audit-log.webp new file mode 100644 index 000000000..66d09fabe Binary files /dev/null and b/midpoint/methodology/first-steps/verify-configuration-behavior/midpoint-geena-user-audit-log.webp differ diff --git a/midpoint/methodology/first-steps/verify-configuration-behavior/midpoint-geena-user-history-modified-by-reconciliation.webp b/midpoint/methodology/first-steps/verify-configuration-behavior/midpoint-geena-user-history-modified-by-reconciliation.webp new file mode 100644 index 000000000..7651fea84 Binary files /dev/null and b/midpoint/methodology/first-steps/verify-configuration-behavior/midpoint-geena-user-history-modified-by-reconciliation.webp differ diff --git a/midpoint/methodology/first-steps/verify-configuration-behavior/midpoint-knight-ldap-projection-pending-delete.webp b/midpoint/methodology/first-steps/verify-configuration-behavior/midpoint-knight-ldap-projection-pending-delete.webp new file mode 100644 index 000000000..2ad191e35 Binary files /dev/null and b/midpoint/methodology/first-steps/verify-configuration-behavior/midpoint-knight-ldap-projection-pending-delete.webp differ diff --git a/midpoint/methodology/first-steps/verify-configuration-behavior/midpoint-knight-ldap-projections-only-hris.webp b/midpoint/methodology/first-steps/verify-configuration-behavior/midpoint-knight-ldap-projections-only-hris.webp new file mode 100644 index 000000000..241339756 Binary files /dev/null and b/midpoint/methodology/first-steps/verify-configuration-behavior/midpoint-knight-ldap-projections-only-hris.webp differ diff --git a/midpoint/methodology/first-steps/verify-configuration-behavior/midpoint-knight-user-suspended-long-term-leave.webp b/midpoint/methodology/first-steps/verify-configuration-behavior/midpoint-knight-user-suspended-long-term-leave.webp new file mode 100644 index 000000000..fe5482a1b Binary files /dev/null and b/midpoint/methodology/first-steps/verify-configuration-behavior/midpoint-knight-user-suspended-long-term-leave.webp differ diff --git a/midpoint/methodology/first-steps/verify-configuration-behavior/midpoint-ldap-projection-job-title-nicer.webp b/midpoint/methodology/first-steps/verify-configuration-behavior/midpoint-ldap-projection-job-title-nicer.webp new file mode 100644 index 000000000..d14767773 Binary files /dev/null and b/midpoint/methodology/first-steps/verify-configuration-behavior/midpoint-ldap-projection-job-title-nicer.webp differ diff --git a/midpoint/methodology/first-steps/verify-configuration-behavior/provision-new-attributes-to-target-resource.adoc b/midpoint/methodology/first-steps/verify-configuration-behavior/provision-new-attributes-to-target-resource.adoc new file mode 100644 index 000000000..7406c2448 --- /dev/null +++ b/midpoint/methodology/first-steps/verify-configuration-behavior/provision-new-attributes-to-target-resource.adoc @@ -0,0 +1,104 @@ += Add new attribute provisioning from HRIS to AD +:page-nav-title: Provision new attributes to target +:page-display-order: 540 +:page-toc: top +:experimental: +:icons: font +:page-description: Test how your midPoint configuration handles revised provisioning requirements and the resulting mapping changes in both the source and target resources + +Test how your midPoint configuration handles revised provisioning requirements and the resulting mapping changes in both the source and target resources. + +== What awaits you in this module + +You will import a new user attribute from the HRIS and provision it to Active Directory. +You will create two new mappings: one inbound mapping to get the HRIS data to midPoint, and one outbound mapping to populate AD accounts with the data. + +The attribute in question is the job title. +The employees have their job titles in the HRIS, but not in Active Directory. +Your goal is to propagate the job titles to AD as well and see if nothing in your midPoint configuration breaks with this change. + +:sectnums: + +== Create new HRIS mapping + +In the HRIS resource in midPoint, create a new inbound mapping. + +*Follow this guide: xref:/midpoint/reference/admin-gui/resource-wizard/object-type/mapping/#inbound_mappings[Create inbound mappings]* + +** *Name*: e.g., _job-to-title_ +** *From resource attribute*: _job_ +** *Expression*: _As is_ +** *Target*: _title_ +** *Lifecycle state*: _Proposed_ + +The mapping is in the _Proposed_ lifecycle state, meaning the recurring HRIS reconciliation task cannot work with it yet and you can safely simulate. + +.Inbound mapping to insert the job attribute value from the HRIS resource into the title attribute in midPoint +image::hris-inbound-mapping-job-to-title.webp["Inbound mapping to insert the job attribute value from the HRIS resource into the title attribute in midPoint"] + +== Create new AD mapping + +In the AD resource in midPoint, create a new outbound mapping. + +[NOTE] +==== +If you use the Docker image prepared for this guide, the mapping is already there preconfigured. +Just change its lifecycle state to _Proposed_. +==== + +*Follow this guide: xref:/midpoint/reference/admin-gui/resource-wizard/object-type/mapping/#outbound_mappings[Create outbound mappings]* + +** *Name*: e.g., _mapping-title_ +** *From resource attribute*: _title_ +** *Expression*: _As is_ +** *Target*: _title_ +** *Lifecycle state*: _Proposed_ + +== Simulate import from HRIS + +Your configuration is ready, it is time to verify what it does. +Go to the HRIS resource and run a simulated development import task. +You have it ready for use from the earlier module: xref:/midpoint/methodology/first-steps/connect-source-system/import-accounts-from-hris/#simulate-a-single-account-import[]. + +.Lifecycle states knowledge refresher +[NOTE] +==== +Tasks in the _preview_ mode with the configuration set to _development_ evaluate all _active_ and _proposed_ configuration items but make no permanent changes. +==== + +After the task finishes, click btn:[Show simulation result]. + +The result should be that a resource object has been affected for all focal objects that have a projection to the AD resource. +Click [.nowrap]#*More info* icon:arrow-circle-right[]#, open an item in the list, and inspect the changes. +The only change should be the title being provisioned to AD. + +Note that certain users on the AD resource already have the `title` attribute filled in. +Since the outbound mapping is _strong_, midPoint overwrites the existing value in AD. +That is desired as you cannot know whether the data in the non-authoritative Active Directory server are correct. + +.HRIS import simulation result for Diane Davis showing the job title would be provisioned to and corrected in Active Directory +image::hris-import-simul-devel-provision-job-title.webp["HRIS import simulation result for Diane Davis showing the job title would be provisioned to and corrected in Active Directory"] + +== Put the configuration to prodution + +Once you have verified the configuration did not break anything and works as expected, put it to production. + +. Change the lifecycle state of the HRIS inbound mapping to _Active_. +. Change the lifecycle state of the AD outbound mapping to _Active_. +. Wait for the recurring HRIS reconciliation task to pick up the changes and provision the job titles to all accounts in AD. + +Once done, have a look at the *Projections* screen in user profiles in midPoint and look for the `title` attribute. +Similarly, open the link:http://localhost/phpldapadmin/[AD web administration UI] and see the account attributes there. + +.The job title is now correct in Active Directory +image::ldap-corrected-job-title.webp["A user profile screen in LDAP showing user attributes, including the corrected value of the job title attribute"] + +:sectnums!: + +== Next steps + +To be fair, the job title value does not look very nice because it contains the internal numeric code from the HRIS. +It is the job for the next module to fix that by amending the existing mapping to make the value more human friendly, +and to show that midPoint can cope just fine with changes made "on the fly". + +[.nowrap]#icon:arrow-right[] *xref:/midpoint/methodology/first-steps/verify-configuration-behavior/update-existing-mapping/[]*# \ No newline at end of file diff --git a/midpoint/methodology/first-steps/verify-configuration-behavior/rectify-unauthorized-changes-on-target-resource.adoc b/midpoint/methodology/first-steps/verify-configuration-behavior/rectify-unauthorized-changes-on-target-resource.adoc new file mode 100644 index 000000000..7d03c8eee --- /dev/null +++ b/midpoint/methodology/first-steps/verify-configuration-behavior/rectify-unauthorized-changes-on-target-resource.adoc @@ -0,0 +1,143 @@ += Rectify unauthorized changes in Active Directory +:page-nav-title: Rectify unauthorized changes +:page-display-order: 510 +:page-toc: top +:experimental: +:icons: font +// This redirect is here to move visitors directly to the first child of the section +:page-moved-from: /midpoint/methodology/first-steps/verify-configuration-behavior/ +:page-description: Test how your midPoint configuration enforces data consistency across connected applications. + +Test how your midPoint configuration enforces data consistency across connected applications. +You have already seen how midPoint detects orphaned accounts and deletes them unless explicitly told otherwise. +However, what about unauthorized changes to legitimate accounts made directly on the Active Directory server? + +== What awaits you in this module + +You will make several "mistakes" or "malicious attacks" on the target AD system without changing the source HRIS data. +You will then observe how midPoint fixes the data inconsistencies you will have introduced: + +. Pause the recurring HRIS reconciliation task to so that it does not fix all the issues immediately without you knowing what exactly happened. +. "Make a mistake" and delete an account on the AD server. +. "Malevolently" edit a few account attributes on the AD server, as well as remove someone from the _all-users_ group. +. Simulate production reconciliation to confirm midPoint reverts your edits according to your configuration rules. +. Resume the HRIS reconciliation task to make the disaster recovery setup automated again. + +:sectnums: + +== Put automatic HRIS reconciliation on hold + +In order to observe midPoint behavior in detail, you need to stop the recurring HRIS reconciliation task that automatically synchronizes HRIS accounts with the rest of your IGA ecosystem (midPoint and AD). + +. In the HRIS resource, go to [.nowrap]#icon:tasks[] *Defined Tasks*# and open the production HRIS reconciliation task for editing. + ** You can easily identify the task by the *Execution state*—it should be the only one in the _Runnable_ state. +. In the top task bar, under *Task operations*, click the red [.nowrap]#icon:pause[] btn:[Suspend]# button. + +.Suspend the recurring reconciliation task on the HRIS resource before you start testing your configuration +image::hris-suspend-hris-reconciliation-task.webp["HRIS reconciliation task with the mouse pointer on the Suspend button"] + +With the task suspended, accounts added or changed in the HRIS cannot be picked up and provisioned automatically, +and changes performed directly in Active Directory cannot be overwritten with the correct HRIS data. + +== Delete an account directly in Active Directory + +Now, make the first "mistake": Delete one account directly on the AD server. +Such an action is certainly possible, as an AD administrator may, in error or not, delete an account managed by midPoint. + +. Navigate to the link:http://localhost/phpldapadmin/[AD server web UI]. +. In the left-side navigation, expand `dc=example,dc=com`. +. Expand `ou=users`. +. Pick whichever user you like, e.g., `cn=Alexander Freeman`, and click the item to edit the user. +. In the toolbar at the top, click *Delete this entry* to delete the user. +. Click btn:[Delete] on the confirmation screen. + +.Delete an arbitrary user directly on the AD to test midPoint provisioning configuration +image::ldap-delete-user-in-ldap-ui.webp["AD UI with user details opened and mouse pointer on the delete user button."] + +== Change account data directly in Active Directory + +The next step is to edit some user's data directly on the target AD server. +This action is fairly realistic as well, for an AD admin may make a mistake or even go rogue and start making malevolent changes all over the place. +Your goal is to test the resiliency of your setup against such actions. + +. In the AD user interface, open a whichever user for editing, e.g., `cn=Alice Baker`. +. Change some attributes of hers. For example: + ** `l` (locality) to _Black Ash City_ + ** `givenName` to _Rabbit_ +. Click btn:[Update Object]. + +Next, remove the user (or any other user) from the `all-users` group: + +. Under `dc=example,dc=com`, expand `ou=groups`. +. Click `cn=all-users` to open the group for editing. +. Scroll down and click btn:[modify group members] beneath the group member list. +. Select the user you want to remove from the group +. Click btn:[<<< Remove selected]. +. Click btn:[Save changes]. +. The confirmation screen that appears highlights the removed member. Click btn:[Update Object] to confirm the change. + +image::ldap-remove-user-from-group-in-ldap-ui.webp[] + +Now, this is enough sabotage activities, let us see what midPoint does about the situation. + +== Simulate reclassification to observe data rectification + +To get the opportunity to observe how midPoint deals with the new discrepancies on the target system, run a simulated production reconciliation task on the HRIS resource. +The simulation needs to use the production configuration because all your settings are in the _Active_ lifecycle state. + +If you do not yet have a task to simulate reconciliation on production, create one. + +*Follow this guide: xref:/midpoint/reference/tasks/synchronization-tasks/import-and-reconciliation/gui/[]* + +. In the HRIS resource, create a new *reconciliation* task with the *simulation* toggle on. +. Name the task, e.g., _HRIS reconciliation - production simulation_ +. Keep kind and intent to their default (_Account_, _default_). +. On the *Execution* screen, set *Mode* to _Preview_ and *Configuration* to _Production_. +. Save the task and run it. + +After it finishes, click btn:[Show simulation result] to observe the outcome. + +* You should see that one projection entitlement has changed—that means Alice Baker would get back her membership in the _all-users_ group. +* There should be two resource objects affected—Alice Baker getting the changed attributes corrected, and Alexander Freeman getting his account in AD back. + +.Simulated production reconciliation of the HRIS resource fixed all unauthorized changes made directly on the AD server +image::hris-reconcile-simul-prod-fixed-malevolent-ldap-changes.webp["Simulated production reconciliation of the HRIS resource fixed all unauthorized changes made directly on the AD server"] + +Obviously, the numbers may differ based on the number of changes you have actually made. +Nevertheless, the end result should be the same: +All accounts impacted by unauthorized changes made directly on the target AD server +should have their data corrected based on the HRIS resource data. + +.What if I need to make changes in AD and keep them? +[TIP] +==== +If you find yourself in need of changing the AD data directly, then *mark the affected accounts* in midPoint as _Do not touch_, for example. +With that, the reconciliation task will not touch their data on AD. +==== + +== Put the disaster recovery plan to production + +You have verified your configuration acts exactly as it should: +It rectifies illegally edited attributes, +recreates wrongfully deleted accounts, +and places users back to groups of which they are supposed to be members. +With this confirmed, resume the recurring HRIS reconciliation task: + +. Open the production HRIS reconciliation task for editing as you did when suspending it. +. Click [.nowrap]#icon:check-square[] btn:[Resume]# + +.Resume the recurring HRIS reconciliation task +image::hris-resume-hris-reconciliation-task.webp["HRIS reconciliation task with the mouse pointer on the Resume button"] + + +:sectnums!: + +== Next steps + +You now know that your midPoint setup handles unauthorized changes on the target system well. +It puts everything back in line automatically with every run of the HRIS reconciliation task. + +With the possible damage done by a deranged or simply tired AD administrator mitigated, it is now time to verify that changes done on existing users in the source HR information system propagate well into the target AD system. +This may sound similar to what you have already confirmed—that is, that you can create new users in the HRIS and they get into the AD system fine—but you have yet to confirm the same happens for changes on existing users. + +[.nowrap]#icon:arrow-right[] *xref:/midpoint/methodology/first-steps/verify-configuration-behavior/handle-source-system-data-updates/[]*# \ No newline at end of file diff --git a/midpoint/methodology/first-steps/verify-configuration-behavior/trigger-scaner-task-edit-schedule.webp b/midpoint/methodology/first-steps/verify-configuration-behavior/trigger-scaner-task-edit-schedule.webp new file mode 100644 index 000000000..991c4508b Binary files /dev/null and b/midpoint/methodology/first-steps/verify-configuration-behavior/trigger-scaner-task-edit-schedule.webp differ diff --git a/midpoint/methodology/first-steps/verify-configuration-behavior/update-existing-mapping.adoc b/midpoint/methodology/first-steps/verify-configuration-behavior/update-existing-mapping.adoc new file mode 100644 index 000000000..58cc0ecd7 --- /dev/null +++ b/midpoint/methodology/first-steps/verify-configuration-behavior/update-existing-mapping.adoc @@ -0,0 +1,148 @@ += Update existing mapping +:page-nav-title: Update existing mapping +:page-display-order: 550 +:page-toc: top +:experimental: +:icons: font +:page-description: Update live resource configuration to see that production configuration can be safely updated, tested, and re-deployed to production without any downtime + +Update live resource configuration to see that production configuration can be safely updated, tested, and re-deployed to production without any downtime. + +== What awaits you in this module + +In the previous module, you have newly imported the `job` attributed from the HRIS and provisioned it to Active Directory. +The issue with the values from HRIS is that beside the actual position name, they contain ugly internal codes, like `124#CEO`. +Your goal in this module is to remove the codes and populate the `title` attribute in midPoint and AD with clean values, such as `CEO`. + +The trick to learn here is how to make such a configuration update without causing any downtime. +You need to keep the old configuration in production during the testing until you are ready to seamlessly replace it with the new configuration. +For this to work, you will use two new lifecycle states. + +Suggested reading: xref:/midpoint/reference/concepts/object-lifecycle/#relation-of-task-configurations-and-lifecycle-states[Relation of task configurations and lifecycle states] + +:sectnums: + +== How to ensure continuity using lifecycle states + +While it is true that you already have an inbound mapping in the HRIS resource for the `job` attribute, you cannot simply update it. +By doing that, you would forfeit the option to test the new configuration using simulations because the mapping is _active_, i.e., on production. +Alternatively, you could move the mapping to the _Proposed_ lifecycle state, but that would mean putting it out of production during the testing phase, i.e., downtime. + +To ensure the continuity without interruption, you need to keep the old mapping on production and create a new mapping to test with. +Once the testing is over, you will swap them using the appropriate lifecycle phases: + +* The old mapping that needs to stay on production goes to the _Deprecated_ lifecycle state. +* The new mapping is in the _Proposed_ lifecycle state during testing. +* Once the new mapping is tested, it goes to the _Active_ lifecycle state. +* The old mapping is then retired and goes to the _Archived_ lifecycle state. + +== Adjust mappings in HRIS + +Let us adjust the inbound mappings for the HRIS resource. + +=== Deprecate the old mapping + +Firstly, put the old inbound production mapping to the _Deprecated_ lifecycle state. +This is a purely semantic change but it is useful because it makes it clear that it is intended to go away sooner or later. +It is important to know that while _deprecated_, the configuration object is *still used on production*. + +.Deprecated HRIS mapping is still used on production +[cols="5*", options="header"] +|================================================================================ +| Name | From resource attribute | Expression | Target | Lifecycle state +| job-to-title | `job` | As is | `title` | Deprecated +|================================================================================ + +=== Propose new mapping for cleaner title values + +Secondly, create a new inbound HRIS mapping in the _Proposed_ lifecycle state. +You do not want to put it to production yet, you need to test it first—hence, _propose_ it before you _activate_ it. + +.New HRIS mapping first needs to be tested. See below for the script. +[cols="5*", options="header"] +|===================================================================================== +| Name | From resource attribute | Expression | Target | Lifecycle state +| job-to-title-nice | `job` | Script | `title` | Proposed +|===================================================================================== + +Click btn:[Show script] on the _job-to-title-nice_ mapping. +Use the script below. + +.Script for the job-to-title-nice mapping +[source,groovy] +---- +def separator = '#' + +if (input == null || input.indexOf(separator) == -1) { <1> + return input +} else { + return input.tokenize(separator)[1] <2> +} +---- +<1> If the input string is `null`, empty, or cannot be split by the separator, return the string unchanged. +<2> Split the string by the hash character (set in the `separator` variable) and return the second part of the string. + +.HRIS inbound mappings with the old job-to-title mapping deprecated and the new job-to-title-nice mapping proposed +image::hris-inbound-mapping-job-to-title-deprecated-job-to-title-nice-proposed.webp.webp["HRIS inbound mappings with the old job-to-title mapping deprecated and the new job-to-title-nice mapping proposed"] + +[TIP] +==== +You do not need to change the Active Directory outbound mapping because the new HRIS inbound mapping writes to the same focus attribute as did the old mapping. +==== + +== Test the new mapping + +With the new _proposed_ configuration ready, it is time to test it. + +. In the HRIS resource, run the _HR Reconciliation - development simulation_ task xref:/midpoint/methodology/first-steps/automate-target-system-integration/automate-group-membership/#verify-your-configuration[you have used in the group membership automation module]. +. After the task finishes, click btn:[Show simulation result]. +. In the *Resource object affected* tile, you should see changes to all users mapped from the HRIS to midPoint. + Click [.nowrap]#*More info* icon:arrow-circle-right[]#, open an item in the list, and inspect the changes made to the item. + +[NOTE] +==== +Simulated development task evaluates all _active_ and _proposed_ configuration items, but makes no permanent changes to the data. +At the same time, the scheduled production reconciliation task executes all _active_ and _deprecated_ configuration items, +so the old configuration is still in production. +==== + +.The reconciliation simulation shows the job title is going be nicer thanks to the new mapping +image::hris-reconcile-simul-devel-improved-job-titles.webp["The reconciliation simulation shows the job title is going be nicer thanks to the new mapping"] + +== Put the new configuration to production + +Currently, your production HRIS reconciliation task (the recurring one) uses the _deprecated_ mapping, while the simulation reconciliation task uses the _proposed_ mapping. +To seamlessly move production from the old deprecated configuration to the new proposed one, _archive_ the _deprecated_ mapping and _activate_ the _proposed_ mapping. + +. In the HRIS resource, open inbound mapping configuration. +. Set the _job-to-title_ mapping lifecycle state to _Archived_. +. Set the _job-to-title-nice_ mapping lifecycle state to _Active_. +. Wait for the recurring HRIS reconciliation task to pick up the changes and provision the nicer job titles to all accounts in AD. + +.HRIS inbound mappings with the old job-to-title mapping archived and the new job-to-title-nice mapping active +image::hris-inbound-mapping-job-to-title-archived-job-to-title-nice-active.webp.webp["HRIS inbound mappings with the old job-to-title mapping archived and the new job-to-title-nice mapping active"] + +== Verify the results on AD + +Once the recurring HRIS reconciliation task processes the change, have a look at the AD projections in user profiles in midPoint to see the new prettified job titles there. + +.Improved job title format shown in AD projection in midPoint +image::midpoint-ldap-projection-job-title-nicer.webp["Improved job title format shown in AD projection in midPoint"] + +Then, navigate to the link:http://localhost/phpldapadmin/[AD server web UI] and check the job titles there. + +.Improved job title format shown in user AD profile +image::ldap-user-job-title-nicer.webp["Improved job title format shown in user AD profile"] + +You have successfully updated mappings using lifecycle states and simulations during normal operation (the scheduled HRIS reconciliation task was not suspended in the process). +This use of lifecycle states helped you improve and test properly your configuration thanks to simulations without disrupting the system operation. +The mapping in the _Archived_ lifecycle state can eventually be removed. + +:sectnums!: + +== Next steps + +This module concludes this section of the First steps guide dedicated to confirming the functionality and resilience of the setup you have created. +Up next is the last section of this guide focusing on the source data rectification. + +[.nowrap]#icon:arrow-right[] *xref:/midpoint/methodology/first-steps/override-incorrect-source-data/[]*# \ No newline at end of file diff --git a/why-evolveum/adopt-midpoint.drawio.svg b/why-evolveum/adopt-midpoint.drawio.svg index 3b0a8714f..20f868971 100644 --- a/why-evolveum/adopt-midpoint.drawio.svg +++ b/why-evolveum/adopt-midpoint.drawio.svg @@ -1,4 +1,4 @@ -
X
X
X
X
HR
HR
LDAP
LDAP
X
X
X
X
AD
AD
X
X
CSV
CSV
Accounting
Accounting
?
?
midPoint?
midPoint?
?
?
?
?
midPoint Methodology
midPoint Methodol...
Deploy midPoint
Deploy midPoint
HR
HR
LDAP
LDAP
AD
AD
CSV
CSV
Accounting
Accounting
midPoint
midPoint
How to solve this chaos?
How to solve this chaos?
Day 1
Day 1
From now to eternity…
From now to eternity…
Day 2
Day 2
… and ever after
… and ever after
A few months later…
A few months later…
Once upon a time…
Once upon a time…
Automate
Automate
Clean up data
Clean up data
Connect
new system
Connect...
Clean up
and activate on production
Clean up...
Day 3
Day 3
Connect the first systems
Connect the first systems
HR
HR
midPoint
midPoint
LDAP
LDAP \ No newline at end of file +
X
X
X
X
HR
HR
LDAP
LDAP
X
X
X
X
AD
AD
X
X
CSV
CSV
Accounting
Accounting
?
?
midPoint?
midPoint?
?
?
?
?
midPoint Methodology
midPoint Methodol...
Deploy midPoint
Deploy midPoint
HR
HR
LDAP
LDAP
AD
AD
CSV
CSV
Accounting
Accounting
midPoint
midPoint
How to solve this chaos?
How to solve this chaos?
Day 1
Day 1
From now to eternity…
From now to eternity…
Day 2
Day 2
… and ever after
… and ever after
A few months later…
A few months later…
Once upon a time…
Once upon a time…
Automate
Automate
Clean up data
Clean up data
Connect
new system
Connect...
Clean up
and activate on production
Clean up...
Day 3
Day 3
Connect the first systems
Connect the first systems
HR
HR
midPoint
midPoint
LDAP
LDAP \ No newline at end of file