Product SiteDocumentation Site

Chapter 4. Basic Usage

4.1. About the FreeIPA Client Tools
4.1.1. About the FreeIPA Command-Line Tools
4.1.2. Looking at the FreeIPA UI
4.2. Logging into FreeIPA
4.2.1. Logging into FreeIPA
4.2.2. Logging in When an FreeIPA User Is Different Than the System User
4.2.3. Checking the Current Logged in User
4.2.4. Caching User Kerberos Tickets
4.3. Using the FreeIPA Web UI
4.3.1. Supported Web Browsers
4.3.2. Opening the FreeIPA Web UI
4.3.3. Configuring the Browser
4.3.4. Using a Browser on Another System
4.3.5. Enabling Username/Password Authentication in Your Browser
4.3.6. Using the UI with Proxy Servers
4.3.7. Troubleshooting UI Connection Problems
All of the access to FreeIPA, both through the web UI and through the command line, is done by a user authenticating to the FreeIPA domain. This chapter covers the basics of setting up browsers to handle Kerberos authentication, logging into FreeIPA, and troubleshooting some common connection issues.

4.1. About the FreeIPA Client Tools

FreeIPA creates a domain of recognized services, host machines, and users with universally-applied authentication sources and common policies. From the perspective of a client machine and a FreeIPA user, the domain itself is fairly transparent after the initial configuration. All users need to do is log into the domain using Kerberos, and that's it.
However, an administrator has two ongoing tasks: add principals to the FreeIPA Kerberos domain and set the domain policies and server configuration that govern domain interactions. FreeIPA has both command-line and web-based interfaces for administrators to use to manage the domain, services, and FreeIPA entries.

4.1.1. About the FreeIPA Command-Line Tools

The most common method to maintain the domain is using the command-line tools. FreeIPA has an incredibly broad set of scripts and commands that are available to administrators. The command-line scripts offer a number of benefits:
  • The scripts allow management tasks to be automated and performed repeatedly in a consistent way without manual intervention.
  • Entries can be added with all possible attributes configured (or a desired subset of attributes) in a single step. The web UI frequently requires two steps to fully configure an entry: the first to create the entry and the next to add optional attributes.
  • The command-line scripts support adding additional attributes which may not be available in the UI or even custom attributes to entries, if the schema is configured.
The potential disadvantage to the command-line scripts is that they are complex, which makes them difficult to use.

4.1.1.1. ipa and Other Command-Line Scripts

There are two basic categories of command-line scripts that FreeIPA has available.
The first is a selection of independent configuration scripts which are used to set up machines that operate within the domain. Most commonly, these are scripts to add machines to the domain (including ipa-server-install, ipa-client-install, and ipa-replica-install). Some scripts are also available to enable services within the FreeIPA server. The domain server has a large number of different installation options and services — such as DNS, certificate services, and NIS management. All of these can be enabled at the time the server is set up, but none of those services are required. If a server is configured without a service like DNS, that service can be enabled later using a specific installation script, such as ipa-dns-install.
The real management functions of the domain are carried out with a single script: ipa. The ipa command is essentially a big plug-in container, and it supports dozens of plug-ins which it executes as subcommands. For example, adding a user is done using the user-add plug-in, which is run like a user-add subcommand:
ipa user-add options
Related subcommands are grouped together into plug-in modules. Commands for managing DNS entries like dnszone-add and dnsrecord-add all belong to the dns module or topic. All of the information for managing a specific area, with all of the supported commands and examples for each, are available by viewing the help for that topic:
ipa help topic
To get a list of all available help topics, run the help command without a topic name:
ipa help

4.1.1.2. Adding Attributes with --setattr and --addattr

For the most common attributes, the ipa use specified command-line arguments to set values. For example, adding a mail attribute to a user can be done with the --mail argument; enabling dynamic updates for a DNS zone can be done with the --allow-dynupdate option with zone commands; and a map key for an automount map is given in the --key option.
However, entries can also allow attributes that may not have command-line (or UI) options for setting them. Partially, this is because the underlying LDAP schema is very rich, particularly for user entries. Additionally, FreeIPA allows limited schema extensions for users and groups, and those custom schema elements are not reflected in the UI or command-line tools.
Most ipa allow the --setattr and --addattr options to define attributes and values explicitly.
Both options have this format:
--setattr=attribute=value
The --setattr option sets one value for the given attribute; any existing values are overwritten, even for multi-valued attributes.
The --addattr option adds a new value for an attribute; for a multi-valued attribute, it adds the new value while preserving any existing values.
Both --setattr option and --addattr can be used multiple times in the same command invocation. For example:
$ ipa user-mod jsmith --addattr=mail=johnnys@me.com --addattr=mail=jsmith@example.com --setattr=description="backup IT manager for the east coast branch"

4.1.1.3. Tips for Running FreeIPA Tools

The FreeIPA command-line tools are run as any other utilities in a shell. If there are special characters in the command — such as angle brackets (> and <), ampersands (&), asterisks (*), and pipes (|) — the characters must be escaped. Otherwise, the command fails because the shell cannot properly parse the unescaped characters.

