Configuring Helix Authentication Service

The authentication service is configured using environment variables. Because there are numerous settings, it is easiest to create a file called .env that contains all of the settings. If you change the .env file while the service is running, the service must be restarted for the changes to take effect.

The choice of process manager affects how these environment variables are defined. For further details, see Starting Helix Authentication ServiceStarting Helix Authentication Service.

The example.env and .env files

We recommend that you use the example.env file as your starting point for configuring the service. The example.env file is in your installation directory. The example.env file is a plain text file that contains:

• NAME=VALUE pairs

• comment lines starting with #

For example:

# this is a comment
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/'

If you use example.env as your starting point, rename it to .env because the service needs that name to operate.

Make sure your .env file is located in the current working directory when the service is started. Typically this is the same directory as the package.json file of the service code.

Recommended: configure-auth-service.sh

We recommend that you use the configure-auth-service.sh script because it is easier than a manual configuration of .env file.

The configuration script is in the bin directory of your installation. For example, if you installed HAS using the package, to get the help for the configuration script, type

/opt/perforce/helix-auth-svc/bin/configure-auth-service.sh -h

and the output will be:

Certificates

The Helix Authentication Service reads its certificate and key files using the paths defined in SP_CERT_FILE and SP_KEY_FILE, respectively. The path for the CA certificate is read from the CA_CERT_FILE environment variable. Providing a CA file is only necessary if the CA is not one of the root authorities whose certificates are already installed on the system. Clients accessing the /requests/status/:id route will require a valid client certificate signed by the certificate authority.

If the certificate files are changed, the service will need to be restarted because the service only reads the files at startup.

Restarting the Service

If you installed by using the packager or the installation script, HAS is already running and its helix-auth is its service name. However, any changes to the HAS environment settings only take effect when the service is restarted.

• If you installed the HAS by using the package or install script, use the systemd system manager to restart the helix-auth service.
• If you are running the service under Windows, see Installing as a Windows service .

OpenID Connect settings variables

Variable Name	Description
OIDC_CLIENT_ID	The client identifier as provided by the OIDC identity provider
OIDC_CLIENT_SECRET	The client secret as provided by the OIDC identity provider
OIDC_CLIENT_SECRET_FILE	Path of the file containing the client secret as provided by the OIDC identity provider. This setting should be preferred over OIDC_CLIENT_SECRET to prevent accidental exposure of the client secret.
OIDC_CODE_CHALLENGE_METHOD	The default behavior is to detect the supported methods in the OIDC issuer data. Therefore, in most cases it is optional to specify the authorization code challenge method, which is either S256 or plain. However, not all identity providers supply this information, in which case this setting becomes necessary.
OIDC_ISSUER_URI	The OIDC provider issuer URL

OpenID Connect has a discovery feature in which the identity provider advertises various properties via a "discovery document". The URI path will be /.well-known/openid-configuration at the IdP base URL, which is described in the OpenID Connect (OIDC) specification. This information makes the process of configuring an OIDC client easier.

The OIDC client identifier and secret are generally provided by the identity provider during the setup and configuration of the application, and this is unique to each identity provider. For guidance with several popular identity providers, see Example Identity Provider configurations.

The OIDC issuer URI value is advertised in the discovery document mentioned above, and will be a property named issuer. Copy this value to the OIDC_ISSUER_URI service setting. Do NOT to use one of the "endpoint" URL values, because those are different from the issuer URI.

SAML settings variables

 

Name	IDP_CERT_FILE
Description	Path of the file containing the public certificate of the identity provider, which is used to validate signatures of incoming SAML responses. Warning For security, we strongly recommend setting IDP_CERT_FILE. Otherwise, an attacker might try to pose as the IdP and forge SAML assertions. Note Setting IDP_CERT_FILE is necessary when: SAML_IDP_SSO_URL is set, but neither SAML_IDP_METADATA_URL or SAML_IDP_METADATA_FILE is set. The metadata provided by the IdP lacks the public certificate of the IdP.
Default	none

 

Name	IDP_CONFIG_FILE
Description	Path of the configuration file that defines SAML service providers that will be connecting to the authentication service.
Default	When the authentication service is acting as a SAML identity provider, it reads some of its settings from a configuration file in the auth service installation. By default, this file is named saml_idp.conf.js and is identified by the IDP_CONFIG_FILE environment variable. It is evaluated using the Node.js require() function.

 

Name	SAML_AUTHN_CONTEXT
Description	The authn context defines the method by which the user will authenticate with the IdP. Normally the default value works on most systems, but it may be necessary to change this value. For example, Azure might want this set to urn:oasis:names:tc:SAML:2.0:ac:classes:Password in certain cases.
Default	urn:oasis:names:tc:SAML:2.0:ac:classes:PasswordProtectedTransport

 

Name	SAML_DISABLE_CONTEXT
Description	If set to true, do not request a specific authentication context from the SAML IdP. Instead, allow Active Directory Federation Services (ADFS) to decide. Some configurations use different contexts depending on how the user is authenticating. For example, accessing the server from outside the corporate network might correspond to a different context than accessing the server from inside the corporate network.
Default	false

 

Name	SAML_IDP_ENTITY_ID
Description	The entity identifier for the identity provider. This is not required, but if provided, then the IdP issuer will be validated for incoming logout requests/responses.
Default	none

 

Name	SAML_IDP_METADATA_FILE
Description	Specifies the path of a local file that contains the identity provider's metadata in XML format. An example of a SAML IdP that uses a file instead of a URL is Google Workspace (G Suite). If you use SAML_IDP_METADATA_FILE, it takes precedence over SAML_IDP_METADATA_URL.
Default	none

 

Name	SAML_IDP_METADATA_URL
Description	URL of the IdP metadata configuration in XML format. Note If you fetch the IdP metadata by the SAML_IDP_METADATA_URL setting, several other settings might be configured automatically by the service. The settings that are configured automatically depends on the information the IdP advertises via the metadata. Possibilities include: SAML_IDP_SSO_URL SAML_IDP_SLO_URL SAML_NAMEID_FORMAT the IdP certificate that would be loaded from the file named in IDP_CERT_FILE In the unlikely scenario that the IdP returns data that needs to be modified, set the correct value in the appropriate environment variable, such as SAML_NAMEID_FORMAT
Default	none

 

Name	SAML_IDP_SLO_URL
Description	URL of IdP Single Log-Out service.
Default	none

 

Name	SAML_NAMEID_FIELD
Description	Name of the property in the user profile to be used if nameID is missing, which is likely to be the case when using another authentication protocol (such as OIDC) with the identity provider (such as Okta).
Default	none Note: Changing the configuration file requires restarting the service because Node caches the file contents in memory.

 

Name	SAML_SP_AUDIENCE
Description	Service provider audience value for AudienceRestriction assertions.
Default	none

 

Name	SAML_SP_ENTITY_ID
Description	The entity identifier (entityID) for the Helix Authentication Service.
Default	https://has.example.com

Other Settings

Name	Description	Default
BIND_ADDRESS	Define the IP address upon which the service will listen for requests. Setting this to 127.0.0.1 (that is, localhost) means that only processes on the same host can connect, while a value of 0.0.0.0 means requests made against any address assigned to the machine will work.	0.0.0.0
DEBUG	Set to any value to enable debug logging in the service (writes to the console).	none
CA_CERT_FILE	Path of certificate authority file for service to use when verifying client certificates.	none
CA_CERT_PATH	Path of directory containing certificate authority files for service to use when verifying client certificates. All files in the named directory will be processed.	none
CLIENT_CERT_CN	By default, HAS accepts any valid client certificate that is signed by the designated certificate authority. If you want additional security, consider using this setting. Specify a name or pattern to match against the Common Name in the client certificate used to acquire the user profile data. The patterns supported are described in the library at https://github.com/isaacs/minimatch, with the asterisk (*) being the most common wildcard. For example: client.example.com *.example.com *TrustedClient*	none
DEFAULT_PROTOCOL	The default authentication protocol to use. Can be oidc or saml.	saml
FORCE_AUTHN	If set to any non-empty value, will cause the service to require the user to authenticate, even if the user is already authenticated. For SAML, this means setting the forceAuthn field set to true, while for OIDC it will set the max_age parameter to 0. This is not supported by all identity providers, especially for OIDC.	none
KEY_PASSPHRASE	Passphrase to decrypt the private key of the PFX_FILE public/private key pair or the private key of SP_KEY_FILE. The passphrase is provided as a string. For example, "3my$2eR*5tJ"	none
KEY_PASSPHRASE_FILE	This alternative to KEY_PASSPHRASE specifies the path to a UTF-8 encoded file that contains the passphrase to decrypt the private key of PFX_FILE or SP_KEY_FILE. If KEY_PASSPHRASE_FILE is provided, KEY_PASSPHRASE is ignored.	none
LOGGING	Path of a logging configuration file. See the Logging section below. Setting this will override the DEBUG setting.	none
LOGIN_TIMEOUT	How long in seconds to wait for user to successfully authenticate before a timeout occurs in the login process.	60
PFX_FILE	Path to a PKCS#12 formatted public/private key pair for TLS/SSL communications. Typically, the filename ends with .pfx and often PFX is used to refer to this file type. If the private key is encrypted, a passphrase must be provided to decrypt it. See KEY_PASSPHRASE and KEY_PASSPHRASE_FILE.	none
SESSION_SECRET	Password used for encrypting the in-memory session data.	keyboard cat
SP_CERT_FILE	The service provider public certificate file, needed with SAML.	none
SP_KEY_ALGO	The algorithm used to sign the requests.	sha256
SP_KEY_FILE	The service provider private key file, typically needed with SAML.	none
SVC_BASE_URI	The authentication service base URL visible to end users. Needs to match the application settings defined in IdP configuration. Note If you use a load balancer in front of HAS, such as Amazon Web Services Elastic Load Balancing (ELB), the load balancer can have a certificate installed and use SSL termination (decryption). Such a process requires a protocol to forward the traffic to a port. Therefore, HAS supports setting the PORT and PROTOCOL configuration variables. If SVC_BASE_URI is defined, it sets the value of PORT and PROTOCOL. For example, https://has.example.com:443explicitly sets PROTOCOL to https and PORT to 443. In this scenario, 443 might also be considered the DNS name of the load balancer. The default value of PORT is 3000, and the default value of PROTOCOL is http. You can explicitly set PROTOCOL to http or https. The PORT value can be implicitly defined because http defaults to 80 and https defaults to 443. Note that the PORT for SVC_BASE_URI is distinct from the syslog port described under Logging. For information about configuring the service to treat the connection to the load balancer and/or proxy as secure, use the TRUST_PROXY setting. For details, see http://expressjs.com/en/guide/behind-proxies.html.	none

