Jump to: navigation, search

V4/Permissions V2

Name: V4/Permissions V2
Ticket: #3566
Target version: 4.0.0
Author: Pviktorin
Green tick.png Reviewed by: Mkosek
Last updated: 2015-01-26 by Mkosek


The internal workings of Permissions and their relationship to ACIs are overhauled.

  • Permission flags are extended to ensure backwards compatibility
  • Permission ACIs may be located in any container, not just $SUFFIX
  • Permission entries now contain all data needed to (re-)generate (or check) the ACI
  • It is now possible to grant read rights

Use Cases

This feature brings no major user-visible changes, but will enable development of Managed Read permissions.

The UI is re-organized and the CLI now allows some previously disabled combinations of options -- see the respective sections.


V2 permissions

This document describes the semantics of "V2" permissions. These are permissions with a "V2" flag.

V2 permissions cannot be modified by older versions of IPA. An old-style permission will be converted to V2 whenever it is modified.

Assigning permissions to privileges will still be possible on older IPA servers.

Permission flags

Permission objects can have flags in their "ipaPermissionType" attribute. Currently we use one such flag, SYSTEM, which means that the underlying ACI is not managed by the Permission object. The code does not even assume an underlying ACI exists for SYSTEM permissions.

The permission flags will be repurposed to allow adding new functionality while retaining a degree of backwards compatibility.

New flags will be added for additional features. Permissions that have an unknown flag will be assumed to have unknown semantics implemented in future IPA versions, and the underlying ACI will not be manipulated (as with current SYSTEM flags).

For compatibility with old versions of IPA, all new flags must be accompanied by SYSTEM. Permissions with only the SYSTEM flag retain the old semantics.

Data in the permission entry

The new permission objects will contain all data needed to generate (or check) the ACI. This means IPA code will no longer need to parse ACIs (except when upgrading old permissions). Any change to a Permission will result in removing any old ACI and adding a new one.

The new schema (including schema from other related designs) is as follows:

attributeTypes: (2.16.840.1.113730. NAME 'ipaPermDefaultAttr' DESC 'IPA permission default attribute' EQUALITY caseIgnoreMatch ORDERING caseIgnoreOrderingMatch SYNTAX X-ORIGIN 'IPA v3' )
attributeTypes: (2.16.840.1.113730. NAME 'ipaPermIncludedAttr' DESC 'IPA permission explicitly included attribute' EQUALITY caseIgnoreMatch ORDERING caseIgnoreOrderingMatch SYNTAX X-ORIGIN 'IPA v3' )
attributeTypes: (2.16.840.1.113730. NAME 'ipaPermExcludedAttr' DESC 'IPA permission explicitly excluded attribute' EQUALITY caseIgnoreMatch ORDERING caseIgnoreOrderingMatch SYNTAX X-ORIGIN 'IPA v3' )
attributeTypes: (2.16.840.1.113730. NAME 'ipaPermBindRuleType' DESC 'IPA permission bind rule type' EQUALITY caseExactMatch SYNTAX SINGLE-VALUE X-ORIGIN 'IPA v3' )
attributeTypes: (2.16.840.1.113730. NAME 'ipaPermLocation' DESC 'Location of IPA permission ACI' EQUALITY distinguishedNameMatch SYNTAX SINGLE-VALUE X-ORIGIN 'IPA v3' )
attributeTypes: (2.16.840.1.113730. NAME 'ipaPermRight' DESC 'IPA permission rights' EQUALITY caseIgnoreMatch SYNTAX X-ORIGIN 'IPA v3' )
attributeTypes: (2.16.840.1.113730. NAME 'ipaPermTargetFilter' DESC 'IPA permission target filter' EQUALITY caseIgnoreMatch SYNTAX X-ORIGIN 'IPA v3' )
attributeTypes: (2.16.840.1.113730. NAME 'ipaPermTarget' DESC 'IPA permission target' EQUALITY caseIgnoreMatch SYNTAX X-ORIGIN 'IPA v3' )

objectClasses: (2.16.840.1.113730. NAME 'ipaPermissionV2' DESC 'IPA Permission objectclass, version 2' SUP ipaPermission AUXILIARY MUST ( ipaPermissionType $ ipaPermBindRuleType $ ipaPermRight $ ipaPermLocation ) MAY ( ipaPermDefaultAttr $ ipaPermIncludedAttr $ ipaPermExcludedAttr $ ipaPermTargetFilter $ ipaPermTarget ) X-ORIGIN 'IPA v3' )

(Note: ipaPermIncludedAttr was known as ipaPermAllowedAttr in the first versions of this document, and in the patches that implement it. It has been renamed for V3/Managed Read permissions.)

  • ipaPermIncludedAttr lists the attributes of the ACI; for example:
   ipaPermIncludedAttr: cn
   ipaPermIncludedAttr: sn
   ipaPermBindRuleType: permission
  • ipaPermLocation is the location of the ACI in the tree.
   ipaPermLocation: cn=users,cn=accounts,dc=idm,dc=lab,dc=eng,dc=brq,dc=redhat,dc=com
  • ipaPermRight is the right(s) the permission grants; for example:
   ipaPermRight: add
   ipaPermRight: write
  • ipaPermTargetFilter is the target filter part of the ACI, for example:
   ipaPermTargetFilter: (memberOf=cn=ipausers,cn=groups,cn=accounts,dc=idm,dc=lab,dc=eng,dc=brq,dc=redhat,dc=com)
  • ipaPermTarget is the target part of the ACI, as a DN with possible wildcards; for example:
   ipaPermTarget: uid=*,cn=users,cn=accounts,dc=idm,dc=lab,dc=eng,dc=brq,dc=redhat,dc=com

