stackstorm 21. stackstorm的校验方式

1 校验

如果仅仅需要默认的密码，使用用户名st2admin,密码 Ch@ngeMe
需要改变密码吗? 运行: sudo htpasswd /etc/st2/htpasswd st2admin
更复杂的情况则需要阅读stackstorm的校验。

StackStorm包含了一个校验服务，该服务用于处理用户校验并且会生成有过期时间的
token。当校验开启时(默认开启)，这些tokens会在发送st2 rest apis请求时被校验。

逻辑流程图如下:
用户: 发送校验凭证(例如: 用户名，密码)    --->    st2auth服务: 执行校验    ---> 校验后端
st2auth服务: 返回用户可访问范围的token    --->    用户

2 配置服务

默认情况下，st2配置文件是在/etc/st2/st2.conf。配置文件中auth部分的就是配置访问权限的内容。
该服务可以配置不同的后端(例如: PAM, LDAP等等)来处理校验。如果校验后端没有被指定，
一个兼容htpasswd的平面文件校验后端就会被时用。
我们推荐服务监听https(use_ssl选项)并且可以被st2 clients访问。
host: 服务监听的主机名称
port: 服务监听的端口
use_ssl: 设置为True会开启SSL/TLS模式
cert: ssl凭证文件。只有当use_ssl被设置为True的时候使用
key: SSL私有key文件的路径。只有当use_ssl被设置为True的时候使用
mode: 使用proxy模式或者standalone(单机)模式。默认是standalone。
backend: 在standalone模式中使用的校验后端(例如pam, flat_file)。请查看
支持的校验后端。
backend_kwargs: JSON序列化参数，可以在standalone模式中被传递给校验后端。
token_ttl: token的生命周期，单位是秒。默认情况下，token会在24小时后过期。
api_url: 校验服务也充当服务访问目录的角色。当校验成功的时候，它返回一个url到API端点。
    这些信息会被clients使用，例如:CLI和web UI。这个设置需要包含一个public的base URL
    来到API端点(排除API版本)。例如: https://myhost.example.com/api/
enable: stackstorm的api校验不会开启除非被设置为True。如果在多个服务器上运行StackStorm，请
    确保这个在所有st2系统上都被设置为True。
debug: 开启debug模式。

如果你做了任何改动，你需要重启st2。
sudo st2ctl restart

3 单机校验模式

单机模式是默认校验模式，在该模式中外部用户直接和stackstorm校验。
st2auth服务向配置的backend后端执行校验。当后端服务校验用户成功后，
就会返回一个校验token。这个token可以被用于后续的API调用。

4 代理校验模式

代理模式可以用于有一个服务在st2的前方时，该代理去执行用户校验(
例如load balancer, apache, nginx等等)。当前端服务校验了一个用户，
它需要发送一个api调用:
POST https://<stackstorm>/auth/v1/tokens
到st2auth服务来获取一个校验token。在下面的CGI环境中请求中的变量需要设置:
REMOTE_ADDR: 请求源(代理校验用户所在的主机名或ip)
REMOTE_USER: 代理模式校验下的用户身份(用户名)

请求将会返回一个校验token用于校验用户使用后续的API调用。
当使用一个代理例如Apache在st2auth的前面时，这两个CGI环境变量通常可以被代理
自动设置，直到校验成功。

5 校验后端

校验服务可以配置不同的后端(例如PAM, LDAP等等)来处理校验。
如果一个后端没有被指定，一个兼容 htpasswd的平面文件校验后端就会
被时用。为了使用一个不同的后端，需要从st2社区repos中选择和安装正确的python包
并配置st2auth。
例如，为了手动安装用于PAM后端的包，在运行st2auth的相同的服务端运行如下的命令:
$ sudo /opt/stackstorm/st2/bin/pip install git+https://github.com/StackStorm/st2-auth-backend-pam.git@master#egg=st2_auth_backend_pam