Logging

The authentication service will, by default, write only HTTP request logs to the console. With the DEBUG environment variable set to any value, additional logging will be written to the console. For more precise control, the LOGGING environment variable can be used to specify a logging configuration file. The format of the logging configuration file can be either JSON or JavaScript. Name the logging file with an extension of .json for a JSON file, or .js for a JavaScript file.

The top-level properties are listed in the table below.

Name	Description	Default
level	Messages at this log level and above will be written to the named transport; follows syslog levels per RFC5424, section 6.2.1. Levels in order of priority: emerg, alert, crit, error, warning, notice, info, debug	none
transport	console, file, or syslog	none

An example of logging messages to the console, starting explicitly at debug and including emerg:

module.exports = {
    level: 'debug',
    transport: 'console'
}

Logging to a named file can be achieved by setting the transport to file. Additional properties can then be defined within a property named file, as described in the table below.

Name	Description	Default
filename	Path for the log file.	auth-svc.log
maxsize	Size in bytes before rotating the file.	none
maxfiles	Number of rotated files to retain.	none

An example of logging messages to a named file, starting at the level of warning and including emerg, is shown below. This example also demonstrates log rotation by defining a maximum file size and a maximum number of files (maxfiles) to retain.

module.exports = {
    level: 'warning',
    transport: 'file',
    file: {
        filename: '/var/log/auth-svc.log',
        maxsize: 1048576,
        maxfiles: 10
    }
}

Logging to the system logger, syslog, is configured by setting the transport to syslog. Additional properties can then be defined within a property named syslog, as described in the table below. Note that the syslog program name will be helix-auth-svc for messages emitted by the authentication service.

Name	Description	Default
facility	Syslog facility, such as auth, cron, daemon, kern, mail, etc.	local0
path	Path of the syslog unix domain socket. For example, /dev/log	none
host	Host name of the syslog daemon.	none
port	Port number on which the syslog daemon is listening.	none
protocol	Communication protocol, such as tcp4, udp4, unix	none

An example of logging all messages at levels from info up to emerg, to the system log, is shown below. This example demonstrates logging to syslog on Ubuntu 18, in which the default installation uses a unix domain socket that has /dev/log as its name.

module.exports = {
 level: 'info',
transport: 'syslog',
syslog: {
   path: '/dev/log',
   protocol: 'unix'
   }
}

Load configuration changes without restarting HAS

If you want to change the configuration for HAS, choose one of the following methods:

• Edit the configuration file, stop the service instance, then restart it.

• Signal the service process to reload the configuration.

  • One way is to use the Unix command kill -HUP <pid> to send a literal "signal" to the process. (This is similar to how some daemon programs might use SIGHUP as a signal to restart themselves to re-read a configuration file that has been changed.)

  • Another way is to send the USR2 signal to the process, get the process identifier of the service, and invoke the kill command:

    kill -USR2 <pid>

    An example of this command, and the correct process ID, are written to the log at info level when the service starts up.

    When HAS receives the USR2 signal, it reloads all the environment variables except those settings that cannot be changed during runtime:

    BIND_ADDRESS	CA_CERT_FILE
    CA_CERT_PATH	DEBUG
    LOGGING	PROTOCOL
    PORT	REDIS_URL
    SESSION_SECRET	SVC_BASE_URI
    TRUST_PROXY

Next

See Starting Helix Authentication Service.