Uploaded image for project: 'OpenIDM'
  1. OpenIDM
  2. OPENIDM-5193

Provide the ability to conditionally assign a role to a user based on a declarative filter





      Our current role model only allows (out of the box) direct grants of roles to users. The default scripts used to calculate role membership can be extended to add some "conditional" features but they essentially require development for each deployment.

      The basic requirement can be defined as such :

      Roles (Managed Roles) can be granted to Users (Managed Users) in a declarative manner by specifying a filter / predicate in the Role definition. The User's effective role list will contain one or more conditional roles if the filter / predicate evaluates to true for that User, alongside other (static) Roles


      Let's define the following role : Employee Role. This role is granted only to actual employees of the company "ACME, Inc.". I.e. contractors or interns working for ACME will not be granted this role because from an HR standpoint they are not actual employees of the company.

      This Employee Role might provide access to some special privileges not available to non-employees : access to the library and ability to order free Blue Star Doughnut on Wednesdays. Those might be driven by some LDAP groups, in a "target" directory server, defined in associated assignments :

      • FreeWednesdayDonut : cn=FreeDonut, ou=Groups, dc=acme, dc=com
      • LibraryCard : cn=LibraryCardAccess, ou=Groups, dc=acme, dc=com

      This role however is not manually assigned to employees of ACME directly since they have over 150,000 employees. The role assignments are derived from an attribute present in the user entries : the worker_type attribute. This attribute can have the following values : employee, intern and contractor. The Employee Role holds an attribute-based filter which instructs the system to grant this role only if : worker_type eq "employee".

      This is a very traditional use case and should be used to demo the functionality provided in this Epic.


      While the declarative approach seems pretty straightforward, there are a couple of things to formalize :

      • the proper role grant (relationship) should be added if
        • a new user with an attribute / value pair that successfully validates the filter is added
        • a new attribute / value pair, validating the filter, is added to an existing user
        • the attribute value is changed so it matches the filter
      • the proper role grant (relationship) should be removed if
        • the user previously granted the role is removed
        • the attribute / value pair, of a user that was granted the role, is removed from the user
        • the attribute value is changed so that it doesn't match the filter anymore

      The following use case might require a little more work and could be coupled with future improvements so as to diminish the impact on performance :

      • when a new conditional role is added new grants (relationships) are added to the users matching the filter
      • when a conditional role is removed all the previously assigned grants are removed

      Those attribute / value pair changes would happen as a result of a direct CRUD operation on the managed user or during a reconciliation.

      Note : in the description above, "matching the filter" or "validating the filter" means that the user with that attribute / value pair would appear in the result of a query based on the predicate / filter defined in the role entry.

      Business Value

      Based on feedback we got from the field this is probably one of the most common use cases for role based provisioning.

      In most real implementations there are a fairly well known set of birthright roles. These are usually tied to geolocation, organizational structure or employee type. For example, [a customer] had a requirement to grant a specific set of entitlements based on hospital location that a doctor was associated with. It is also common to have such roles as “Employee”, “Department ABC”, etc.

      As demonstrated earlier, the manual grant of Roles is just not possible for companies with many users and therefore having the ability to define role grants based on some values of specific attributes enables the business to be more responsive to changes in their workforce or their customer base.

      Administration through the Admin Console (UI)

      While the creation of a conditional role through the REST API is obviously available, the Admin Console should provide the ability to create a conditional role with the following feature :

      • a conditional role cannot be manually assigned to a user – this contradicts the fundamental concept on which conditional roles are built. While that would be technically feasible, it is not recommended because of the implications (inconsistencies) that mixing conditional and manual grants would have.
      • a new role type should be introduced so that when a new role is created a role is either static / manual or conditional
      • the conditional role filter should be defined based on the attributes currently available through the Managed User schema – but this isn't a strict requirement : i.e. a filter could be defined even though no corresponding attribute exist in the MU schema. So the visual element in charge of defining the filter should provide a type-ahead (completion) based on the MU schema but should not restrict the value to those attributes defined in it.
      • the conditional role filter "widget" should mimic our usage of the query filter syntax – this should NOT be a free form box, but rather a combination of type-ahead (for the attribute and its value, if defaults or constraints are provided) and a defined list of operators allowing the construction of a complex but valid filter.
      • a sample user selection should help the administrator to verify whether this user would be granted the role or not – or (more along the lines of the role simulation requirement) once the filter is built a validation box could list all the potential members of this role with a max of 100 or 200 users for example and way to search through those results – this might be the preferred approach.

      Regarding the first 2 bullet points which were stricken : there seems to be a consensus within the SE community that roles can be conditional and static at the same time. I.e. even if a role defines a filter / predicate to build a membership list based on a condition, individual members can still be manually assigned to this role. Therefore the type difference and restricting the ability to manually add roles were both removed from the requirements.

      That said, in order to maintain the ability to differentiate between grants that were created based on a filter and grants that were manually created, each grant relationship should clearly indicate a type (conditional vs. static) so that the appropriate logic can be built during the allotment or, more importantly, the removal of a grant.

      Conditional roles should be listed along side the current roles in the Admin Console, but a visual cue (a funnel, maybe) should clearly indicate that the role has a conditional property. The list of members would be displayed in a similar fashion with the exception that members that were added conditionally can be visually differentiated and filtered.

      Conditional roles should be identical in all other aspects, like managed assignments.

      Possible Enhancements

      Here's a list of potential future enhancements for conditional roles to keep in mind :

      • having the ability to define the filter / predicate based on a script (JavaScript). The result of the evaluation (true / false) dictates whether the role is granted or not.
      • having the ability to declare external resources attribute / value pair to the filter evaluation.

      Acceptance Criteria

      For this Epic to be deemed complete, there should be :

      • a way to define a filter (query filter) for a role, maybe via a new role property, to build the role's members list conditionally, through the REST APIs ; this is in addition to the existing REST APIs available for role manipulations
      • the ability to define this new filter through the Admin UI
      • a set of QA tests that verify the results of different filters applied and removed to some sample roles
      • a documentation set that describes ways to create the conditional roles via the REST API and the Admin Console
      • a new use case that can be added to the existing role sample
      • unit test coverage


        Issue Links



              npvisual Nicolas Philippe [X] (Inactive)
              npvisual Nicolas Philippe [X] (Inactive)
              0 Vote for this issue
              3 Start watching this issue