This pack provides integration with the FreeIPA API (https://www.freeipa.org/) Actions within this pack mirror one-for-one the "Commands" in the API (https://github.com/freeipa/freeipa/blob/master/API.txt). Data types and payloads also mirror one-for-one.
- Currently this pack is in incubation, so installation must be performed from the github page:
st2 pack install freeipa
- Execute an action (example: add a new host)
st2 run freeipa.host_add server=ipaserver.domain.tld user=administrator password=xxx
---
connections:
<credential-name-1>:
server: <hostname or ip of the IPA server>
user: <[email protected] (preferred) or domain\username>
password: <password for username>
<credential-name-2>:
server: <hostname or ip of the IPA server>
user: <[email protected] (preferred) or domain\username>
password: <password for username>
<connection-name-3>:
... # note: multiple connections can be specified!
---
connections:
# note: if no 'connection' parameter is specified, then the 'default' connection
# from the pack config will be used
default:
user: "userexample"
password: "passwordexample"
server: "serverexample"
test:
user: ipaadminuser
password: super secret
server: same thing as hostname
Note : All actions allow you to specify a set of credentials as inputs to the action instead of requiring a configuration. See the Actions section for more information.
Actions in this pack are auto-generated based on an API specfication file located in
etc/spec/API-release-*.txt
. The specification file is the API.txt
file in the
freeipa git repository. We then use that API.txt
file to auto-generate all of our actions using the script etc/generate_actions.py
.
Each command
in the API.txt generates a new action YAML file.
FreeIPA commands are parsed and all args
and options
are added in as action parameters
using their native StackStorm data types.
Actions created mirror the FreeIPA API, so passing in arguments and options
st2 run freeipa.host_add fqdn='hostname.domain.tld' all=true
st2 run freeipa.host_del fqdn='hostname.domain.tld' all=true
st2 run freeipa.hostgroup_add_member cn='nameofhostgroup' all=true host=['hostname.domain.tld']
The following example demonstrates running the freeipa.host_add
action using action input parameters.
$ st2 run freeipa.host_add fqdn='ipahostname.domain.tld all=true
..
id: 59722f939900aa7b61ca9983
status: succeeded
parameters:
fqdn: ipahostname.domain.tld
all: True
result:
exit_code: 0
result:
error:
code: 4002
data: {}
message: host with name "ipahostname.domain.tld" already exists
name: DuplicateEntry
id: 0
principal: [email protected]
result: null
version: 4.4.0
stderr: ''
stdout: ''
This pack is designed to store commonly used connection information in the pack's
config file located in /opt/stackstorm/config/freeipa.yaml
. The connection
info is specified in the config once, and then referenced by name within an
action and/or workflow.
Using the action from the basic example, we can enter this connection information in our config:
$ cat /opt/stackstorm/configs/freeipa.yaml
---
connections:
prod:
server: freeipa.domain.tld
user: administrator
password: xxx
Now we can reference this connection (by name) when executing our action:
$ st2 run freeipa.login connection=prod
This pays off big time when running multiple commands in sequence.
To avoid repeated typing of the connection
parameter this pack also supports
the concept of a default
connection. Simply specify a connection in the pack
config with the name default
and this connection will be used for all commands.
$ cat /opt/stackstorm/configs/freeipa.yaml
---
connections:
default:
server: freeipa.domain.tld
user: administrator
password: xxx
Now we can omit the connection
option when running our actions and the default
connection will be used:
$ st2 run freeipa.login
By default this pack performs a login operation in every action if the session
parameter is not passed in. To avoid these repetitive logins under the hood
we can perform the login operation and then re-use the login session cookie
in all subsequent actions
There are 2 ways you can use this feature as explained above:
- Config
$ st2 run freeipa.login connection=prod
....
id: 598c977da2fb38cf298a28f9
status: succeeded
parameters:
connection: abc
result:
exit_code: 0
result: MagBearerToken=abcdef
stderr: 'st2.actions.python.login: INFO Successfully logged in as administrator
'
stdout: ''
- Basic
$ st2 run freeipa.login server=ipaserver.domain.tld user=administrator password=xxx
....
id: 598c977da2fb38cf298a28f9
status: succeeded
parameters:
connection: abc
result:
exit_code: 0
result: MagBearerToken=abcdef
stderr: 'st2.actions.python.login: INFO Successfully logged in as administrator
'
stdout: ''
Both options return a string for the cached session cookie that is then passed into the next actions the user invokes in the "session" parameter for example:
st2 run freeipa.host_add session='MagBearerToken=abcdef' args=ipahostname.domain.tld params=['all':True,'force':True]'
...
id: 598dcac0a2fb38cf298a2983
status: succeeded
parameters:
args:
- ipahostname.domain.tld
params: {}
server: ipahostname.domain.tld
session: MagBearerToken=abcdef
result:
exit_code: 0
result:
id: 0
principal: [email protected]
result: null
version: 4.5.0
stderr: ''
stdout: ''
The session string is passed into "cookies" while posting the request, thus, allowing for Single Sign-On(SSO) rather than having to pass credentials for every action.
When logging in to a system and invoking commands you will need to authenticate to login to the host, and maybe need to pass in a different set of credentials to the cmdlet. When logging in to the remote system there are two ways to pass in authentication credentials to the action.
- user/password parameters passed directly to the action
- connection parameter passed to the action
- session cookie string from login action
In this case the user/password are specified where the action is invoked, thus allowing you to pass in credentials on the commandline for easy testing.
st2 run freeipa.host_add args='hostname' server='ipa.domain.tld' user='[email protected]' password='Password1'
In this case the name of the connection to used is passed in where the action
is invoked, and the actual credentials themselves are stored in the pack's
configuration file /opt/stackstorm/configs/freeipa.yaml
.
Let's say we had a configuration file with the contents:
---
connections:
abc:
user: "userexample"
password: "passwordexample"
server: "serverexample"
test:
user: ipaadminuser
password: super secret
server: same thing as hostname
We could invoke the login action using the abc
credentials to login to hostname
like so:
st2 run freeipa.login connection=abc
..
id: 598dcaaaa2fb38cf298a297a
status: succeeded
parameters:
connection: abc
result:
exit_code: 0
result: MagBearerToken=12345
stderr: 'st2.actions.python.login: INFO Successfully logged in as admin
'
stdout: ''
Similarly if we wanted to invoke the same action using the test
credentials:
st2 run freeipa.login connection=test
..
id: 598dcaaaa2fb38cf298a297a
status: succeeded
parameters:
connection: abc
result:
exit_code: 0
result: MagBearerToken=12345
stderr: 'st2.actions.python.login: INFO Successfully logged in as admin
'
stdout: ''
The result session string is MagBearerToken='12345'
which is then passes into any action for a single sign on.
st2 run freeipa.host_add session='MagBearerToken=12345' args=ipahostname.domain.tld params=['all':True,'force':True]'
...
id: 598dcac0a2fb38cf298a2983
status: succeeded
parameters:
args:
- ipahostname.domain.tld
params: {}
server: ipahostname.domain.tld
session: MagBearerToken=12345
result:
exit_code: 0
result:
id: 0
principal: [email protected]
result: null
version: 4.5.0
stderr: ''
stdout: ''
In this case the session cookie that is returned by the freeipa.login action, invoked by either Basic Usage or Config Usage, is passed in where the action is invoked.
st2 run freeipa.login connection=abc
....
id: 598c977da2fb38cf298a28f9
status: succeeded
parameters:
connection: abc
result:
exit_code: 0
result: MagBearerToken=abcdef
stderr: 'st2.actions.python.login: INFO Successfully logged in as administrator
'
stdout: ''
The result session string is MagBearerToken='abcdef'
which is then passes into any action for a single sign on.
st2 run freeipa.host_add session='MagBearerToken=abcdef' args=ipahostname.domain.tld params=['all':True,'force':True]'
...
id: 598dcac0a2fb38cf298a2983
status: succeeded
parameters:
args:
- ipahostname.domain.tld
params: {}
server: ipahostname.domain.tld
session: MagBearerToken=abcdef
result:
exit_code: 0
result:
id: 0
principal: [email protected]
result: null
version: 4.5.0
stderr: ''
stdout: ''