当校验后端安装了，在/etc/st2/st2.conf中配置校验后端，并重启st2.
详细的配置细节可以在对应repo的README。下面是一个配置文件中采用PAM作为校验部分的例子:
[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

下面是一个校验后端列表:
pam: https://github.com/StackStorm/st2-auth-backend-pam
flat-file: https://github.com/StackStorm/st2-auth-backend-flat-file
OpenStack Keystone: https://github.com/StackStorm/st2-auth-backend-keystone

6 LDAP(企业版本)

......

7 重启服务

st2auth被设置为以服务的方式运行。它运行在gunicorn。
这个服务被可以通过下面列表中的任意一个启动:
# 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

8 测试

运行下面的curl命令来测试:
# 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

9 用法

一旦st2auth开启了，API调用需要在请求中加入token。命令行调用需要通过参数的形式或者环境变量
中携带token。
为了通过命令行获取一个新的token,运行st2 auth命令。如果密码没有提供，st2 auth将会提示密码。
如果成功，就会在响应中返回一个token。

# with password
st2 auth yourusername -p 'yourpassword'

# without password
st2 auth yourusename
Password:

如果你的密码中含有特殊字符$,他们会被shell解释。将你的密码中包裹一个'。
下面是一个通过curl携带token调用API的简单例子:
$ curl -H "X-Auth-Token: 4d76e023841a4a91a9c66aa4541156fe" https://myhost.example.com/api/v1/actions

这等同于下面的命令:
# 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

可能存在某种场景，你想获取一个非默认TTL的token。你可以在请求token时指定一个TTL(
单位是秒)。例如，请求一个只有10分钟有效时间的token:
# with TTL and password
st2 auth yourusername -p 'yourpassword' -l 600

注意，如果请求的TTL大与配置所允许的最大TTL，你会得到一个错误。

如果你不想在启动一个新的shell会话的时候查询新的token并配置在环境变量中配置，
你可以将你的st2即哦呵言信息放入命令行配置文件中。
然后命令行将会自动校验，查找和缓存你的校验token。

如何像上述这样做，请看如下文章:
https://docs.stackstorm.com/reference/cli.html#cli-configuration

10 API Keys

st2也支持API keys。这个不同于token，因为它们不会过期。
这个使得它们适配用于继承其他应用，例如: webhooks。
所有的API key管理当前可以通过st2命令行或者API来获取。

创建一个API key:
st2 apikey create -k -m '{"used_by": "my integration"}'
<API_KEY_VALUE>

注意:
为了安全起见, <API_KEY_VALUE> 仅仅在创建的时候显示一下。
st2本身不会存储API key的值到数据库中，仅仅会存储单向的hash。
它不可以在创建之后通过查询API key。如果API key丢失了或者在
创建的时候没有被记录下来，删除这个API key并重新创建一个新的。

可选属性-m包含了创建的key的元数据信息。最佳实践时分配一个有意义的
值例如使用这个key的外部服务名称来与st2进行验证。
针对API keys的命令行支持: get, list, delete, enable和disable命令。
如果一个API key被禁用了，将不允许访问它。直到API key被再次开启。
对于临时取消外部服务访问st2是一种好的方式。

11 API Key用法

API key被设计用于API访问。到目前位置，它们不能通过client例如UI和CLI使用。
下面是一个使用API Keys来通过curl进行API调用的样例:
$ 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>

12 API Key迁移

API keys可以从一个st2实例迁移到另一个上。这种方式使得
已经配置了API Keys的外部服务不需要更新一系列keys。遵循如下的步骤进行迁移:
......

13 在API中使用校验Tokens或者API Keys

为了通过st2 api校验，要么提供一个校验token，要么提供一个API key,
它需要被放在HTTP请求的头部中。头部叫做X-Auth-Token， St2-Api-Key。

如果因为某种原因你不能在headers中指定一个校验token或者API key
(例如: 你正在使用一个第三方服务来集成到StackSTorm，而这个服务不允许你指定
定值的headers)，你可以以查询参数x-auth-token和st2-api-key的形式各自提供它们
中的一个。
下面是一些关于如何在headers中发送校验token和API key的例子，查询参数使用了curl:
在请求头部提供它们:
$ curl -H "X-Auth-Token: <auth token value>" https://myhost.example.com/api/v1/actions
$ curl -H "St2-Api-Key: <api key value>" https://myhost.example.com/api/v1/actions

作为一个查询参数提供它们:
$ curl "https://myhost.example.com/api/v1/actions?x-auth-token=<auth token value>"
$ curl "https://myhost.example.com/api/v1/actions?st2-api-key=<api key value>"

参考:
https://docs.stackstorm.com/authentication.html
https://www.jb51.net/article/59468.htm