Overview and Definitions

Authorization for resources served by the services running on the Bamboo Services Platform (BSP), or resources for which the BSP manages policy, is architected to the XACML 2.0 specification (PDF). XACML is an OASIS specification; the acronym stands for eXtensible Access Control Markup Language. Some elements of the XACML spec were implemented in a manner that offers less-than-ideal usability in phase one of the Bamboo Technology Project, e.g., the Policy Access Point is implemented as a directory into which a system administer writes policy files prior to activation of the Policy bundles (see Deploying Policies, below), instead of (for example) a database with an appropriate service API and user interface for easier, permission-controlled administrative access.

Authorization decisions are based on a policy-driven process that takes into account:

It is important to note that "the resource in question" may be a resource provisioned by a service, or the service itself. In the latter case, a policy is governing rights to make requests of a service.

The process of authorizing a client's request can be broken down into four steps:

  1. Intercepting the request and harvesting passed attributes
  2. Resolving the attributes required to make a decision
  3. Deciding whether to allow or deny the request
  4. Logging the request

Here are some useful concepts and definitions:

Policy Enforcement Point (PEP): The system entity that performs access control by making decision requests and enforcing authorization decisions. See Policy Enforcement, below.

Policy Decision Point (PDP): A service that assembles the needed information to evaluate a policy with respect to a concrete request for which authorization is required, evaluates the policy, and boils the answer down to ALLOW or DENY (plus, optionally, some additional obligations). In Bamboo's implementation, the PDP is accessed through the Request Manager service.

Policy: A policy is a set of rules; a rule consists of a target, an effect, and a condition. See Policy Examples, below. Policies are XML documents that conform to the XACML schema for Policy Sets.

Policy Information Point (PIP): a system entity that acts as a source of attribute values. See Factors used in deciding Policy, below.

Context Handler: The system entity that converts decision requests in the native request format to the XACML canonical form and converts authorization decisions in the XACML canonical form to the native response format. In Bamboo's implementation, this function is handled by the Request Manager service.

Subject / Principal: An actor whose attributes may be referenced by a predicate. This is a general way of describing a user whose attributes that matter vis-a-vis policy decisions are the  Factors used in deciding Policy, see below.

Environment: The set of attributes that are relevant to an authorization decision and are independent of a particular subject, resource or action. An example of an environmental attribute that could figure into a policy is time (e.g., a policy might contain rules that boil down to "this resource is only available on weekdays").

Authorization Request: The roles, resource, action and environment data to use when making a policy decision. In Bamboo's implementation, the Request Manager service assembles these data and routes the authorization request to the Policy Decision Point.

Authorization Decision: The result of evaluating applicable policy, returned by the PDP to the PEP. A function that evaluates to “Permit”, “Deny”, “Indeterminate” or “NotApplicable", and (optionally) a set of obligations. In Bamboo's implementation, only "Permit" decisions are authorized; any other resolution is denied access to the requested resource.

A comprehensive treatment of these terms and concepts can be found in the XACML 2.0 specification (PDF).

Policy Enforcement

 Policy may be enforced at two conceptual points:

  1. when a request arrives at the BSP, and is evaluated 'at the perimeter' as to whether or not it may be forwarded to a service hosted on the BSP; and/or,
  2. when a request is being processed by a service, and the service requires an authorization decision based on policies that were not or could not be evaluated 'at the perimeter.'

The sequence diagram included here (click to enlarge) served as a model use case to which Bamboo's IAM infrastructure was built. Further explanation follows below.

Of particular note in the diagram:

In phase one of the Bamboo Technology Project, no service implemented the 'inner loop' of this sequence diagram. That is, the only policies written, tested, and enforced at the time the BTP ended were those that govern access at a service level, as described in the second bullet above. However, the Request Manager service provides the interface a BSP-deployed service would need to obtain ALLOW/DENY decisions at the finer-grained level described in the third bullet above and its sub-bullets.

 

Policy Decisions