4.1.2. Looking at the FreeIPA UI

The FreeIPA web UI is designed for simplicity. This was the primary design goal, and this means that the web UI offers benefits that make using FreeIPA simpler and clearer:
  • It shows instant, visual relationships between entries (such as a user and all the groups, sudo rules, netgroups, and policies which are associated with that user).
  • All entries are listed immediately without having to run a search. This makes it possible to browse entries. The UI also has a simple search box which quickly filters the list of entries.
  • The interface is intuitive to use, without having to learn the command-line tools.
  • The web UI can be accessed from machines outside the FreeIPA domain, so the domain can be managed from anywhere.
    Using the web UI requires a valid Kerberos ticket for the FreeIPA domain (by default), meaning that it can only be accessed from a machine within the FreeIPA domain. Alternatively, the web UI can be configured to allow password authentication along with Kerberos authentication (Section 4.3.5, “Enabling Username/Password Authentication in Your Browser”), or a machine outside the FreeIPA can be configured to work with Kerberos (Section 4.3.4, “Using a Browser on Another System”).

4.1.2.1. The UI Layout

The web UI has three major functional areas which correspond to each of the major functions of FreeIPA: identity management, policy management, and domain configuration.
Table 4.1. Configuration Areas Per Tab
Main Menu Tab Configuration Areas
Identity
  • User entries
  • User groups entries
  • Host/client entries
  • Host group entries
  • Netgroups entries
  • Domain services entries
  • DNS (if configured)
Policy
  • Host-based access control
  • Sudo rules
  • Automount
  • User password policies
  • Kerberos ticket policy
Access controls within FreeIPA
  • Role-based access control (permissions based on group membership)
  • Self permissions
  • Delegations (user access control over other users)

The main menu at the top of every page has three tabs which correspond to the functional areas listed in Table 4.1, “Configuration Areas Per Tab”. When a tab is selected, there is a submenu of the different configuration areas. Some configuration areas may have multiple possible entries; for example, role-based access controls define user roles/groups, the areas that access can be granted or denied (privileges), and then the permissions granted to those areas. Each separate configuration entry has its own task area beneath the primary configuration area.
The Main Menu
Figure 4.1. The Main Menu

All entries for a configuration area are listed together on the main page for that area. This page provides direct links to individual entry pages, as well as basic information (the attributes) about the entry. (This is usually just the description, but user entries show a lot more information.)
The page also has some tasks that can be performed on it. For a list page that shows entries, this can be creating or deleting an entry. For a list page for groups, the tasks are for establishing relationships between entities, either by adding (enrolling) or removing an entity from that group. Both individual entries and groups can be searched for through the list page.
List View
Figure 4.2. List View

Each entry page is a form which allows that entry to be edited. This is done by editing text fields or by selecting items from drop-down menus.
Form/Entry View
Figure 4.3. Form/Entry View

4.1.2.2. Page Elements

The web UI uses common elements on all pages.
The most basic is that all blue text is a link to an entry or to an action.
When a task like adding an entry or saving a change is possible, the task link it blue. When it is not possible (such as no items have been selected to be deleted) then the task is grayed out.

All list pages display direct links to entry pages. However, some entries are essentially nested. For example, in automount configuration, the primary entry is the location, and then keys, mount points, and maps are associated with that location as children entries. This hierarchy is reflected in breadcrumb navigation near the top of the page, so it is easy to identify where you are in the UI and how this entry relates to any other related entries.
Entry Breadcrumbs
Figure 4.5. Entry Breadcrumbs

Most entries have a variety of different configuration areas. A simple user entry has account activity settings, personal information, address information, organizational information, and other contact information. Related attributes are grouped together logically in the UI. These entry form areas can be collapsed or expanded using the arrows to control the amount of information displayed on the page.
Collapsing and Expanding Form Elements
Figure 4.6. Collapsing and Expanding Form Elements

When entries are created, they are added with only the required attributes. Additional attributes can be added manually. Some attributes have default values added to the entry and simply need to be edited; other attributes may not exist at all in the new entry and need to be added.
Add an Attribute
Figure 4.7. Add an Attribute

Any changes to any attribute can be undone. A single attribute change can be undone by clicking the dynamic undo button; all changes can be undone by clicking the Reset link at the top of the entry details page.
Undo Edits
Figure 4.8. Undo Edits

4.1.2.3. Showing and Changing Group Members

Members can be added to a group through the group configuration. There are tabs for all the member types which can belong to the group, and an administrator picks all of the marching entries and adds them as members.
However, it is also possible for an entity to be added to a group through its own configuration. Each entry has a list of tabs that displays group types that the entry can join. The list of all groups of that type are displayed, and the entity can be added to multiple groups at the same time.
Member Of...
Figure 4.9. Member Of...

4.1.2.4. Looking at Search Results

Searches can be performed on attributes that are not displayed in the UI. This means that entries can be returned in a search that do not appear to match the given filter. This is especially common if the search information is very short, which increases the likelihood of a match.
For more information on setting and changing attributes which are searched, see Section 5.7.3, “Setting User Search Attributes” and Section 5.7.4, “Setting Group Search Attributes”.