User Management - CLI Reference

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

Use Cases

Bulk User Provisioning for New Hires

Scenario: HR onboards 50 new employees monthly requiring automated account creation.

Solution:

# CSV format: firstname,lastname,username,email,title,department,manager
# alice,smith,asmith,alice.smith@example.com,Engineer,Engineering,jdoe

while IFS=, read -r first last user email title dept manager; do
    ipa user-add "$user" \
        --first="$first" \
        --last="$last" \
        --email="$email" \
        --title="$title" \
        --department="$dept" \
        --manager="$manager" \
        --random

    # Capture random password for email to user
    echo "User: $user, Password: [sent securely]"
done < new-hires.csv

# Add users to department groups
ipa group-add-member engineering --users=asmith,bsmith

Temporary Contractor Access with Expiration

Scenario: External contractors need time-limited access that automatically expires.

Solution:

# Create user with principal expiration
ipa user-add contractor1 \
    --first=John \
    --last=Contractor \
    --email=john.contractor@vendor.com \
    --title="Security Consultant" \
    --principal-expiration=20241231235959Z

# User account automatically becomes unusable after Dec 31, 2024
# No manual cleanup needed

# Add to contractor group for HBAC/sudo policies
ipa group-add-member contractors --users=contractor1

Executive Smart Card Authentication

Scenario: C-level executives require high-security smart card authentication.

Solution:

# Create executive user account
ipa user-add ceo \
    --first=Jane \
    --last=Executive \
    --email=ceo@example.com \
    --title="Chief Executive Officer" \
    --department="Executive"

# Add smart card certificate
ipa user-add-cert ceo --certificate="$(cat ceo-smartcard.pem)"

# Configure certificate mapping for smart card
ipa certmap-add exec-smartcard \
    --matchrule "<ISSUER>:CN=Corporate PIV CA" \
    --maprule "(employeeNumber={<SUBJECT:serialNumber>})"

# CEO authenticates with smart card, no password needed

Employee Departure with Account Preservation

Scenario: Employee leaves company; account must be disabled but preserved for compliance.

Solution:

# Disable user account (stops new authentication)
ipa user-disable departing-employee

# Remove from active groups (revokes access)
ipa group-remove-member developers --users=departing-employee
ipa group-remove-member engineering --users=departing-employee

# Move to preserved users after retention period (e.g., 90 days)
# Wait 90 days...
ipa user-del departing-employee --preserve

# Account preserved for audit/compliance, cannot authenticate
# Can restore if needed: ipa user-undel departing-employee

Passwordless Authentication with FIDO2 Passkeys

Scenario: Security team requires phishing-resistant passwordless authentication.

Solution:

# User registers passkey (YubiKey, Touch ID, Windows Hello)
# From user workstation:
ipa user-add-passkey alice --register

# Follow prompts to insert YubiKey and touch it
# Passkey registered with IPA

# User can now authenticate without password
# kinit alice
# (prompts for YubiKey touch instead of password)

# Phishing-resistant, hardware-backed authentication

Manager Hierarchy for Approval Workflows

Scenario: Manager relationships drive approval workflows in external systems.

Solution:

# Create organizational hierarchy
ipa user-add ceo --first=Jane --last=Doe
ipa user-add cto --first=Bob --last=Smith --manager=ceo
ipa user-add eng-manager --first=Alice --last=Johnson --manager=cto
ipa user-add developer --first=Charlie --last=Brown --manager=eng-manager

# Query reports (direct or indirect)
ipa user-find --manager=eng-manager  # Charlie's direct reports
ipa user-find --manager=cto  # Alice's reports (direct)

# External systems can query manager chain for approval routing
# Developer → Eng Manager → CTO → CEO

SSH Public Key Distribution for Infrastructure

Scenario: Developers need SSH access to infrastructure with centralized key management.

Solution:

# User adds SSH public key to their account
ipa user-mod alice \
    --sshpubkey="ssh-rsa AAAAB3NzaC1... alice@workstation"

# SSSD on infrastructure servers retrieves SSH keys from IPA
# /etc/ssh/sshd_config configured:
# AuthorizedKeysCommand /usr/bin/sss_ssh_authorizedkeys
# AuthorizedKeysCommandUser nobody

# Alice can SSH to any server without managing authorized_keys files
# Centralized key rotation: update IPA, affects all servers immediately

Account Lockout Investigation and Recovery

Scenario: User locked out after password failures, needs investigation and unlock.

Solution:

# User reports unable to login
# Check lockout status across servers
ipa user-status alice

# Output shows which IPA servers have locked the account
# Server: ipa1.example.com, Failures: 5, Last failure: 2024-05-12 10:15
# Server: ipa2.example.com, Failures: 0

# Unlock on affected servers
ipa user-unlock alice --server=ipa1.example.com

# Investigate if credential compromise suspected
# Review auth logs, check for unusual patterns
# Force password reset if needed
ipa user-mod alice --password

Principal Alias for Email-Based Authentication

Scenario: Users want to authenticate using email addresses instead of usernames.

Solution:

# Add email as principal alias
ipa user-add-principal alice alice.smith@example.com

# User can now authenticate with either:
kinit alice
# or
kinit alice.smith@example.com

# Both work, same user account
# Useful for SSO integrations expecting email-based identities

Staged User Approval Workflow

Scenario: New accounts require manager approval before activation.

Solution:

# HR creates staged user (not yet active)
ipa stageuser-add pending-user \
    --first=New \
    --last=Employee \
    --email=new.employee@example.com

# Manager reviews and approves
ipa stageuser-show pending-user
# If approved:
ipa stageuser-activate pending-user

# User now active and can authenticate
# If denied:
ipa stageuser-del pending-user

Security Considerations

Password storage and reset security: User passwords never stored in cleartext, only Kerberos hashes. However, --password on command line may appear in shell history. Use --random or interactive prompts for production. Clear shell history after manual password sets.

Disabled accounts retain Kerberos tickets: Disabling a user doesn’t invalidate existing Kerberos TGTs. Tickets remain valid until expiration (typically 24 hours). For immediate revocation, must also invalidate tickets on KDCs or wait for natural expiration.

Account lockout inconsistency across servers: Lockout tracked per IPA server, not globally replicated. User locked on one server can still authenticate to others. Must unlock on all affected servers for complete recovery. Consider this in multi-master deployments.

UID/GID reuse risks: Deleting users without --preserve releases UID/GID for reuse. Files owned by old UID could become accessible to new user receiving same UID. Always use --preserve or audit/remove files before permanent deletion.

Principal alias enables impersonation: Adding principal aliases grants additional authentication paths. Malicious admin could add alias to their account matching legitimate user’s email, enabling impersonation. Audit principal alias additions.

Certificate mapping bypass potential: User certificates stored in usercertificate attribute enable authentication without passwords. Compromised certificates or certificate mapping rules could bypass password policies. Protect certificate private keys and validate mapping rules.

Manager relationship visibility: Manager attributes visible to all authenticated users. In organizations where reporting structure is sensitive, this could reveal organizational hierarchy. Consider LDAP ACLs for sensitive environments.

SSH key persistence across password changes: SSH public keys remain valid even after password changes. Compromised SSH keys continue working until explicitly removed. Rotate SSH keys periodically and audit public key usage.

Preserved user data retention: Preserved users retain all attributes including group memberships and certificates. If restored accidentally or maliciously, old permissions reactivate. Carefully audit preserved user restorations.

Random passwords security: --random generates high-entropy passwords but they must be securely transmitted to users. Sending random passwords via email is insecure. Use secure password distribution mechanisms or force immediate change at first login.

GECOS field information disclosure: GECOS (full name) visible to all authenticated users. Some organizations store sensitive information in GECOS. Validate GECOS content doesn’t expose private data.

Passkey backup and recovery: FIDO2 passkeys typically bound to specific hardware. Lost hardware means lost authentication method. Ensure users have backup authentication methods (password, OTP) before relying solely on passkeys.

External principal aliases cross-realm risks: Principal aliases can include cross-realm principals. Misconfigured aliases could grant unintended trust relationships. Carefully validate principal alias formats and realms.

User modification audit trail: User account modifications logged in IPA but may not include all context. Implement additional logging for compliance environments requiring complete audit trails.

Troubleshooting

User creation fails with “UID already in use”:

# UID conflict with existing user
ipa user-find --uid=10000

# Either delete conflicting user or use different UID
ipa user-add newuser --first=New --last=User --uid=10001

# Or let IPA auto-assign UID (recommended)
ipa user-add newuser --first=New --last=User

User cannot authenticate - “principal not found”:

# Verify user exists
ipa user-show username

# Check if user is disabled
ipa user-show username | grep "Disabled"

# If disabled, enable
ipa user-enable username

# Verify Kerberos principal exists
ipa user-show username --all | grep "Kerberos principal"

# Test authentication
kinit username

User locked out after password failures:

# Check lockout status across all servers
ipa user-status username

# Shows which servers have locked the account
# Unlock on each affected server
ipa user-unlock username --server=ipa1.example.com
ipa user-unlock username --server=ipa2.example.com

# Or unlock globally (unlocks on all servers)
for server in $(ipa server-find --pkey-only | grep 'Server name' | awk '{print $3}'); do
    ipa user-unlock username --server=$server
