Skip to main content

Filter resources

Bravura Security Fabric offers a resource filtering plugin infrastructure as an alternative to automatic resource selection. Resource filtering is complementary to the manual resource selection process. The result of resource filtering is a shorter list of resources that is presented to users. With a shorter list, it is easier for the end user to select appropriate resources. You can also use this method to control the resources that product administrators are allowed to manage in the Help users (IDA) module and the Manage the system (PSA) module.

To use a resource filter plugin:

  1. Click Manage the system > Modules> Options.

  2. Type the name of the plugin program or PSLang script in one of the following fields:

    • FILTER ACCOUNT PLUGIN – Filters the list of accounts the user can manage.

    • FILTER ACCTGROUP PLUGIN – Filters the list of available managed groups the user can pick from.

    • FILTER GROUP MEMBER PLUGIN – Filters managed groups that users can pick to add to, or remove from, other groups.

    • FILTER ROLE PLUGIN – Filters the list of available roles the user can pick from.

    • FILTER TEMPLATE PLUGIN – Filters the list of available templates the user can pick from.

  3. Click Update.

    You cannot use the same plugin program or script for more than one plugin point. The plugin must be altered for each filter.

If you want the filters to operate when product administrators use the Manage the system (PSA) module, click and enable the PSA FILTERING option (Manage the system > Modules > Manage the system (PSA)). This option is turned off by default.

There are no shipped plugins for the resource filter plugin points. You can write a custom resource filter plugin.

The group member plugin operates differently to the other plugin types described in this section. Its rules and requirements are similar to the search filter plugin. You can write a custom group member filter plugin.

See also

Filter users shows you how to write and configure plugins to filter user profiles.

Write a custom resource filter plugin

Requirements

The plugins are run with a maximum of RECORDS PER PAGE entries.

See Writing plugins for general requirements.

Execution points

Resource filter plugins are run by modules when a user attempts to manage, view, or select a resource, before the resource selection page is displayed. This happens when a user is creating a new user, managing an existing user’s accounts, or adding new resources to existing accounts. They can also be configured to run in the Manage the system (PSA) module.

Filter plugins operate differently from most plugins, which are synchronous. All filter plugins support asynchronous calling. There are two forms of asynchronous calling:

Resource filter standard input/output mode

In standard input/output (stdio) mode, filter plugins work in the following way:

  1. An event triggers a CGI program to call the plugin program or script and sends it standard user data.

  2. The calling program continues to stream input from stdin, one item at a time until there are no more items.

  3. For each item, the plugin returns the filter result to stdout.

  4. The calling program receives the final standard output and continues.

Input

Input is similar for all resource filter plugins. The plugin first receives standard data in the format:

"" "" = {
  "sessionid" = "<session ID>" # The session ID of the request.
  "module" = "<idr|ids|idp|idwfm>"
                     
  "accountID" = "<account ID>" # The account ID of the recipient.
                     
  "template = "<template ID>" # The selected template ID.
  "targetid" = "<target ID>" # The target ID for the recipient.
  "navigation" "" = { ... } # User navigation data
  "recipient" "<user|empty>" = {
     # The "recipient" group contains standard information about the
                     
     # subject of the request.
   }
  "viewer" "user" = {
     # The "viewer" group contains standard information about the
     # person using the CGI.
   }
  "request" "" = {
     # The "request" group contains standard information about the
     # the request.
   }
 }

Some of the values above may be empty, due to the stage and type of the request.

The plugin then receives a series of KVGroups; one for each item. An account filter plugin receives, for example:

"account" "" = {
  "account" "" = {
    "userid" = "ACOS0000"
    "hostid" = "NORSE"
    "longid" = "ACOS0000"
    "shortid" = "ACOS0000"
    "helpdesk" = "FALSE"
    "list" = "TRUE"
    "user" = "FALSE"
    "associated" = "TRUE"
    "invalid" = "FALSE"
  }

  "target" "" = {
    "targetid" = "NORSE"
    "platform" = "WIN2K"
    "address" = "\\\\10.0.12.21/basedn=ou=staff"
    "standardid" = "true"
    "targetgroupid" = "DEFAULT"
  }
}

