Jump to: navigation, search

FreeIPAv2:Concepts and Objects

FreeIPAv2 Development Documentation

Please note that this content was made during FreeIPAv2 development and it may no longer be relevant for current versions of FreeIPA. We left the content here for study and archaeological purposes.

Please check our Documentation for a recent list of topics.

This wiki page covers the new concepts that will be expressed in the IPA v2 using DS objects.


In IPA v1 there was no notion of a host. There was a notion of the kerberos principal that corresponds to the host. In IPA v2 the specific new object will be created to represent host. There are several main uses of the host object:

  • Host object will contain kerberos principal and keytab. These will be used for secure connection from the client installed on the host to the server.
    This does not eliminate the option of just adding a kerberos principal for the kerberos enabled service (nfs, cifs, etc) that is not managed by IPA as a host (in this case we are talking about just kerberos authentication and no access control or policy management).
  • Host will be used to define host based access control rules
  • Host will be used in the netgroups
  • Hosts will be used as a factor in deciding what role user should assume
  • Policy can be associated (destined) to a specific host
  • For the purpose of policy distribution, access control and role definition the hosts can be collected into a group of hosts in the same way as the users are combined into the groups of users.

Host will be a new object in the DS.
It will contain at least following attributes:

Attribute Meaning and use
Fully qualified hostname Name of the host used in UI/CLI to identify the host
Kerberos principal This a kerberos name of the host
Kerberos keytab Key the host will use to authenticate against IPA
User password Standard DS hash of password used for the bulk enrollment (see below)
Kerberos key expiration Expiration information for the kerberos keytab
Unique identifier It is assigned to the host at the moment of the enrollment or record creation (see section below dedicated to the two use cases).
Cn of the administrator who enrolled the machine See the enrollment scenarios section below
Version of the client installed on the machine This version is maintained and updated by the client
OS version This attribute is maintained by the client
Comment This field will be used by the administrator to add comment about the purpose of the machine

The following sections describes two different scenarios about how the machine can be enrolled.

Enrollment Scenarios

There are enrollment scenarios IPA v2 will support.

  • Manual host enrollment with privileged administrator
  • Manual enrollment with separation of duties
  • Bulk host deployment

We will look into those scenarios in more details

Manual Host Enrollment with Privileged Administrator

This scenario implies the following sequence of operations:

  • Administrator logs into the host that he wants to enroll with IPA
  • Administrator installs client packages on the machine
  • Administrator invokes enrollment script providing his kerberos credentials as parameters to the script
    • The script authenticates against IPA using administrator credentials.
    • The host entry for the host is synthesized and saved in DS
    • Keytab is generated on the server and provisioned to the client
  • Keytab is saved with the root:root ownership and 0400 permissions in a specific directory
  • The enrollment is complete and machine can now automatically connect and communicate with IPA server.

This is a pure manual scenario that requires administrator involvement. The enrollment script should take into the account the fact that the host might already exist as a service in the IPA from previous version. When it tries to add hosts it should validate the services area too and make sure that service entry is removed when host entry is added.

Manual Enrollment with Separation of Duties

This scenario implies that there different administrators with different levels of privileges regarding host related operations. One administrator (A) is allowed to add and edit host entries and thus enroll the hosts as is is described in the scenario above. The second administrator (B) is not allowed to create host entries but is allowed to enroll the machine. The whole sequence of operations will look like this:

  • Administrator A authorizes enrollment of a host by creating the host entry in the back end using web UI or command line script.
  • Administrator B installs client packages on the machine
  • Administrator B invokes enrollment script providing his kerberos credentials as parameters to the script
    • The script authenticates against IPA using administrator B credentials.
    • Keytab is generated on the server, stored in the host entry and provisioned to the client
  • Keytab is saved with the root:root ownership and 0400 permissions in a specific directory
  • The enrollment is complete and machine can now automatically connect and communicate with IPA server.

Bulk Host Deployment

This scenario is very useful for automatic provisioning of multiple hosts (or virtual machines).
It implies the following sequence of operations:

  • The host entry is pre-created in the IPA server. It can be done using
    • UI – manually
    • Command line interface – manually or via a script
    • XML-RPC – using custom Python program developed by (or for) customer
  • When the entry is created a user password attribute is set to some value
  • The password is set to expire after first authentication in the same way as in the user password after it has been reset by administrator.
  • The bulk provisioning scripts/tools (like kickstart) will be hard coded to use the same password that was used to create host entries on the server side
    • The script (kickstart) will install IPA
    • The script (kickstart) will run the enrollment script and pass in the password
    • The enrollment script will connect to IPA server using bind dn derived from the machine name and provided password. It will authenticate using LDAP SASL bind mechanism (DIGEST-MD5).
    • The authentication will succeed
  • Since the password is set to expire the kerberos keytab will be generated and password attribute cleared


As a result of the enrollment the GUID (that is automatically associated with the entry in DS) is downloaded and stored on the local host in a file. This is the GUID that would identify the host for the rest of its life for audit purposes and potentially other operations. There is a concern about the validity of this GUID and can it be trusted. The audit system will use the scheme involving host's keytab to authenticate packages coming from the client. If GUID gets modified and does not match the GUID of the host the packets are coming from the audit system will log a corresponding event. Later it can me extended into the alert system.

Host Renames

One of the important use cases is the host renames. The kerberos principal contains the host name. Also the host name is one of the arguments to keytab generation. When the IPA client host is renamed the principal name and the keytab has to be changed and keytab re-provisioned. One of the approaches how it can be done is before renaming the host one would run the special utility that will:

  • Connect to IPA server using administrator's credentials
  • Modify host principal attribute in the server
  • Generate a new keytab using new principal and save it in DS and on the host

After this operation the host can be safely renamed. This operation however requires manual involvement. It is considered insecure to allow running rename operation using host's keytab. If self renames allowed the compromised host might cause damage to the enterprise by renaming itself and starting to provide rogue services.

The approach above requires additional work. In v2 we might not implement it. The alternative would be to provide instructions to the customers to create a script or manually perform following steps if the host rename is required:

  • Run script to un-enroll host from IPA (this will just remove the kerberos keytab from the host entry – it will not remove the entry – at least it will have such option). IPA client will provide this script.
  • Rename host
  • Run script to enroll the host again. IPA client will provide this script.

Given the two provisioning scenarios described above this operation can be automated to either require administrative involvement or not.

Hosts and Audit

From the audit perspective all the logs sent from the host to the IPA audit server will contain host GUID. Using this GUID and a special mapping database (kept in the audit server) the audit subsystem will be able to find all the records that belonged to the host regardless of its name.
The design of this database and related mechanisms is covered in a separate document. If GUID is modified the server will start rejecting audit stream coming from the host since it would not be able to locate the keys to verify signature (or decrypt data. There is no final word yet about what kind of security mechanism will be used.). The audit server will log an event indicating that there is bad audit stream is coming. In v2 we do not plan to have an alert mechanism but in future we will extend it to allow alerts to notify administrators that something bad is happening.

Host Deletes

There is currently a discussion about a “graveyard” for the host entries. It is unclear if it is really needed. The only reason why it might be needed around is for audit purposes. However latest thinking is to create a post operation plugin for all (add/modify/delete) operations that will capture those and generate specific log events that would be later processed by audit subsystem. The audit server would have to have special handling of this log and not only index things as it usually does but build a special table of names and UUIDs so that it can build more effective searches later on.

Host and DNS

The DNS is described in more details later on this page. Here we want to mention that though there is some relation between host account and DNS entry for a host there are several key differences. Because of this DNS and machine account entries will be different entities (entries) stored in different parts of the DIT. Here are some of the reasons for not combining DNS and Host objects together:

  • Not all entries in DNS are the machines enrolled with IPA. It will be a management overhead to deal with those machines that are not enrolled but part of DNS.
  • DNS information is usually managed by the network administrators while machine account information shall be managed by the system administrators. Having to objects creates a better separation of duties.
  • There is really not much common between the two entries other than the name of the host
  • It is expected that DNS portion of the tree will be bulk modified using DNS related set of tools. For host accounts it really depends on the deployment scenario but the tools would be different

To summarize Host and DNS will be different entries. The only relation we might implement is give the link to view/edit/add DNS information when one is viewing/editing or adding host to the system using web interface.


