Red Hat Summit Red Hat SummitSupportConsoleDevelopersStart a trialContact

Chapter 1. Managing user accounts using the command line

Manage the complete user lifecycle in Identity Management (IdM) using command-line tools. Create, activate, preserve, delete, and restore user accounts to handle employee onboarding, departures, and returns.

1.1. User life cycle
Copy link

Identity Management (IdM) user accounts progress through three states: Stage, Active, and Preserved. Understanding this lifecycle helps you provision new accounts, manage departures, and restore users when needed.

  • Stage users are not allowed to authenticate. This is an initial state. Some of the user account properties required for active users cannot be set, for example, group membership.
  • Active users are allowed to authenticate. All required user account properties must be set in this state.
  • Preserved users are former active users that are considered inactive and cannot authenticate to IdM. Preserved users retain most of the account properties they had as active users, but they are not part of any user groups.

A flow chart displaying 4 items: Active users - Stage users - Preserved users - Deleted users. Arrows communicate the relationships between each kind of user: Active users can be "preserved" as Preserved users. Preserved users can be "restored" as Active users. Preserved users can be "staged" as Stage users and Stage users can be "activated" into Active users. All users can be deleted to become "Deleted users".

You can delete user entries permanently from the IdM database.

Important

Deleted user accounts cannot be restored. When you delete a user account, all the information associated with the account is permanently lost.

A new administrator can only be created by a user with administrator rights, such as the default admin user. If you accidentally delete all administrator accounts, the Directory Manager must create a new administrator manually in the Directory Server.

Warning

Do not delete the admin user. As admin is a pre-defined user required by IdM, this operation causes problems with certain commands. If you want to define and use an alternative admin user, disable the pre-defined admin user with ipa user-disable admin after you granted admin permissions to at least one different user.

Warning

Do not add local users to IdM. The Name Service Switch (NSS) always resolves IdM users and groups before resolving local users and groups. This means that, for example, IdM group membership does not work for local users.

1.2. Adding users using the command line
Copy link

Add user accounts to Identity Management (IdM) from the command line to provision access for new employees or prepare stage accounts in advance. You can create active users who can authenticate immediately or stage users who require activation before use.

The following procedure describes adding active users to the IdM server with the ipa user-add command.

Similarly, you can create stage user accounts with the ipa stageuser-add command.

Warning

IdM automatically assigns a unique user ID (UID) to new user accounts. You can assign a UID manually by using the --uid=INT option with the ipa user-add command, but the server does not validate whether the UID number is unique. Consequently, multiple user entries might have the same UID number. A similar problem can occur with user private group IDs (GIDs) if you assign a GID to a user account manually by using the --gidnumber=INT option. To check if you have multiple user entries with the same ID, enter ipa user-find --uid=<uid> or ipa user-find --gidnumber=<gidnumber>.

Red Hat recommends you do not have multiple entries with the same UIDs or GIDs. If you have objects with duplicate IDs, security identifiers (SIDs) are not generated correctly. SIDs are crucial for trusts between IdM and Active Directory and for Kerberos authentication to work correctly.

Prerequisites

Procedure

  1. Open terminal and connect to the IdM server.

  2. Add user login, user’s first name, last name and optionally, you can also add their email address. 

    $ ipa user-add user_login --first=first_name --last=last_name --email=email_address

    IdM supports user names that can be described by the following regular expression: 

    [a-zA-Z0-9_.][a-zA-Z0-9_.-]{0,252}[a-zA-Z0-9_.$-]?
    Note

    User names ending with the trailing dollar sign ($) are supported to enable Samba 3.x machine support.

    If you add a user name containing uppercase characters, IdM automatically converts the name to lowercase when saving it. Therefore, IdM always requires to enter user names in lowercase when logging in. Additionally, it is not possible to add user names which differ only in letter casing, such as user and User.

    The default maximum length for user names is 32 characters. To change it, use the ipa config-mod --maxusername command. For example, to increase the maximum user name length to 64 characters: 

    $ ipa config-mod --maxusername=64
 Maximum username length: 64
 ...

    The ipa user-add command includes a lot of parameters. To list them all, use the ipa help command: 

    $ ipa help user-add

    For details about ipa help command, see What is the IPA help.

Verification

  1. List all IdM user accounts: 

    $ ipa user-find

1.3. Activating users using the command line
Copy link

Activate a stage user account to enable authentication. Use the ipa stageuser-activate command to move prepared accounts from stage to active status when the user is ready to begin work.

Prerequisites

Procedure

  1. Open terminal and connect to the IdM server.

  2. Activate the user account with the following command: 

    $ ipa stageuser-activate user_login
-------------------------
Stage user user_login activated
-------------------------
...

Verification

  • List all IdM user accounts: 

    $ ipa user-find

1.4. Preserving users using the command line
Copy link

Preserve a user account using the Identity Management (IdM) CLI to remove the account from active use while retaining the option to restore it later.

Prerequisites

Procedure

  1. Open terminal and connect to the IdM server.

  2. Preserve the user account with the following command: 

    $ ipa user-del --preserve user_login
--------------------
Deleted user "user_login"
--------------------
    Note

    Despite the output saying the user account was deleted, it has been preserved.

1.5. Deleting users using the command line
Copy link

Permanently delete user accounts from Identity Management (IdM) when the account data is no longer needed. You can delete active, stage, or preserved users using the appropriate ipa command.

Use the following commands to delete users based on their account state:

  • ipa user-del - Delete active or preserved users
  • ipa stageuser-del - Delete stage users

When deleting multiple users, use the --continue option to force the command to continue regardless of errors. A summary of the successful and failed operations is printed to the stdout standard output stream when the command completes. 

$ *ipa user-del --continue user1 user2 user3*

If you do not use --continue, the command proceeds with deleting users until it encounters an error, after which it stops and exits.

Prerequisites

Procedure

  1. Open terminal and connect to the IdM server.

  2. Delete the user account with the following command: 

    $ ipa user-del user_login
--------------------
Deleted user "user_login"
--------------------

    The user account has been permanently deleted from IdM.

1.6. Restoring users using the command line
Copy link

Restore a preserved user account to active or stage status to, for example, re-enable access for returning employees. You can restore preserved users to active or stage status.

Restoring a user account does not restore all of the account’s previous attributes. For example, the user’s password is not restored and must be set again.

Prerequisites

Procedure

  1. Open terminal and connect to the IdM server.

  2. Activate the user account with the following command: 

    $ ipa user-undel user_login
------------------------------
Undeleted user account "user_login"
------------------------------

    Alternatively, you can restore user accounts as staged: 

    $ ipa user-stage user_login
------------------------------
Staged user account "user_login"
------------------------------

Verification

  • You can verify if the new user account is successfully created by listing all IdM user accounts: 

    $ ipa user-find

    This command lists all user accounts with details.

Red Hat logoGithubredditYoutubeTwitter

Learn

Try, buy, & sell

Communities

About Red Hat Documentation

We help Red Hat users innovate and achieve their goals with our products and services with content they can trust. Explore our recent updates.

Making open source more inclusive

Red Hat is committed to replacing problematic language in our code, documentation, and web properties. For more details, see the Red Hat Blog.

About Red Hat

We deliver hardened solutions that make it easier for enterprises to work across platforms and environments, from the core datacenter to the network edge.

Theme

© 2026 Red HatBack to top