Skip to content

Upgrade process from 3.1.6 to 4.0

Jump to bottom
Jose edited this page Oct 23, 2019 · 15 revisions

Requisites: oxauth.war already updated to 4.0

Show intro messages

It is up to you showing some intro text

Download files

Download the casa 4.0 installer to a temp location (eg. /tmp) inside chroot and extract it (eg. /tmp/casa).

Currently we have beta links only, eg. https://repo.gluu.org/debian/pool/main/stretch-testing/gluu-server-4.0_55-beta1~Db9stretch_amd64.deb.

Stop casa service

OXD

Casa 4.0 requires oxd 4.0 while Casa 3.1.6 used oxd 3.1.4 (socket only or socket + https flavor), thus we should automate the oxd upgrade the following way:

  • If oxd 3.1.4 is installed in chroot, warn the user (show yes/no prompt) that it will be removed and replaced by oxd 4.0

    • If user hits 'no', show An oxd 4.0 instance is required for this product to run. and exit the upgrade tool.
    • Otherwise, uninstall oxd 3.1.4 and install oxd 4.0 (package found at /tmp/casa/opt/gluu-server/opt/dist/oxd)

  • If no oxd installation was detected, show the following message:

    Your current casa installation points to an oxd 3.1.4 server located at {host}:{port}. 
