Configuring the Service

By default, the StackStorm configuration file is located at /etc/st2/st2.conf. The 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 authentication. If a backend is not specified, an htpasswd-compatible flat file authentication backend is used.

We recommend that the service be configured to listen on https (use_ssl option) and be accessible to 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.

• mode Mode to use (proxy or standalone). Default is standalone.

• backend Authentication backend to use in standalone mode (i.e. pam, flat_file). Please review the supported list of authentication backends below.

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

• token_ttl The token lifetime, in seconds. By default, the token expires in 24 hours.

• api_url The 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 the CLI 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 StackStorm API until this is set to True. If running StackStorm on multiple servers, please ensure that this is set to True on all StackStorm systems.

• debug Enable debug mode.

If you make any changes, you must restart StackStorm:

$ sudo st2ctl restart

Standalone Auth Mode

Standalone mode is the default auth mode where external users authenticate directly with StackStorm. Under the hood the st2auth service delegates to the configured backend to perform the authentication. When the backend service properly authenticates the user, an auth token is returned. This token can then be used to make further API calls.

Proxy Auth Mode

Proxy mode can be used when there is a service (proxy) that sits in front of StackStorm that performs user authentication (ex: load balancer, apache, nginx, etc). When the frontend service authenticates a user, it will need to make an API call POST https://<stackstorm>/auth/v1/tokens to the st2auth service in order to obtain an auth token. In this request the following CGI environment variables need to be set:

• REMOTE_ADDR - Source of the request (hostname/ip of the user who authenticated against the proxy).

• REMOTE_USER - User identity (username) of proxy authenticated user.

The request will return an auth token that authenticated user can use to make further API calls.

When using a reverse proxy such as Apache in front of st2auth, those two CGI environment variables are usually set automatically by a proxy upon successful authentication.

Auth Backends

The service can be configured with different backends (i.e. PAM, LDAP, etc.) to handle the authentication. If a backend is not specified, an htpasswd-compatible flat file authentication backend is used. To use a different backend, select and install the appropriate python package from the StackStorm 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:

$ sudo /opt/stackstorm/st2/bin/pip install git+https://github.com/StackStorm/st2-auth-backend-pam.git@master#egg=st2_auth_backend_pam

# by activating the virtual environment

$ source /opt/stackstorm/st2/bin/activate

$ sudo pip install foo

# or by directly invoking binaries from the virtual environment
$ /opt/stackstorm/st2/bin/python

$ sudo /opt/stackstorm/st2/bin/pip install foo

After the backend is installed, configure the backend at /etc/st2/st2.conf, and restart StackStorm. 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:

[auth]
mode = standalone
backend = pam
enable = True
use_ssl = True
cert = /path/to/ssl/cert/file
key = /path/to/ssl/key/file
logging = /etc/st2/logging.auth.conf
api_url = https://myhost.examples.com/api/
debug = False

The following is a list of auth backends for the community edition to help get things started:

• PAM

• Flat File

• OpenStack Keystone

LDAP

LDAP is now included by default with StackStorm core and needs to be enabled and configured via st2.conf. The source code for the LDAP auth backend can be accessed here: https://github.com/stackstorm/st2-auth-ldap

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

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

[auth]
mode = standalone
backend = ldap
backend_kwargs = {"bind_dn": "CN=st2admin,ou=users,dc=example,dc=com", "bind_password": "foobar123", "base_ou": "dc=example,dc=com", "group_dns": ["CN=st2users,ou=groups,dc=example,dc=com", "CN=st2developers,ou=groups,dc=example,dc=com"], "host": "identity.example.com", "port": 636, "use_ssl": true, "cacert": "/path/to/cacert.pem"}
enable = True
use_ssl = True
cert = /path/to/mycert.crt
key = /path/to/mycert.key
logging = /etc/st2/logging.auth.conf
api_url = http://myhost.example.com:9101/
debug = False

If your LDAP server uses a different name for the user ID attribute, you can simply specify the id_attr configuration option.

[auth]
mode = standalone
backend = ldap
backend_kwargs = {"bind_dn": "CN=st2admin,ou=users,dc=example,dc=com", "bind_password": "foobar123", "base_ou": "dc=example,dc=com", "id_attr": "username", "group_dns": ["CN=st2users,ou=groups,dc=example,dc=com", "CN=st2developers,ou=groups,dc=example,dc=com"], "host": "identity.example.com", "port": 636, "use_ssl": true, "cacert": "/path/to/cacert.pem"}
enable = True
use_ssl = True
cert = /path/to/mycert.crt
key = /path/to/mycert.key
logging = /etc/st2/logging.auth.conf
api_url = http://myhost.example.com:9101/
debug = False

This will need customization for your environment - e.g. the LDAP server to bind to, and the cert and key paths if you are using SSL.

Running the Service

st2auth is set up to run as a service. It runs under gunicorn.

The service can be started with one of the options below:

# Individually
sudo service st2auth start

# Individually via st2ctl
sudo st2ctl start st2auth

# Collectively with other st2 components
sudo st2ctl start

# Using the launcher for debugging purposes
sudo /usr/bin/st2auth --config-file /etc/st2/st2.conf

Testing

Run the following curl commands to test:

# 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

Usage

Once authentication is enabled, API calls require a token to be passed via the headers. CLI calls require the token to be included as a CLI argument or as an environment variable. Using st2 login will simplify logging in, getting a token, and automatically adding it to the environment.

To use the CLI, use the st2 login command. If you do not provide a password, it will prompt for the password:

# without password
st2 login yourusename
Password:

# with password
st2 login yourusername -p 'yourpassword'

# write password to config file
st2 login -w yourusername -p 'yourpassword'

If you need to acquire a token - for example to use with an API call, use the st2 auth command. If a password is not provided, it will prompt for the password. If successful, a token is returned in the response:

# with password
st2 auth yourusername -p 'yourpassword'

# without password
st2 auth yourusename
Password:

The following is a sample API call via curl using that token:

$ curl -H "X-Auth-Token: 4d76e023841a4a91a9c66aa4541156fe" https://myhost.example.com/api/v1/actions

This is the CLI equivalent:

# Include the token as command line argument.
st2 action list -t 4d76e023841a4a91a9c66aa4541156fe

# Or set the token as an environment variable.
export ST2_AUTH_TOKEN=4d76e023841a4a91a9c66aa4541156fe
st2 action list

There may be use-cases where you want a token with a different TTL from the default. You can specify a TTL (in seconds) when you request a token. For example, to request a token that is valid for 10 minutes:

# with TTL and password
st2 auth yourusername -p 'yourpassword' -l 600

Note that if the TTL requested is greater than the configured maximum allowed TTL, you will 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 StackStorm credentials in the CLI configuration file. Then the CLI will automatically authenticate, retrieve and cache the auth token for you.

For information on how to do that, see the CLI configuration page.

API Keys

StackStorm also supports API keys. These differ from tokens in that they do not expire. This makes them suited for integrations with other applications, e.g. through webhooks.

All API key management is currently available via the StackStorm CLI or API.

To create an API key:

st2 apikey create -k -m '{"used_by": "my integration"}'
<API_KEY_VALUE>

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 StackStorm.

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 StackStorm.

$ curl -H "St2-Api-Key: <API-KEY-VALUE>" https://myhost.example.com/api/v1/actions
$ curl https://myhost.example.com/api/v1/actions?st2-api-key=<API-KEY-VALUE>