done

Cannot delete user - “preserved user exists”:

# User was previously deleted with --preserve
# Must permanently delete preserved user first

# Check preserved users
ipa user-find --preserved

# Permanently delete
ipa user-undel username --preserve=False

# Or delete preserved user entirely
# This is permanent and cannot be undone
ipa user-del username --continue

User principal alias not working for authentication:

# Verify alias exists
ipa user-show username --all | grep "Principal alias"

# Ensure alias includes realm
# Correct: alice@example.com@EXAMPLE.COM
# Incorrect: alice@example.com

# Add with correct format
ipa user-add-principal username alice@example.com@EXAMPLE.COM

# Test alias authentication
kinit alice@example.com@EXAMPLE.COM

SSH public key not working for user:

# Verify key in IPA
ipa user-show username --all | grep -A5 "SSH public key"

# On client, verify SSSD SSH integration
sss_ssh_authorizedkeys username

# If empty, SSSD not configured for SSH
# /etc/ssh/sshd_config should have:
# AuthorizedKeysCommand /usr/bin/sss_ssh_authorizedkeys
# AuthorizedKeysCommandUser nobody

# Restart sshd
systemctl restart sshd

User certificate authentication failing:

# Verify certificate in user entry
ipa user-show username --all | grep -A5 "Certificate"

# Check certificate mapping rules
ipa certmap-find

# Verify certificate hasn't expired
openssl x509 -in user-cert.pem -noout -dates

# Check if certificate matches user
ipa certmap-match "$(cat user-cert.pem)"

# Should return the correct user

User’s manager relationship not visible:

# Verify manager set
ipa user-show username | grep Manager

# If missing, add manager
ipa user-add-manager username --managers=manager-username

# Verify manager user exists
ipa user-show manager-username

# Query direct reports of manager
ipa user-find --manager=manager-username

Password reset not taking effect:

# Password change may need time to replicate
# Wait 30 seconds and retry

# Verify password set successfully
ipa user-show username | grep "Password"

# Force password sync across replicas
# On each IPA server:
ipa-replica-manage force-sync

# User should destroy old tickets and re-kinit
kdestroy
kinit username

Cannot modify user - “Insufficient access”:

# Verify user has appropriate permissions
ipa user-show $USER --all | grep "memberof"

# Check if user is in admins group
ipa group-show admins

# Check specific permissions
ipa permission-find --attrs=cn --attrs=uid

# Grant user modification privileges
ipa role-add-member "User Administrator" --users=adminuser

User’s UID changed causing file permission issues:

# Files owned by old UID become orphaned
# Find files with old UID
find /home -uid 10000 -ls

# Update ownership to new UID
find /home -uid 10000 -exec chown 10001:10001 {} \;

# Or if UID change was mistake, revert
ipa user-mod username --uid=10000

Passkey registration failing:

# Verify passkey configuration enabled
ipa passkeyconfig-show

# Check if user verification required
ipa passkeyconfig-show | grep "require user verification"

# Ensure client has WebAuthn support
# Browser-based: Chrome/Firefox/Safari modern versions
# CLI: ipa-client with FIDO2 library installed

# Try registration again with verbose output
ipa user-add-passkey username --register -v

User shows in IPA but not resolving on clients:

# Clear SSSD cache on client
sudo sssctl cache-expire --users=username
sudo systemctl restart sssd

# Test user resolution
getent passwd username
id username

# If still missing, check SSSD connectivity
sudo sssctl domain-status example.com

# Check SSSD logs
sudo journalctl -u sssd -n 100 | grep username

User account not expiring despite principal expiration set:

# Verify principal expiration set
ipa user-show username --all | grep "Principal expiration"

# Format must be: YYYYMMDDHHmmssZ
# Example: 20241231235959Z for Dec 31, 2024 23:59:59 UTC

# Set with correct format
ipa user-mod username --principal-expiration=20241231235959Z

# Expiration checked at authentication time
# Test by attempting login after expiration

Bulk user creation failing partway through:

# Some users created, others failed
# Identify failures

# Check which users already exist
ipa user-find --pkey-only | grep username

# Use --continue flag for batch operations
while IFS=, read -r user first last; do
    ipa user-add "$user" --first="$first" --last="$last" --continue
done < users.csv

# --continue processes all records even if some fail
# Review output for specific failures

Cannot add user to group - “user not found”:

# Verify user exists
ipa user-show username

# Check if user is disabled
ipa user-show username | grep Disabled

# Cannot add preserved users to groups
# Must undelete first
ipa user-undel username

# Then add to group
ipa group-add-member groupname --users=username

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

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