Product SiteDocumentation Site

5.2. Managing User Accounts

5.2.1. About User Entries

User accounts in FreeIPA are ultimately stored as user accounts in an LDAP directory. This grants both flexibility and certain restrictions on the structure and information stored in FreeIPA user entries.

5.2.1.1. About User Schema

When a user entry is created, it is automatically assigned certain LDAP object classes which, in turn, make available certain attributes. LDAP attributes are the way that information is stored in the directory. (This is discussed in detail in the Directory Server Deployment Guide and the Directory Server Schema Reference.)
Table 5.1. Default FreeIPA User Object Classes
Description Object Classes
FreeIPA object classes ipaobject
Person object classes
person
organizationalperson
inetorgperson
inetuser
posixaccount
Kerberos object classes
krbprincipalaux
krbticketpolicyaux
Managed entries (template) object classes mepOriginEntry

A number of attributes are available to user entries. Some are set manually and some are set based on defaults if a specific value is not set. There is also an option to add any attributes available in the object classes in Table 5.1, “Default FreeIPA User Object Classes”, even if there is not a UI or command-line argument for that attribute. Additionally, the values generated or used by the default attributes can be configured, as in Section 5.7, “Specifying Default User and Group Settings”.
Table 5.2. Default FreeIPA User Attributes
UI Field Command-Line Option Required, Optional, or Default[a]
User login username Required
First name --first Required
Last name --last Required
Full name --cn Optional
Display name --displayname Optional
Initials --initials Default
Home directory --homedir Default
GECOS field --gecos Default
Shell --shell Default
Kerberos principal --principal Default
Email address --email Optional
Password --password
Unlike the other options, this accepts no value. The script prompts for the new password.
Optional
User ID number

IMPORTANT

When a user is created without specifying a UID number, then the user account is automatically assigned an ID number that is next available in the server or replica range. (Number ranges are described more in Section 5.4, “Managing Unique UID and GID Number Assignments”.) This means that a user always has a unique number for its UID number and, if configured, for its private group.
If a number is manually assigned to a user entry, the server does not validate that the uidNumber is unique. It will allow duplicate IDs; this is expected (though discouraged) behavior for POSIX entries.
If two entries are assigned the same ID number, only the first entry is returned in a search for that ID number. However, both entries will be returned in searches for other attributes or with ipa user-find --all.
--uid Default
Group ID number

IMPORTANT

When a user is created without specifying a GID number, then the user account is automatically assigned an ID number that is next available in the server or replica range. (Number ranges are described more in Section 5.4, “Managing Unique UID and GID Number Assignments”.) This means that a user always has a unique number for its UID number and, if configured, for its private group.
If a number is manually assigned to a user entry, the server does not validate that the uidNumber is unique. It will allow duplicate IDs; this is expected (though discouraged) behavior for POSIX entries.
If two entries are assigned the same ID number, only the first entry is returned in a search for that ID number. However, both entries will be returned in searches for other attributes or with ipa user-find --all.
--gidnumber Default
Street address --street Optional
City --city Optional
State/Province --state Optional
Zip code --postalcode Optional
Telephone number --phone Optional
Mobile telephone number --mobile Optional
Pager number --pager Optional
Fax number --fax Optional
Organizational unit --orgunit Optional
Job title --title Optional
Manager --manager Optional
Car license --carlicense Optional
Additional attributes --addattr Optional
[a] Required attributes must be set for every entry. Optional attributes may be set, while default attributes are automatically added with a pre-defined value unless a specific value is given.

5.2.1.2. About Username Formats

FreeIPA supports a wide range of username formats, based on this regular expression:
[a-zA-Z0-9_.][a-zA-Z0-9_.-]{0,252}[a-zA-Z0-9_.$-]?

TIP

The trailing $ symbol is permitted for Samba 3.x machine support.
Any system limits — such as starting a username with a number on Unix systems — apply to the usernames in FreeIPA.

5.2.1.3. About Changing the Default User and Group Schema

It is possible to add or change the object classes and attributes used for user and group entries (Section 5.2.1.1, “About User Schema”).
The FreeIPA configuration provides some validation when object classes are changed:
  • All of the object classes and their specified attributes must be known to the LDAP server.
  • All default attributes that are configured for the entry must be supported by the configured object classes.
There are limits to the FreeIPA schema validation, however. Most important, the FreeIPA server does not check that the defined user or group object classes contain all of the required object classes for FreeIPA entries. For example, all FreeIPA entries require the ipaobject object class. However, when the user or group schema is changed, the server does not check to make sure that this object class is included; if the object class is accidentally deleted, then future entry add operations will fail.
Also, all object class changes are atomic, not incremental. The entire list of default object classes has to be defined every time there is a change. For example, a company may create a custom object class to store employee information like birthdays and employment start dates. The administrator cannot simply add the custom object class to the list; he must set the entire list of current default object classes plus the new object class. The existing default object classes must always be included when the configuration is updated. Otherwise, the current settings will be overwritten, which causes serious performance problems.

