Bug 1441676 - [Docs][Install] Add information about where to access upgraded certificates
Summary: [Docs][Install] Add information about where to access upgraded certificates
Keywords:
Status: CLOSED CURRENTRELEASE
Alias: None
Product: Red Hat Enterprise Virtualization Manager
Classification: Red Hat
Component: Documentation
Version: 4.1.0
Hardware: Unspecified
OS: Unspecified
high
unspecified
Target Milestone: ovirt-4.1.3
: ---
Assignee: Emma Heftman
QA Contact: Tahlia Richardson
URL:
Whiteboard:
Depends On:
Blocks:
TreeView+ depends on / blocked
 
Reported: 2017-04-12 12:43 UTC by Emma Heftman
Modified: 2019-05-07 12:55 UTC (History)
9 users (show)

Fixed In Version:
Doc Type: If docs needed, set a value
Doc Text:
Clone Of:
Environment:
Last Closed: 2017-06-22 16:02:23 UTC
oVirt Team: Docs
Target Upstream Version:
Embargoed:


Attachments (Terms of Use)

Description Emma Heftman 2017-04-12 12:43:07 UTC
While working on bug 1420577 (a new signed certificate protocol), it was discovered that the KB article referenced by the Admin Guide is out-of-date.

See the links in the Important note, here:
https://access.redhat.com/documentation/en-us/red_hat_virtualization/4.1/html/installation_guide/connecting_to_the_administration_portal

Didi is the contact for this information.

Comment 1 Yaniv Lavi 2017-04-24 07:49:56 UTC
Is anything needs to updated?
Or do we only need to list the links?
We don't think it makes sense to add those KBase to the mainline docs as this is not RHV docs, it's a browser specific flow we do not control.

Comment 2 Emma Heftman 2017-04-24 12:28:32 UTC
(In reply to Yaniv Dary from comment #1)
> Is anything needs to updated?
> Or do we only need to list the links?
> We don't think it makes sense to add those KBase to the mainline docs as
> this is not RHV docs, it's a browser specific flow we do not control.

1. Steve, could you advise us as to how other teams handle this kind of issue - updating browser certificates. 
2. The KB articles themselves are out-of-date, so there is still an action item to at least find the correct external documentation to link to.

Comment 3 Steve Bream 2017-04-24 13:41:13 UTC
Thanks Emma:

1. As a rule, where we don't own the process, we should avoid including the specifics in our documentation, as they can change without our knowledge (as has happened here). 

2. I suggest refraining from even linking to the external documentation. We don't control that documentation or how the owners update it, which opens the door to repeating this problem every time the browser doc is updated. I was able to locate the procedure for adding certificates to all three browsers on the first Google search, so I think that what makes the most sense is to tell users that to avoid warnings and maintain security, they should import the new CA, located at: %CA location in RHV%, according to the process for their browser.

3. As an additional item, I also suggest moving the information about updating CAs to section 3.3 Configuring the Red Hat Virtualization Manager, which has the advantage treating the CA update as a regular part of the configuration process rather than as an interruption in accessing the admin console.

Comment 4 Emma Heftman 2017-04-24 15:12:35 UTC
(In reply to Steve Bream from comment #3)
> Thanks Emma:
> 
> 1. As a rule, where we don't own the process, we should avoid including the
> specifics in our documentation, as they can change without our knowledge (as
> has happened here). 
> 
> 2. I suggest refraining from even linking to the external documentation. We
> don't control that documentation or how the owners update it, which opens
> the door to repeating this problem every time the browser doc is updated. I
> was able to locate the procedure for adding certificates to all three
> browsers on the first Google search, so I think that what makes the most
> sense is to tell users that to avoid warnings and maintain security, they
> should import the new CA, located at: %CA location in RHV%, according to the
> process for their browser.

Thanks Steve. Makes sense and sounds like a good policy.
> 
> 3. As an additional item, I also suggest moving the information about
> updating CAs to section 3.3 Configuring the Red Hat Virtualization Manager,
> which has the advantage treating the CA update as a regular part of the
> configuration process rather than as an interruption in accessing the admin
> console.

Sounds like a good workaround.

Comment 5 Emma Heftman 2017-04-25 05:14:51 UTC
(In reply to Emma Heftman from comment #0)
> While working on bug 1420577 (a new signed certificate protocol), it was
> discovered that the KB article referenced by the Installation Guide is out-of-date.
> 
> See the links in the Important note, here:
> https://access.redhat.com/documentation/en-us/red_hat_virtualization/4.1/
> html/installation_guide/connecting_to_the_administration_portal
> 
> Didi is the contact for this information.

See https://bugzilla.redhat.com/show_bug.cgi?id=1441676#c4

Comment 6 Lucy Bopf 2017-05-29 02:28:11 UTC
Assigning to Emma for review.

Comment 7 Emma Heftman 2017-06-05 08:52:08 UTC
Hi Didi
Can you please review step 21 in 3.3. Configuring the Red Hat Virtualization Manager. I added this step here, and removed it from the Connecting to the Admin Portal chapter, as per Steve Bream's suggestion.


http://file.tlv.redhat.com/~eheftman/bz1441676/html-single/#Red_Hat_Enterprise_Virtualization_Manager_Configuration_Overview

Comment 8 Yedidyah Bar David 2017-06-05 11:54:17 UTC
The text in your section 21, which seems to be a copy of the current "Important" note in "3.4. Connecting to the Administration Portal", talks about "certificate authority", but makes it seem like the process will be guided by the browser itself, on the first time you connect, with the text "according to the instructions provided by your browser" seeming like a suggestion more than an instruction. I didn't test this with all browsers, but I am pretty certain this is wrong, at least for all the common ones.

We have here two certificates:

1. The CA (certificate authority) certificate
2. The https certificate

On first connecting, most/all browsers will prompt to import/trust the _second_ one. This is enough for much, but not all, of the web admin functionality.

To import the _first_ one, which is required for things like websocket-proxy, vmconsole-proxy and the web-based image uploader, most/all browsers require some manual actions, such as the current links in the current Important box.

So, perhaps something like this:

Install the certificate authority according to the instructions provided by your browser. You can get the certificate authority's certificate by connecting to:

http://your-manager-fqdn/ovirt-engine/services/pki-resource?resource=ca-certificate&format=X509-PEM-CA

replacing your-manager-fqdn with the fully qualified domain name that you provided during installation.


Note You need to log in before you can comment on or make changes to this bug.