Skip to main content

Generate role list

You can control who can view and select which roles by using a role list generation plugin. By default, end users and product administrators can select any role for a user. You may want to set up a restriction, for example, to allow a certain requester to select a particular group of roles.

The role list generation plugin is a whitelist of accepted roles to manage. The filter plugin excludes roles like a blacklist.

If business logic can dictate an explicit list of roles that a user can select, then you can use the role list generation plugin. If the role list generated is significantly small in comparison to the roles that would be filtered out, this plugin is also preferred.

To use a role list generation plugin:

  1. Click Modules > Options.

  2. Type the name of the plugin program or PSLang script in the GENERATE ROLE PLUGIN field.

  3. Click Update.

There are no shipped plugins for use with this plugin point.

Write a custom role list generation plugin

Requirements

See Writing plugins for general requirements.

Execution points

The plugin is called by the View and update profile (IDR) module and Help users (IDA) module before the role list is displayed. It is called once when a role select page is first rendered. Only roles that are returned by the plugin are available for selection. If the set of roles is empty, the end user is not able to select a role for anyone.

Role list generation is similar to the filter plugins. This plugin supports synchronous calling. There are two forms of synchronous calling:

GENERATE ROLE PLUGIN standard input/output mode

In standard input/output (stdio) mode, a synchronous list generation plugin works in the following way:

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

  2. When the CGI program is ready to receive an object, it sends an empty KVGroup ( "" "" = { }) to the plugin program.

  3. The plugin program sends a KVGroup that includes an object ID, or is empty to indicate end of list.

  4. Steps 2 and 3 continue until the plugin sends an empty KVGroup to indicate end of list, or the objects generated reaches the limit required by the calling program.

Input

Input sent to the plugin is as follows:

"" "" = {
  "module" = "<idr|ida>"
                     
  "recipient" "<user|empty>" = {
                     
     # The "recipient" group contains standard information about the
                     
     # subject of the request.
   }
  "viewer" "<user|admin>" = {
     # The "viewer" group contains standard information about the
     # person using the CGI.
   }
 }

Output

The list of roles is passed from the plugin on stdout. A KVGroup is sent for each user.

The output KVGroup sent from the plugin must be as follows:

"" "" = {
  "roleid" = "<role ID>"
                     
      # Optional; This indicates the next role to add to the list of roles.
      # If omitted, this indicates there are no more roles to add.
  "abort"  = "<true|false>" #If true, bypass the list generation plugin
  "errmsg" = "<text message>" # A message sent on an error
  "retval" = "0" # Mandatory; non-zero indicates failure
}

GENERATE ROLE PLUGIN callback mode

In callback mode the role list generation plugin uses two functions:

  • OnGeneratorInit( $inkvg ) This function retrieves the initial information about the request, requester and viewer.

  • GetGenList( $list ) This function returns an array of roles that the CGI will display.

Example

A simple example is as follows:

  function OnGeneratorInit( input $inkvg )
  {
      log( "inkvg: " + kvgToString($inkvg ));
  }
  function GetGenList( output $list )
  {
      var $include_role[]
      $include_role[ size( $include_role ) ] = "ROLE7";
      $include_role[ size( $include_role ) ] = "ROLE1";
      $list = $include_role;
  }
In this section: