{{tag> topic module pam privileged accounts cyberark password provisioning idm-pam }}

====== Modules - Privileged Accounts Management [pam] ======

<note important>This is a paid module, contact your sales representative for purchase information.</note>

===== Introduction =====

The Privileged Accounts Management (PAM) module integrates IdStory IdM with **CyberArk** and manages the lifecycle and passwords of privileged **secondary personal accounts**. It builds on the standard **acc** (accounts and provisioning) module and reacts to account and provisioning events - it does not expose its own REST agenda.

Core responsibilities:

  * Automatically maintain a **CyberArk account** (also referred to as CBA) for a PAM identity that owns one or more secondary personal accounts in a given zone.
  * Propagate password changes of managed accounts to CyberArk.
  * Block provisioning of generated passwords for accounts whose password is managed by PAM.
  * Enforce **zone** and **tier** compatibility when roles are assigned to secondary accounts.
  * Notify identities about newly created accounts and generated passwords using PAM specific notification topics.

===== Version =====

^Module version  ^Compatible with IdStory IdM  ^Notes  |
|15.1.3-SNAPSHOT  |15.9.0  |Current development version  |

//The module is built against the ''idm-parent'' / IdStory IdM version listed above. It depends on the ''idm-acc'' and ''idm-core'' modules.//

