Something more complex? Read on to learn about EWC authentication.
EWC includes an auth service that is responsible for handling user authentication and generating time-limited access tokens. When authentication is enabled (the default), those access tokens are used to authenticate against the EWC REST APIs.
By default, the EWC 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.
enable Authentication is not enabled for the EWC API until this is set to True. If running EWC on multiple servers, please ensure that this is set to True on all EWC systems.
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 EWC community repos and configure st2auth accordingly.
EWC uses a Python virtual environment in /opt/stackstorm/st2/ for EWC dependencies and components.
This means that if you want to work with the EWC installation (e.g. use the python binary from that virtualenv or to install a new auth backend), you need to use the EWC virtual environment.
EWC-developed auth backends such as LDAP are only available in Extreme Workflow Composer. For more information on Extreme Workflow Composer, please visit https://stackstorm.com/features/#ewc The auth backends included with Extreme Workflow Composer are developed, tested, maintained, and supported by Extreme Networks.
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 EWC credentials in the CLI configuration file. Then the CLI will automatically authenticate, retrieve and cache the auth token for you.
EWC 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 EWC CLI or API.
For security purposes the <API_KEY_VALUE> is only shown at create time. EWC 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 EWC.
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 EWC.
On the old EWC 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-API 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 EWC 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 an auth token or API key in the headers (e.g. you are using a third party service to integrate with EWC 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.