The following permissions are defined for the Nemo release:

Follow these steps to enable security on a ZipTie SOAP Provider. New permissions can be added to the system via the SecurityPermissions Extension.

In the bundle MANIFEST.MF add a dependency on org.ziptie.zap.security and org.ziptie.server.security.

The Provider Delegate getProvider() method should wrap the Provider in a Security Proxy. Here is an example using a hypothetical IYourProvider interface and YourProviderDelegate.

public class YourProviderDelegate implements IYourProvider
{
   // delegate methods that call getProvider()
   ...
 
   private IYourProvider getProvider()
   {
      IYourProvider provider = YourProviderActivator.getYourProvider();
      if (provider == null)
      {
         throw new RuntimeException(Messages.YourProviderDelegate_yourProviderUnavailable);
      }
 
      return (IYourProvider) SecurityHandler.newProxy(provider);
   }
}

New permissions are added to the system via the SecurityPermissions extension point defined by the org.ziptie.zap.security bundle. This section documents how to add new permissions using this extension point.

The SecurityPermissions extension point contains a sequence of 1 or more permissions. Each permission contains two attributes:

id - The internal identifier of the permission. Should be descriptive and follow a Java package name-like convention. For example, org.ziptie.job.backup.create or org.ziptie.credentials.administer.

display - The descriptive display string shown to the user who is creating new roles containing this permission. The current convention (in English) is to start the display description with the words “Permission to”. For example, “Permission to administer credentials”. As you will see next, this display string should be externalized to enable i18n translation into other languages.

The extension point should be defined in your bundle's plugin.xml. Here is an example.

  <extension point="org.ziptie.zap.security.SecurityPermissions">
     <permission
           display="%org.ziptie.launchers.administer"
           id="org.ziptie.launchers.administer">
     </permission>
  </extension>

In order to enable translation of display strings into other languages these steps (and conventions) should be followed:

1. In the permission definition inside of the SecurityPermissions extension, the display string property should start with a percent sign (%) followed by the id string defined in the id property. For example, if the id is org.ziptie.credentials.administer then the display string should be %org.ziptie.credentials.administer.
2. You should create plugin.properties file in the root of the bundle. In this file are properties that map the display string (%org.ziptie.credentials.administer) to the real description (for example, “Permission to administer credentials.”). Like so: org.ziptie.credentials.administer=Permission to administer credentials.
3. Add the following header to the MANIFEST.MF file: Bundle-Localization: plugin
4. Add plugin.properties to the distribution on the Build tab of the plugin.xml editor.

Finally, add invocation security annotations to your Provider interface methods using the ZInvocationSecurity annotation. The ZInvocationSecurity annotation contains a single property defining the permission required to invoke the provider method. These permissions should match the permission id(s) that you defined in the SecurityPermissions extension point.

Again, using our hypothetical IYourProvider interface the annotations might look like this:

public interface IYourProvider
{
   @ZInvocationSecurity(perm = "org.ziptie.provider.your.dance")
   void dance(int wildnessLevel);
 
   @ZInvocationSecurity(perm = "org.ziptie.provider.your.sing")
   void sing(boolean loudly);
}

The build.xml file in your Provider needs to contain an additional classpath entry to allow WSDL generation to occur without error. Add the following to your invocation of BuildCG.xml:

<property name="genwsdl.additional.classpath" value="../org.ziptie.zap.security/bin" />