example.env

#
# Example environment configuration for use with the authentication service.
#
# When running the authentication service via systemd or `npm start`, create a
# file named .env in this directory, using this file as an example.
#
# See https://www.perforce.com/manuals/helix-auth-svc/ for documentation on the
# available settings in the authentication service.
#

# If set to 'true' then the routes for the administrative web interface will be
# enabled, and ADMIN_USERNAME and ADMIN_PASSWD_FILE will be used to authenticate
# an administrative user when accessing the web interface.
#
# ADMIN_ENABLED=false

# The user name that must entered in the login form to access the administrative
# web interface. Alternatively, ADMIN_P4_AUTH can be used to authenticate using
# Helix Core Server.
#
# ADMIN_USERNAME='perforce'

# The file that contains password for the admin account named by ADMIN_USERNAME.
# If this is not set, the administrative interface will effectively be disabled.
# As with ADMIN_USERNAME, ADMIN_P4_AUTH can be used as an alternative.
#
# ADMIN_PASSWD_FILE=undefined

# If set to any value, the web interface will authenticate against the Helix
# Core Server instance identified by the P4PORT setting, and the user must have
# a maximum permission of `super`. The ADMIN_USERNAME and ADMIN_PASSWD_FILE
# settings are ignored when ADMIN_P4_AUTH is in effect.
#
# ADMIN_P4_AUTH=undefined

# A JSON value containing the configuration for multiple identity providers.
# See the documentation for examples and all of the available property names.
#
# AUTH_PROVIDERS=undefined

# Path of a file containing JSON that defines the configuration for multiple
# identity providers. The contents are the same as the AUTH_PROVIDERS setting.
# See the documentation for examples and all of the available property names.
#
# AUTH_PROVIDERS_FILE=undefined

# Path of certificate authority file for service to use when verifying client
# certificates, in particular the Helix Server loginhook extension.
#
CA_CERT_FILE='certs/ca.crt'

# HTTP Bearer authentication token for allowing access to the SCIM endpoint.
#
BEARER_TOKEN='keyboard cat'

# Path of a file containing the plain text form of the bearer token. Use this
# instead of BEARER_TOKEN to avoid having the shared secret exposed in the
# configuration.
#
# BEARER_TOKEN_FILE=undefined

# The client identifier as provided by the OIDC identity provider.
#
# OIDC_CLIENT_ID=undefined

# File containing the OIDC client secret value. Use this instead of
# OIDC_CLIENT_SECRET to avoid having the password exposed in the configuration.
#
# OIDC_CLIENT_SECRET_FILE=undefined

# The client secret as provided by the OIDC identity provider.
#
# OIDC_CLIENT_SECRET=undefined

# Public key of the certificate used when initiating an authentication request
# with an OIDC provider that supports private key JWT. If supported by the IdP,
# the public/private key files can be used instead of the "client secret" value.
#
# OIDC_CLIENT_CERT_FILE=undefined

# The private key that corresponds to CERT_FILE.
#
# OIDC_CLIENT_KEY_FILE=undefined

# The OIDC provider issuer URL.
#
# OIDC_ISSUER_URI=undefined

# Algorithm used by the OIDC issuer when signing the id token. The default value
# is RS256.
#
# OIDC_TOKEN_SIGNING_ALGO=RS256

# Specify the OAuth code challenge method to be used with the OpenID identity
# provider. Permitted values include 'S256' and 'plain'. If unset, the value
# will be determined from the issuer metadata.
#
# OIDC_CODE_CHALLENGE_METHOD=undefined

# Set OIDC_SELECT_ACCOUNT to true to have the `prompt` OAuth parameter set to
# include 'select_account', which should cause the OIDC identity provider to
# prompt the user to select an account.
#
# OIDC_SELECT_ACCOUNT=false

# Set OIDC_MAX_AGE to an integer to require the user to authenticate if their
# session is older than OIDC_MAX_AGE seconds. This may or may not be honored by
# your identity provider; testing is encouraged.
#
# OIDC_MAX_AGE=undefined

# URL of IdP Single Sign-On service.
#
# SAML_IDP_SSO_URL=undefined

# URL of IdP Single Log-Out service.
#
# SAML_IDP_SLO_URL=undefined

# The entity identifier (entityID) for the Helix Authentication Service.
#
# SAML_SP_ENTITY_ID='https://has.example.com'

# Public key of the certificate used by HAS when connecting to the IdP, and when
# responding to HTTPS requests from clients.
#
# Renamed from SP_CERT_FILE, which will take effect if CERT_FILE is not defined.
#
CERT_FILE='certs/server.crt'

# The private key that corresponds to CERT_FILE.
#
# Renamed from SP_KEY_FILE, which will take effect if KEY_FILE is not defined.
#
KEY_FILE='certs/server.key'

# The authentication service base URL visible to end users. See the
# documentation for an explanation of how this setting is used to determine the
# port and protocol that the service will use.
#
# If not set, this value will be `localhost` with the scheme set by PROTOCOL and
# the port number set by PORT (or http://localhost:3000 if those are not set).
#
# SVC_BASE_URI=undefined

# Name of the user that the service will setuid after binding to the port given
# in SVC_BASE_URI (either explicitly or implicitly) or in PORT. This allows the
# service to bind to a low port (<1024) and then switch to a less privileged
# user for security purposes. See also SVC_GROUP.
#
# Changing this setting may require restarting the service.
#
# SVC_USER=undefined

# Name of the group that the service will setgid after binding to the port given
# in SVC_BASE_URI (either explicitly or implicitly) or in PORT. See also SVC_USER.
#
# Changing this setting may require restarting the service.
#
# SVC_GROUP=undefined

# Define the IP address upon which the service will listen for requests.
#
# Changing this setting may require restarting the service.
#
# By default, Node.js will bind to the unspecified address of '0.0.0.0' if using
# IPv4 and '::' if using IPv6.
#
# BIND_ADDRESS=undefined

# Alternative to CA_CERT_FILE that specifies a directory containing certificates
# of multiple authorities that authorize client requests.
#
# CA_CERT_PATH=undefined

# Specify a name or pattern to match against the Common Name in the client
# certificate used to acquire the user profile data. Multiple values can be
# provided, separated by commas and wrapped in square brackets ([cn1,cn2,cn3]).
#
# CLIENT_CERT_CN=undefined

# Specify a SHA256 fingerprint of the client certificate used to acquire the
# user profile data. Multiple values can be provided, separated by commas and
# wrapped in square brackets ([fp1,fp2,fp3]).
#
# CLIENT_CERT_FP=undefined

# Name of the HTTP header, if any, that contains the base64 encoded client
# certificate. This will be used to validate the client rather than using the
# TLS certificate associated with the underlying connection.
#
# CLIENT_CERT_HEADER=undefined

# Set to any value to enable debug logging in the service (writes to the
# console). The LOGGING setting overrides this setting.
#
# Changing this setting may require restarting the service.
#
# DEBUG=undefined

# Set to any value to enable detailed logging of reverse proxy details for OIDC
# and SAML login requests. Requires setting either DEBUG or LOGGING to enable
# debug logging.
#
# DEBUG_PROXY=undefined

# Set to any value to enable detailed logging of SCIM requests. Requires setting
# either DEBUG or LOGGING to enable debug logging.
#
# DEBUG_SCIM=undefined

# The default authentication protocol to use. Can be oidc or saml.
#
# Will default to 'saml' if one of the SAML IdP settings are configured, or
# 'oidc' if OIDC_ISSUER_URI is set, otherwise defaults to 'saml'.
#
# DEFAULT_PROTOCOL=undefined

# If set to a non-empty value, will cause the service to require the user to
# authenticate, even if the user is already authenticated. This overrides any
# protocol specific settings, such as OIDC_MAX_AGE and SAML_FORCE_AUTHN, or
# their maxAge and forceAuthn equivalents in AUTH_PROVIDERS.
#
# FORCE_AUTHN=undefined

