Skip to content

Authorization

Jump to bottom
Vladimir Kotal edited this page Jul 24, 2019 · 28 revisions

Using OpenGrok authorization

If OpenGrok instance is deployed in an environment where indexed data (usually source code) needs to be protected for some reason, the built in authorization framework can be used to provide access controls with high granularity.

In order to perform authorization, authentication needs to be performed first. By itself, OpenGrok does not perform any authentication, this is to be performed by the application server (e.g. Tomcat) or by a reverse proxy passing data to and from the application server. This is deliberate design decision that allows for very flexible configurations.

The OpenGrok authorization framework resembles the PAM, i.e. the configuration specifies a stack of authorization plugins where each plugin instance is paired with a flag saying how to interpret the decision of the plugin.

OpenGrok distribution contains set of various plugins that can be used for various scenarios. If that is not enough, custom plugins can be implemented using the documented programmatic API.

Configuration

You can configure:

  1. Plugin directory

    The configuration has been moved from web.xml to the usual OpenGrok configuration XML file. The way you provide new plugin directory is by creating a new XML configuration "read-only configuration" file which gets merged with the configuration made by the indexer.

    There in the file provide a new variable named pluginDirectory with a String parameter with absolute path to the directory with plugins.

    By default the directory points to OPENGROK_DATA_ROOT/plugins. The OPENGROK_DATA_ROOT is the dataRoot directory set in the main configuration.xml. If no plugin is available/the directory does not exist then the framework allows every request.

    OpenGrok authorization framework expects plugin classes in that directory, it loads those classes in memory as plugins and then perform the authorization for each request.

    If plugin directory does not exist or if it contains no plugins the framework just allows every request.

  2. Watchdog service

    Similar for the watchdog service there is a dedicated option in the configuration which you can set as described above. The name of it is authorizationWatchdogEnabled and the value is a boolean type.

    This service watches for changes (even recursive) in the plugin directory and if such change was done (modifing, deleting); it reloads the plugins. All old plugins in memory are discarded and only the plugins contained in plugin directory are loaded. This is done in real time

    NOTE: Modification of every file in plugin directory is propagated as an event. This means that modifying bunch of files in the plugin directory leads to several reload events

    By default the value is false.

  3. Authorization stack

    Discussed under advanced configuration.

  4. Provide a plugin

    You can provide your own plugin by putting the compiled plugin class (.class or in .jar) into plugin directory.

    NOTE: The important experience came out when using .jar files and is discussed in troubleshooting section.

For details about the plugin implementation (handy when implementing custom plugin) see https://github.com/oracle/opengrok/wiki/Authorization-framework-internals

Advanced configuration

The new 1.0 release contain a new feature about how to configure the plugin invocation in more details.

A stack of plugins

The plugins form a linear structure of a list (called stack). The order of invocation of the plugins methods isAllowed is determined by their position in the stack. Moreover you can configure a different flag for each of your plugins which is respected when performing the authorization.

There are three flags:

  1. REQUIRED Failure of such a plugin will ultimately lead to the authorization framework returning failure but only after the remaining plugins have been invoked.

  2. REQUISITE Like required, however, in the case that such a plugin returns a failure, control is directly returned to the application. The return value is that associated with the first required or requisite plugin to fail.

  3. SUFFICIENT If such a plugin succeeds and no prior required plugin has failed the authorization framework returns success to the application immediately without calling any further plugins in the stack. A failure of a sufficient plugin is ignored and processing of the plugin list continues unaffected.

These are inspired by the PAM Authorization framework and the definition is taken directly from the man pages of the PAM configuration. However OpenGrok does not implement all PAM flags.

Backwards compatibility

You can use the authorization framework without providing such an advanced configuration because all loaded plugins which do not occur in this advanced configuration are appended to the list with REQUIRED flag. However, as of the nature of the class discovery this means that the order of invocation of these plugins is rather random.

Example

This is an example snippet that can be inserted into the read-only configuration file. This defines three plugins, each of them has a different role and so affect the stack processing in different way. Use the class name to specify the targeted plugin and one of the flags as the authorization role. This stack is then used for every request and is processed from the top to the bottom (as it is a list) evaluating the flags with the particular plugin decisions.

<void property="pluginStack">
  <void method="add">
    <object class="org.opengrok.indexer.authorization.AuthorizationPlugin">
      <void property="flag">
        <string>REQUISITE</string>
      </void>
      <void property="name">
        <string>some.my.package.RequisitePlugin</string>
      </void>
    </object>
  </void> 
  <void method="add">
    <object class="org.opengrok.indexer.authorization.AuthorizationPlugin">
      <void property="flag">
        <string>SUFFICIENT</string>
      </void>
      <void property="name">
        <string>Plugin</string>
      </void>
    </object>
  </void>
  <void method="add">
    <object class="org.opengrok.indexer.authorization.AuthorizationPlugin">
      <void property="flag">
        <string>REQUIRED</string>
      </void>
      <void property="name">
        <string>ExamplePlugin</string>
      </void>
    </object>
  </void>   
</void>

A typical use of this configuration would be:

RequisitePlugin

  1. Determine a user identity in the requisite plugin and store it in the request
  2. Return true or false if such action was successful

Plugin

  1. Use the user identity determined in the requisite plugin which is stored in the request
  2. Perform an authorization check which can lead to immediately return from the stack with a success value
  3. If the check is negative, the stack continues to the third plugin

ExamplePlugin

  1. Use the user identity determined in the requisite plugin which is stored in the request
  2. Filter the rest of which was not enabled by the previous Plugin implementation

Troubleshooting

Using IDE

When using IDE (e.g. IDEA) to build your plugin; you can face a problem when the framework does not load your .jar file with ClassFormatError resulting to ClassNotFoundException.

Possible solutions are:

  1. disable debugging symbols
  2. compile the .java files with javac manually and then package it into .jar manually (command above)
  3. compile the .java files with javac manually and use this directory structure (without packaging)

This should solve the problem. If it does not then try to change the code.

OpenGrok

Clone this wiki locally