In UI, CLI and messages we will refer to the object as “Host”.

Group of Hosts

Groups of hosts will be implemented in the same way as groups of users. The only difference is that the DN of the member will be the DN of the host entry rather than DN of user entry. The Group of Hosts will support nesting as the group of users does.


In UI, CLI and messages we will refer to the object as “Host Group”.


Service is an application that provides some kind of function (service) to other applications or users.

Kerberised Services

Some of the services are kerberos enabled. For those services to participate in the single-sign-on a corresponding entry shall be created in the DS. It should contain kerberos principal. Then the ipa-getkeytab shall be used on the host where the service runs to get the keytab for this service. This is the scope how it is implemented in v1. Currently the the provisioning on the keytab requires administrator's involvement. He has to run the ipa-getkeytab command on the client and his credentials are verified before the keytab is provisioned. In IPA v2 we will modify the ipa-getkeytab and password plugin on the server side to allow the host to request keytab for the services running on the same host (and only on the same host). The password plugin will enforce that only keytabs for the services running on the requesting host will be provisioned. This change would allow IPA client to provision and automatically refresh keytabs (when expired) for the services running on the host. IPA client would have to keep track of this information in the LDB and request new keytabs for itself and services as needed. The only requirement would be that the service record should already exist on the server. The ipa-getkeytab would create and provision keytab only if the service entry was previously created in the DS. It can be created by some XML-RPC or LDAP commands or via UI but those commands would require different privileges. This way a compromised host won't be able to inject a new service into the server.

Certificates for Services

Some of the services (whether they are kerberised or not) can require certificate(s) to function. In IPA v2 the IPA should be able to issue service a certificate. This would be a client side command. Something like: ipa-get-cert HTTP nss /etc/httpd/cert.db foo bar

The command would connect to the IPA server and request the CA to generate a certificate. The command will support two different authentication schemes:

  • Run manually using administrator's credentials.
  • Run by some kind of tool (like kickstart) using host' credentials.

The latter means that in v2 any host with valid keytab would be able to request any certificate without limitation. There will be no check if the host is requesting certificate for the service running on the same host. In the grand picture it is not clear whether it should be checked or not. In later versions this might be tightened if we decide that there should be any restrictions.

In the described scheme there is not need to have any object in IPA's DS to represent the service that requires a certificate.


In UI, CLI and messages we will refer to the keytab enabled or certificate enabled service as “Service”.

Host Based Access Control

Host base access control is the set of policies that define which users can access (log into) which machines. There are multiple ways how user can login into a machine. For example locally at the console or remotely via ssh, telnet, rlogin etc. For some customers it is also important from where the user is trying to log in. The access control rules will take into the account the following factors:

  • User who is trying to log in
  • Machine he is trying to access
  • Service (login method) he is trying to use
  • Source machine from where he is trying to log in
  • Time of day

On the client side there will be logic implemented in the PAM responder and IPA provider to determine whether the user allowed to log in or not. To make a decision all factors should (and will be) evaluated.

On the server side the host base access control will be expressed using two types of rules:

  • Allow rules – the rules that state that the user is allowed to access the machine
  • Deny rules – the rule that state that the user is not allowed to access the machine

In the absence of any rules the access is denied. Here is the example set of rules (time column is omitted for simplicity):

User Host Service Source Type
simo client.server.my * * allow
Engineers Engservers * * allow
rob web.server.my ftp * deny

Assume that mentioned above users are members of the “Engineers” group and hosts are members of the the “Engservers” host group.

The logic of the lookup is the following:

  • First evaluate the deny rules.
  • If any deny rule is satisfied the user is access denied. -> Done
  • If the there is no explicit denial rule check that user is allowed to log in.
  • If there is a matching allow rule grant user access. -> Done
  • If no matching rule is found deny access. -> Done

Using the table above we can see that “rob” will be denied access if he tries to access web.server.my host using ftp. He will be granted access to any Engserver machine using “login” for example. He will not be able to access any machines in finance since that there is no rule that allows him to access the finance machines.

Lookup Logic

