Upgrading Helix Authentication Service
The upgrade process for the authentication service is essentially the same as installing for the first time, with the addition of copying the configuration and certificate files.
- 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.
- Consider renaming the directory containing the service code to indicate it is no longer in use.
- Download the updated release of the service to a new file location. Do not attempt to upgrade the service "in-place" because that might cause subtle issues, such as unintentionally loading old versions of dependencies.
- Install HAS by using one of the ways the Installing Helix Authentication Service 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.
- Copy the SSL certificates from the old install location to the new one.
- Copy the configuration settings from the old install location to the new install location. 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.js 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',
SP_CERT_FILE: 'certs/server.crt',
SP_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.js',
// 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',
}
If the upgraded service has already been started, restart it for the configuration changes to take effect.