# If set to any value, will prompt the user in the browser before proceeding to
# the configured identity provider. This is provided as a means to prevent
# phishing attacks in which a user is sent a link to authenticate.
#
# PROMPT_FOR_AUTHORIZATION=undefined

# Public key of the certificate used by HAS when connecting to the SAML IdP, and
# when servicing SAML authentication requests from other applications (such as
# Swarm). If this setting is not defined, then CERT_FILE will be used.
#
# SAML_CERT_FILE=undefined

# The private key that corresponds to SAML_CERT_FILE.
#
# If this setting is not defined, then KEY_FILE will be used.
#
# SAML_KEY_FILE=undefined

# Path of the file containing the public certificate of the identity provider,
# used to validate signatures of incoming SAML responses.
#
# IDP_CERT_FILE=undefined

# Path of the configuration file that defines SAML service providers that will
# be connecting to the authentication service.
#
# IDP_CONFIG_FILE='./routes/saml_idp.conf.cjs'

# This value is added to the login URL as a query parameter named 'instanceId'
# which can be used with a rule-based reverse proxy to achieve session affinity
# without relying on browser cookies.
#
# INSTANCE_ID='none'

# Path of a logging configuration file. Set to "none" to disable logging.
#
# Changing this setting may require restarting the service.
#
# LOGGING=undefined

# How long in seconds to wait for user to successfully authenticate.
#
# LOGIN_TIMEOUT=60

# Passphrase to be used to decrypt the private key given in KEY_FILE
# or PFX_FILE, if the private key is encrypted.
# 
# KEY_PASSPHRASE=undefined

# File containing the passphrase to be used to decrypt the private key given in
# KEY_FILE or PFX_FILE, if the private key is encrypted.
#
# KEY_PASSPHRASE_FILE=undefined

# PKCS#12 formatted file containing the public and private key for the TLS/SSL
# certificate to be used by the service. Supercedes the CERT_FILE and
# KEY_FILE settings, if this setting is provided.
#
# PFX_FILE=undefined

# Override the port number in SVC_BASE_URI if running behind a reverse proxy.
#
# If SVC_BASE_URI is not set, then this value will default to 3000.
#
# PORT=undefined

# Override the protocol in SVC_BASE_URI if running behind a reverse proxy.
#
# If SVC_BASE_URI is not set, then this value will default to 'http'.
#
# PROTOCOL=undefined

# The URL of a redis server which will be used to cache session data.
#
# REDIS_URL=undefined

# Configuration file for use with Redis Sentinel. See sentinel.config.cjs for an
# example. Available options are documented at https://github.com/luin/ioredis
#
# Changing this setting may require restarting the service.
#
# SENTINEL_CONFIG_FILE=undefined

# Time to live for cached requests and user profile data, in seconds. Defaults
# to five minutes (300 seconds). This applies to both the in-memory cache as
# well as the Redis-based cache.
#
# CACHE_TTL=300

# Public key of the certificate used by HAS when connecting to Redis, if the
# REDIS_URL starts with "rediss://" (note the extra 's'). If not set, falls back
# to the CERT_FILE setting, and in turn default for that setting.
# 
# REDIS_CERT_FILE=undefined

# The private key that corresponds to REDIS_CERT_FILE.
#
# REDIS_KEY_FILE=undefined

# The authn context defines the method by which the user will authenticate with
# the IdP.
#
# SAML_AUTHN_CONTEXT='urn:oasis:names:tc:SAML:2.0:ac:classes:PasswordProtectedTransport'

# If set to a non-empty value, do not request a specific authentication context.
# This is known to help when authenticating against Active Directory servers.
#
# SAML_DISABLE_CONTEXT=undefined

# The entity identifier for the identity provider.
#
# SAML_IDP_ENTITY_ID=undefined

# URL of the IdP metadata configuration in XML format.
#
# SAML_IDP_METADATA_URL=undefined