To be able to determine if user is allowed to login into a host his identity needs to be checked against the allow and deny rules. The logic that is described above is a high level logic and does not deal with the service and the “from host” data. If we factor this in the queries to pull out rules relevant to current user it is impossible to determine if user should be granted access to the host using one or two simple DS lookups. There are several approaches how the issue can be resolved.

Pull All Model

This approach suggests pulling all deny and allow rules, storing them on the client in LDB and making the client code just evaluate rules one by one.

  • No much computations on the server
  • One simple query


  • There might be a lot of rules so it might be costly to pull them in one chunk
  • We would have to pull it pretty frequently (once in 3 minutes for example) and cache for couple minutes to get some performance gain. But the authentications will be bumpy because once in several minutes the whole set of rules would have to be downloaded again.
  • A lot of network traffic

The amount of data in this case can be reduced by pulling only entries that are related to the current host and group of hosts if is a member of. The issue with this solution is that it needs to pull the records that apply to "all" hosts too. So it is some optimization but not clear how much of optimization it is.

Pull Only Needed

We can try to reduce the amount of data going back and forth by downloading only the data that is more or less related to the the logging in user. With such approach there will be multiple smaller requests with the more or less simple filters. However the problem comes when one would try to reuse the data for other users logging in. It definitely might not be enough to make a decision. So we would either have to request the data on every authentication or determine somehow only the missing part. This seems to be pretty complex and susceptible to errors.

  • Smaller lists of data
  • No much computation on the server


  • Many queries
  • Tricky logic to keep track what data is needed to make a decision or need to download data on each authentication.

Server Side Processing

Use XML-RPC or a DS plugin to do the processing on the server side. If we want to use XML-RPC then the LDAPI can be used to access DS. The logic would have to implemented in the XML-RPC code. It will get the relevant rules only and process them. The yes-no decision will be sent to client and cached.
Alternatively a DS plugin can be developed. In this case the client would try to perform some operation and pass user, host, service and remote host information. The server will respond with an attribute that will be yes or no. This will be cached on client in LDB. The DS plugin will probably have a better performance but XML-RPC might be easier to implement.


  • One request
  • Minimal possible set of data to transfer to client
  • Logic is more or less simple since the server can just traverse data it has at hand and does not need to ship it over the network
  • No problems with client logic and no complexity there at all


  • More burden on server


After evaluating the approaches the following implementation is planned:

  • Download and cache only rules that apply to the current user logging on the current host.
  • Use two boolean variables denyMatched and allowMatched both initially set to FALSE.
  • Walk the list once. If a deny rule is mathed set denyMatched to TRUE, if an allow rule matched set allowMatched = TRUE
  • In the end if denyMatched = TRUE or (denyMatched = FALSE and allowMatched = FALSE) then deny access, otherwise grant access.

The exact query lookup syntax will be described on a different page.


The overview of the DNS related design and implementation is given on the DNSService page.

NIS Maps

One of the main values of the IPA solution is the replacement of NIS server. Modern hosts that will be clients of the IPA have the capability to get NIS map information from an LDAP server (using nss_ldap). The older systems do not have this capability. To be able to completely eliminate the presence of the old NIS infrastructure the IPA should be able to emulate the NIS maps for the older systems. To accomplish this a special DS plugin has been developed. This plugin reads the information from the DS entries and serves it to the NIS clients over the NIS protocol.

RFC2307bis defines the basic LDAP schema that is used for serving NIS maps. This schema is not optimal for the purposes of IPA. For example the IPA server will have the host object class but RFC2307bis defines a schema to represent the netgroups that does not take this fact into account. That means that the schema for the NIS maps should be adjusted to avoid duplication of the information.

So far we have identified only the discrepancy with the netgroups. Other maps are already derived from the same objects IPA uses (users, groups) or do not overlap with the information stored in the IPA.

The IPA team strongly believes that using the LDAP server (specifically, via the LDAP protocol) as the source of host information is wrong. The host information should be retrieved using the DNS protocol. The DNS data will also be stored in IPA, however we do not plan to make any optimization between DNS schema and host map schema to serve one and the same information via DNS and host map.

The IPA v2 will not provide management capabilities (UI, CLI) to every single map that IPA server can serve. This means that customers (should they want to use these maps) would have to develop scripts to manipulate the data for those maps using LDAP interface. The following table give an overview of how NIS maps are handled in the IPA.

Map Schema source Management Comment
Aliases N/A N/A Map is not available from IPA
Ethers N/A N/A Map is not available from IPA
Group 2307bis via Group entry in UI and CLI
Hosts 2307bis N/A Not recommended. No correlation with DNS data or IPA host objects.
Netgroup Custom. See below. IPA will provide UI and CLI for management of netgroups The netid.byname map will also be provided using the same data
Networks 2307bis N/A Develop custom management scripts if required
Passwd 2307bis via User entry
Shadow 2307bis N/A We are not planning to use and manage shadow attributes in IPA
Protocols 2307bis N/A Develop custom management scripts if required
Publickey 2307bis N/A Develop custom management scripts if required
RPC 2307bis N/A Develop custom management scripts if required
Services 2307bis N/A Develop custom management scripts if required
Automount 2307bis IPA will provide UI and CLI for management of automount information
Bootparams 2307bis N/A Develop custom management scripts if required

Netgroups will be covered in more detail in the next section.


As it was mentioned above IPA will be a source of the netgroup information. However it is not going to use standard schema to avoid duplication of information. Without this the customers would have to manage the netgroups separately from the user and host entities already available in IPA. This situation will be corrected by creating schema that will take advantage of the user and host objects. However the IPA server should consistently serve the netgroup information to clients coming over the NIS interface or assume standard schema LDAP. The following diagram shows how the problem will be addressed.

How applications will get information they need

On the server side there will be a bunch of objects stored in the DS. These objects will represent users, user groups, hosts, groups of hosts etc. We will also add a new netgroup object (see below). The NG (netgroup) plugin will create a virtual view of the data stored in the back end in the format compliant with RFC 2307bis. The NIS plugin already takes advantage of the RFC 2307bis schema too. It will use the results of the NG plugin to serve out netgroups via NIS protocol.

Applications (A-C) running on the client will leverage standard Libc interface to get information.

  • Internally on the clients where IPA client software will be installed the IPA NSS plug-in will be used. It will connect to IPA via LDAP. The details of how it would work can be found in the overview of the client design. "App X" can leverage IPA client to interact with the IPA server and get information from it or go directly to IPA server using LDAP or XML-RPC interfaces.
  • On the machines where IPA client is not installed but LDAP NSS plug-in is supported the plug-in will be configured to look at the entries located in the virtual view. The server side NG plug-in will provide this view based on the real objects. The NG plugin will be similar to the compatibility plugin released in 1.x stream.
  • The older clients that do not support LDAP as NSS service can use NIS plug-in. NIS plug-in for the netgroup information will use the data generated by the NG plugin.

This approach allows abandoning schema solutions that do not address IPA needs without breaking backward compatibility.


Application is a concept we introduce to group policies and configuration settings together. The main idea behind this concept is that the policies and roles usually have meanings only in the context of an application. This means that the UI should allow customers to define policies on per application basis.
The application object in DS is a “helper” object. It will hold information that will cover the specifics of the application. For example the application name, names of the schema files for XML policy schema, what kind of role model application expects (we talk about role models below) and other information that would help the UI and policy engines to process the application related data properly. For more specifics see the roles section and schema description below.


