| Identity Management GuideAll of the access to Identity Management, both through the web UI and through the command line, is done by a user authenticating to the IdM domain. This chapter covers the basics of setting up browsers to handle Kerberos authentication, logging into Identity Management, and troubleshooting some common connection issues. 4.1. About the IdM Client ToolsIdM 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 an IdM 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 IdM Kerberos domain and set the domain policies and server configuration that govern domain interactions. Identity Management has both command-line and web-based interfaces for administrators to use to manage the domain, services, and IdM entries. 4.1.1. About the IdM Command-Line ToolsThe most common method to maintain the domain is using the command-line tools. Identity Management has an incredibly broad set of scripts and commands that are available to administrators. The entry management functions of the domain are carried out with a single script: ipa. This script is a parent or control script for associated subcommands; each subcommand relates to a specific entry type. 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.
4.1.1.1. The Structure of the ipa CommandThe ipa command is essentially a big plug-in container. It supports dozens of subcommands; these subcommands are actually plug-ins which manage specific types of objects in Identity Management. The first type of a subcommand identifies the object type (such as user, sudo, group, host, or dns), and the second part identifies the operation being performed on that object. ipa objectType-operation objectName --option=value For example, adding a user is done using the user-add subcommand: ipa user-add entryName 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 topics, run the help command without a topic name: ipa help All topic or command areas follow a consistent pattern for how entries are managed. 4.1.1.1.1. Adding, Editing, and Deleting Entries with ipaNew entries are added using an *-add command. For example: $ ipa user-add jsmith $ ipa user-addFirst name: JohnLast name: SmithUser login [jsmith]: jsmith--------------------Added user "jsmith"--------------------... Likewise, entries are usually edited through a *-mod commands, and then any new or edited attributes are listed as options after it. $ ipa user-mod jsmith --title="Editor III" Last, entries can be deleted using the *-del command and the entry's name. $ ipa user-del jsmith 4.1.1.1.2. Finding and Displaying Entries with ipaEntries for an entire type are searched for using the *-find command and an optional search criterion. The criterion is a string which can either be an exact match or use an asterisk (*) as a wildcard. ipa user-find *smith With no search criterion, every entry of that type is displayed. Searches (any *-find command) have certain limits imposed as part of the server configuration, specifically how many entries are returned (size limits) and how long a search will run (time limits). This is covered in Section 4.4.2, "Setting IdM Search Limits". Part of the server configuration is setting global defaults for size and time limits on searches. While these limits are always enforced in the web UI, they can be overridden with any *-find command with the --sizelimit and --timelimit options. For example, if the default time limit is 60 seconds and a search is going to take longer, the time limit can be increased to 120 seconds: [jsmith@ipaserver ~]$ ipa user-find *sen --timelimit=120 Not every possible attribute in an entry type can be searched for. A certain subset of attributes are predefined and indexed for searches. (This list is configurable for users and groups, but not for other types of entries.) When entries are returned, only certain default attributes are displayed with the entry; to return all attributes currently set for entries, use the --all option. To display a specific entry, use the *-show command and the entry name. As with searches, only a subset of attributes are displayed with the entry unless the --all option is used. 4.1.1.1.3. Adding Members to Groups and Containers with ipaGroup members are added and removed with separate commands, apart from simply modifying an entry. Member commands essentially create a relationship between different IdM entries. While this is obvious in traditional group-member roles, it is also true for some policy entries (like SELinux and sudo policies) where entries are associated with another entry. Most commonly, the command format for adding a member entry is *-add-member, although the command may specify an entry type, such as *-add-user. Likewise, entries are removed as members (not deleted) using a *-remove-member or *-remove-type command. 4.1.1.2. Positional Elements in ipa CommandsUsually, ipa subcommands have only two elements: the name of the entry being modified (the object) and then any options available for the subcommand: ipa command entryName --options=values With a few types of entries, however, not only the entry name itself needs to be specified; the entry's parent must also be specified. This is the case with automount commands, for example. With automount, the location must be included whenever a new key or map is created. The parent entry name is given first, and then the child entry name. For example, for automount, the location is given first, and then the map or key entry name. ipa command parentEntryName chidlEntryName --childOptions=childValues 4.1.1.3. Managing Entry Attributes with --setattr, --addattr, and --delattrAll identities and configuration in Identity Management are stored as LDAP entries, with standard attribute-value assertions (AVAs). Whether an entry is created through the UI or the CLI, there are certain attributes which are required and others which are available, depending on the default and custom object classes for that entry type. 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, with many possible allowed attributes. Additionally, Identity Management allows schema extensions for users and groups, and those custom schema elements are not necessarily reflected in the UI or command-line tools. Any supported attribute can be added or edited to an entry using the --setattr and --addattr options. 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 [email protected] [email protected] --setattr=description="backup IT manager for the east coast branch" Likewise, an attribute or specific attribute value can be removed from an entry using the --delattr option. For a single-valued attribute, this removes the attribute; for a multi-valued attribute, it removes only the specified value. For example: $ ipa user-mod jsmith [email protected] Deleting attributes is evaluated last, after adding or editing attributes. If the same attribute is added and deleted in the same modify operation, it is a no-op. $ ipa user-mod jsmith [email protected] [email protected] 4.1.1.4. Using Special Characters with IdM ToolsThe IdM 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.1.5. Logging into the IdM Domain Before RunningBefore running any IdM commands (with the exception of the installation scripts, such as ipa-server-install), the user must first authenticate to the IdM domain by obtaining a Kerberos ticket. This is done using kinit: [jsmith@ipaserver ~]$ kinit admin 4.1.2. Looking at the IdM UIThe Identity Management web UI is designed for simplicity. This was the primary design goal, and this means that the web UI offers benefits that make using IdM 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 IdM domain, so the domain can be managed from anywhere. Using the web UI requires a valid Kerberos ticket for the IdM domain (by default), meaning that it can only be accessed from a machine within the IdM domain. Alternatively, the web UI can be configured to allow password authentication along with Kerberos authentication, or a machine outside the IdM can be configured to work with Kerberos ( Section 4.3.4, "Using a Browser on Another System").
The web UI has three major functional areas which correspond to each of the major functions of IdM: 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 | | | IdM Server (access controls within Identity Management) | |
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. 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. 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. 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 is 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. 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. 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. 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. 4.1.2.3. Showing and Changing Group MembersMembers 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. Users are authenticated to IdM services, including the command-line tools and the web UI, using Kerberos authentication. This means that logging into Identity Management requires running kinit. Running kinit issues the user a Kerberos ticket. This ticket is checked by any IdM or Kerberos-aware service, so that a user only needs to log in once to access all domain services. Domain services include the IdM web UI, mounted file shares, wikis, or any other application which uses IdM as its identity/authentication store. Logging into Identity Management requires running kinit on a client within the IdM domain. $ kinit The kinit command must be run from a machine which has been configured as a client within the IdM domain, so that the client retrieves authenticates with the IdM KDC. Simply running kinit logs into IdM as the currently logged-in user account. This user account must also be an IdM user for them to authenticate to the IdM Kerberos domain successfully. For example, if you are logged into the machine as jsmith: $ kinitPassword for [email protected]: If SSSD or pam_krb5 is configured on the IdM client machine, then when a user logs into the machine, a ticket is created which can be used for machine services which require authentication, such as sudo. 4.2.2. Logging in When an IdM User Is Different Than the System UserTo specify an IdM username - because a person's system username is different then the IdM username or to switch IdM user accounts - simply rerun the kinit command, specifying the new user. For example: $ kinit userName Password for userName@EXAMPLE.COM: When the server was first set up, an administrative user, admin, is created to perform normal administrative activities. To authenticate as the admin user, use the name admin when running kinit: $ kinit admin Only one set of tickets can be stored per logged-in user. The current stored credentials are the ones that will be used when accessing IdM services. If you were already connected to the IdM web UI as another user, refresh the browser to display the updated details for the new user. 4.2.3. Checking the Current Logged in UserUse the klist command to verify the identity and the ticket granting ticket (TGT) from the server: $ klistTicket cache: FILE:/tmp/krb5cc_500Default principal: [email protected] starting Expires Service principal11/10/08 15:35:45 11/11/08 15:35:45 krbtgt/[email protected] 4 ticket cache: /tmp/tkt500klist: You have no tickets cached It's important to know who the authenticated user is because the currently-authenticated user is the only one who can access the IdM services. The Kerberos client libraries for kinit have some limitation, one of them being that the current ticket is overwritten with any new invocation of kinit. Authenticating as User A and then authenticating as User B overwrites User A's ticket. To allow there to be multiple authenticated users on a machine, set the KRB5CCNAME environment variable. This variable keeps credential caches separate in different shells. 4.2.4. Caching User Kerberos TicketsOnly one set of tickets can be stored per logged-in user. The current stored credentials are the ones that will be used when accessing IdM services. For example, if you authenticated as admin, added a new user, set the password, and then tried to authenticate as that user, the administrator's ticket is lost. To keep separate credential caches in different shells, a special environment variable, KRB5CCNAME, can be used. 4.3. Using the IdM Web UIIn order to use the web UI, the user must be authenticated with the IdM Kerberos domain and have an active Kerberos ticket ( Section 4.2, "Logging into IdM"). Generally, the web UI can only be accessed from an IdM server or client machine and the user must be locally authenticated. There are a couple of ways to work around this, either by configuring Kerberos on a non-domain machine to connect to the Kerberos domain ( Section 4.3.4, "Using a Browser on Another System") or by password authentication to the UI. 4.3.1. Supported Web BrowsersThese browsers are supported for connecting to the web UI: 4.3.2. Opening the IdM Web UITo open the web UI: Open the IdM URL. The full URL is https://IPAserver-FQDN/ipa/ui, but this service is also accessed simply by opening https://IPAserver-FQDN. For example: https://server.example.comhttps://server.example.com/ipa/ui 4.3.3. Configuring the BrowserFirefox can use Kerberos credentials to authenticate to the IdM UI, but Kerberos negotiation needs to be configured to use the IdM domain. At the first log-in attempt, if Firefox has not been configured to support Kerberos authentication, then an error message appears. If you see that error, then the IdM web UI can perform the required configuration: Click the follow these directions link. Click the link to import the CA certificate for the IdM server. Set the web site and software developer (first and last) trust bits for the CA certificate. Click the Configure Firefox button. This automatically fills out all the negotiate settings in the Firefox configuration to use the IdM domain settings. When the process is complete, a success box pops up saying that Firefox has been configured for single sign-on. For there, you are redirected to the IdM web UI.
This can also be done manually: Open Firefox. Type about:config in the address bar. In the Search field, type negotiate to filter out the Kerberos-related parameters. On Red Hat Enterprise Linux, enter the domain name for the URI parameters, including the preceding period (.) and set the gsslib parameter to true: network.negotiate-auth.trusted-uris .example.comnetwork.negotiate-auth.using-native-gsslib true On Windows, set the trusted URIs and library path, and disable the built-in Microsoft Kerberos for authentication: network.negotiate-auth.trusted-uris .example.comnetwork.auth.use-sspi false network.negotiate-auth.gsslib: C:\Program Files\MIT\Kerberos\bin\gssapi32.dll On a 64-bit system, the library location is in C:\Program Files(x86)\MIT\Kerberos\bin\gssapi32.dll. Open the web UI by going to the fully-qualified domain name of the IdM server such as http://ipaserver.example.com. Make sure that you can open the web UI and that there are no Kerberos authentication errors. Next, download the IdM server's CA certificate from http://ipa.example.com/ipa/config/ca.crt. Select the first (Trust this CA to identify web sites) and third (Trust this CA to identify software developers) check boxes.
4.3.4. Using a Browser on Another SystemIt is possible to connect to the Identity Management web UI from a system which is not a member of the IdM domain. In this case, it is possible to specify an IdM-specific Kerberos configuration file on the external (non-IdM) machine before running kinit, and then the user can authenticate against the IdM server domain. This is especially useful there are multiple realms or overlapping domains across your infrastructure. Copy the /etc/krb5.conf file from the IdM server. Do not overwrite the existing krb5.conf file. On the external machine, set the terminal session to use the copied IdM Kerberos configuration file: $ export KRB5_CONFIG=/etc/krb5_ipa.conf
4.3.5. Logging in with Simple Username/Password CredentialsIf Kerberos authentication fails, then browser login also fails. That prevents access to the IdM web UI. Simple authentication for the UI allows users to log in even if there are problems with the Kerberos service or if the system is outside the IdM domain. When the IdM server cannot find a valid Kerberos ticket for the user attempting to log into the web UI, it splashes an error message. Since the preferred method of connecting to IdM domain services (including the UI) is using Kerberos authentication, the error first says to renew the Kerberos credentials or to configure the browser to support Kerberos authentication. The second part of the message offers the alternative of using simple authentication. The form-based authentication link opens a login page. Then simply supply the UID and password for a configured IdM user. 4.3.6. Using the UI with Proxy ServersProxy servers can be used to access the web UI without any additional configuration in IdM. Port forwarding is not supported with the IdM server. However, because it is possible to use proxy servers with IdM, an operation similar to port forwarding can be configured using proxy forwarding with OpenSSH and the SOCKS option. This is described in http://www.meadowy.org/~gotoh/ssh/openssh-socks.html. 4.3.7. Troubleshooting UI Connection ProblemsIf negotiate authentication is not working, turn on verbose logging for the authentication process to help diagnose the issue: Close all browser windows. In a terminal, set the new log levels for Firefox: export NSPR_LOG_MODULES=negotiateauth:5export NSPR_LOG_FILE=/tmp/moz.log This enables verbose logging and logs all information to /tmp/moz.log. Restart the browser from the same terminal window and attempt t .
Table 4.2. UI Error Log Messages | Error Log Message | Description and Fix |
|---|
-1208550944[90039d0]: entering nsNegotiateAuth::GetNextToken()-1208550944[90039d0]: gss_init_sec_context() failed: Miscellaneous failureNo credentials cache found | There are no Kerberos tickets. Run kinit. | -1208994096[8d683d8]: entering nsAuthGSSAPI::GetNextToken()-1208994096[8d683d8]: gss_init_sec_context() failed: Miscellaneous failureServer not found in Kerberos database | This can occur when you have successfully obtained Kerberos tickets but are still unable to authenticate to the UI. This indicates that there is a problem with the Kerberos configuration. The first place to check is the [domain_realm] section in the /etc/krb5.conf file. Make sure that the IdM Kerberos domain entry is correct and matches the configuration in the Firefox negotiation parameters. For example: .example.com = EXAMPLE.COMexample.com = EXAMPLE.COM | | Nothing is in the log file. | It is possible that you are behind a proxy which is removing the HTTP headers required for negotiate authentication. Try to connect to the server using HTTPS instead, which allows the request to pass through unmodified. Then check the log file again. |
4.4. Understanding Search Limits and SettingsSome searches can result in a large number of entries being returned, possibly even all entries. Search limits improve overall server performance by limiting how long the server spends in a search and how many entries are returned. 4.4.1. Types of Search Limits and Where They ApplySearch limits have a dual purpose to improve server performance by reducing the search load and to improve usability by returning a smaller - and therefore easier to browse - set of entries. The IdM server has several different limits imposed on searches: The search limit configuration for the IdM server. This is a setting for the IdM server itself, which is applied to all requests sent to the server from all IdM clients, the IdM CLI tools, and the IdM web UI for normal page display. By default, this limit is 100 entries. The time limit configuration for the IdM server. Much like the search size limit, the time limit sets a maximum amount of time that the IdM server, itself, waits for searches to run. Once it reaches that limit, the server stops the search and returns whatever entries were returned in that time. By default, this limit is two seconds. The page size limit. Although not strictly a search limit, the page size limit does limit how many entries are returned per page. The server returns the set of entries, up to the search limit, and then randomly selects up to 20 entries per page for display. Paging results makes the results more understandable and more viewable. This is hard-coded to 20 for all searches. The LDAP search limit (--pkey option). All searches performed in the UI, and CLI searches which use the --pkey option, override the search limit set in the IdM server configuration and use the search limit set in the underlying LDAP directory. By default, this limit is 2000 entries. It can be edited by editing the 389 Directory Server configuration.
4.4.2. Setting IdM Search LimitsSearch limits set caps on the number of records returned or the time spent searching when querying the database for user or group entries. There are two types of search limits: time limits and size (number) limits. With the default settings, users are limited to two-second searches and no more than 100 records returned per search. Setting search size or time limits too high can negatively affect IdM server performance. Open the IPA Server tab. Select the Configuration subtab. Scroll to the Search Options area. Change the search limit settings. Search size limit, the maximum number of records to return in a search. Search time limit, the maximum amount of time, in seconds, to spend on a search before the server returns results.
Setting the time limit or size limit value to -1 means that there are no limits on searches. When the changes are complete, click the Update link at the top of the Configuration page.
4.4.2.2. With the Command LineThe search limits can be changed using the config-mod command. $ ipa config-mod --searchtimelimit=5 --searchrecordslimit=500 Max. username length: 32 Home directory base: /home Default shell: /bin/sh Default users group: ipausers Default e-mail domain for new users: example.com Search time limit: 5 Search size limit: 50 User search fields: uid,givenname,sn,telephonenumber,ou,title Group search fields: cn,description Enable migration mode: FALSE Certificate Subject base: O=EXAMPLE.COM Password Expiration Notification (days): 4 Setting the time limit or size limit value to -1 means that there are no limits on searches. 4.4.3. Overriding the Search DefaultsPart of the server configuration is setting global defaults for size and time limits on searches. While these limits are always enforced in the web UI, they can be overridden with any *-find command run through the command line. The --sizelimit and --timelimit options set alternative size and time limits, respectively, for that specific command run. The limits can be higher or lower, depending on the kinds of results you need. For example, if the default time limit is 60 seconds and a search is going to take longer, the time limit can be increased to 120 seconds: [jsmith@ipaserver ~]$ ipa user-find *sen --timelimit=120 4.4.4. Setting Search AttributesA search for users or groups does not automatically search every possible attribute for that attribute. Rather, it searches a specific subset of attributes, and that list is configurable. When adding attributes to the user or group search fields, make sure that there is a corresponding index within the LDAP directory for that attribute. Searches are performed based on indexes. Most standard LDAP attributes have indexes, but any custom attributes must have indexes created for them. Creating indexes is described in the indexes chapter in the Directory Server Administrator's Guide. 4.4.4.1. Setting User Search Attributes4.4.4.1.1. From the Web UIOpen the IPA Server tab. Select the Configuration subtab. Scroll to the User Options area. Add any additional search attributes, in a comma-separated list, in the User search fields field. When the changes are complete, click the Update link at the top of the Configuration page.
4.4.4.1.2. From the Web UITo change the search attributes, use the --usersearch option to set the attributes for user searches. $ ipa config-mod --usersearch=uid,givenname,sn,telephonenumber,ou,title Always give the complete list of search attributes. Whatever values are passed with the configuration argument overwrite the previous settings. 4.4.4.2. Setting Group Search AttributesA search for users or groups does not automatically search every possible attribute for that attribute. Rather, it searches a specific subset of attributes, and that list is configurable. When adding attributes to the user or group search fields, make sure that there is a corresponding index within the LDAP directory for that attribute. Searches are performed based on indexes. Most standard LDAP attributes have indexes, but any custom attributes must have indexes created for them. Creating indexes is described in the indexes chapter in the Directory Server Administrator's Guide. 4.4.4.2.1. From the Web UIOpen the IPA Server tab. Select the Configuration subtab. Scroll to the Group Options area. Add any additional search attributes, in a comma-separated list, in the Group search fields field. When the changes are complete, click the Update link at the top of the Configuration page.
4.4.4.2.2. From the Command LineTo change the search attributes, use the --groupsearch options to set the attributes for group searches. $ ipa config-mod --groupsearch=cn,description Always give the complete list of search attributes. Whatever values are passed with the configuration argument overwrite the previous settings. 4.4.5. Attributes Returned in Search ResultsSearches 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. |
| |