===== Key concepts =====

  * **PAM identity** - an identity flagged as PAM (''IdmIdentityDto#isPam()''). Almost all module logic runs only for these identities.
  * **Secondary personal account** (also "other personal account") - an account whose system mapping has account type ''PERSONAL_OTHER''. This is the account type the module manages.
  * **CyberArk system (CBA)** - the privileged vault system. The module supports **multiple** CyberArk systems, each with its own set of **connected systems** (the systems whose privileged accounts are vaulted under that CyberArk system).
  * **Zone** - attribute on accounts and roles used to group accounts that belong together (locality). CyberArk accounts are resolved per identity + zone.
  * **Tier** - numeric attribute on accounts and roles used for authorization of role assignment.
  * **Password management type** - how the account password is handled by PAM: ''KEYPASS'', ''MANAGED'' or ''UNKNOWN'' (see [[#password_management_model|Password management model]]).

===== Getting Started =====

FIXME Add a step-by-step walkthrough (with screenshots) for a first setup: flag the identity as PAM, prepare the CyberArk system and connected systems, and create the first secondary personal account.

Prerequisites at a glance:

  * A configured CyberArk **system** in IdStory IdM with a provisioning mapping for account type ''PERSONAL_OTHER''.
  * Connected systems (the target systems) with their own ''PERSONAL_OTHER'' provisioning mappings.
  * The ''idm.sec.pam.cyberArk.*'' configuration filled in (see [[#configuration|Configuration]]).
  * Identities that should be managed flagged as PAM.

===== Configuration =====

==== Installation ====

FIXME Describe module deployment for the target installation (backend jar into the IdM, frontend module into the FE build).

==== CyberArk systems ====

These properties define which systems are CyberArk systems, their processing order, and which systems are connected to them. They are secure properties (''idm.sec.'' prefix), editable through the configuration service by the application administrator.

<code properties>
# Default CyberArk system (order 1) - UUID of the SysSystem
idm.sec.pam.cyberArk.order1.systemId=<system-uuid>
# Additional CyberArk systems, numbered from 1 upwards without gaps
idm.sec.pam.cyberArk.order2.systemId=<system-uuid>

# Systems connected to CyberArk system order1 (numbered from 1)
idm.sec.pam.cyberArk.order1.connectedSystemId1=<connected-system-uuid>
idm.sec.pam.cyberArk.order1.connectedSystemId2=<connected-system-uuid>
</code>

  * The system with **order 1** is the **default** CyberArk system.
  * ''getAllCyberArkSystemIds()'' reads ''order1'', ''order2'', ... and stops at the first missing ''systemId'' - keep the ordering contiguous.
  * For a given connected system the module resolves its CyberArk system by matching the connected system UUID against the ''connectedSystemId*'' values; if no match is found, the **default** CyberArk system is used.

==== Zone and tier ====

Zone and tier are attributes on both accounts and roles. When a role is requested for a secondary account (''PERSONAL_OTHER''), the module checks that:

  * both the account and the role have a **zone** and a **tier** filled in,
  * the role **zone** equals the account **zone**,
  * the tier values are numeric and the account **tier** is less than or equal to the role **tier** (the account's tier must not be higher than the role's).

Violations are reported with the [[#result_codes|result codes]] below. The check is performed by the ''pam-role-request-check-zone-and-tier-processor''.

==== Blocking generated passwords on managed accounts ====

For PAM identities, generated passwords must not be provisioned to accounts whose password is managed by PAM. This is handled by a pair of processors - see the dedicated page:

  * [[.:modules_pam:pam-check-provisioning-processor|Provisioning of generated passwords to PAM accounts]]

===== Password management model =====

The module derives the password management type from the **account UID**. The UID is split by underscores; the character immediately following the **first** underscore determines the type:

<code>
userName_Nxxxx_...   -> KEYPASS   (character after first underscore is N)
userName_Pxxxx_...   -> MANAGED   (character after first underscore is P)
</code>

^Type  ^Meaning  |
|''KEYPASS''  |Password is stored in CyberArk but **not rotated**. Password changes are forwarded to CyberArk.  |
|''MANAGED''  |Password is stored **and rotated** by CyberArk. Provisioning of generated passwords from IdM is blocked.  |
|''UNKNOWN''  |Type could not be resolved from the UID (fewer than two underscore separated parts, or an unexpected character).  |

<note important>The module recognizes managed accounts by the character right after the **first** underscore in the account UID. If the user name part itself contains an underscore, the detection reads the wrong part and the module will not behave correctly. Keep user names free of underscores.</note>

===== Maintenance =====

This section describes what the module does around the lifecycle of secondary personal accounts. The behaviour is fully event driven.

==== Creating a secondary account ====

When a new ''PERSONAL_OTHER'' account is linked to a PAM identity (''pam-new-secondary-account-added-processor''):

  * The module resolves the CyberArk system for the account's system.
  * If this is the first non protected secondary account for that identity + zone (or no CyberArk account exists), a CyberArk account is created via the ''PersonalOtherAccountWizard''.
  * An inactive (protected) CyberArk account for the same identity + zone is **reactivated** instead of creating a new one.
  * If a CyberArk account already exists, provisioning is (re)published for it and, for ''KEYPASS'' accounts, the password is reset so it is propagated.

==== Protecting or deleting a secondary account ====

Before a secondary account is set to protected or deleted (''pam-secondary-account-before-change-to-protected-processor'', ''pam-secondary-account-before-delete-processor''), the related CyberArk account id is stored on the event. After the action (''pam-secondary-account-after-delete-processor''):

  * If the changed account was the **only** remaining non protected secondary account under that CyberArk system, the CyberArk account is deleted.
  * Otherwise the CyberArk account is re-provisioned (internal provisioning, so account protection is respected).

FIXME Add the administrator's step-by-step view of these actions (GUI screenshots).

===== Processors =====

All PAM processors are guarded by ''@Enabled("pam")''.

==== Account ====

  * ''pam-new-secondary-account-added-processor'' - on create of an identity-account for a ''PERSONAL_OTHER'' account of a PAM identity, ensures the CyberArk account exists (creates or reactivates it), and resets the password for ''KEYPASS'' accounts.
  * ''pam-secondary-account-before-change-to-protected-processor'' - before a secondary account becomes protected, records the related CyberArk account for post processing.
  * ''pam-secondary-account-before-delete-processor'' - before a secondary account is deleted, records the related CyberArk account for post processing.
  * ''pam-secondary-account-after-delete-processor'' - after update / delete, deletes the CyberArk account if it was the last secondary account, otherwise re-provisions it.

==== Provisioning ====

  * ''pam-reset-password-for-first-cyber-ark-account-processor'' - on the first successful creation of a CyberArk account, resets the password of the pre-existing secondary ''KEYPASS'' account so it is propagated to CyberArk.
  * ''pam-send-password-to-cyber-ark-account-processor'' - after a successful password provisioning to a connected system for a ''KEYPASS'' account, pushes the password to the matching CyberArk account via a direct connector call and archives the operation. <wrap hi>Note: this bypasses the standard provisioning queue and mapping strategies.</wrap>
  * ''pam-check-provisioning-password-processor'' and ''pam-set-is-generate-property-on-password-generate'' - block provisioning of generated passwords for ''MANAGED'' accounts of PAM identities (see the linked page above).
  * ''pam-notify-acc-creation-processor'' - sends an account creation notification for ''PERSONAL_OTHER'' accounts of PAM identities, choosing the KEYPASS or MANAGED topic.
  * ''pam-provisioning-send-notification-processor'' - sends the new password notification; uses the PAM KEYPASS / MANAGED topics for ''PERSONAL_OTHER'' accounts, otherwise the core topic.

==== Role request ====

  * ''pam-role-request-check-zone-and-tier-processor'' - on role request create / update in state CONCEPT, validates zone and tier compatibility for concepts adding a role to a ''PERSONAL_OTHER'' account.

==== Module ====

  * ''pam-init-module-processor'' - initializes the module and seeds the default (disabled) notification configurations.

===== Notifications =====

The module registers its own notification topics and default templates.

^Topic  ^Used for  ^Default template  |
|''pam:accountCreatedManaged''  |Creation of a MANAGED secondary account  |''pamAccountCreatedManaged''  |
|''pam:accountCreatedKeypass''  |Creation of a KEYPASS secondary account  |''pamAccountCreatedKeypass''  |
|''pam:newPasswordManaged''  |New generated password for a MANAGED account  | |
|''pam:newPasswordKeypass''  |New generated password for a KEYPASS account  | |

Default notification configurations are created disabled on module init and can be enabled in **Settings - Notifications**.

===== Permissions =====

The module currently defines only an example group permission ''EXAMPLEPAM'' (with ''EXAMPLEPAM_ADMIN''). Access to PAM related data (accounts, systems, role requests) is governed by the standard **core** and **acc** permissions and evaluators - for example the frontend dashboard requires ''ACCOUNT_READ''.

FIXME Define the real PAM group permissions / evaluators once they exist and document them here.

===== Working with module components =====

  * [[https://wiki.czechidm.com/devel/documentation/accounts/dev/personal-other-accounts|Personal other accounts]]
  * [[https://wiki.czechidm.com/devel/documentation/roles#roles_and_accounts|Roles with accounts]]
  * Processors:
      * [[https://wiki.czechidm.com/devel/documentation/modules_pam/pam-check-provisioning-processor|PamCheckProvisioningPasswordProcessor]]

===== Frontend components =====

  * **Other personal accounts** dashboard <badge>@since 15.0.0</badge> - an identity dashboard panel that lists the identity's ''PERSONAL_OTHER'' accounts (requires ''ACCOUNT_READ''). Registered as identity dashboard component ''personal_other-account-dashboard''.

===== Database =====

The module keeps its own Flyway history table ''idm_schema_version_pam''. Migrations are located at ''classpath:eu/bcvsolutions/idm/pam/sql/${dbName}'' (currently PostgreSQL only).

===== Result codes =====

^Code  ^HTTP  ^Meaning  |
|''ACCOUNT_MANAGED_BY_PAM''  |400  |Password change was blocked because the account's password is managed by the PAM system.  |
|''MISSING_ZONE_ON_ACCOUNT''  |500  |The secondary account has no zone attribute.  |
|''MISSING_ZONE_ON_ROLE''  |500  |The role has no zone attribute.  |
|''MISSING_TIER_ON_ACCOUNT''  |500  |The secondary account has no tier attribute.  |
|''MISSING_TIER_ON_ROLE''  |500  |The role has no tier attribute.  |
|''MISMATCHED_ZONE_ON_ROLE_REQUEST''  |400  |The role zone and the account zone do not match.  |
|''MISMATCHED_TIER_ON_ROLE_REQUEST''  |400  |The account's tier is insufficient for the requested role.  |
|''INVALID_TIER_ON_ROLE''  |500  |The role tier is not a number.  |
|''INVALID_TIER_ON_ACCOUNT''  |500  |The account tier is not a number.  |

===== Troubleshooting =====

=== Underscores in account UID ===

The module determines which accounts are managed by PAM from the character immediately after the **first** underscore in the account UID (for example `userName_Nxxxx_...`). If the user name part contains an underscore, detection reads the wrong part and the module will not work correctly. Keep user names free of underscores.

=== CyberArk system id not configured ===

Processors log //"Configuration property for cyber ark system id is not configured correctly or missing."// when ''idm.sec.pam.cyberArk.orderN.systemId'' is missing or invalid. Verify the [[#cyberark_systems|CyberArk systems]] configuration and that the referenced systems exist.

=== CyberArk account not found ===

If a password change or account action logs that the CyberArk account was not found, check that the identity is flagged as PAM, that the account is ''PERSONAL_OTHER'', and that a CyberArk account for the same identity + zone exists and is not in protection.

===== Glossary =====

  * **PAM identity** - identity flagged as privileged (''isPam()''); PAM logic applies only to these.
  * **Secondary / other personal account** - account of type ''PERSONAL_OTHER'' managed by the module.
  * **CyberArk system (CBA)** - privileged vault system integrated with the module; can be several, ordered from 1.
  * **Connected system** - a target system whose privileged accounts are vaulted under a CyberArk system.
  * **Zone** - locality attribute grouping accounts (and roles) that belong together.
  * **Tier** - numeric authorization level on accounts and roles.
  * **KEYPASS / MANAGED** - password management types (stored not rotated / stored and rotated).