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 example, the pm2 process manager allows environment variables to be defined in the ecosystem.config.js file. For further details, see Starting Helix Authentication Service.

If you use a .env file, make sure it 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.

Note

Be aware that the configuration might require some assistance from Perforce Support.

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 the ecosystem.config.js file. The prerequisite for using configure-auth-service.sh is an installation of both pm2 and Node.js. If you used the package installation or the install.sh script described at Four ways to install HAS, you already have an installation of both.

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:

Example of ecosystem.config.js

Certificates

Warning

We strongly recommend that you use proper certificates and a trusted certificate authority (CA). A self-signed certificate might be rejected at any time.

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

Changes to the environment settings take effect when the service is restarted.

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_ISSUER_URI The OIDC provider issuer URL
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.

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, used to validate signatures of incoming SAML responses. This is not required, but it does serve as an additional layer of security.
Default none
Name SAML_IDP_SSO_URL
Description URL of IdP Single Sign-On service.
Default none

 

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

none

 

Name SAML_SP_ENTITY_ID
Description

The entity identifier (entityID) for the Helix Authentication Service.

Default https://has.example.com

 

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 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_IDP_SLO_URL
Description URL of IdP Single Log-Out service.
Default

none

 

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

none

 

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_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_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. Which settings depends on the information the IdP advertises via the metadata. Possibilities include SAML_IDP_SSO_URL, SAML_IDP_SLO_URL, SAML_NAMEID_FORMAT, and 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

SAML identity providers advertise some of this information through their metadata URL. The URL is different for each provider, unlike OIDC. See Example Identity Provider configurations.

When configuring the service as a "service provider" within a SAML identity provider, provide an entityID that is unique within your set of registered applications. By default, the service uses the value https://has.example.com, which can be changed by setting the SAML_SP_ENTITY_ID environment variable. Anywhere that https://has.example.com appears in this documentation, replace it with the value you defined in the identity provider.

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
LOGGING Path of a logging configuration file. See the Logging section below. Setting this will override the DEBUG setting. none
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
SESSION_SECRET Password used for encrypting the in-memory session data. keyboard cat
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:443 explicitly 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
SP_CERT_FILE The service provider public certificate file, needed with SAML. none
SP_KEY_FILE The service provider private key file, typically needed with SAML. none
SP_KEY_ALGO The algorithm used to sign the requests. sha256
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
LOGIN_TIMEOUT How long in seconds to wait for user to successfully authenticate. 60

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 (like the ecosystem.config.js file, use an extension of .json for a JSON file, and .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 named /dev/log.

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

Next

See Starting Helix Authentication Service.