Document step ssh login and step ssh certificate usage and best practices

[mikemaxey]

These new features are included in our latest release (version 18.1).

New behavior includes:
Running step ssh login without any positional argument (without an email or username) will produce a certificate with your default posix username and email address as principals, as determined by the CA. In other words, it should just "do the right thing".

We've also added a --principal flag to step ssh login if you want to explicitly specify the principal(s) to include in a certificate.
Running step ssh logout without any positional arguments will automatically remove all certificates signed by your SSH CA (and associated keys) from your SSH Agent. Again, it should just "do the right thing".
I think what this means for you is that your UI tool can be simplified to just a "login" and "logout" button that exec step ssh login and step ssh logout, respectively. You could get fancier than that, but I think that would be sufficient.

[maraino]

We haven't changed step ssh certificate when is used like:

step ssh certificate [email protected] jane

That will request the principal jane with the key id [email protected]. So the behavior right now is different than step ssh login, even when a positional argument is used.

We didn't change it because there was already a way to do the desired request using the --principal flags, and we don't want to remove the positional arguments in this request. So it works fine if your username matches your email, and you were able to use --principal if doesn't.

I'm not sure if we want to keep doing that or not.