# Path to an XML file containing the identity provider metadata, an alternative
# to specifying a URL in the SAML_IDP_METADATA_URL setting.
#
# SAML_IDP_METADATA_FILE=undefined

# 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).
#
# SAML_NAMEID_FIELD=undefined

# Specify the format of the NameID value, if necessary.
#
# SAML_NAMEID_FORMAT='urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified'

# Service provider audience value for AudienceRestriction assertions.
#
# SAML_SP_AUDIENCE=undefined

# If set to 'false', the SAML client library will not require that the SAML
# assertion is signed. The library will require that either the assertion or the
# response is signed regardless of the settings.
#
# SAML_WANT_ASSERTION_SIGNED=true

# If set to 'false', the SAML client library will not require that the SAML
# response is signed. The library will require that either the assertion or the
# response is signed regardless of the settings.
#
# SAML_WANT_RESPONSE_SIGNED=true

# Like FORCE_AUTHN but affects SAML authentication only.
#
# SAML_FORCE_AUTHN=undefined

# Password used for encrypting the in-memory session data.
#
# SESSION_SECRET='keyboard cat'

# The algorithm used to sign the requests.
#
# SP_KEY_ALGO='sha256'

# Time to live for JSON web tokens created by the service, in seconds.
# Defaults to one hour (3600 seconds).
#
# TOKEN_TTL=3600

# To configure HAS to trust a reverse proxy for terminating SSL connections,
# specify the address of the proxy here.
#
# c.f. https://expressjs.com/en/guide/behind-proxies.html
#
# TRUST_PROXY=undefined

# The 'P4PORT' for connecting to Helix Core Server for SCIM support.
#
# P4PORT=undefined

# The Perforce user with administrative access to manage users and groups.
#
# P4USER=undefined

# The password or ticket for the Perforce user.
#
# P4PASSWD=undefined

# The path to the file containing the Perforce tickets. 
#
# P4TICKETS=undefined

# The path to the Perforce trust file. 
#
# P4TRUST=undefined

# Specify the URI that provides the JSON Web Key Sets used to validate an JSON
# Web Token that was issued by the issuer identified in the OAUTH_ISSUER
# setting.
#
# OAUTH_JWKS_URI=undefined

# The algorithm used to sign and encrypt the JSON Web Token.
#
# OAUTH_ALGORITHM=undefined

# Specify the key identifier of the key used to sign the JSON Web Token. This is
# optional and provides an alternative to trusting the `kid` property in the
# token header.
#
# OAUTH_JWKS_KEYID=undefined

# Specify the path to the public key used to sign the JSON Web Token. This is
# optional and provides an alternative to using OAUTH_JWKS_URI to retrieve the
# signing key from the issuer.
#
# OAUTH_SIGNING_KEY_FILE=undefined

# The "audience" value that will be compared to the `aud` field of the JSON Web
# Token to ensure that the token is valid for this service. This setting is
# optional but recommended.
#
# OAUTH_AUDIENCE=undefined

# The issuer that provided the JSON Web Token to the client, to be compared to
# the `iss` field of the JSON Web Token to ensure that it is from a trusted
# source. This setting is optional but recommended.
#
# OAUTH_ISSUER=undefined

# The "tenant identifier" that can be used to further restrict access to clients
# that have been granted permission to use this service. This setting is
# optional but recommended.
#
# OAUTH_TENANT_ID=undefined

# If set to 'true' then the routes for the REST API related to validation will
# be enabled. In particular, the route /validate/swarm can be used to validate
# Swarm configuration with respect to SAML integration.
#
# VALIDATE_ENABLED=false

# If set to 'true' (the default) then the /status route will be enabled.
#
# STATUS_ENABLED=true

# If set to true, the user provisioning feature will allow the client to rename
# user accounts, which normally can be very detrimental.
#
# ALLOW_USER_RENAME=false

# The Origin value for CORS requests to the REST API. Defaults to the service
# base URI as computed from SVC_BASE_URI, PORT, and PROTOCOL.
#
# CORS_ORIGIN=undefined