5.2.1.4. Applying Custom Object Classes to New User Entries

User and group accounts are created with a pre-defined set of LDAP object classes applied to the entry. Any attributes which belong to the object class can be added to the user entry.
While the standard and FreeIPA-specific LDAP object classes will cover most deployment scenarios, administrators may have custom object classes with custom attributes which should be applied to user entries.
5.2.1.4.1. From the Web UI
  1. Add all of the custom schema elements to the 389 Directory Server instance used by FreeIPA. Adding schema elements is described in the schema chapter of the Directory Server Administrator's Guide.
  2. Open the IPA Server tab.
  3. Select the Configuration subtab.
  4. Scroll to the User Options area.
  5. At the bottom of the users area, click the Add link to add a new field for another object class.

    IMPORTANT

    Always include the existing default object classes when the configuration is updated. Otherwise, the current settings will be overwritten. If any object classes required by FreeIPA are not included, then subsequent attempts to add an entry will fail with object class violations.
  6. When the changes are complete, click the Update link at the top of the Configuration page.
5.2.1.4.2. From the Command Line
  1. Add all of the custom schema elements to the 389 Directory Server instance used by FreeIPA. Adding schema elements is described in the schema chapter of the Directory Server Administrator's Guide.
  2. Add the new object class to the list of object classes added to entries. The option for user object classes is --userobjectclasses.

    IMPORTANT

    Always include the existing default object classes when the configuration is updated. Otherwise, the current settings will be overwritten. If any object classes required by FreeIPA are not included, then subsequent attempts to add an entry will fail with object class violations.
    For example:
    $ ipa config-mod --userobjectclasses=top,person,organizationalperson,inetorgperson,inetuser,posixaccount, krbprincipalaux,krbticketpolicyaux,ipaobject,employeeinfo

5.2.1.5. Applying Custom Object Classes to New Group Entries

As with user entries, administrators may have custom object classes with custom attributes which should be applied to group entries. These can be added automatically by adding the object classes to the FreeIPA server configuration.
5.2.1.5.1. From the Web UI
  1. Add all of the custom schema elements to the 389 Directory Server instance used by FreeIPA. Adding schema elements is described in the schema chapter of the Directory Server Administrator's Guide.
  2. Open the IPA Server tab.
  3. Select the Configuration subtab.
  4. Scroll to the Group Options area.
  5. Click the Add link to add a new field for another object class.

    IMPORTANT

    Always include the existing default object classes when the configuration is updated. Otherwise, the current settings will be overwritten. If any object classes required by FreeIPA are not included, then subsequent attempts to add an entry will fail with object class violations.
  6. When the changes are complete, click the Update link at the top of the Configuration page.
5.2.1.5.2. From the Command Line
  1. Add all of the custom schema elements to the 389 Directory Server instance used by FreeIPA. Adding schema elements is described in the schema chapter of the Directory Server Administrator's Guide.
  2. Add the new object class to the list of object classes added to entries. The option for group object classes is --groupobjectclasses.

    IMPORTANT

    Always include the existing default object classes when the configuration is updated. Otherwise, the current settings will be overwritten. If any object classes required by FreeIPA are not included, then subsequent attempts to add an entry will fail with object class violations.
    For example:
    $ ipa config-mod --groupobjectclasses=top,groupofnames,nestedgroup,ipausergroup,ipaobject,employeegroup

5.2.2. Adding Users

5.2.2.1. From the Web UI

  1. Open the Identity tab, and select the Users subtab.
  2. Click the Add link at the top of the users list.
  3. Fill in the user's first and last names. The user login (UID) is automatically generated based on the user's full name, but this can be set manually by clicking the Optional field link.
  4. Click the Add and Edit button to go directly to the expanded entry page and fill in more attribute information, as in Section 5.2.3.1, “From the Web UI”. The user entry is created with some basic information already filled in, based on the given user information and the user entry template.

5.2.2.2. From the Command Line

New user entries are added with the user-add command. Attributes (listed in Table 5.2, “Default FreeIPA User Attributes”) can be added to the entry with specific values or the command can be run with no arguments.
$ ipa user-add [username] [attributes]
When no arguments are used, the command prompts for the required user account information and uses the defaults for the other attributes, with the defaults printed below. For example:
$ ipa user-add
First name: John
Last name: Smith
User login [jsmith]: jsmith
--------------------
Added user "jsmith"
--------------------
User login: jsmith
First name: John
Last name: Smith
Home directory: /home/jsmith
GECOS field: jsmith
Login shell: /bin/sh
Kerberos principal: jsmith@EXAMPLE.COM
UID: 387115841
Any of the user attributes can be passed with the command. This will either set values for optional attributes or override the default values for default attributes.
$ ipa user-add jsmith --first=John --last=Smith --manager=bjensen --email=johnls@example.com --homedir=/home/work/johns --password