Moving ACIs out of the root

ACIs will be created on appropriate containers, rather than in the $SUFFIX. This will increase performance of LDAP operations, as fewer ACIs need to be checked for an entry.

The location of the ACI will be determined by ipaPermLocation.

Option/Attribute mapping

Due to technical reasons, API parameters need to be named the same as LDAP attributes. (This assumption runs rather deep in the framework, and makes adding new LDAP attributes for previously existing options somewhat complicated.)

In each of the following pairs of options, the two are mutually exclusive; if the second is present it acts as the first one. The second option will only be available when called with a lower API version than the one where V2 permissions are introduced.

  API name            CLI name
/ ipapermright        permissions
\ permissions         (no_cli)

/ ipapermincludedattr  attrs
\ attrs               (no_cli)

/ ipapermtargetfilter filter
\ filter              (no_cli)

/ ipapermlocation     subtree
\ subtree             (no_cli)

A new no-cli option will be added: ipapermtarget.

IPA will validate the filter before setting it by performing a search.

Finally, 3 existing options will be available to set the above:

memberof will set target filter to (memberOf={group}), after checking that the group exists. memberof and filter are mutually exclusive.

targetgroup will set target to ldap:///{group}, after checking that the group exists. targetgroup and target are mutually exclusive.

type will set target and subtree to one of pre-defined values correspondint to IPA object types. type, subtree and target are mutually exclusive.

These values will be output if the filter/target/location values match the respective patterns.

Note that this introduces an incompatibility: when a permission "type" is set, updating it to "memberof" or "targetgroup" will NOT reset all aspects of "type", as was the case before. (This change is part of ticket 2355 - Allow filter and subtree to be added in same permission)

Also Note that subtree (ipapermlocation) must now always refer to an existing entry; wildcards or non-existent DNs are not allowed.

add_noaci command

There is no expectation of backwards compatibility for permission_add_noaci. This command will be marked as internal.


See the Test Plan below.

Compatibility with old clients

For clients which report an API version lower than the one of this feature, the output will be modified to keep basic compatibility. A new "permissions2" capability will be added to track the version.

Attributes ipapermright, ipapermincludedattr, ipapermtargetfilter, ipapermlocation will be output under their old names: permissions, attrs, filter, subtree.

The type, targetgroup, and memberof will be output as single values rather than single-element lists.

For subtree (ipapermlocation), the entry will also be made single-valued, and a 'ldap:///' prefix will be added to it.

Modifying and Upgrading Permissions

A permission object can not be modified if:

  • it has any unknown flags (ipaPermissionType), or
  • it has *only* the SYSTEM flag

The process for modifying a permission (and its ACI) is as follows:

1. Before a permission object is changed, location of its corresponding ACI is found using the old permission name and ipaPermLocation (which defaults to $SUFFIX).

2. If the permission object does not have any flags (i.e. it is an old-style permission), the ACI is parsed and appropriate attributes are set on the Python representation of the entry, the SYSTEM and V2 flags are added, and the ipaPermissionV2 objectclass is added. The new ACI string is calculated from this.

3. If the location (subtree) did *not* change, the old ACI is replaced by the new ACI.

4. If the location (subtree) changed, the old ACI is removed.

5. The permission entry is updated in LDAP.

6. If the location (subtree) changed, the new ACI is added.

Adding and Deleting Permissions

When adding, the ACI is inserted after the permission entry.

When deleting, the ACI is deleted first, then the permission entry.

Mass update

Old permisisons can be updated to V2 by running the process in "Modifying and Upgrading Permissions" on all permissions without the SYSTEM flag. We can run this process on upgrade (for example in the release where we introduce an audit tool), or just let users upgrade manually.

The decision on when/if to do this has been postponed.

(The upgrade-on-modify mechanism, and permission-{find,show} for old-style permissions, need to be in place in any case, because old-style permisisons can be created on old servers.)

Find/show for old permissions

Old-style permissions will continue be recognized by permission-{find,show} commands.

The show command will upgrade the entry (in memory, without commiting to LDAP), before outputting data.

This "output only" upgrade is the same as step 2 in "Modifying and Upgrading Permissions", except it will not touch the flags, i.e. "V2" and "SYSTEM" will not be added, and the 'ipaPermissionV2' objectclass is not added.

The find command will iterate through all old-stryle permissions, do the "output-only" upgrade on each one, and filter the result based on given options.

Read rights

The "read", "search", and "compare" rights are added to "write", "add", "delete", and "all" in the list of rights that can be granted (ipaPermRight).


The UI will need to be updated to use the attribute names in the API, see the "Option/Attribute mapping" section.

Feature Management


As part of the related ticket 2355, The UI is reorganized to allow type, filter, subtree, targetgroup to be specified independently.


  • As part of the related ticket 2355, the type, filter, subtree, targetgroup options are no longer mutually exclusive
  • The type is a convenience option that sets rawfilter and subtree on input, and is computed from them on output

Test Plan

See dedicated Test Plan page