Update documentation for keystone policy support

This change adds information about keystone policy support in the
following places:

* api-ref: add notes to the Nodes reference, indicating that
  password and configdrive contents may be hidden in responses
* deploy security guide: add a section about limiting API access
  by using the new policies and roles
* deploy install guide: add instructions for creating the necessary
  Roles with the Identity service
* dev quickstart guide: use devstack "demo" user throughout the guide,
  and add a note about why. Incidentally, switch to using "openstack"
  client instead of "ironic" and "nova" clients.

Partial-bug: #1526752
Change-Id: I392cabbf04badabd8ae7bb00a914b0a06db3d421

api-ref/source/baremetal-api-v1-nodes.inc

@@ -17,6 +17,11 @@ and by a unique human-readable "name" in any request. Throughout this
 documentation, this is referred to as the ``node_ident``. Responses clearly
 indicate whether a given field is a ``uuid`` or a ``name``.
 
+Depending on the Roles assigned to the authenticated OpenStack User, and upon
+the configuration of the Bare Metal service, API responses may change. For
+example, the default value of the "show_password" settings cause all API
+responses to mask passwords within ``driver_info`` with the literal string
+"\*\*\*\*\*\*".
 
 Create Node
 ===========

doc/source/deploy/install-guide.rst

@@ -26,13 +26,14 @@ includes:
 - the OpenStack Image service (glance) from which to retrieve images and image meta-data
 - the OpenStack Networking service (neutron) for DHCP and network configuration
 - the OpenStack Compute service (nova) works with the Bare Metal service and acts as
-  a user-facing API for instance management, while the Bare Metal service provides
+  a user-facing API for instance management, while the Bare Metal service
-  the admin/operator API for hardware management.
+  provides the admin/operator API for hardware management.  The OpenStack
-  The OpenStack Compute service also provides scheduling facilities (matching
+  Compute service also provides scheduling facilities (matching flavors <->
-  flavors <-> images <-> hardware), tenant quotas, IP assignment, and other
+  images <-> hardware), tenant quotas, IP assignment, and other services which
-  services which the Bare Metal service does not, in and of itself, provide.
+  the Bare Metal service does not, in and of itself, provide.
 
-- the OpenStack Block Storage (cinder) provides volumes, but this aspect is not yet available.
+- the OpenStack Block Storage (cinder) provides volumes, but this aspect is not
+  yet available.
 
 The Bare Metal service includes the following components:
 
@@ -96,33 +97,77 @@ Configure the Identity service for the Bare Metal service
    Use the ``service`` tenant and give the user the ``admin`` role::
 
     openstack user create --password IRONIC_PASSWORD \
-    --email ironic@example.com ironic
+      --email ironic@example.com ironic
     openstack role add --project service --user ironic admin
 
 #. You must register the Bare Metal service with the Identity service so that
    other OpenStack services can locate it. To register the service::
 
     openstack service create --name ironic --description \
-    "Ironic baremetal provisioning service" baremetal
+      "Ironic baremetal provisioning service" baremetal
 
 #. Use the ``id`` property that is returned from the Identity service when
    registering the service (above), to create the endpoint,
    and replace IRONIC_NODE with your Bare Metal service's API node::
 
     openstack endpoint create --region RegionOne \
-    baremetal admin http://IRONIC_NODE:6385
+      baremetal admin http://IRONIC_NODE:6385
     openstack endpoint create --region RegionOne \
-    baremetal public http://IRONIC_NODE:6385
+      baremetal public http://IRONIC_NODE:6385
     openstack endpoint create --region RegionOne \
-    baremetal internal http://IRONIC_NODE:6385
+      baremetal internal http://IRONIC_NODE:6385
 
    If only keystone v2 API is available, use this command instead::
 
     openstack endpoint create --region RegionOne \
