AuthZForce Upgrader

If you intend to install a new version of Authzforce on the same server as the old version, first create a backup of the folder /opt/authzforce in the case of v4.2.0, or /opt/authzforce-ce-server for later versions, and proceed with the instructions below, using the backup folder as old.install.dir.

To upgrade AuhZForce data from an older version to 6.0.0, proceed as follows:

  1. Install Ivy and Ant-Contrib on your system:

    $ sudo apt-get install ivy ant-contrib

  2. If you have custom AuthZForce PDP attribute providers, for each one, you have to adapt them to the new PDP AttributeProvider’s Java interface, deploy and enable them on the new AuthZForce Server. Please refer to the online User and Programmer Guide for more information on this process (select the latest version with the 3 first dot-separated numbers – MAJOR.MINOR.PATCH – matching your AuthZForce Server version). Then you have to add a new xsl:when element in the following form in the XSL template named attribute-finders-upgrade in XSL stylesheet xslt/M.m.x/domain-pdp-upgrade.xsl (path relative to the current working directory) – replace M.m with the MAJOR.MINOR version of your old Authzforce version to be upgraded – where you defined the transformation rules to upgrade the attribute provider configuration to the new model (the TestAttributeProvider below is just an example and may be ignored):

    <xsl:when test="$typeLocalName = 'TestAttributeFinder'">
    <xsl:attribute name="xsi:type">test:TestAttributeProvider</xsl:attribute>
    <!-- For this attribute finder (for example), we copy child nodes as is. -->
    <xsl:copy-of select="child::node()" />
</xsl:when>
<xsl:when test="$typeLocalName = 'MyOldCustomAttributeFinder'">
    <xsl:attribute name="xsi:type">my-new-namespace-prefix:MyCustomAttributeProvider</xsl:attribute>
    <!-- Below the transformation rules for my custom attribute finder -->
    ...
</xsl:when>

  3. Run the following command, where argument old.version is the old version (in the form x.y.z) of Authzforce you are upgrading from, argument old.install.dir is the installation directory of the old version, or a backup of it if you are installing the new version on the same server, and argument new.install.dir is the new installation directory of the Authzforce version corresponding to this upgrade tool:

    WARNING 1: by default, for each domain, the following command will convert the old domain property ‘name’ to the new ‘externalId’ property (the value is copied from one to the other during the upgrade). Make sure that each old domain ‘name’ is UNIQUE. Indeed, each ‘externalId’ MUST BE UNIQUE after the upgrade. If this is not the case, either fix it or skip this conversion step by adding the following argument: -Dignore.domain.name=true. In this case, the ‘externalId’ will not be set by the upgrader tool. This is not an issue for new AuthZForce versions since ‘externalId’ values are optional. You may set them later with the API if you need to.

    WARNING 2: the following command will replace all standard XACML identifiers planned for deprecation in Appendix A.4 of XACML 3.0 Core specification with the new XACML 3.0 identifiers.

    WARNING 3: if you don’t use sudo, make sure you are executing the command as a user with read-write permissions on new.install.dir.

    $ sudo ant -Dold.version=4.2.0 \
  -Dold.install.dir=/path/to/old/opt/authzforce-4.2.0 \
  -Dnew.install.dir=/path/to/new/opt/authzforce-ce-server \

    Another example with extra argument ignore.domain.name to skip domain name-to-externalId conversion, in case domain name properties of the old Authzforce installation are not unique:

    $ sudo ant -Dold.version=4.2.0 \
  -Dold.install.dir=/path/to/old/opt/authzforce-4.2.0 \
  -Dnew.install.dir=/path/to/new/opt/authzforce-ce-server \
  -Dignore.domain.name=true

  4. Set the permissions properly on the new data: 

    $ sudo chown -RH tomcat7 /path/to/new/opt/authzforce-ce-server
$ sudo chgrp -RH tomcat7 /path/to/new/opt/authzforce-ce-server

  5. Restart Tomcat on the new AuthZForce server to load the new data.

  6. If your old Authzforce version was 4.2.0 and the upgrade was successful, you may remove this old version: shell $ sudo aptitude purge authzforce Note: in v4.2.0, the Ubuntu package name was called authzforce, then it was renamed authzforce-ce-server in later versions. Therefore, the command above should remove only the old v4.2.0.