From 2f062ed105a499c80c2e288ba1add53c9b213e3a Mon Sep 17 00:00:00 2001 From: Matt Oswalt Date: Fri, 3 Feb 2017 16:02:24 -0800 Subject: [PATCH 1/7] Added references to 'st2 login' and 'st2 whoami' commands Signed-off-by: Matt Oswalt --- docs/source/reference/cli.rst | 27 +++++++++++++++++++++++---- 1 file changed, 23 insertions(+), 4 deletions(-) diff --git a/docs/source/reference/cli.rst b/docs/source/reference/cli.rst index abb9ca612..f4ceb0d9a 100644 --- a/docs/source/reference/cli.rst +++ b/docs/source/reference/cli.rst @@ -79,13 +79,32 @@ by passing ``--skip-config`` flag to the CLI as shown below: Authentication and auth token caching ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -If you specify username and password as authentication credentials in the -configuration file, the CLI will try to use those credentials to authenticate and -retrieve an auth token. +The best way to authenticate to StackStorm via the CLI is using the +``st2 login`` command. Similar to ``st2 auth``, you must provide your +username and password: -This auth token is by default cached on the local filesystem (in the ``~/.st2/token`` + st2 login st2admin --password Password1! + +However, instead of just caching the token, this command will also modify the +CLI configuration to include the referenced username. This way, future commands +will know which cached token to use for authentication (since tokens are cached +using the ``token-`` format). + +These auth tokens are by default cached on the local filesystem (in the ``~/.st2/token-`` file) and re-used for subsequent requests to the API service. +You can also use the ``st2 whoami`` command for a quick look at who is the currently +configured user. + +The ``st2 login`` command is a good option if you want an easy way to authenticate +via the CLI without storing your password in plain text. Switching between users is also +as easy as re-running the ``st2 login`` command. Other users' token cache files will remain, +but the CLi configuration will be changed to point to the new username. + +However, should you choose to specify username and password as authentication +credentials in the configuration file, the CLI will try to use those credentials +to authenticate and retrieve an auth token. + If you want to disable auth token caching and want the CLI to retrieve a new auth token on each invocation, you can do that by setting ``cache_token`` option to ``False``: From 0ae05e289c9fb00708d7c6613ed0c55f15932505 Mon Sep 17 00:00:00 2001 From: Matt Oswalt Date: Fri, 3 Feb 2017 16:05:35 -0800 Subject: [PATCH 2/7] Fixed minor typo --- docs/source/reference/cli.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/source/reference/cli.rst b/docs/source/reference/cli.rst index f4ceb0d9a..b6a84c432 100644 --- a/docs/source/reference/cli.rst +++ b/docs/source/reference/cli.rst @@ -99,7 +99,7 @@ configured user. The ``st2 login`` command is a good option if you want an easy way to authenticate via the CLI without storing your password in plain text. Switching between users is also as easy as re-running the ``st2 login`` command. Other users' token cache files will remain, -but the CLi configuration will be changed to point to the new username. +but the CLI configuration will be changed to point to the new username. However, should you choose to specify username and password as authentication credentials in the configuration file, the CLI will try to use those credentials From 26a0e0d50a6b718c9d9a1c3dee17da5ebde6d0af Mon Sep 17 00:00:00 2001 From: Matt Oswalt Date: Fri, 3 Feb 2017 17:35:10 -0800 Subject: [PATCH 3/7] Added minor fix, as well as note about removing password Signed-off-by: Matt Oswalt --- docs/source/reference/cli.rst | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/docs/source/reference/cli.rst b/docs/source/reference/cli.rst index b6a84c432..183279041 100644 --- a/docs/source/reference/cli.rst +++ b/docs/source/reference/cli.rst @@ -83,6 +83,8 @@ The best way to authenticate to StackStorm via the CLI is using the ``st2 login`` command. Similar to ``st2 auth``, you must provide your username and password: +.. sourcecode:: bash + st2 login st2admin --password Password1! However, instead of just caching the token, this command will also modify the @@ -90,6 +92,9 @@ CLI configuration to include the referenced username. This way, future commands will know which cached token to use for authentication (since tokens are cached using the ``token-`` format). +.. NOTE:: + By default, ``st2 login`` will remove any configured password from the configuration. + These auth tokens are by default cached on the local filesystem (in the ``~/.st2/token-`` file) and re-used for subsequent requests to the API service. From a6f461208856a10bf063f39c5051ba33f85ada88 Mon Sep 17 00:00:00 2001 From: Matt Oswalt Date: Mon, 6 Feb 2017 01:45:57 -0800 Subject: [PATCH 4/7] Some rephrasing and minor improvements --- docs/source/reference/cli.rst | 24 +++++++++++++++--------- 1 file changed, 15 insertions(+), 9 deletions(-) diff --git a/docs/source/reference/cli.rst b/docs/source/reference/cli.rst index 183279041..a35a192a4 100644 --- a/docs/source/reference/cli.rst +++ b/docs/source/reference/cli.rst @@ -79,8 +79,8 @@ by passing ``--skip-config`` flag to the CLI as shown below: Authentication and auth token caching ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -The best way to authenticate to StackStorm via the CLI is using the -``st2 login`` command. Similar to ``st2 auth``, you must provide your +If you don't wish to store your password in plain-text as shown in the previous section, +the ``st2 login`` command offers an alternative. Similar to ``st2 auth``, you must provide your username and password: .. sourcecode:: bash @@ -90,10 +90,13 @@ username and password: However, instead of just caching the token, this command will also modify the CLI configuration to include the referenced username. This way, future commands will know which cached token to use for authentication (since tokens are cached -using the ``token-`` format). +using the ``token-`` format), meaning the password can be omitted from +the config file altogether. -.. NOTE:: - By default, ``st2 login`` will remove any configured password from the configuration. +.. WARNING:: + ``st2 login`` will overwrite the "credentials" section of the configuration. + By default, it will overwrite the configured username, and will remove any + configured password. These auth tokens are by default cached on the local filesystem (in the ``~/.st2/token-`` file) and re-used for subsequent requests to the API service. @@ -101,10 +104,13 @@ file) and re-used for subsequent requests to the API service. You can also use the ``st2 whoami`` command for a quick look at who is the currently configured user. -The ``st2 login`` command is a good option if you want an easy way to authenticate -via the CLI without storing your password in plain text. Switching between users is also -as easy as re-running the ``st2 login`` command. Other users' token cache files will remain, -but the CLI configuration will be changed to point to the new username. +The previous section showed how to authenticate to StackStorm by embedding the username and +password in plain text in configuration file. The ``st2 login`` command is good alternative +to this, as you only need to store your username in configuration. + +Switching between users is also as easy as re-running the ``st2 login`` command. +Other users' token cache files will remain, but the CLI configuration will be changed +to point to the new username. However, should you choose to specify username and password as authentication credentials in the configuration file, the CLI will try to use those credentials From cbad4d92454475ec987453aa4bb7875b0bc7750f Mon Sep 17 00:00:00 2001 From: Matt Oswalt Date: Mon, 6 Feb 2017 14:01:34 -0800 Subject: [PATCH 5/7] Removed redundant section; added note about not creating the config file Signed-off-by: Matt Oswalt --- docs/source/reference/cli.rst | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/docs/source/reference/cli.rst b/docs/source/reference/cli.rst index a35a192a4..5e6bc0769 100644 --- a/docs/source/reference/cli.rst +++ b/docs/source/reference/cli.rst @@ -104,17 +104,17 @@ file) and re-used for subsequent requests to the API service. You can also use the ``st2 whoami`` command for a quick look at who is the currently configured user. -The previous section showed how to authenticate to StackStorm by embedding the username and -password in plain text in configuration file. The ``st2 login`` command is good alternative -to this, as you only need to store your username in configuration. - Switching between users is also as easy as re-running the ``st2 login`` command. Other users' token cache files will remain, but the CLI configuration will be changed to point to the new username. -However, should you choose to specify username and password as authentication -credentials in the configuration file, the CLI will try to use those credentials -to authenticate and retrieve an auth token. +.. NOTE:: + As with many other ``st2`` commands, ``st2 login`` will not create the configuration file + for you. Keep this in mind especially if you're leveraging the ``--config-file`` CLI option, + or similar + +Note that you can still use the "old" method of supplying both username and password +in the configuration file if you wish. If you want to disable auth token caching and want the CLI to retrieve a new auth token on each invocation, you can do that by setting ``cache_token`` From 03668e570e6f64b39f06ba916a2c8b138178dfa5 Mon Sep 17 00:00:00 2001 From: Matt Oswalt Date: Mon, 6 Feb 2017 14:13:52 -0800 Subject: [PATCH 6/7] Provide the coveted period Signed-off-by: Matt Oswalt --- docs/source/reference/cli.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/source/reference/cli.rst b/docs/source/reference/cli.rst index 5e6bc0769..feecbf1f9 100644 --- a/docs/source/reference/cli.rst +++ b/docs/source/reference/cli.rst @@ -111,7 +111,7 @@ to point to the new username. .. NOTE:: As with many other ``st2`` commands, ``st2 login`` will not create the configuration file for you. Keep this in mind especially if you're leveraging the ``--config-file`` CLI option, - or similar + or similar. Note that you can still use the "old" method of supplying both username and password in the configuration file if you wish. From 8e3dc4654294f88e6c0ef88f3fd8f7938e9d0375 Mon Sep 17 00:00:00 2001 From: Matt Oswalt Date: Tue, 7 Feb 2017 12:33:27 -0800 Subject: [PATCH 7/7] Some additional minor fixes/improvements Signed-off-by: Matt Oswalt --- docs/source/reference/cli.rst | 9 ++++++--- 1 file changed, 6 insertions(+), 3 deletions(-) diff --git a/docs/source/reference/cli.rst b/docs/source/reference/cli.rst index feecbf1f9..7c324f9b2 100644 --- a/docs/source/reference/cli.rst +++ b/docs/source/reference/cli.rst @@ -87,7 +87,7 @@ username and password: st2 login st2admin --password Password1! -However, instead of just caching the token, this command will also modify the +However, in addition to caching the token, this command will also modify the CLI configuration to include the referenced username. This way, future commands will know which cached token to use for authentication (since tokens are cached using the ``token-`` format), meaning the password can be omitted from @@ -99,7 +99,9 @@ the config file altogether. configured password. These auth tokens are by default cached on the local filesystem (in the ``~/.st2/token-`` -file) and re-used for subsequent requests to the API service. +file) and re-used for subsequent requests to the API service. Note that because the default behavior +is to remove the password from the configuration, you will need to re-login once the generated token +has expired - or make use of the ``--write-password`` flag, which writes the password to the config. You can also use the ``st2 whoami`` command for a quick look at who is the currently configured user. @@ -114,7 +116,8 @@ to point to the new username. or similar. Note that you can still use the "old" method of supplying both username and password -in the configuration file if you wish. +in the configuration file if you wish. If both a username and password are present in the +configuration, then the client will automatically try to authenticate with these credentials. If you want to disable auth token caching and want the CLI to retrieve a new auth token on each invocation, you can do that by setting ``cache_token``