From 739fa6c2ef3d4862fbe7573883307079c6d93022 Mon Sep 17 00:00:00 2001
From: Kaifeng Wang <kaifeng.w@gmail.com>
Date: Tue, 3 Apr 2018 10:58:29 +0800
Subject: [PATCH] Describe unmasking fields in security document

This adds some words about how to unmask passwords or secrets applied
by default policy.

Change-Id: I0295cfa3bce09b336a3f460e3fd7741549e8483b
Story: #1669331
Task: #9725
---
 doc/source/admin/security.rst | 14 ++++++++++++--
 1 file changed, 12 insertions(+), 2 deletions(-)

diff --git a/doc/source/admin/security.rst b/doc/source/admin/security.rst
index 52f8c1bddf..d15b46c4a0 100644
--- a/doc/source/admin/security.rst
+++ b/doc/source/admin/security.rst
@@ -31,7 +31,16 @@ operators significant control over API access:
 * Access may be divided between an "administrative" role with full access and
   "observer" role with read-only access. By default, these roles are assigned
   the names ``baremetal_admin`` and ``baremetal_observer``, respectively.
-* As before, passwords may be hidden in ``driver_info``.
+* By default, passwords and instance secrets are hidden in ``driver_info`` and
+  ``instance_info``, respectively. In case of debugging or diagnosing, the
+  behavior can be overridden by changing the policy file. To allow password
+  in ``driver_info`` unmasked for users with administrative privileges, apply
+  following changes to policy configuration file::
+
+    "show_password": "role:is_admin"
+
+  And restart the Bare Metal API service to take effect. Please check
+  :doc:`/configuration/policy` for more details.
 
 Prior to the Newton (6.1.0) release, the Bare Metal service only supported two
 policy options:
@@ -41,7 +50,8 @@ policy options:
   privileges may only access public API resources.
 * Passwords contained in the ``driver_info`` field may be hidden from all API
   responses with the ``show_password`` policy setting. This defaults to always
-  hide passwords, regardless of the user's role.
+  hide passwords, regardless of the user's role. You can override it with
+  policy configuration as described above.
 
 
 Multi-tenancy