smtp and password reset env var documentation

[mpeck]

We need to add documentation for the smtp and password reset env vars

[mpeck]

Cog provides two endpoints to facilitate password resets: POST /v1/users/reset-password and PUT /v1/users/reset-password/:id.

POSTing to the first endpoint with a body like { "email_address": "bob@example.com" } creates a password reset and sends an email to the specified user. The email contains a token along with some additional instructions for resetting your password. The user can then hit the second endpoint with the token and their new password to finish the reset.

In order to work Cog needs to be able to send emails. Email is sent via SMTP and is configured with the following env vars:

• COG_SMTP_SERVER
• COG_SMTP_PORT
• COG_SMTP_USERNAME
• COG_SMTP_PASSWORD
• COG_SMTP_SSL (default: false)
• COG_SMTP_RETRIES (default: 1)

Additionally there are a couple other env vars used to configure Cog for password resets:

• COG_EMAIL_FROM - The email address from which Cog will send emails.
• COG_PASSWORD_RESET_BASE_URL - If you want to provide a custom form for password resets you can set this variable. Cog will provide this link with ?token=<token> appended as the query string. Your form should make a PUT request to /v1/users/reset-password/:id using the token as the id and a json body containing the new password, { "password": "5ecrit" }. If this isn't set, Cog will still provide instructions for the user to reset their password via curl or cogctl.

[mpeck]

Docs for review
http://docs.operable.io/v0.14/docs/resetting-passwords
http://docs.operable.io/v0.14/docs/installation#configuring-smtp

[christophermaier]

Kind of weird reviewing docs this way, but we'll give it a shot....

At the very least, all the email-related environment variables must be documented at http://docs.operable.io/docs/cog-environment-variables... that's the definitive list; if it's not there, it may as well not exist.

If a user cannot update themselves via cogctl without admin rights, that seems like something we should fix (whether it's for fixing their password or not). If that is indeed the current behavior, can you file a ticket to fix it?

The "resetting passwords" page is a mix of high-level end-user instruction and low-level API and configuration detail, along with detail for "people making their own web UIs for Cog", which seems a bit odd. I think people hitting this page will be users (or administrators) trying to figure out the concrete steps they need to take to reset their password. Writing the documentation from the point of view of that user would be more clear... detail about specific API endpoints muddies the picture. I'm still not exactly clear what the process looks like after reading it. (Also, it says the email will include instructions on how to reset the password via cogctl, but presumably people are going through this email route because they can't do it via cogctl... it's a little confusing.)

Having the "Configuring SMTP" section on the "Installing Cog" page seems a bit out of place... it's a detail that is too specific for what is basically a "get up and running quickly" page. The fact that it comes after "Install your first bundle" is also awkward from a narrative flow standpoint.

Is there no default value for the SMTP port, i.e. 25?

[mpeck]

@christophermaier

Yeah, don't know what other way to do it though. Maybe when we get the book going we can just do PRs like normal :)

Here are some updated pages:
http://docs.operable.io/v0.14/docs/cog-environment-variables#section--cog_smtp_-variables
http://docs.operable.io/v0.14/docs/cog-environment-variables#section--cog_email_from-
http://docs.operable.io/v0.14/docs/cog-environment-variables#section--cog_password_reset_base_url-

http://docs.operable.io/v0.14/docs/configuring-password-resets

http://docs.operable.io/v0.14/docs/resetting-passwords

http://docs.operable.io/v0.14/docs/using-a-custom-form-for-password-resets

[christophermaier]

http://docs.operable.io/v0.14/docs/cog-environment-variables#section--cog_email_from- - Make "password resets" a hyperlink, and add a "See Also" blurb linking to the COG_SMTP_* variables and the COG_PASSWORD_RESET_BASE_URL (For that matter, we should have reciprocal "See Also" blurbs linking all these things together... no matter how you get into this constellation of variables, you should be able to quickly jump to the other related variables.)

Indicating that the COG_PASSWORD_RESET_BASE_URL config is probably best for advanced users might be nice.

The "Resetting Passwords" page is much improved. I would reword this sentence, however:

But if you have forgotten your password don't worry, when configured, Cog provides a means to generate a password reset.

to something along the lines of

If you have forgotten your password, Cog provides an email-based way to reset your password (ask your Cog Administrator to enable this if they haven't already)
(and then provide a link to the configuration instructions)

That raises a question: How does the cogctl command to reset via email behave if the server isn't properly configured to enable that?

Including the email output is a nice touch, and makes it clear what's going on. The instructions that follow ("follow the instructions, substituting "newpassword" for your password") seem like they should be part of the email, though.

What does the email look like if they're using Flywheel? Is there a link to click?

After reading through this, I think including curl instructions in the email is probably overkill. If the user has gotten to this point, they will presumably have done so either through a web UI or through cogctl. If they actually did it by hitting the API directly with curl in the first place, then they'll probably know exactly which curl command to run without us telling them. Also, we'll have non-programmers using this functionality; including curl commands is just going to be noise for them at best, and confusing at worst.

Are we really expecting a lot of people to be creating their own Cog password reset UIs? I'm wondering if we even really need this set of instructions.

[mpeck]

@christophermaier updated the links and changed the wording of that sentence. Good suggestion btw, that sentence was bothering me a bit too.

In regards to cogctl resetting passwords. If Cog isn't configured then the command will fail. We should probably add some better error messaging around that, but I don't think that's part of this PR. You can still update password via cogctl users update regardless if password resets are enabled or not.

We can change the text of the email if you think it would be better. I don't disagree that the curl bit could be confusing to some folks. I don't remember exactly why we added it. I remember there was some discussion about it and I think it had something to do with users not necessarily having access to cogctl, but I'm not certain. Regardless, I think that is something for another PR. We may want to discuss allowing users to configure their own email for password resets?

If the user is using Flywheel to reset their password then their is an additional section with a link to the password reset page. We actually use the same process as described in the custom password reset form section.

I don't know if there will be a lot of people creating their own custom reset forms or not. I would lean towards thinking that it probably wouldn't be many, but does it hurt having it in case someone wanted to?

[christophermaier]

@mpeck I agree that changes to email text, error messages, and so on shouldn't be part of this PR. Issues ought to be created, though, to follow up on them (preferably linking back to this discussion for context).

As for whether or not the custom reset UI instructions "hurt" or not... I don't know that it's necessarily a question of "hurt" as a question of cost vs. benefit for maintaining that documentation when I doubt there will be many people ever using it. It just strikes me as very esoteric information; I'd be curious to hear other opinions on it, though.

[mpeck]

@christophermaier that's fair. I just didn't want this PR to be tied to changes in Cog. I'll create an issue to do a UX review of the password reset flow and link back to this discussion. I do think it could use some work. It's pretty rudimentary as it sits right now.

Regarding the custom reset form instructions. I'm not married to them. I included them because I thought it would be useful if just for a few. They are only referenced in one other spot, the configuring password resets page. What if I remove the reference there and just leave the page hidden for now? We can get input on whether or not it should be included and make it visible later. If the other pages are good to go, I don't see why that page should hold them back. Thoughts?

[christophermaier]

@mpeck that sounds good 👍