BWC includes an auth service that is responsible for handling user authentication and generating
time limited access tokens. When authentication mode is enabled (default), those access tokens are
used to authenticate against the BWC REST APIs.

By default, the BWC configuration file is located at /etc/st2/st2.conf. The available settings
listed below are configured under the auth section in the configuration file. The service can
be configured with different backends (i.e. PAM, LDAP, etc.) to handle the authentication. If
backend is not specified, a htpasswd compatible flat file authentication backend is used. It is
recommended that the service be configured to listen on https (use_ssl option) and be accessible
to the st2 clients.

host - Hostname for the service to listen on.

port - Port for the service to listen on.

use_ssl - Set to True to enable SSL / TLS mode.

cert - Path to the SSL certificate file. Only used when “use_ssl” is set to True.

key - Path to the SSL private key file. Only used when “use_ssl” is set to True.

backend_kwargs - JSON serialized arguments which are passed to the authentication backend in
standalone mode.

token_ttl - The value in seconds when the token expires. By default, the token expires in 24
hours.

api_url - Authentication service also acts as a service catalog. It returns a URL to the API
endpoint on successful authentication. This information is used by clients such as command line
tool and web UI. The setting needs to contain a public base URL to the API endpoint (excluding
the API version). Example: https://myhost.example.com/api/

enable - Authentication is not enabled for the BWC API until this is set to True. If
running BWC on multiple servers, please ensure that this is set to True on all BWC
configuration files.

The service can be configured with different backends (i.e. PAM, LDAP, etc.) to handle the
authentication. If backend is not specified, a htpasswd compatible flat file authentication
backend is used. To use a different backend, select and install the appropriate python package
from the BWC community repos and
configure st2auth accordingly. For example, to install the package for the PAM backend manually,
run the following command on the same server where st2auth is running.

When using packages to install BWC a special Python virtual environment is
created in /opt/stackstorm/st2/ for BWC dependencies and components.

This means that if you want to work and manipulate StackStorm installation
(e.g. use python binary from that virtualenv or install new auth backend)
you need to work with the BWC virtual environment.

You can do so by activating the virtual environment or running python /
pip binary directly from the virtual environment as shown below.

After the backend is installed, configure the backend at /etc/st2/st2.conf, and restart BWC.
Specific configuration details for the backend can be found in the README at the corresponding
repo. The following is a sample auth section in the config file for the PAM backend:

The LDAP backend authenticates the user against an LDAP server. The following is a list of
configuration options for the backend:

option

required

default

description

bind_dn

yes

DN of the service account to bind with the LDAP server

bind_password

yes

Password of the service account

base_ou

yes

Base OU to search for user and group entries

group_dns

yes

Which groups user must be member of to be granted access

group_dns_check

no

and

What kind of check to perform when validating user group membership (and / or). When and behavior is used, user
needs to be part of all the specified groups and when or behavior is used, user needs to be part of at least one or more
of the specified groups.

host

yes

Hostname of the LDAP server

port

yes

Port of the LDAP server

use_ssl

no

false

Use LDAPS to connect

use_tls

no

false

Start TLS on LDAP to connect

cacert

no

None

Path to the CA cert used to validate certificate

id_attr

no

uid

Field name of the user ID attribute

scope

no

subtree

Search scope (base, onelevel, or subtree)

network_timeout

no

10.0

Timeout for network operations (in seconds)

chase_referrals

no

false

True if the referrals should be automatically chased within the underlying LDAP C lib

debug

no

false

Enable debug mode. When debug mode is enabled all the calls (including the results) to LDAP server are logged

client_options

no

A dictionary with additional Python LDAP client options which can be passed to set_connection() method

Note

By default and check is performed when validating user group membership against groups
defined in group_dns config option. This means if multiple groups are specified, user
needs to be member of all the specified groups for authentication to succeeed. If you want
to use or behavior instead (user needs to be a member of one or more of the specified
groups), you can achieve that by setting group_dns_check config option to or.

The following is a sample auth section for the LDAP backend in the st2 config file:

The installer sets up st2auth to run as a service. The service is setup to run under
nginx with uwsgi. Alternate configuration with gunicorn or apache is also possible using wsgi.py
under st2auth but we leave as an exercise for the reader.

# If use_ssl is set to True, the following will fail because SSL is required.
curl -X POST http://myhost.example.com/auth/v1/tokens
# The following will fail with 401 unauthorized. Please note that this is executed with "-k" to skip SSL cert verification.
curl -X POST -k https://myhost.example.com/auth/v1/tokens
# The following will succeed and return a valid token. Please note that this is executed with "-k" to skip SSL cert verification.
curl -X POST -k -u yourusername:'yourpassword' https://myhost.example.com/auth/v1/tokens
# The following will verify the SSL cert, succeed, and return a valid token.
curl -X POST --cacert /path/to/cacert.pem -u yourusername:'yourpassword' https://myhost.example.com/auth/v1/tokens

# Include the token as command line argument.st2actionlist-t4d76e023841a4a91a9c66aa4541156fe# Or set the token as an environment variable.exportST2_AUTH_TOKEN=4d76e023841a4a91a9c66aa4541156fest2actionlist

Note that there can be use cases when you want the TTL to be different from default.
You can specify a TTL (in seconds) when you request a token. To get a token that is valid
for 10 minutes, use the following:

# with TTL and passwordst2authyourusername-p'yourpassword'-l600

Note that if the TTL requested is greater than maximum allowed TTL in st2 configuration, you’d get an error.

If you don’t want to retrieve a new token and configure the environment variable
every time you start a new shell session, you can put your BWC
credentials in the CLI configuration file and the CLI will automatically authenticate,
retrieve and cache the auth token for you.

For security purposes the <API_KEY_VALUE> is only shown at create time. BWC itself does not
store this API Key value in its database, only a one-way hash is stored. It is not possible to
retrieve an API Key after creation. If the API Key is lost or not recorded at the time of
creation, delete the API Key and create a new one.

The optional -m attribute allows metadata to be associated with the created key. It is good
practice to assign a meaningful value like the external service which uses this key to authenticate
with BWC.

The CLI for API keys also support get, list, delete, enable and disable commands.

If an API Key is disabled it will disallow access until that API key is enabled again. This is a
good way to temporarily revoke access of an external service to BWC.

API keys can be migrated from one BWC instance to another. This way external services that have already
been configuered with API Keys do not need to be updated with a new set of keys. Follow these steps to migrate -

On old BWC instance run the following command to save API keys into a file. Note that secrets are masked based
on configuration setting. If masking is enabled an admin can on a per call basis disable the masking without having
to make config changes. See Configure secrets masking to see how to disable masking on a system wide basis.

To authenticate against the BWC API, either an authentication token or an API key
(but not both) should be provided in the HTTP request headers. The headers are
named X-Auth-Token and St2-Api-Key respectively.

If for some reason you can’t specify auth token or API key in the headers (e.g.
you are using a third party service to integrate with BWC and this service
doesn’t allow you to specify custom headers), you can provide it as a query
parameter named x-auth-token and st2-api-key respectively.

Keep in mind that using HTTP header is preferred since some of the web servers
and third party services log query parameters which are sent with each request
which could be a security risk.

Below you can find some examples on how to send authentication token and API
key in the headers and as a query parameter using cURL.