QuantumAuthSpec

Authentication and Authorization: plan for Diablo
Quantum will provide some form of authentication and authorization for the Diablo release, leveraging integration with Keystone.

The AuthN/AuthZ model for Diablo will NOT include:
 * Full RBAC model including the ability of specifying different roles for tenants’ user (e.g.: “Alice” is an administrator and can do anything for tenant “A”, whereas “Bob” is a simple user and can only plug its own interface into networks owned by tenant “A”)
 * Shared network model, in which a tenant owns the network, but other tenants can plug interfaces into it. This use case will be useful for “public” and possibly “service” networks.

On the other hand, this what will be provide in AuthN/AuthZ model for Diablo:
 * Simplified model: only one “administrator” user per tenant. Although in theory several users can be defined for a tenant, we will assume that each user has the same administrative rights.
 * Authentication service: users must authenticate before submitting requests to Quantum API
 * The plan is to integrate Quantum with Keystone.
 * The user will authenticate with Keystone, which will return an authentication token, which should be used for subsequent requests to Quantum API, which will validate this token with Keystone; (It should be actually possible to achieve this without adding a single line of code to Quantum)
 * Object ownership verification: Before dispatching a call to a plugin the Quantum service layer must verify that all the resources involved are owned by the tenant submitting the request.
 * This can be handled with an authZ middleware which will precede the API app in the wsgi pipeline. Even if it could be handled within the API layer, I reckon it will be better to keep it orthogonal.
 * Interfaces being plugged in a port are rather tricky as they are not managedby Quantum. It will be necesaary to query nova in order to understand whether a tenant owns or not an interface.
 * We would be happy to avoid storing information about object ownership in the service layer and keep the database into the plugin. For networks and ports, the existing plugin interface is probably already good enough to return the appropriate ownership information.

RBAC Specification (post-Diablo)

Introduction
This page discusses specification and implementation for authentication and authorization in the Quantum API.

Roles
For managing quantum network it is possible to identify two distinct roles:
 * 1) Administrator - Owner of the network, the only user authorized to change network's attributes (both core and extended attributes)
 * 2) User - Has the right to plug and unplug virtual network interfaces to Quantum networks. To this aim, it should be allowed to perform operation such as create and delete ports as well. However, users can only operate on ports they created.

Analogies with real world scenarios
If we look at how this would managed in a 'physical data centre', network switches are typically managed by the network administrator; users do not "own" port on network switches. However, the analogy with a physical switch probably does not suit very well the scenario we are trying to achieve with Quantum. Wireless networks are probably a better analogy, as there is no concept of 'physical port'. Administrators set up the network and provide access credential to users, which can then connect their devices to the wireless network; however, policies for the wireless connection are enforced by network administrators; in Quantum terms, this means that even if the user 'owns' the port, he/she does not have any control over the policies defined for that port (e.g.: the port profile); it is worth remarking that the only attribute for a port currently supported by the core Quantum API is the administrative state; all the other attributes are likely to be supported extensions.

AuthN/AuthZ model with single tenant per network
Administrator has complete control of the network, and can perform operations on each port and interface, including the ones created by other users. On the other hand, users can create ports and plug interfaces, as well as unplug previously connected interfaces and delete previously created ports.

When a request for an operation on a network is sent to the Quantum API endpoint, the Quantum API service looks for the authentication token or the user's credentials. If none of them is found, Quantum API will return a 401 error.

If user credentials are supplied in the request, they are forwarded to the authentication service, which verifies them, and, in case of successful authentication, return an authentication token. The authentication token is then returned with the response and can be used for subsequent requests. If the authentication fails, i.e. credentials are incorrect or do not belong to a user for the tenant of the network specified in the request, a 401 error is returned.

If an authentication token is supplied in the request, it is forwarded to the authentication service for validation. If the validation is not successful, i.e. the token does not belong to a user for the tenant of the network specified in the request or is expired, a 401 error is returned.

If both credentials and a token are supplied in the request, priority is given to user credentials, and the token is ignored.

Once the authentication phase has been completed, the Quantum API service queries the authorization service for retrieving the role of the current user. If the operation specified in the request URI is enabled for that specific role, the Quantum API service dispatches the operation to the plugin; otherwise a 403 error is returned.

AuthN/AuthZ model with multiple tenants per network
The model for multiple tenants per networks is very similar to the one with a single tenant, with the only exception that the administrator can give access to the network to other tenants; users from the other tenants will always have the "user" role in network where they have been granted access, even if they are administrators in their own networks.

Alternatively, it is possible to think about "Open" and "Private" networks. An open network is by default a public network to which each tenant can connect as a "user"; the network will be owned by the service provider, which could be modeled as a particular tenant. On the other hand, for a private network, only the tenant which own the network can operate on it.

The Open/Private model suits particularly well a scenario in which a single public network is available to tenants, which can however also create their own private networks; bridges (L2/L3) between private and public networks are at the moment outside the Quantum Scope, even if L2 bridging could become in the future part of the Quantum API.

On the other hand, the first model, in which a tenant can "extend" access to the network to other tenants suits well a scenario in which there might be several public networks; for instance a provider might allow tenants to join public networks with different levels of service.

Implementation
Authentication and authorization will be implemented as wsgi middleware; this means that the code for managing authN/authZ will be completely separate from the API code. Nova, Swift, and Glance already adopt a similar approach.

Integration with Keystone
The plan is that authentication will be implemented using Keystone, which is meant to become the "default" identity service for all Openstack Service. At the moment a beta of the Keystone identity service is available; the beta also include a paste configuration file for nova api which replaces 'traditional' nova authentication with Keystone.

Integration between Quantum and Keystone could work as follows: If authentication is successful, Keystone replies with an auth token and the list of endpoints accessible to the user; this list should include the Quantum API service endpoint ''The Quantum service delegates authentication to Keystone using the Token Authentication protocol. This WSGI middleware extracts the token from the request and sends a token validation request to Keystone's admin API. It is therefore important that the Quantum service has a Keystone Admin auth token.''
 * 1) User authenticates in Keystone. Credentials (username, password, and optionally tenant id) are included in the request body.
 * 1) User sends a request to the Quantum Service; The auth token is provided as a request header.
 * 1) If token validation is successful, the WSGI middleware decorates the request with headers concerning the identity of the user, including his/her role as stored in Keystone.
 * 2) The previous step only validates the identity of the user; a second WSGI middleware filter, or the API layer itself, could be used to verify whether the user is authorized for the requested operation according to his/her role (which is now in the request).

If this is achievable, authorization and authentication for Quantum could be achieved without a significant effort in terms of code development.

Changes to Quantum API
At the moment we do not foresee any change in quantum API.

Discussion points

 * 1) Validating ownership of interfaces being pluggied. When a user makes a port attachment API call it is important to verify that the user actually owns the interface-id being attached. It is important to find a way in which the authentication service can verify the ownership of an object managed by an external service (nova in this case).

2. Public networks. During the summit, we discussed that the service-provider (or a service like nova) may itself act as a tenant to the quantum API in order to model networks. Some elements on this point have been provided in this specification (see AuthN/AuthZ model with multiple tenants per network)

3. AuthN/AuthZ services. Altough we are planning to use Keystone, this code should be written in a way that is amenable to plugging in authentication stores other than Keystone. If that is the case, the authentication middleware could use a driver, with the default driver using KeyStone. However, it should be also noted that KeyStone itself support pluggable modules, so probably the case for a configurable authentication/authorization service is quite weak.