User Management

User management in FreeIPA provides centralized control over user accounts across the enterprise. All IPA users are POSIX-compliant, supporting traditional UNIX/Linux authentication while integrating with Kerberos for single sign-on capabilities. Users can be associated with certificates for smart card authentication, passkeys for passwordless authentication, and SSH public keys for secure remote access.

User Account Lifecycle

User accounts in IPA follow a complete lifecycle from creation through deletion, with support for preservation and staging:

• Active Users: Standard operational user accounts with full authentication capabilities
• Disabled Users: Temporarily suspended accounts that cannot obtain new Kerberos credentials
• Preserved Users: Deleted users retained for potential restoration or compliance requirements
• Staged Users: Pre-provisioned accounts awaiting activation (see stageuser)

Username Format and Constraints

IPA supports flexible username formats that can be customized via ipa config-mod to meet organizational requirements. However, administrators should be aware of potential compatibility issues with certain UNIX systems.

Username Rules

User names must adhere to the following constraints:

• Cannot contain only numbers (at least one non-numeric character required)
• Must start with a letter, number, underscore (_), or period (.)
• May contain letters, numbers, underscores (_), periods (.), or hyphens (-)
• May end with a letter, number, underscore (_), period (.), hyphen (-), or dollar sign ($)
• Length restrictions may apply based on underlying OS compatibility requirements

POSIX Attributes

All IPA users are POSIX users with automatically assigned or manually specified attributes:

• UID: Unique user identifier number, auto-assigned from configured ID ranges
• GID: Primary group identifier, typically matching a private user group
• Home Directory: User’s home directory path (default: /home/username)
• Login Shell: User’s default shell (default: /bin/sh or configured default)
• GECOS: Traditionally the full name, used for user description

Authentication Methods

IPA users support multiple authentication mechanisms:

• Password Authentication: Traditional password-based authentication with policy enforcement
• Kerberos: Single sign-on via Kerberos tickets
• Certificate Authentication: Smart card or client certificate authentication
• Passkey Authentication: FIDO2/WebAuthn passwordless authentication
• OTP: One-time password for two-factor authentication
• SSH Keys: Public key authentication for SSH access

Account State Management

Disabling User Accounts

Disabling a user account immediately prevents the user from obtaining new Kerberos credentials. This is a non-destructive action suitable for temporary suspensions. Important considerations:

• Existing Kerberos tickets remain valid until expiration
• The user’s data and group memberships are preserved
• The account can be re-enabled without data loss
• Use for temporary suspensions, security incidents, or pending investigations

Account Lockout

Account lockout occurs automatically when password failure thresholds are exceeded, as defined by password policies. Key points:

• Lockout status is tracked per IPA server (not globally synchronized)
• Use user-status to identify which servers have locked the account
• Must unlock on each server where the lockout occurred
• Lockout is temporary and may auto-clear based on policy settings

User Attributes and Metadata

Beyond basic POSIX attributes, IPA users support extensive organizational metadata:

• Personal Information: Name variations, initials, display name
• Contact Information: Email, phone, mobile, pager, fax
• Organizational Data: Title, department, employee number, manager
• Location: Street address, city, state, postal code
• Custom Attributes: Extensible schema for organization-specific data

Principal Aliases

Users can have multiple Kerberos principal aliases beyond their primary principal (user@REALM). Principal aliases enable:

• Alternative authentication names
• Integration with external systems
• Email address-based authentication
• Legacy username support during migrations

Certificate and Passkey Management

Modern authentication methods are supported through certificate and passkey mappings:

• Certificates: Multiple certificates can be associated with a user for smart card authentication
• Certificate Mapping Data: Rules for mapping certificate attributes to user accounts
• Passkeys: FIDO2/WebAuthn credentials for passwordless authentication
• Multiple Credentials: Users can register multiple passkeys for redundancy

Manager Relationships

IPA supports organizational hierarchies through manager relationships, enabling:

• Organizational chart representation
• Delegated administration workflows
• Self-service delegation to direct reports
• Approval chain automation

Examples

Basic User Management

Add a new user with required attributes:

ipa user-add jdoe --first=John --last=Doe --email=jdoe@example.com

Add a user with a specific UID and prompt for password:

ipa user-add jsmith --first=Jane --last=Smith --uid=5001 --password

Generate a random password for a new user:

ipa user-add tempuser --first=Temporary --last=User --random

User Modification

Update user attributes:

ipa user-mod jdoe --title="Senior Engineer" --phone="555-0123"

Change user’s login shell:

ipa user-mod jdoe --shell=/bin/bash

Add a manager relationship:

ipa user-add-manager jdoe --manager=jsmith

Searching and Discovery

Find all users with “John” in any attribute:

ipa user-find John

Search for users by specific first name:

ipa user-find --first=Jane

Find all disabled users:

ipa user-find --disabled

List all members of a specific group:

ipa user-find --in-group=engineers

Find users NOT in a specific group:

ipa user-find --not-in-group=contractors

Account Lifecycle Operations

Disable a user account (temporary suspension):

ipa user-disable jdoe

Re-enable a previously disabled account:

ipa user-enable jdoe

Delete a user (moves to preserved users):

ipa user-del jdoe

Delete a user and preserve for later restoration:

ipa user-del jdoe --preserve

Restore a deleted user:

ipa user-undel jdoe

Lockout Management

Check lockout status across all servers:

ipa user-status jdoe

Unlock a locked account:

ipa user-unlock jdoe

Certificate Authentication

Add a certificate for smart card authentication:

ipa user-add-cert jdoe --certificate="MIIDtDCCApygAwIBAgI..."

Add certificate mapping data:

ipa user-add-certmapdata jdoe --subject="CN=John Doe,O=Example" --issuer="CN=Example CA"

Passkey Authentication

Add a passkey for passwordless authentication (interactive):

ipa user-add-passkey jdoe

Principal Management

Add an alternative Kerberos principal:

ipa user-add-principal jdoe --principal=john.doe@EXAMPLE.COM

Remove a principal alias:

ipa user-remove-principal jdoe --principal=john.doe@EXAMPLE.COM

Advanced Queries

Display complete user information including all attributes:

ipa user-show jdoe --all

Show raw LDAP representation:

ipa user-show jdoe --raw

Best Practices

Account Creation

• Always provide at least first name, last name, and email
• Use --password for manual password setting or --random for system-generated passwords
• Consider using staged users for bulk provisioning workflows
• Document manager relationships for organizational clarity

Account Naming

• Establish consistent username conventions (e.g., first.last, firstinitiallast)
• Reserve administrative accounts with clear naming (e.g., admin-jdoe)
• Avoid special characters that may cause compatibility issues
• Consider email address format compatibility

Security Considerations

• Use account disable rather than deletion for temporary suspensions
• Monitor lockout events via user-status for security incidents
• Implement certificate or passkey authentication for privileged users
• Regularly audit user accounts and remove unused accounts
• Use preserved deletion to maintain compliance records

Performance Optimization

• Use --sizelimit and --timelimit for large directory searches
• Leverage group membership searches for efficient user discovery
• Consider indexed attributes when developing custom search filters
• Use user-find with specific attributes rather than broad searches

Integration Points

User management integrates with multiple IPA subsystems:

• Groups: Users are members of groups for access control (see group)
• Password Policies: Password requirements and lifecycle (see pwpolicy)
• HBAC Rules: Host-based access control (see hbacrule)
• Sudo Rules: Privilege escalation policies (see sudorule)
• RBAC: Role-based administrative delegation (see role)
• Certificates: PKI integration (see cert)
• OTP Tokens: Two-factor authentication (see otptoken)

Commands

Command	Description
user-add	Add a new user
user-add-cert	Add certificates to user for authentication
user-add-certmapdata	Add certificate mapping rules
user-add-manager	Establish manager relationship
user-add-passkey	Register passkey for passwordless auth
user-add-principal	Add Kerberos principal alias
user-del	Delete user account
user-disable	Temporarily disable account
user-enable	Re-enable disabled account
user-find	Search for users by criteria
user-mod	Modify user attributes
user-remove-cert	Remove user certificates
user-remove-certmapdata	Remove certificate mappings
user-remove-manager	Remove manager relationship
user-remove-passkey	Unregister passkey credential
user-remove-principal	Remove principal alias
user-show	Display user information
user-stage	Move deleted user to staging
user-status	Check account lockout status
user-undel	Restore deleted user
user-unlock	Clear account lockout

---

user-add

Create a new active user account with specified attributes. Users are created as POSIX users with automatically assigned UIDs unless explicitly specified. The system generates a private user group by default.

Usage: ipa [global-options] user-add LOGIN [options]

When creating users, first and last names are typically required (may be made optional via configuration). Email addresses should follow organizational standards. Home directories and shells use configured defaults unless overridden.

Arguments

Argument	Required	Description
LOGIN	yes	User login name (must follow username rules)

Options