Policy decisions are accessed through the Request Manager service. They may be accessed by a service local to the BSP, or by an external client. In either case, the resources on which policy decisions are requested must be governed by a policy in effect (known to) the BSP AuthZ infrastructure (see Policy examples... and Deploying Policies, below).

Note that a resource may be brought under the governance of policy restricting/opening access to members of a Group or users holding a scoped role by associating the resource with a Group or scoped role using the Protected Resource Service. The owner (e.g., creator) of a resource is permitted to create such an association.

See the Request Manager service API, which includes links to the service codebase for those who wish to dive deeper into the implementation of the AuthZ infrastructure. External clients use the ROA Layer API; services deployed on the BSP use the SOA Layer API.

 

Factors used in deciding Policy

Supported types of policy decisions are given in the examples described in the following sub-section of this page. These decisions imply the ability of BSP to assemble a set of facts – including user attributes, registered application attributes, user group memberships, user scoped roles, and environmental conditions such as system time – that are checked against a policy for a given resource, resulting in an ALLOW or DENY decision vis-a-vis access to the resource.

The factors assembled for use in evaluating access include:

 

Supported policy decision examples

The following are examples that utilize factors described in the prior sub-section of this page. See the prior section for links to explanatory documentation and relevant APIs.

  1. Access to a protected resource requires affiliation with an institution whose affiliates are permitted access to the resource. If the requesting user is affiliated with 'permitted' institutions s/he is allowed access to the resource.
  2. Access to a protected resource requires membership in a Bamboo-managed group that has been granted access to the resource. If the requesting user is a current member of a group that has been granted access to the resource, s/he is allowed access.
  3. Access to protected resource requires both affiliation with an institution and membership in a Bamboo-managed group (i.e. both of the above must be true).
  4. Access to protected resource is denied if the client application through which a request is made is NOT registered as an app in the Bamboo Trust Federation.
  5. Access to protected resource is permitted if the association of individual (bpid) and requesting innovation app has been registered, where the request is made by the Innovation Licensed application on behalf of a user it is allowed to 'impersonate.'
  6. Access to protected resource requires that the requesting user own the resource, where "ownership" is a concept encapsulated by the service that models the resource. [Example: a Person Profile may be UPDATEd only by the user whose BPId the profile describes; or by users in a group that has been specified, by the Profile owner, as a set of Bamboo Persons permitted to update the profile]

 

User attributes as referenced in Policies

Attributes are the "factors" described above, in Factors used in deciding Policy. These are expressed formally in policies either as standard XACML attributes, or as attributes defined by Project Bamboo. Here is a list of attributes found in Policy examples referenced below, and what they represent.

These attributes are defined in two schema documents located in the Bamboo code repository at these locations:

 

AttributeDescription
urn:mace:projectbamboo.org:attribute:1.0:app-idRepresents the Application Identifier that would be passed by the application making the request (cf. Maintaining Application Catalog Data for Trusted Clients). This attribute is passed by trusted client applications in an HTTP request header called X-Bamboo-AppID; see the Client Responsibilities... section of any service contract listed on the page Service APIs - Centrally-Hosted Bamboo Services.
urn:oasis:names:tc:xacml:1.0:subject:subject-idRepresents the Subject Identifier that would be passed by the application making the request (subject identifiers are passed by trusted client applications in an HTTP request header called X-Bamboo-BPID; see the Client Responsibilities... section of any service contract listed on the page Service APIs - Centrally-Hosted Bamboo Services )
urn:oasis:names:tc:xacml:1.0:resource:resource-idRepresents the resource that is the object of the request
urn:oasis:names:tc:xacml:1.0:action:action-idRESTful actions that can be performed as part of a request (a.k.a. "HTTP verbs"). The allowed actions are: GET, PUT, POST, and DELETE.
urn:mace:projectbamboo.org:attribute:1.0:group-has-view-access-rightsRepresents a group that is associated (via the Protected Resource service) with a protected resource, such that users who are members of the group have view access rights to the resource (cf. Group Service Contract Description - v0.9-alpha)
urn:mace:projectbamboo.org:attribute:1.0:group-has-update-access-rightsRepresents a group that is associated (via the Protected Resource service) with a protected resource, such that users who are members of the group have update access rights to the resource (cf. Group Service Contract Description - v0.9-alpha).
urn:mace:dir:attribute-def:isMemberOfRepresents the Identifier of a group to which the subject (user) belongs (cf. Group Service Contract Description - v0.9-alpha).
urn:mace:projectbamboo.org:attribute:1.0:scopedRoleRepresents an assertion that the user has some role within a domain. "Scoped roles" are passed by trusted client applications in an HTTP request header called X-Bamboo-Roles; see the Client Responsibilities... section of any service contract listed on the page Service APIs - Centrally-Hosted Bamboo Services . A "scoped role" is formatted as an RFC822 Name consisting of a local-part followed by "@" followed by a domain-part, e.g., unspecified@berkeley.edu.
urn:mace:projectbamboo.org:attribute:1.0:scoped-role-has-view-access-rightsRepresents a "scoped role" that is associated (via the Protected Resource service) with a protected resource, such that users who hold the scoped role has view access rights to the resource. Cf. description of urn:mace:projectbamboo.org:attribute:1.0:scopedRole for additional context and formatting information.
urn:mace:projectbamboo.org:attribute:1.0:scoped-role-has-update-access-rightsRepresents a "scoped role" that is associated (via the Protected Resource service) with a protected resource, such that users who hold the scoped role has update access rights to the resource. Cf. description of urn:mace:projectbamboo.org:attribute:1.0:scopedRole for additional context and formatting information.
urn:oasis:names:tc:xacml:1.0:subject:request-timeIndicates the time at which the subject initiated the access request.
urn:mace:projectbamboo.org:attribute:1.0:host-nameRepresents the name of the server that will provision the request
urn:oasis:names:tc:xacml:1.0:environment:current-dateTimeRepresents the time at the server that will provision the request
urn:mace:projectbamboo.org:attribute:1.0:app-contract-typeRepresents the Contract Type that would be passed by the application making the request, where "contract type" refers to contractual relationships in the Bamboo Trust Federation, such as "Trusted Application" or "Innovation Licensed Application." Cf. Maintaining Application Catalog Data for Trusted Clients.

 

Policy examples: tested and versioned in Bamboo Code Repository

Policies are XML documents that conform to the XACML schema for Policy Sets.

Policy examples, which have been tested in the v0.9 release of the Bamboo Services Platform, are versioned in the code repository at multiple locations:

  1. Policies that pertain to BSP services are versioned in the BSP codebase as follows:
    1. Policies that pertain to a secured BSP: ${REPOSITORY_ROOT}/platform-services/bsp/trunk/bsp/utility-services/policy-service/policy-service-domain/src/main/resources/policies/
    2. Policy to ALLOW all requests, appropriate for unsecured instances (e.g., developer environment): ${REPOSITORY_ROOT}/platform-services/bsp/trunk/bsp/utility-services/policy-service/policy-service-domain/src/test/resources/policies/
    3. Note that a test policy for scoped roles is also included in the repository directory indicated in (b) above. This policy (ScopedRoleTest.xml) is referenced in unit tests, and is thus required to build the BSP code base; but it is not intended for inclusion in the "standard" set of secured-BSP policies located in the directory indicated in (a) above.
  2. Policies that pertain to services OTHER THAN those described in (1) above are versioned at ${REPOSITORY_ROOT}/platform-config/trunk/policies/

 

Deploying Policies (rendering policies 'in effect')

To put policies into effect, they must be in a directory on the filesystem of the host running the BSP. The location of this directory is:

${BSPLOCALSTORE_HOME}/policies

Where BSPLOCALSTORE_HOME is assumed to be set in the context in which FUSE ESB (ServiceMix) is running. See the page Developer Workbench Environment for BSP Service Developers re: setting environment variables.

All policies must be located in the specified directory. No nested directories are read. The policies must be in place when the BSP's Policy service bundles are deployed to ServiceMix.