example.toml

#
# Example TOML configuration file for use with the authentication service.
#
# When running the authentication service via systemd or `npm start`, create a
# file named config.toml in this directory, using this file as an example. Note
# that config.toml will only be processed if a .env file is not present.
#
# See https://www.perforce.com/manuals/helix-auth-svc/ for documentation on the
# available settings in the authentication service.
#
# The syntax for TOML is defined here: https://toml.io/
#
# Note that the names of the settings in a TOML file are typically lowercased
# rather than uppercased, but either will work. The nested property names in
# tables like logging and auth_providers should also be in lowercase with
# underscores (_) separating the words in the name.
#

# 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

# An array of tables containing the configuration for multiple identity
# providers. See the documentation for examples and all of the available
# property names. Note that an array of tables of indicated by the double
# brackets around the table name. 
#
# [[auth_providers]]
# issuer_uri = 'https://oidc.example.com'
# client_id = 'client-id'
# client_secret = 'client-secret'
#
# [[auth_providers]]
# sp_entity_id = 'urn:example:sp'
# want_assertion_signed = false
# metadata_url = 'https://saml.example.com'

# 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

# Tables that define SAML service providers that will be connecting to the
# authentication service. Note that the SAML entity identifiers should be
# wrapped in single-quotes (') to avoid interpretation by the TOML parser.
#
# [idp_config.'urn:swarm-example:sp']
# acs_url = 'https://swarm.example.com/api/v10/session'
#
# [idp_config.'http://hth.example.com/account/saml/hth/metadata']
# acs_url = 'https://hth.example.com/account/saml/hth/consume'
#
# [idp_config.'urn:swarm-201?.*:sp']
# acs_url = 'https://swarm.example.com/login'
#
# [idp_config.'urn:swarm-group:sp']
# acs_urls = [
#   'http://swarm.example.com/chicago/api/v10/session',
#   'http://swarm.example.com/tokyo/api/v10/session'
# ]
#
# [idp_config.'urn:swarm-cluster:sp']
# acs_url_re = 'https://swarm\.example\.com/[^/]+/api/v10/session'

# 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'

# Table defining the logging configuration. Use "logging = none" to disable logging.
#
# Changing this setting may require restarting the service.
#
# [logging]
# level = 'info'
# transport = 'file'
# [logging.file]
# filename = 'auth-svc.log'
# maxsize = 1048576
# maxfiles = 4
#
# Logging configuration specific to the user provisioning feature must be nested
# within a table named 'scim' so that it may be configured appropriately.
#
# [logging.scim]
# level = 'info'
# transport = 'file'
# format = 'json'
# [logging.scim.file]
# filename = 'provisioning.log'
# maxsize = 1048576
# maxfiles = 4

# 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

# Table that defines the configuration for use with Redis Sentinel. See
# sentinel.config.cjs for an example. Available options are documented at
# https://github.com/luin/ioredis (note that the original names are in
# "camelCase" while here they are camel_case instead, either will work).
#
# Changing this setting may require restarting the service.
#
# [sentinel_config]
# name = 'mymaster'
# sentinel_password = 'keyboard cat'
# sentinels = [
#   { host = '192.168.56.31', port = 26379 },
#   { host = '192.168.56.32', port = 26379 },
#   { host = '192.168.56.33', port = 26379 }
# ]
#
# [sentinel_config.tls]
# cert = 'containers/redis/client.crt'
# key = 'containers/redis/client.key'
# ca = ['containers/redis/ca.crt']
# reject_unauthorized = false
#
# [sentinel_config.sentinel_tls]
# cert = 'containers/redis/client.crt'
# key = 'containers/redis/client.key'
# ca = ['containers/redis/ca.crt']
# reject_unauthorized = false

# 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

#
# User provisioning configuration that supports multiple cloud service providers
# with one or more Helix Core servers. See the documentation for details on the
# configuration and usage.
#

# [provisioning]
# [[provisioning.providers]]
# bearer_token_file = "feline-token.txt"
# domain = "feline"

# [[provisioning.providers]]
# bearer_token_file = "canine-token.txt"
# domain = "canine"

# [[provisioning.servers]]
# p4port = "ssl:chicago:1666"
# p4user = "super"
# p4passwd = "2E7092CC2CA6BCAC74EB364BF4C4AD99"
# domains = [ "feline", "canine" ]
# leader = [ "canine" ]
# p4tickets = ".p4tickets"
# p4trust = ".p4trust"

# [[provisioning.servers]]
# p4port = "ssl:tokyo:1666"
# p4user = "super"
# p4passwd = "C8478F3F32B62A84731ADDB5A2443E68"
# domains = [ "canine" ]
# p4tickets = ".p4tickets"
# p4trust = ".p4trust"