Option	Description
--first FIRST	First name (typically required)
--last LAST	Last name (typically required)
--cn CN	Full name (auto-generated from first/last if not specified)
--displayname DISPLAYNAME	Display name for applications
--initials INITIALS	User initials
--homedir HOMEDIR	Home directory path (default: /home/LOGIN)
--gecos GECOS	GECOS field (traditionally full name)
--shell SHELL	Login shell (default from configuration)
--principal PRINCIPAL	Additional Kerberos principal alias
--principal-expiration PRINCIPAL-EXPIRATION	Kerberos principal expiration date
--password-expiration PASSWORD-EXPIRATION	Password expiration date
--email EMAIL	Email address (may be required)
--password	Prompt to set initial password
--random	Generate random password (displayed once)
--uid UID	User ID number (auto-assigned if not specified)
--gidnumber GIDNUMBER	Primary group ID (default: auto-generated private group)
--street STREET	Street address
--city CITY	City name
--state STATE	State or province
--postalcode POSTALCODE	Postal/ZIP code
--phone PHONE	Telephone number
--mobile MOBILE	Mobile phone number
--pager PAGER	Pager number
--fax FAX	Fax number
--orgunit ORGUNIT	Organizational unit
--title TITLE	Job title
--manager MANAGER	Manager’s user ID
--carlicense CARLICENSE	Car license plate
--sshpubkey SSHPUBKEY	SSH public key (can be specified multiple times)
--user-auth-type USER-AUTH-TYPE	Supported authentication types (password, otp, radius, passkey, hardened)
--class CLASS	User category for local interpretation
--radius RADIUS	RADIUS proxy server name
--radius-username RADIUS-USERNAME	RADIUS proxy username
--idp IDP	External identity provider reference
--idp-user-id IDP-USER-ID	User identifier at external IdP
--departmentnumber DEPARTMENTNUMBER	Department number
--employeenumber EMPLOYEENUMBER	Employee number
--employeetype EMPLOYEETYPE	Employee type classification
--preferredlanguage PREFERREDLANGUAGE	Preferred language code
--certificate CERTIFICATE	Base-64 encoded user certificate
--setattr SETATTR	Set attribute to value (attr=value)
--addattr ADDATTR	Add attribute value (attr=value)
--noprivate	Don’t create private user group
--all	Retrieve and print all attributes
--raw	Print entries as stored on server
--no-members	Suppress membership attribute processing

---

user-del

Delete one or more user accounts. Deleted users are moved to preserved state by default, allowing potential restoration. Use --preserve=False for permanent deletion.

Usage: ipa [global-options] user-del LOGIN [LOGIN...] [options]

Deletion removes the user from all groups and access control rules. In multi-master environments, deletion propagates through replication.

Arguments

Argument	Required	Description
LOGIN	yes	User login name(s) to delete (multiple allowed)

Options

Option	Description
--continue	Continue processing on errors (for batch deletions)
--preserve	Preserve user for later restoration (default: true)

---

user-disable

Temporarily disable a user account, preventing new Kerberos ticket acquisition. Existing tickets remain valid until expiration. The user’s data and group memberships are preserved intact.

Usage: ipa [global-options] user-disable LOGIN [options]

Account disable is immediate and propagates across all replicas. Use for temporary suspensions, security incidents, or compliance requirements.

Arguments

Argument	Required	Description
LOGIN	yes	User login name to disable

---

user-enable

Re-enable a previously disabled user account, restoring authentication capabilities. The user can immediately obtain new Kerberos tickets upon successful authentication.

Usage: ipa [global-options] user-enable LOGIN [options]

All user data, group memberships, and access control assignments are preserved during the disabled state.

Arguments

Argument	Required	Description
LOGIN	yes	User login name to enable

---

user-find

Search for user accounts using various criteria. Supports free-text search across multiple attributes or targeted searches using specific field filters.

Usage: ipa [global-options] user-find [CRITERIA] [options]

Results can be filtered by group membership, account status, or specific attribute values. Use pagination options for large result sets.

Arguments

Argument	Required	Description
CRITERIA	no	Free-text search string (searches login, name, email, etc.)

Options

Option	Description
--first FIRST	Filter by first name
--last LAST	Filter by last name
--cn CN	Filter by full name
--uid UID	Filter by user login
--email EMAIL	Filter by email address
--title TITLE	Filter by job title
--manager MANAGER	Filter by manager
--in-group GROUP	Only users in specified group
--not-in-group GROUP	Only users NOT in specified group
--in-hbacrule HBACRULE	Users in specified HBAC rule
--not-in-hbacrule HBACRULE	Users NOT in specified HBAC rule
--in-sudorule SUDORULE	Users in specified sudo rule
--not-in-sudorule SUDORULE	Users NOT in specified sudo rule
--in-role ROLE	Users assigned to specified role
--not-in-role ROLE	Users NOT assigned to specified role
--disabled	Only disabled user accounts
--preserved	Only preserved (deleted) users
--timelimit TIMELIMIT	Search time limit in seconds
--sizelimit SIZELIMIT	Maximum results to return
--all	Retrieve all attributes
--raw	Display raw LDAP values
--pkey-only	Return only primary key (login)
--no-members	Suppress membership processing

---

user-mod

Modify attributes of an existing user account. Most user attributes can be updated after account creation except the login name (use --rename for login changes).

Usage: ipa [global-options] user-mod LOGIN [options]

Attribute modifications are immediate and replicate across all IPA servers. Some changes may require user re-authentication to take full effect.

Arguments

Argument	Required	Description
LOGIN	yes	User login name to modify

Options

Option	Description
--first FIRST	Update first name
--last LAST	Update last name
--cn CN	Update full name
--displayname DISPLAYNAME	Update display name
--initials INITIALS	Update initials
--homedir HOMEDIR	Update home directory path
--gecos GECOS	Update GECOS field
--shell SHELL	Update login shell
--principal PRINCIPAL	Add Kerberos principal
--principal-expiration DATE	Set principal expiration
--password-expiration DATE	Set password expiration
--email EMAIL	Update email address
--uid UID	Update UID (use with caution)
--gidnumber GID	Update primary GID
--street STREET	Update street address
--city CITY	Update city
--state STATE	Update state/province
--postalcode POSTALCODE	Update postal code
--phone PHONE	Update phone number
--mobile MOBILE	Update mobile number
--pager PAGER	Update pager number
--fax FAX	Update fax number
--orgunit ORGUNIT	Update organizational unit
--title TITLE	Update job title
--manager MANAGER	Update manager assignment
--departmentnumber DEPT	Update department number
--employeenumber EMP	Update employee number
--employeetype TYPE	Update employee type
--preferredlanguage LANG	Update preferred language
--sshpubkey KEY	Update SSH public key
--user-auth-type TYPE	Update authentication types
--certificate CERT	Update certificate
--rename NEWLOGIN	Rename user login (use with extreme caution)
--setattr ATTR=VAL	Set attribute to value
--addattr ATTR=VAL	Add attribute value (multi-valued)
--delattr ATTR=VAL	Delete attribute value
--all	Retrieve all attributes
--raw	Display raw values
--no-members	Suppress membership processing

---

user-show

Display detailed information about a specific user account including all attributes, group memberships, and associated resources.

Usage: ipa [global-options] user-show LOGIN [options]

Output includes POSIX attributes, organizational data, authentication configurations, and membership information.

Arguments

Argument	Required	Description
LOGIN	yes	User login name to display

Options

Option	Description
--all	Display all attributes including defaults
--raw	Show raw LDAP attribute values
--no-members	Suppress group membership display

---

user-status

Check account lockout status across all IPA servers. Displays per-server lockout state for diagnosing authentication failures.

Usage: ipa [global-options] user-status LOGIN [options]

Account lockout occurs when password failures exceed policy thresholds. Lockout is tracked independently on each IPA server, requiring per-server status checks and unlocking.

This command connects to each replica and returns:

• Server name
• Lockout status (locked/not locked)
• Failed login count
• Last failed login timestamp
• Time until automatic unlock (if configured)

Arguments

Argument	Required	Description
LOGIN	yes	User login name to check

Options

Option	Description
--all	Include all status details
--raw	Display raw status data

---

user-unlock

Clear account lockout status for a user account. Must be executed on each server where the account is locked.

Usage: ipa [global-options] user-unlock LOGIN [options]

Account lockout results from exceeding password failure thresholds defined in password policy. Lockout provides protection against brute force attacks but may require administrative intervention for legitimate lockouts.

After unlocking, users can immediately attempt authentication. Consider investigating the cause of repeated lockouts.

Arguments

Argument	Required	Description
LOGIN	yes	User login name to unlock

---

user-add-cert

Associate X.509 certificates with a user account for certificate-based authentication including smart cards and client certificates.

Usage: ipa [global-options] user-add-cert LOGIN [options]

Certificates enable multi-factor authentication and smart card logon. Multiple certificates can be associated with a single user account.

Arguments

Argument	Required	Description
LOGIN	yes	User login name

Options

Option	Description
--certificate CERT	Base-64 encoded X.509 certificate (PEM format without headers)
--all	Display all attributes
--raw	Show raw values
--no-members	Suppress membership display

---

user-add-certmapdata

Configure certificate mapping rules that define how certificate attributes map to user accounts for authentication purposes.

