[SOLVED] Submitting suggested changes to the Docs

[seamus]

I've found what seems to be a glaring error in the 'How-To' Docs on the subject of "Setup SSL VPN Road Warrior" at the following URL:

https://docs.opnsense.org/manual/how-tos/sslvpn_client.html

All is well until the end of Step 0; specifically, the following passage:

"Click Save and you will be redirected to the User page. Now we will activate your newly created seed with Google Authenticator. To do so click in the (i) symbol on the left of OTP seed now you will see a link to the google authenticator image. Click on it and it will open in a new browser window and an image will be displayed. This image can be scanned with you mobile see also: Configure 2FA TOTP & Google Authenticator."

In the first place, the GUI does not do what's described here: 'click the (i) symbol' only hides or reveals the Help tip. THERE IS NO URL revealed.

Second, clicking the Google Authenticator Image does nothing at all. If I scan it in my iPhone, it tells me that there IS NOT a Google Authenticator client available for iPhone!  If this was intended to be Google-centric, or Android-specific, this should have been stated in the beginning (rather than wasting someone's time reading instructions that won't work).

OTP is great stuff, and my hat's off to the project for incorporating it in OPNsense. However, the Docs should reflect reality, not wishful thinking.

~S

P.S. Here's my version info:
OPNsense 18.1.2_2-amd64
FreeBSD 11.1-RELEASE-p6
OpenSSL 1.0.2n 7 Dec 2017

[seamus]

I think I've sorted the intention of the instructions. As it turns out there is a Google Authenticator app for iPhones, and it has a scan feature that made quick work of the graphic/bar code (whatever). And FWIW, there is also a Google Authenticator 'extension' for Chrome, and I imagine you can use this in lieu of a mobile phone (untried).

That said, the Docs are misleading, but a minor amount of word-smithing could fix that easily.

[franco]

I use the "Authenticator" app in iOS, it has nothing to do with Google. There are plenty of other apps for TOTP available on all mobile devices.

The OTP QR code was a new addition to avoid bouncing through Google as well. It has not yet been documented properly. Fabian added this, maybe he will read and update it. :)


Cheers,
Franco

[seamus]

Yes, well I'm sure that's all well and good, but nevertheless confusing for someone new to the project. And as you well know, there are any number of ways to implement a one-time password system... so how could one logically assume that a "non-Google" version would be compatible with OPNsense??

But I couldn't agree more strongly with your statement that this has not yet been documented properly.

And I'll be glad to provide some wording if that would help; it's the least I can do for using OPNsense, and then whining about the documentation. Let me know...

[fabian]

I am using SailOTP for example - I may be able to post screenshots to the docs. I created a ticket here: https://github.com/opnsense/docs/issues/7

[fabian]

Should be fixed with https://github.com/opnsense/docs/pull/8

[seamus]