Casa 4.0 now depends on oxd 4.0, do you have an oxd 4.0 installation available? [y|N]

    where host and port values can be found in oxd_config section of file /etc/gluu/conf/casa.json

    • If user hits 'no', show prompt Install oxd-server on this host now? [y|N]

      • If user hits 'no', show An oxd 4.0 instance is required for this product to run. and exit the upgrade tool.
      • Otherwise install oxd 4.0 (package found at /tmp/casa/opt/gluu-server/opt/dist/oxd)

    • Otherwise, show prompt Enter the URL + port of your oxd-server and parse the URL (as a guide use this

The intent of this section is grabbing host and port of oxd 4.0 (it will be localhost and 8443 if oxd was installed locally by the upgrade process), or whatever the user entered when prompted Enter the URL + port of your oxd-server.

Update files

Move file /tmp/casa/opt/gluu-server/opt/dist/gluu/casa.war to /opt/gluu/jetty/casa/webapps

Move files in /tmp/casa/opt/gluu-server/install/community-edition-setup to /install/community-edition-setup

Move files in /tmp/casa/opt/gluu-server/opt/gluu/python/libs to /opt/gluu/python/libs

Create an empty file /opt/gluu/jetty/casa/.administrable

External Config files updates

Update Apache .conf file changing casa port 8091 -> 8099

Update port in the analog 4.0 file for this: https://github.com/GluuFederation/community-edition-setup/blob/version_3.1.6/templates/jetty/casa

And any other places you consider so the casa service starts and stops appropriately

Plugin updates

Consent management

If plugins section of 3.1.6 casa.json contains an entry whose id equals authorized-clients, run rm /opt/gluu/jetty/casa/plugins/authorized-clients-*.jar

then copy to /opt/gluu/jetty/casa/plugins the jar file for this plugin which can be found here (as long as state for that plugin is STARTED)

(below there is an example of how plugins section looks like)

Custom branding

If plugins section of 3.1.6 casa.json contains an entry whose id equals custom-branding, run

rm /opt/gluu/jetty/casa/plugins/custom-branding-*.jar

then copy to /opt/gluu/jetty/casa/plugins the jar file for this plugin which can be found here (as long as state for that plugin is STARTED)

Strong authentication settings

If plugins section of 3.1.6 casa.json contains an entry whose id equals strong-authn-settings, run

rm /opt/gluu/jetty/casa/plugins/strong-authn-settings-*.jar

then copy to /opt/gluu/jetty/casa/plugins the jar file for this plugin which can be found here (as long as state for that plugin is STARTED)

Account linking

If plugins section of 3.1.6 casa.json contains an entry whose id equals account-linking, run

rm /opt/gluu/jetty/casa/plugins/account-linking-*.jar

then to /opt/gluu/jetty/casa/plugins copy the jar file for this plugin which can be found here (as long as state for that plugin is STARTED)

Additionally, update /opt/gluu/jetty/oxauth/custom/pages/casa.xhtml with the file found at https://github.com/GluuFederation/casa/raw/version_4.0/plugins/account-linking/extras/casa.xhtml

In the database, update attribute oxScript of the custom script with displayName=casa with the following contents: https://github.com/GluuFederation/casa/raw/version_4.0/plugins/account-linking/extras/casa.py. Also increase by one the current value of oxLevel in that script.

Note: Casa repo is private so you will need to include this couple of files in your package beforehand.

Inwebo

If plugins section of 3.1.6 casa.json contains an entry whose id equals inwebo-plugin, run

rm /opt/gluu/jetty/casa/plugins/inwebo-plugin-*.jar

then copy to /opt/gluu/jetty/casa/plugins the jar file for this plugin which can be found here (as long as state for that plugin is STARTED)

Update configuration file casa.json

From section oxd_config drop use_https_extension and client section.

Drop plugins section.

Example: This is how a real casa.json looks like:

{
  "enable_pass_reset" : true,
  "use_branding" : false,
  "log_level" : "TRACE",
  "min_creds_2FA" : 1,
  "ldap_settings" : {
    "salt" : "/etc/gluu/conf/salt",
    "ox-ldap_location" : "/etc/gluu/conf/ox-ldap.properties"
  },
  "policy_2fa" : [ "CUSTOM" ],
  "trusted_dev_settings" : {
    "location_exp_days" : 15,
    "device_exp_days" : 30
  },
  "acr_plugin_mapping" : {
    "inwebo" : "inwebo-plugin",
    "super_gluu" : null,
    "u2f" : null
  },
  "plugins" : [ {
    "id" : "strong-authn-settings",
    "relativePath" : "strong-authn-settings-3.1.5-SNAPSHOT-jar-with-dependencies.jar",
    "state" : "STARTED"
  }, {
    "id" : "account-linking",
    "relativePath" : "account-linking-3.1.6.Final.jar",
    "state" : "STARTED"
  }, {
    "id" : "inwebo-plugin",
    "relativePath" : "inwebo-plugin-0.1-jar-with-dependencies.jar",
    "state" : "STARTED"
  }, {
    "id" : "hello-world-plugin",
    "relativePath" : "hello-world-plugin-0.1-jar-with-dependencies.jar",
    "state" : "STARTED"
  } ],
  "oxd_config" : {
    "host" : "localhost",
    "port" : 8069,
    "authz_redirect_uri" : "https://dc.gu.org/casa",
    "post_logout_uri" : "https://dc.gu.org/casa/bye.zul",
    "frontchannel_logout_uri" : "https://dc.gu.org/casa/autologout",
    "use_https_extension" : false,
    "client" : {
      "oxdId" : "3aeff426-1b51-4eab-bdae-62daffebf72b",
      "clientName" : "gluu-casa_1549036621"
    }
  }
}

After the upgrade (assuming oxd 4.0 was installed locally), it will become:

{
  "enable_pass_reset" : true,
  "use_branding" : false,
  "log_level" : "TRACE",
  "min_creds_2FA" : 1,
  "ldap_settings" : {
    "salt" : "/etc/gluu/conf/salt",
    "ox-ldap_location" : "/etc/gluu/conf/ox-ldap.properties"
  },
  "policy_2fa" : [ "CUSTOM" ],
  "trusted_dev_settings" : {
    "location_exp_days" : 15,
    "device_exp_days" : 30
  },
  "acr_plugin_mapping" : {
    "inwebo" : "inwebo-plugin",
    "super_gluu" : null,
    "u2f" : null
  },
  "oxd_config" : {
    "host" : "localhost",
    "port" : 8443,
    "authz_redirect_uri" : "https://dc.gu.org/casa",
    "post_logout_uri" : "https://dc.gu.org/casa/bye.zul",
    "frontchannel_logout_uri" : "https://dc.gu.org/casa/autologout"
  }
}

Last steps

Start casa service

Restart apache

Remove /tmp/casa

Addendum

  • authorizationRequestCustomAllowedParameters (oxauth json configuration) should be preserved in the upgrade, not harcoded
  • If account linking plugin was present in the 3.1.x, preserve for passport_social and passport_saml scripts the config property named authz_req_param_provider (if existing)
Clone this wiki locally