The whole concept of roles comes from the notion that different people on different hosts should be allowed to do different things within an application. So this approach creates the need to define a combination between user, host, application and set of his permissions. For management purposes and separation of duties we create a grouping mechanism named “roles”. For the applications that support roles based access control IPA would provide a facility to define the list of application related roles. Each role is the named set of permissions to perform actions that make sense in the context of the application. The idea is that as soon as customer would like to start using the IPA for a new application he would define the collection of the permissions and save the in the XML blob. IPA will deliver this blob to all the hosts it will be associated with. It is assumed that it will be associated with all the hosts that would run the application.
For example, let us assume that there are 1000 hosts in the enterprise and each of them has its name from host1 to host1000. An Oracle based application that supports IPA integration will be run on the hosts10-host15 and hosts345-host350. The first range denotes the hosts that run one instance of the application and the second another (separate) instance of the application. For both instances however the meaning of what “admin”, “guest” and “user” roles are same. “Guest” can review information but not modify it. “User” can modify data but not add new users or perform administrative tasks. “Admin” can do everything. The XML blob would then contain information about the meaning of roles “admin”, “user” and “guest” in the way application would understand it. The customer would create two host groups “instance1” and “instance2” and associate the role definition XML blob with these two groups. Alternatively the customer can create a host group “Oracle App” that will nest other two host groups and assign the XML blob to that one group. The IPA will deliver the XML blob the specified hosts and pass them to application in a shape and form application would define. This will be done by translating the XML code into some kind of configuration file using XSLT or other mechanism. Application might also be XML aware so the might be no need to translate the information at all. So now the application knows what “admins”, “users”, and “guests” can do. When user starts to interact with the application the application can request user authentication against IPA (or other source). After determining that user is a valid user it should be determined what this user can do. That means that the user needs to be mapped to his “role”. The application would be able to ask the IPA client about the user role using the API IPA client will provide. This API will be similar to the LIBC getXX API. The client will turn around and query server (DS portion) about what role should user assume on the current machine regarding the specified application. To be able to perform this query and get user's role(s) back, the mapping of users to roles should be configured on the server.


When dealing with definition of what permissions constitute a role we should use the terms related to “Defining the role”. When we associate users to the roles we should use terms “mapping user to the role”.

Different Types of Roles Mapping Models

So far we have identified two models that can be used to map users to the roles. Unfortunately these two models would require two different kinds of DS objects to express them effectively.
Below when we speak about users and hosts in the context of models we need to understand that user can be expressed via:

  • Specific user(s)
  • User group(s)
  • All

Similarly the hosts can be expressed via:

  • Specific hosts(s)
  • Host group(s)
  • All

Full Mesh Model

This is a mapping of a set of users to a set of hosts that is useful when all specified users assume (map to) one and the same role on all those hosts. To express this mapping we will use one object class that will be able to point to many users and hosts at the same time.
An example of such model is: all users in engineering and support can access issue tracking portals from the machines in engineering and support. This means that if engineer comes to support and logs via computer in support he will get same access rights as if he did it via his own machine. This model is useful when the application is going to be used by a lot of people and the host faction is really not that important.

Pair Based Model

This model is useful when one needs to express the situation when users A and B are administrators of machines X and Y respectfully but user A on machine Y is a guest as well as user B is a guest on machine X.
For this model we pick an object that defines a pair between user entity and host entity and then associate the set of such entries to a role.
This model is useful when the host is an important factor in making decisions about what role the user should be mapped to. The pair model allows having roles like:

Role 1 is:

  • userA on HostX
  • userA on HostGroupA
  • userB on HostX
  • Group1 on HostGroupA
  • All users on HostY

Role 2 is:

  • userB on HostY
  • userB on HostGroupA
  • userB on HostY
  • Group2 on HostGroupA
  • All users on HostX

In case of conflict the role with the higher precedence will win since it will be evaluated in the descending precedence order.

Comparing Models

One can argue that the concept of each model can be expressed via objects that we picked for another model. It is easier to use pair based model to express the full meshed model. The full meshed model can be viewed as a pair collection with just one pair. On other pages will refer to "pair" as a "relation" and would use a collection of relations to express the mapping. This creates a unified approach for different applications without confusing user.


As it was mentioned above the policies will be stored in the XML blobs. The structure and meaning of the XML blob information (other than roles described above) is outside of the scope of the current design page. What is important here is that (at least in v2) the XML blobs will be stored compressed in the DS. In future we might consider using files for the policy storage. This option will be evaluated later if we hit performance and scalability issues with the current approach. The policies will be represented by two different objects. One as the storage for the XML blob container and another is a pointer or link to it that will contain additional attributes that will describe the state of the policy expressed in the XML blob. The main reason for the separation is to avoid replication of the XML blobs if they do not change. If the blobs are made a part of the entry among other attributes the whole entry will be replicated even if the XML blob did not change. Since we anticipate the XML blobs to get big overtime we want to avoid replication of the big chunks of data that can affect the performance of the IPA server as a whole. The two objects are described in detail in the schema section.