Usage: ipa [global-options] user-add-certmapdata LOGIN [options]

Certificate mapping enables flexible certificate-to-user matching using issuer, subject, and other certificate attributes.

Arguments

Argument	Required	Description
LOGIN	yes	User login name

Options

Option	Description
--issuer ISSUER	Certificate issuer DN
--subject SUBJECT	Certificate subject DN
--certificate CERT	Full certificate for mapping
--all	Display all attributes
--raw	Show raw values
--no-members	Suppress membership display

---

user-add-manager

Establish or add to the manager relationship for a user, creating organizational hierarchy.

Usage: ipa [global-options] user-add-manager LOGIN [options]

Manager relationships enable organizational charts, delegated administration, and approval workflows.

Arguments

Argument	Required	Description
LOGIN	yes	User login name (subordinate)

Options

Option	Description
--manager MANAGER	Manager’s user login name
--all	Display all attributes
--raw	Show raw values
--no-members	Suppress membership display

---

user-add-passkey

Register a FIDO2/WebAuthn passkey credential for passwordless authentication. This command initiates an interactive registration flow.

Usage: ipa [global-options] user-add-passkey LOGIN [options]

Passkeys provide phishing-resistant authentication using FIDO2 security keys or platform authenticators.

Arguments

Argument	Required	Description
LOGIN	yes	User login name

Options

Option	Description
--all	Display all attributes
--raw	Show raw values
--no-members	Suppress membership display

---

user-add-principal

Add an alternative Kerberos principal name to a user account, enabling authentication with multiple principal formats.

Usage: ipa [global-options] user-add-principal LOGIN [options]

Principal aliases support email-based authentication, legacy usernames, or integration with external systems.

Arguments

Argument	Required	Description
LOGIN	yes	User login name

Options

Option	Description
--principal PRINCIPAL	Kerberos principal (must include @REALM)
--all	Display all attributes
--raw	Show raw values
--no-members	Suppress membership display

---

user-remove-cert

Remove X.509 certificates from a user account.

Usage: ipa [global-options] user-remove-cert LOGIN [options]

Arguments

Argument	Required	Description
LOGIN	yes	User login name

Options

Option	Description
--certificate CERT	Certificate to remove (exact match required)
--all	Display all attributes
--raw	Show raw values
--no-members	Suppress membership display

---

user-remove-certmapdata

Remove certificate mapping data from a user account.

Usage: ipa [global-options] user-remove-certmapdata LOGIN [options]

Arguments

Argument	Required	Description
LOGIN	yes	User login name

Options

Option	Description
--issuer ISSUER	Issuer DN to remove
--subject SUBJECT	Subject DN to remove
--certificate CERT	Certificate mapping to remove
--all	Display all attributes
--raw	Show raw values
--no-members	Suppress membership display

---

user-remove-manager

Remove manager relationship from a user account.

Usage: ipa [global-options] user-remove-manager LOGIN [options]

Arguments

Argument	Required	Description
LOGIN	yes	User login name

Options

Option	Description
--manager MANAGER	Manager login to remove
--all	Display all attributes
--raw	Show raw values
--no-members	Suppress membership display

---

user-remove-passkey

Unregister a passkey credential from a user account.

Usage: ipa [global-options] user-remove-passkey LOGIN [options]

Arguments

Argument	Required	Description
LOGIN	yes	User login name

Options

Option	Description
--all	Display all attributes
--raw	Show raw values
--no-members	Suppress membership display

---

user-remove-principal

Remove a Kerberos principal alias from a user account. The primary principal cannot be removed.

Usage: ipa [global-options] user-remove-principal LOGIN [options]

Arguments

Argument	Required	Description
LOGIN	yes	User login name

Options

Option	Description
--principal PRINCIPAL	Principal alias to remove
--all	Display all attributes
--raw	Show raw values
--no-members	Suppress membership display

---

user-stage

Move a deleted (preserved) user back to the staged area. Staged users can later be activated as new users.

Usage: ipa [global-options] user-stage LOGIN [options]

This operation is useful for recycling user accounts or implementing approval workflows.

Arguments

Argument	Required	Description
LOGIN	yes	User login name to stage

---

user-undel

Restore a deleted (preserved) user account to active status. All attributes and group memberships are restored.

Usage: ipa [global-options] user-undel LOGIN [options]

Account restoration is only possible for preserved users. Permanently deleted users cannot be restored.

Arguments

Argument	Required	Description
LOGIN	yes	User login name to restore

Options

Option	Description
--all	Display all attributes
--raw	Show raw values
--no-members	Suppress membership display