IMPORTANT

When a user is created without specifying a UID or GID number, then the user account is automatically assigned an ID number that is next available in the server or replica range. (Number ranges are described more in Section 5.4, “Managing Unique UID and GID Number Assignments”.) This means that a user always has a unique number for its UID number and, if configured, for its private group.
If a number is manually assigned to a user entry, the server does not validate that the uidNumber is unique. It will allow duplicate IDs; this is expected (though discouraged) behavior for POSIX entries.
If two entries are assigned the same ID number, only the first entry is returned in a search for that ID number. However, both entries will be returned in searches for other attributes or with ipa user-find --all.

5.2.3. Editing Users

5.2.3.1. From the Web UI

  1. Open the Identity tab, and select the Users subtab.
  2. Click the name of the user to edit.
  3. There are a number of different types of attributes that can be edited for the user. All of the default attributes are listed in Table 5.2, “Default FreeIPA User Attributes”. Most of the attributes in the Identity Settings and Account Settings areas have default values filled in for them, based on the user information or on the user entry template.
  4. Edit the fields or, if necessary, click the Add link by an attribute to create the attribute on the entry.
  5. When the edits are done, click the Update link at the top of the page.

5.2.3.2. From the Command Line

The user-mod command edits user accounts by adding or changing attributes. At its most basic, the user-mod specifies the user account by login ID, the attribute to edit, and the new value:
$ ipa user-mod loginID --attributeName=newValue
For example, to change a user's work title from Editor II to Editor III:
$ ipa user-mod jsmith --title="Editor III"
FreeIPA allows multi-valued attributes, based on attributes in LDAP that are allowed to have multiple values. For example, a person may have two email addresses, one for work and one for personal, that are both stored in the mail attribute. Managing multi-valued attributes can be done using the --addattr option.
If an attributes allows multiple values — like mail — simply using the command-line argument will overwrite the value with the new value. This is also true for using --setaddr. However, using --addattr will add a new attribute; for a multi-valued attribute, it adds the new value in addition to any existing values.
Example 5.1. Multiple Mail Attributes
A user is created first using his work email account.
$ ipa user-add jsmith --first=John --last=Smith --email=johnls@example.com
Then, his personal email account is added.
$ ipa user-mod jsmith --addattr=mail=johnnys@me.com
Both email addresses are listed for the user.
$ ipa user-find jsmith --all
--------------
1 user matched
--------------
  dn: uid=jsmith,cn=users,cn=accounts,dc=example,dc=com
  User login: jsmith
  .....
  Email address: jsmith@example.com, jsmith@new.com
To set two values at the same time, use the --addattr option twice:
$ ipa user-add jsmith --first=John --last=Smith --email=johnls@example.com --addattr=mail=johnnys@me.com --addattr=mail=admin@example.com

5.2.4. Activating and Deactivating User Accounts

User accounts can be deactivated. A deactivated user cannot log into FreeIPA or its related services (like Kerberos) and he cannot perform any tasks. However, the user account still exists within FreeIPA and all of the associated information remains unchanged.

NOTE

Any existing connections remain valid until the Kerberos TGT and other tickets expire. Once the ticket expires, the user cannot renew the ticket.

5.2.4.1. From the Web UI

  1. Open the Identity tab, and select the Users subtab.
  2. Click the name of the user for whom to deactivate or activate.
  3. Scroll to the Account Settings area.
  4. Click the Deactivate link.
  5. Click the Update link at the top of the page.

5.2.4.2. From the Command Line

Users are activated and disabled using user-enable and user-disable commands. All that is required is the user login. For example:
$ ipa user-disable jsmith

5.2.5. Deleting Users

Deleting a user account permanently removes the user entry and all its information from FreeIPA, including group memberships and passwords. External configuration — like a system account and home directory — will still exist on any server or local machine where they were created, but they cannot be accessed through FreeIPA.
Deleting a user account is permanent. The information cannot be recovered; a new account must be created.

NOTE

If all admin users are deleted, then you must use the Directory Manager account to create a new administrative user.
Alternatively, any user who belongs in the group management role can also add a new admin user.

5.2.5.1. With the Web UI

  1. Open the Identity tab, and select the Users subtab.
  2. Select the checkboxes by the names of the users to delete.
  3. Click the Delete link at the top of the task area.
  4. When prompted, confirm the delete action.

5.2.5.2. From the Command Line

Users are deleted using the user-del command and then the user login. For example, a single user:
$ ipa user-del jsmith
To delete multiple users, simply list the users, separated by spaces.
$ ipa user-del jsmith bjensen mreynolds cdickens
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 stdout when the command completes. If --continue is not used, then the command proceeds with deleting users until it encounters an error, and then it exits.