Upgrading

Upgrading a package installation

1. (Recommended) Back up the configuration files of your existing HAS installation.

2. Rename the old .js file names to have the .cjs extension for the LOGGING and IDP_CONFIG_FILE settings.

3. Invoke the sudo apt-get upgrade command.

Updating the HAS certificate

Periodically, a certificate expires and you might need to update it. The CERT_FILE is an option for specifying the CA certificate that authenticates the client certificate.

Be aware that a package update overwrites the server.crt and server.key files.

Upgrading a non-package installation

The upgrade process for a non-package installation is the similar to installing for the first time, except for:

• the addition of copying the configuration and certificate files

• the necessity to rename the old .js file names to have the .cjs extension for the LOGGING and IDP_CONFIG_FILE settings

1. Stop the currently installed authentication service. This makes the port (the default is 3000) available and prevents any confusion when starting the upgraded application within a process manager.
2. Consider renaming the directory containing the service code to indicate it is no longer in use.
3. Download the updated release of the service to a new file location.
   
4. Install HAS by using one of the ways the Installing explains.
   • If you use the install.sh installation script, it will detect the previously installed prerequisites (for example, Node.js) and not install them again.
   • If you perform a manual installation, be sure to run npm install in the authentication service directory to install the module dependencies.
5. Copy the SSL certificates from the old install location to the new one.
6. Copy the configuration settings from the old install location to the new install location.
7. Rename the old files with the .js extension to have the .cjs extension.
8. Note that the configuration settings are in one of the following:
• the .env file
• if you are using the pm2 process manager, the env section of the ecosystem.config.cjs file, which might look similar to this:
  

env: {
CA_CERT_FILE: 'certs/ca.crt',
NODE_ENV: 'production',
OIDC_CLIENT_ID: 'client_id',
OIDC_CLIENT_SECRET_FILE: 'secrets/oidc_client.txt',
OIDC_ISSUER_URI: 'http://localhost:3001/',
SAML_IDP_SSO_URL: 'http://localhost:7000/saml/sso',
SAML_IDP_SLO_URL: 'http://localhost:7000/saml/slo',
SAML_SP_ISSUER: 'urn:example:sp',
CERT_FILE: 'certs/server.crt',
KEY_FILE: 'certs/server.key',
SVC_BASE_URI: 'https://localhost:3000'
//
// Below are additional optional settings and their default values.
//
// BIND_ADDRESS: '0.0.0.0',
// CA_CERT_PATH: undefined,
// DEBUG: undefined,
// DEFAULT_PROTOCOL: 'saml',
// FORCE_AUTHN: false,
// IDP_CERT_FILE: undefined,
// LOGGING: undefined,
// SAML_IDP_ISSUER: undefined,
// IDP_CONFIG_FILE: './saml_idp.conf.cjs',
// LOGIN_TIMEOUT: 60,
// OIDC_CLIENT_SECRET: undefined,
// SAML_AUTHN_CONTEXT: 'urn:oasis:names:tc:SAML:2.0:ac:classes:PasswordProtectedTransport',
// SAML_IDP_METADATA_URL: undefined,
// SAML_NAMEID_FIELD: undefined,
// SAML_NAMEID_FORMAT: 'urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified',
// SAML_SP_AUDIENCE: undefined,
// SESSION_SECRET: 'keyboard cat',
// SP_KEY_ALGO: 'sha256',
}