-    --publicurl http://IRONIC_NODE:6385 \
+      --publicurl http://IRONIC_NODE:6385 \
-    --internalurl http://IRONIC_NODE:6385 \
+      --internalurl http://IRONIC_NODE:6385 \
-    --adminurl http://IRONIC_NODE:6385 \
+      --adminurl http://IRONIC_NODE:6385 \
-    baremetal
+      baremetal
+
+#. You may delegate limited privileges related to the Bare Metal service
+   to your Users by creating Roles with the OpenStack Identity service.  By
+   default, the Bare Metal service expects the "baremetal_admin" and
+   "baremetal_observer" Roles to exist, in addition to the default "admin"
+   Role. There is no negative consequence if you choose not to create these
+   Roles. They can be created with the following commands::
+
+    openstack role create baremetal_admin
+    openstack role create baremetal_observer
+
+   If you choose to customize the names of Roles used with the Bare Metal
+   service, do so by changing the "is_member", "is_observer", and "is_admin"
+   policy settings in ``/etc/ironic/policy.json``.
+
+   More complete documentation on managing Users and Roles within your
+   OpenStack deployment are outside the scope of this document, but may be
+   found here_.
+
+#. You can further restrict access to the Bare Metal service by creating a
+   separate "baremetal" Project, so that Bare Metal resources (Nodes, Ports,
+   etc) are only accessible to members of this Project::
+
+    openstack project create baremetal
+
+   At this point, you may grant read-only access to the Bare Metal service API
+   without granting any other access by issuing the following commands::
+
+    openstack user create \
+      --domain default --project-domain default --project baremetal \
+      --password PASSWORD USERNAME
+    openstack role add \
+      --user-domain default --project-domain default --project baremetal\
+      --user USERNAME baremetal_observer
+
+#. Further documentation is available elsewhere for the ``openstack``
+   `command-line client`_ and the Identity_ service. A policy.json.sample_
+   file, which enumerates the service's default policies, is provided for
+   your convenience with the Bare Metal Service.
+
+.. _Identity: http://docs.openstack.org/admin-guide/identity-management.html
+.. _`command-line client`: http://docs.openstack.org/admin-guide/cli-manage-projects-users-and-roles.html
+.. _here: http://docs.openstack.org/admin-guide/identity-concepts.html#user-management
+.. _policy.json.sample: https://github.com/openstack/ironic/blob/master/etc/ironic/policy.json.sample
 
 
 Set up the database for Bare Metal
@@ -138,9 +183,9 @@ MySQL database that is used by other OpenStack services.
     # mysql -u root -p
     mysql> CREATE DATABASE ironic CHARACTER SET utf8;
     mysql> GRANT ALL PRIVILEGES ON ironic.* TO 'ironic'@'localhost' \
-    IDENTIFIED BY 'IRONIC_DBPASSWORD';
+           IDENTIFIED BY 'IRONIC_DBPASSWORD';
     mysql> GRANT ALL PRIVILEGES ON ironic.* TO 'ironic'@'%' \
-    IDENTIFIED BY 'IRONIC_DBPASSWORD';
+           IDENTIFIED BY 'IRONIC_DBPASSWORD';
 
 Install the Bare Metal service
 ------------------------------
@@ -152,13 +197,13 @@ Install the Bare Metal service
 
     Fedora 21/RHEL7/CentOS7:
         sudo yum install openstack-ironic-api openstack-ironic-conductor \
-        python-ironicclient
+                         python-ironicclient
         sudo systemctl enable openstack-ironic-api openstack-ironic-conductor
         sudo systemctl start openstack-ironic-api openstack-ironic-conductor
 
     Fedora 22 or higher:
         sudo dnf install openstack-ironic-api openstack-ironic-conductor \
-        python-ironicclient
+                         python-ironicclient
         sudo systemctl enable openstack-ironic-api openstack-ironic-conductor
         sudo systemctl start openstack-ironic-api openstack-ironic-conductor
 
@@ -227,17 +272,18 @@ Configuring ironic-api service
     # "keystone" or "noauth". "noauth" should not be used in a
     # production environment because all authentication will be
     # disabled. (string value)
-    #auth_strategy=keystone
+    auth_strategy=keystone
 
     [keystone_authtoken]
     ...
-    # Complete public Identity API endpoint (string value)
+    # Authentication type to load (string value)
-    auth_uri=http://IDENTITY_IP:5000/
+    auth_type = v3password
 
-    # Complete admin Identity API endpoint. This should specify
+    # Complete public Identity API endpoint (string value)
-    # the unversioned root endpoint e.g. https://localhost:35357/
+    auth_uri=http://PUBLIC_IDENTITY_IP:5000/v3/
-    # (string value)
+
-    identity_uri=http://IDENTITY_IP:35357/
+    # Complete admin Identity API endpoint. (string value)
+    auth_url=http://PRIVATE_IDENTITY_IP:35357/v3/
 
     # Service username. (string value)
     admin_user=ironic

doc/source/deploy/security.rst

@@ -1,29 +1,49 @@
 .. _security:
 
-========
+=================
-Security
+Security Overview
-========
+=================
-
-Overview
-========
 
 While the Bare Metal service is intended to be a secure application, it is
 important to understand what it does and does not cover today.
 
 Deployers must properly evaluate their use case and take the appropriate
-actions to secure their environment appropriately. This document is intended to
+actions to secure their environment(s). This document is intended to provide an
-provide an overview of what risks an operator of the Bare Metal service should
+overview of what risks an operator of the Bare Metal service should be aware
-be aware of. It is not intended as a How-To guide for securing a data center
+of. It is not intended as a How-To guide for securing a data center or an
-or an OpenStack deployment.
+OpenStack deployment.
 
 .. TODO: add "Security Considerations for Network Boot" section
 
 .. TODO: add "Credential Storage and Management" section
 
-.. TODO: add "Securing Ironic's REST API" section
-
 .. TODO: add "Multi-tenancy Considerations" section
 
+
+REST API: user roles and policy settings
+========================================
+
+Beginning with the Newton (6.1.0) release, the Bare Metal service allows
+operators significant control over API access:
+
+* Access may be restricted to each method (GET, PUT, etc) for each
+  REST resource. Defaults are provided with the release and defined in code.
+* 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``.
+
+Prior to the Newton (6.1.0) release, the Bare Metal service only supported two
+policy options:
+
+* API access may be secured by a simple policy rule: users with administrative
+  privileges may access all API resources, whereas users without administrative
+  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.
+
+
 Firmware security
 =================
 

doc/source/dev/dev-quickstart.rst

@@ -462,6 +462,13 @@ up to date and has the latest packages installed before beginning this process.
 
     http://docs.openstack.org/developer/devstack/
 
+.. note::
+    The devstack "demo" tenant is now granted the "baremetal_observer" role
+    and thereby has read-only access to ironic's API. This is sufficient for
+    all the examples below. Should you want to create or modify bare metal
+    resources directly (ie. through ironic rather than through nova) you will
+    need to use the devstack "admin" tenant.
+
 
 Devstack will no longer create the user 'stack' with the desired
 permissions, but does provide a script to perform the task::
@@ -609,7 +616,7 @@ Run stack.sh::
 
     ./stack.sh
 
-Source credentials, create a key, and spawn an instance::
+Source credentials, create a key, and spawn an instance as the ``demo`` user::
 
     source ~/devstack/openrc
 
@@ -618,22 +625,22 @@ Source credentials, create a key, and spawn an instance::
 
     # create keypair
     ssh-keygen
-    nova keypair-add default --pub-key ~/.ssh/id_rsa.pub
+    openstack keypair create --public-key ~/.ssh/id_rsa.pub default
 
     # spawn instance
-    nova boot --flavor baremetal --image $image --key-name default testing
+    openstack server create --flavor baremetal --image $image --key-name default testing
 
 .. note::
     Because devstack create multiple networks, we need to pass an additional parameter
     ``--nic net-id`` to the nova boot command when using the admin account, for example::
 
-      net_id=$(neutron net-list | egrep "$PRIVATE_NETWORK_NAME"'[^-]' | awk '{ print $2 }')
+      net_id=$(openstack network list | egrep "$PRIVATE_NETWORK_NAME"'[^-]' | awk '{ print $2 }')
 
-      nova boot --flavor baremetal --nic net-id=$net_id --image $image --key-name default testing
+      openstack server create --flavor baremetal --nic net-id=$net_id --image $image --key-name default testing
 
-As the demo tenant, you should now see a Nova instance building::
+You should now see a Nova instance building::
 
-    nova list
+    openstack server list
     +--------------------------------------+---------+--------+------------+-------------+----------+
     | ID                                   | Name    | Status | Task State | Power State | Networks |
     +--------------------------------------+---------+--------+------------+-------------+----------+
@@ -644,9 +651,7 @@ Nova will be interfacing with Ironic conductor to spawn the node.  On the
 Ironic side, you should see an Ironic node associated with this Nova instance.
 It should be powered on and in a 'wait call-back' provisioning state::
 
-    # Note that 'ironic' calls must be made with admin credentials
+    openstack baremetal node list
-    . ~/devstack/openrc admin admin
-    ironic node-list
     +--------------------------------------+--------------------------------------+-------------+--------------------+
     | UUID                                 | Instance UUID                        | Power State | Provisioning State |
     +--------------------------------------+--------------------------------------+-------------+--------------------+
@@ -671,7 +676,7 @@ This provisioning process may take some time depending on the performance of
 the host system, but Ironic should eventually show the node as having an
 'active' provisioning state::
 
-    ironic node-list
+    openstack baremetal node list
     +--------------------------------------+--------------------------------------+-------------+--------------------+
     | UUID                                 | Instance UUID                        | Power State | Provisioning State |
     +--------------------------------------+--------------------------------------+-------------+--------------------+
@@ -683,9 +688,7 @@ the host system, but Ironic should eventually show the node as having an
 This should also be reflected in the Nova instance state, which at this point
 should be ACTIVE, Running and an associated private IP::
 
-    # Note that 'nova' calls must be made with the credentials of the demo tenant
+    openstack server list
-    . ~/devstack/openrc demo demo
-    nova list
     +--------------------------------------+---------+--------+------------+-------------+------------------+
     | ID                                   | Name    | Status | Task State | Power State | Networks         |
     +--------------------------------------+---------+--------+------------+-------------+------------------+