From d3da2200c6dd476be801c2076b8e2067609763fb Mon Sep 17 00:00:00 2001 From: Kamal Hussain Date: Wed, 16 Nov 2016 14:39:39 -0600 Subject: [PATCH] First draft of Gluon access control blueprint This is the first draft on implementing authentication and authorization for Gluon subsystem. The document explains the identity objects that need to be created and suggests a policy.json file for Gluon. Change-Id: Id7a9972b379987a3eb7bd9856d2c0c9af8ac74ee Implements: blueprint gluon-auth --- doc/source/devref/gluon-auth.rst | 203 +++++++++++++++++++++++++++++++ 1 file changed, 203 insertions(+) create mode 100644 doc/source/devref/gluon-auth.rst diff --git a/doc/source/devref/gluon-auth.rst b/doc/source/devref/gluon-auth.rst new file mode 100644 index 0000000..18d1e77 --- /dev/null +++ b/doc/source/devref/gluon-auth.rst @@ -0,0 +1,203 @@ +==================================== +Gluon Authentication & Authorization +==================================== + +Summary +------- + +This document explains the integration of Gluon with OpenStack identity service +or Keystone. When Keystone is enabled, users that submit requests to Gluon +networking service will have to provide an authentication token in X-Auth-Token +request header. The token is obtained by making a call to the Keystone authentication +service by passing in username and password. + +Assumptions +----------- + +The document uses the proposed "port and service binding model"[1] to determine the +policy actions (see section on Authorization). + +Authentication +-------------- + +Authentication is the process of determining that users are who they say they are. +Keystone acts as an authentication proxy which intercepts HTTP calls from clients, +validates the tokens and forwards requests to the OpenStack service. + +If the token is valid, Keystone will retrieve additional information from token +such as user name, user id, project name, project id etc and send this information +to the OpenStack service. Otherwise, the request will be rejected. + + Setting up + ~~~~~~~~~~ + + Once Keystone is installed and running, services have to be configured to work with it. + This involves setting up projects, roles, users, and services. By default, OpenStack + already has several projects, roles and users created. + + Following is the normal process to add a service to Keystone. + + - Create a project + - Create a user for the service and add the user to the project + - Create an admin role and assign to the user + - Create service + - Create endpoint + + For Gluon, we will add these objects. + + - Create a new user called "gluon" + - Add "gluon" user to "service" project + - Add "service" role to "gluon" user in the "service" project + - Create a new service called "gluon" + - Create a new endpoint under the service "gluon" + +Authorization +------------- + +Each OpenSack service has its own role-based access policies to allow/disallow access to +specific actions. The policy.json is used to define the access control, which contains +each policy defined in the format " : ". + +The represents an API call like "create network" whereas determines +under which circumstances API call is permitted. As an example, consider following rule + +``"identity:create_user" : "role:admin"`` + +This rule allows admin role to create a new user in the identity service. + +Authorization Scope +~~~~~~~~~~~~~~~~~~~ + +It will be possible to specify authorization at object level. In the future, we may allow +setting access control at the attribute level. + +Defining authorization rules +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The YAML model definitions will be enhanced to support authorization rules. We will add a new +section for policies. + +The "rules" will be defined at the system level and model authors can use the rules while +defining the actions. + +Following will be the default rules: + + "owner": "tenant_id:%(tenant_id)s", + "admin_or_owner": "rule:context_is_admin or rule:owner", + "admin_or_network_owner": "rule:context_is_admin or tenant_id:%(network:tenant_id)s", + "admin_owner_or_network_owner": "rule:owner or rule:admin_or_network_owner", + "admin_only": "rule:context_is_admin", + +The actions are defined within the "policies" section as shown below. + + ProtonBasePort: + ... + existing model definition + ... + + + policies: + + actions: + create: + role: "rule:admin_or_network_owner" + delete: + role: "rule:admin_or_network_owner" + get: + role: "rule:admin_or_owner" + get_one: + role: "rule:admin_or_owner" + update: + role: "rule:admin_or_network_owner" + + +This policy defines create, delete, get, get_one and update actions on the ProtonBasePort object. +The rules section can embed any openstack policy directive that is supported. Please see +http://docs.openstack.org/kilo/config-reference/content/policy-json-file.html for complete details +of the policy.json file + +Converting to policy.json file +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +During the installation of Gluon, the embedded policies in the YAML model file will be converted +to /etc/gluon/policy.json file. This file will have the following format. + + { + "context_is_admin": "role:admin or user_name:gluon", + "owner": "tenant_id:%(tenant_id)s", + "admin_or_owner": "rule:context_is_admin or rule:owner", + "context_is_advsvc": "role:advsvc", + "admin_or_network_owner": "rule:context_is_admin or tenant_id:%(network:tenant_id)s", + "admin_owner_or_network_owner": "rule:owner or rule:admin_or_network_owner", + "admin_only": "rule:context_is_admin", + "regular_user": "", + "default": "rule:admin_or_owner", + + "create_baseport": "rule:admin_or_network_owner", + "get_baseport": "rule:admin_or_owner", + "update_baseport": "rule:admin_or_network_owner", + "delete_baseport": "rule:admin_or_network_owner", + + "create_service": "rule:admin_or_network_owner", + "get_service": "rule:admin_or_owner", + "update_service": "rule:admin_or_network_owner", + "delete_service": "rule:admin_or_network_owner", + + "create_function": "rule:admin_or_network_owner", + "get_function": "rule:admin_or_owner", + "update_function": "rule:admin_or_network_owner", + "delete_function": "rule:admin_or_network_owner", + + "create_service_binding": "rule:admin_or_network_owner", + "delete_service_binding": "rule:admin_or_network_owner", + + "create_function_binding": "rule:admin_or_network_owner", + "delete_function_binding": "rule:admin_or_network_owner", + } + + +Bootstrapping policy.json +~~~~~~~~~~~~~~~~~~~~~~~~~ + +In the Devstack environment, the gluon software is installed using "python setup.py install" +command from the gluon directory. The setup script will be enhanced to support creating +/etc/gluon/policy.json file from the YAML model file. Users will be able to edit the generated +policy.json file to add their own local rules even though it is not a recommended approach. + +For a production OpenStack environment, the above steps need to be done from the package +installation scripts that are supported by tools such as rpm or dpkg. + +Action to API Mapping +~~~~~~~~~~~~~~~~~~~~~ + +Gluon service has to map actions to respective API calls. The OpenStack keystonemiddleware +and oslo.policy(http://docs.openstack.org/developer/oslo.policy/) modules will be integrated +with Gluon to add keystone authentication and enforce RBAC policies defined in the JSON.policy file. + +The pecan-wsgi service in the Neutron will be used as a reference code for Gluon implementation + +Appendix +-------- +Configuring identity details for Keystone: + + 1. Create gluon user: + + > openstack user create --name gluon --pass + + 2. Add the admin role to the gluon user: + + > openstack user role add --user gluon --tenant service --role admin + + 3. Create the gluon service + + > openstack service create --name gluon --type network --description "Gluon" + + 4. Create Gluon API endpoints + + > openstack endpoint create —publicurl http://10.0.2.15:2705 \ + —adminurl http://10.0.2.15:2705 —internalurl http://10.0.2.15:2705 \ + —region regionOne gluon + +Reference +--------- + 1) Port and service binding model - https://review.openstack.org/#/c/392250 \ No newline at end of file