I can see that the How-To guide has been edited - thank you for that! But it hasn't addressed all of the errors, unless there's been a code change  (I couldn't see where that had happened, but if it has, please disregard the following):

Second, clicking the Google Authenticator Image does nothing at all. <snip>

Here's what the How-To guide says now:

To do so click in the (i) symbol on the left of OTP seed now you will see a link to the google authenticator image. Click on it and it will open in a new browser window and an image will be displayed. This image can be scanned with you mobile

I think what it should say (again, unless there's been a code change) is something along these lines:

To do so click in the (i) symbol on the left of OTP seed now you will see an Aztec code (https://en.wikipedia.org/wiki/Aztec_Code) displayed in this area. Position the Aztec code so that it is fully visible on your computer display, start the Google Authenticator app on your mobile device, select the "Scan" function in the app, point the mobile's camera at the Aztec code and read it. Your Google Authenticator app should now have the information it needs, and begin generating the 6-character OTP codes immediately!

Finally, pardon me if this seems ungrateful or nit-picking (or incorrect). This is how it worked for me, once I got past some of the confusion. It's such an amazing feature really... it seems a shame to sully it with instructions that are misleading.

~S

[fabian]

I can see that the How-To guide has been edited - thank you for that! But it hasn't addressed all of the errors, unless there's been a code change  (I couldn't see where that had happened, but if it has, please disregard the following):

Second, clicking the Google Authenticator Image does nothing at all. <snip>

Which image, and what do you expect - I cannot follow you.

Here's what the How-To guide says now:

To do so click in the (i) symbol on the left of OTP seed now you will see a link to the google authenticator image. Click on it and it will open in a new browser window and an image will be displayed. This image can be scanned with you mobile

This is the behaviour of very old OPNsense boxes - I patched the link out of it so I don't think you are referring to a 17.x or 18.x version.

I think what it should say (again, unless there's been a code change) is something along these lines:

To do so click in the (i) symbol on the left of OTP seed now you will see an Aztec code (https://en.wikipedia.org/wiki/Aztec_Code) displayed in this area. Position the Aztec code so that it is fully visible on your computer display, start the Google Authenticator app on your mobile device, select the "Scan" function in the app, point the mobile's camera at the Aztec code and read it. Your Google Authenticator app should now have the information it needs, and begin generating the 6-character OTP codes immediately!

We do NOT provide an Aztec code - it is a standard QR code. An that information is exactly what I have added in the pull request (adding the phone side).

Finally, pardon me if this seems ungrateful or nit-picking (or incorrect). This is how it worked for me, once I got past some of the confusion. It's such an amazing feature really... it seems a shame to sully it with instructions that are misleading.

Incorrect stuff should be fixed but we need detailed information.

[seamus]

I'm afraid quotes would only make this more confusing, so I'll address your points this way:

1. Which image, and what do you expect - I cannot follow you.

Ans: The image I was referring to was the QR image that was displayed on the configuration page for the OTP. This image only appeared if the Help link was clicked. But, contrary to the information in the How-To guide at the time, clicking that image took you nowhere.

2. This is the behaviour of very old OPNsense boxes - I patched the link out of it so I don't think you are referring to a 17.x or 18.x version.

Ans: This was not an "old box"; this is what I saw on the OTP configuration page while following the How-To guide. The OPNsense version was the current one: OPNsense 18.1.2_2-amd64

3. We do NOT provide an Aztec code - it is a standard QR code. An that information is exactly what I have added in the pull request (adding the phone side).

Ans: My mistake - a thousand pardons, please... yes, a QR code, not an Aztec code.

4. Incorrect stuff should be fixed but we need detailed information.

Ans: And what I tried to give you was detailed information - a detailed description for the How-To guide that could be used in lieu of the one that's there now. I think the only point I got wrong was incorrectly calling the QR code an Aztec code. Other than that, I feel the description reflects the way the OTP configuration page is implemented.

~S

[fabian]

I'm afraid quotes would only make this more confusing, so I'll address your points this way:

1. Which image, and what do you expect - I cannot follow you.

Ans: The image I was referring to was the QR image that was displayed on the configuration page for the OTP. This image only appeared if the Help link was clicked. But, contrary to the information in the How-To guide at the time, clicking that image took you nowhere.

I am talking about that one - maybe we are not talking about the same thing:
https://docs.opnsense.org/manual/how-tos/two_factor.html

Ans: And what I tried to give you was detailed information - a detailed description for the How-To guide that could be used in lieu of the one that's there now. I think the only point I got wrong was incorrectly calling the QR code an Aztec code. Other than that, I feel the description reflects the way the OTP configuration page is implemented.

Can you provide the URL please?

[seamus]

I'm afraid quotes would only make this more confusing, so I'll address your points this way:

1. Which image, and what do you expect - I cannot follow you.

Ans: The image I was referring to was the QR image that was displayed on the configuration page for the OTP. This image only appeared if the Help link was clicked. But, contrary to the information in the How-To guide at the time, clicking that image took you nowhere.

I am talking about that one - maybe we are not talking about the same thing:
https://docs.opnsense.org/manual/how-tos/two_factor.html

Ans: And what I tried to give you was detailed information - a detailed description for the How-To guide that could be used in lieu of the one that's there now. I think the only point I got wrong was incorrectly calling the QR code an Aztec code. Other than that, I feel the description reflects the way the OTP configuration page is implemented.

Can you provide the URL please?

Yes - this is the same URL that I put in my OP: https://docs.opnsense.org/manual/how-tos/sslvpn_client.html

And again, the passage I am referring to is the paragraph just above "Step 1 - Add SSL Server"

Hope that helps, and again, please let me know if I can do anything to help progress. I wonder if it might be "better" to link the "2 FA Auth How-To" to the SSL VPN How-To?... rather than maintaining the information in 2 places?

~S

[fabian]

Pull request: https://github.com/opnsense/docs/pull/9

[seamus]

This seems to clarify things nicely; thank you.

[seamus]

One final comment: For those that prefer getting their OTPs on their laptop instead of on their phone, Google also has you covered: the "GAuth Authenticator" may be added as an 'extension' to Chrome. After adding the extension, simply copy and paste the "OTP Seed" from your User page into the Authenticator, give it a descriptive title, and it just goes on and on and on....