A template filter plugin receives:

"template" "" = {
  "description" = "Corporate Active Directory"
  "hostid" = "AD"
  "id" = "AD_TEMPLATE"
  "location" = ""
  "longid" = "template_user"
  "type" = ""
}

A group filter plugin receives:

"nosgroup" "" = {
  "addtype" = "MODR"
  "deltype" = "MODR"
  "groupid" = "CN=arch_frv_owners,OU=groups,OU=staff,DC=norse,DC=bravurasecurity,DC=com"
  "hostid" = "AD"
  "location" = ""
  "mgrpid" = "e371a413-a417-4d67-9085-538ab963d886"
  "subgrpid" = "00000000-0000-0000-0000-000000000000"
  "type" = ""
}

A role filter plugin receives:

 "role" "" = {
  "desc" = "Corporate employee"
  "roleid" = "CORP_AD_ROLE"
}

Output

For each item, one output KVGroup is expected on stdout, with an optional "filter" = "true" pair to indicate that the item should not be displayed:

"" "" = {
"filter" = "true|false"
       # If false, the user is displayed
       # If true, the user is not displayed
"retval" = "<#>"
       # Optional, if non-zero returned, abort the plugin
}

A plugin that encounters errors in its processing can add standard output pairs for individual items, which should cause the plugin execution to be aborted.

Resource filter callback mode

In callback mode the resource filter plugin uses two functions:

  • OnFilterInit(const $inkvg, output $detail) This function is called once to retrieve initial information about the request, requester, and viewer.

    • $inkvg – the viewer

    • $detail – if 0, no detail provided on input kvg for each user

      – if 1, detail is provided on input kvg for each user

      – can also be expressed as a KVGroup

  • OnItemFilter(const $inkvg, output $msg, output $allow) This function is called once per item to determine what resource the user can view or manage.

    • $inkvg – the resource to filter

    • $msg – error message

    • $allow – if 1, this user is displayed and available

      – if 0, this user is not displayed and is unavailable

Example

A simple example is as follows:

 function OnFilterInit( const $inkvg, output $detail )
 {
     log ( kvgToString( $inkvg ))
     $detail = 0;
     return 0;
 }
  function OnItemFilter(const $inkvg, output $msg, output $allow )
 {
     log ( "OnItemFilter:" );
     log ( kvgToString( $inkvg ))
      $msg = ""; # Error message
     $allow = 0; # not allowed
     # $allow = 1; # allowed
     return 0;
 }

Write a custom group member filter plugin

The FILTER GROUP MEMBER PLUGIN operates differently to other resource filter plugins. It uses the same rules and criteria as the search filter plugin but acts only on the GROUPFORGROUP search engine.

You can use this plugin to:

  • Create an include list for the GROUPFORGROUP search engine such that only search results in this list will be returned to the user.

  • Create an exclude list for the GROUPFORGROUP search engine to exclude some search results.

  • Set up some search criteria for groups so that only search results that satisfy the criteria will be visible to the user.

    An exclude list overrides an include list or filter criteria; that is, if an item is in an exclude list AND include list, or in an exclude list AND selected by criteria, then the item will be excluded.

Requirements

See Writing plugins for general requirements.

Execution points

This plugin is called by the GROUPFORGROUP search engine after a user submits a search request.

Input

The input presented to the plugin is a KVGroup that includes the viewer information, search type, and a list of advanced search keys; for example:

"" "" = {
  "viewer" "user" = {
    "id" = "jonh"
    "name" = "jon hoo"
  };
  "module" = "ajaxsvc"
         
  "searchType" = "GROUPFORGROUP"
  "ValidKeys" "" = {
    "groupid" = ""
    "groupname" = ""
    "targetdesc" = ""
    "targetid" = ""
    "url" = ""
    "RBACflag" = ""
    "valid" = ""
    "issecurity" = ""
    "parentgroupid" = ""
    "authorizer" = ""
         
    "grouptype" = ""
  };
  "request" "" = {
    "requestID" = "56677492AC6B0890CAD8144821AA1B3A"
    "macroStatus" = "U"
    "requester" = "jonh"
         
    "requesterName" = "jon hoo"
    "requesterEmail" = ""
    "recipient" = "jonh"
         
    "recipientEmail" = ""
    "entryDate" = "1449620980"
    "notes" = ""
    "reason" = ""
    "batchauthnote" = ""
    "segment" = ""
    "reservationid" = "00000000-0000-0000-0000-000000000000"
    "autoressig" = ""
    "prequest" = "PDR_CHILD"
    "requestModule" = "idr.exe"
    "resource" "566774A11814D12045F992432D55F6DF" = {
      "childtargetid" = "OAK"
      "childgroupID" = "CN=testgrp2,OU=ngrptest,DC=oak,DC=devel,DC=bravurasecurity,DC=com"
      "itemType" = "groupID"
      "groupID" = "CN=Account Operators,CN=Builtin,DC=jasonh,DC=bravurasecurity,DC=com"
      "targetid" = "OAK"
      "longIDSet" = "false"
      "userid" = "jonh"
      "newgroup" = "false"
      "enact" = "true"
      "pseudoOp" = "false"
      "pseudoTag" = ""
      "pseudoData" = ""
      "finalized" = "false"
      "authtype" = "P"
      "operation" = "GRGA"
      "status" = "O"
      "statusreason" = ""
      "notes" = ""
      "reason" = ""
      "acctauthnote" = ""
      "result" = "I"
      "implicit" = "false"
      "groupApproval" = "00000000-0000-0000-0000-000000000000"
      "parentRole" = ""
      "autoselect" = "none"
    };
    ...
  };
  "targetid" = "OAK"
  "groupID" = "CN=testgrp2,OU=ngrptest,DC=oak,DC=devel,DC=bravurasecurity,DC=com"
  "membertype" = "child"
  "sessionid" = "Sb1882a33-0984-402a-aa3b-554b32721508"
};

Output

The plugin provides one to three groups of an include list, an exclude list, and/or filter criteria to the search engine; for example:

Because groups must also be identified by a host value (accounts and managed groups), you must also add default_host and/or compound_id pairs. In the following example, Group1 and Group2 are on host AD1, and Group3 is on host AD2:

   "" ""  = {
      "includelist" "" = {
        "default_host" = "AD1"
        "id" = "Group1"; #On default host AD1
        "id" = "Group2"; #On default host AD1
        "compound_id" "" = {
           "host" = "AD2"
           "id"= "Group3"
            }
        };
    };

In a "criteria" group, each filter includes the following key-value pairs:

  • key Search engine advanced keys as listed here.

  • comparator Must be one of:

    • "EQUAL" (or "EQ")

    • "LESS_THAN" (or "LT")

    • "LESS_THAN_OR_EQUAL" (or "LTE")

    • "GREATER_THAN" (or "GT")

    • "GREATER_THAN_OR_EQUAL" (or "GTE")

    • "CONTAIN" (or "CT")

    • "START_WITH" (or "SW")

    • "IS"

    • "ON"

    • "BEFORE" (or "BF")

    • "BEFORE_OR_ON" (or "BFO")

    • "AFTER" (or "AF")

    • "AFTER_OR_ON" (or "AFO")

  • value What is compared by comparator. When comparator is "IS", <value> must be "SET" or "EMPTY". When comparator is "CT" or "SW", <value> can contain wildcards "*" and "?". Otherwise, <value> is a wide string (can contain unicode characters).

  • operator Required when "position" is greater than 1. Must be "OR" or "AND". The logical operator is applied before "filter", in order to logically connect "filter"s together, in order of "position" value. AND always has precedence over OR.

  • field Optional key to specify field when the key is not sufficient; for example, when dealing with attributes, field = attribute key; when dealing with resource groups, field = resource group id.

  • negate When "1", this generates the logical NOT of "filter".

The following example of criteria instructs the search engine to find records such that the target system ID contains ad2:

 "output" "member_group_filter_plugin" = {
  "criteria" "" = {
    "filter" "" = {
      "position" = "1"
      "key" = "targetid"
      "comparator" = "CT"
      "value" = "ad2"
      "negate" = "0"
    }
  }
  "retval" = "0"
}
In this section: