home > Authorization Policy

OSCARS Authorization Policy


  1. Introduction
  2. Authorization policy requirements
    1. Permissions with respect to users and institutions
    2. Permissions with respect to bandwidth and reservations
    3. Permissions with respect to topology
    4. Permission with respect to authorizations
    5. Permission with respect to notification server
  3. Policy Tables
    1. Table summary
    2. Default behaviors
  4. Mapping of requirements to authorizations
    1. Permissions with respect to users and institutions
    2. Permissions with respect to bandwidth and reservations
    3. Permissions with respect to topology
    4. Permission with respect to authorizations
    5. Permission with respect to notification server
  5. Default Tables
    1. Attributes Table
    2. Default Authorizations Table
  6. API for access checks
    1. CheckAccess Implementation
    2. Standard method
    3. Method for create and modify reservations

Introduction

An authorization decision consists of deciding if an authenticated entity should be allowed to perform some action on a controlled resource. In OSCARS an authenticated entity may be a bandwidth user or a bandwidth reservation service from another domain; the fundamental resource is bandwidth though the domain, and the fundamental permission is right to reserve some fraction of the available bandwidth. Since available bandwidth is a limited resource, some finer control is needed such as the maximum allowed bandwidth and duration. In addition, some users of the system needed to request or suggest possible internal routing for the data path.

OSCARS chose to do attribute-based authorization primarily as a way of consolidating authorization policy to make it more understandable to users and OSCARS administrators and partly in anticipation of integrating with an external attribute provider such as Shibboleth or VOMS. An attribute is some characteristic of a user, such as being a member of some project, a holder of some role, or just his identity as expressed as a registered user name or x.509 identity certificate. A user gets the maximum of all the privileges granted to all of the attributes that he has.

OSCARS is currently a self-contained system that defines who its registered users are and what attributes each one has. As a result, it needs to control who may manage users and their permissions, so users become a controlled resource in addition to bandwidth. Another resource is the internal topology, since we want control who may view the or reload the topology tables that are used in pathfinding. In addition, there is a notification service running as part of OSCARS, and the right to publish events there or subscribe to events is controlled.

The underlying guideline of our design and implementation is to keep authorization policy and implementation as simple as possible. We have tried to make the granularity of access decisions no finer than is actually required, and have defined roles to consolidate sets of authorizations into roles that will accommodate the use cases we anticipate. Some of our underlying assumptions are: Most users will get their permissions by being members of a role, rather than by individual grants. The number of roles will be small. The number of resources and permissions will be small. While the implementation may scale to larger numbers, the ability of the users and administrators to understand it will not.

We are currently intending to authorize a reservation that has been forwarded to ESnet from an adjacent domain based on the attributes assigned to that domain rather than the end user who is requesting the reservation. Thus the number of users that must be registered with the system can remain manageable. The name of the user is included in the forwarded request, so it can be used for auditing purposes or can later be used for authorization.

Authorization policy requirements

The following paragraphs list the various actions that we want to control with respect to the resources that OSCARS controls.

Permissions with respect to users and institutions

Permissions with respect to bandwidth and reservations

(signaling instantiates a reservation or tears down an established circuit by causing the appropriate commands to be sent to the routers involved)

Permissions with respect to topology

Permission with respect to authorizations

Permission with respect to notification server

Policy Tables

All access decisions are made by one of two methods which are called from each place in the code that is about to grant some access. Access policy is stored in a database, and an access decision is made by doing table lookups based on the requester, the action requested and the resource. Authorizations may have constraints attached, in which case the parameters of the request must meet the constraints.

Table summary

The following tables define the components for authorization:

Users may have one or more attributes although the role attributes, except for administrator are designed to be used alone. Attributes and authorizations are arbitrary strings and while there is a default set defined, it is expected that sites may re-define or add new ones to meet their needs.  On the other hand, resources, permissions, and constraints are strings that are used by the code and changing them must be accompanied by code changes that enforce the semantics desired.

Using attributes to grant authorizations, rather than just the user identity, allows a set of authorizations to be crafted which can then be applied to a class of users. Otherwise, each time a new user registers, he must be given the correct and complete set of permissions for whatever he wants to do. Currently the OSCARS AA system registers users and assigns them attributes. In the future, user identities and attributes may be available from multiple external identity or attributes providers.

Default behaviors

If a user has no entry in the user table or has no attributes in the userAttribute table, any attempted OSCARS access will be rejected immediately by Oscars:OscarsSkeleton:checkUser or Servlets:AuthenticateUser
If no attribute that the user possesses has an entry for the required resource/permission pair in the authorization table, the request is denied.
The constraint defaults are intended to be the most common cases, not the most restricted.

Mapping of requirements to authorizations

The following tables describe the possible actions and the authorizations that they require.

Permissions with respect to users and institutions

desired action permission resource, constraint
see own profile query users
modify own profile modify users
list all users list users
see all user profiles query users, all-users
add a user create users, all-users
delete a user
modify users, all-users
modify any user profile modify users, all-users
grant or remove attributes for any user modify users, all-users
add, edit or delete institutions
modify AAA

Permissions with respect to bandwidth and reservations

desired action permission resource, constraint
make unlimited reservation create reservations
make reservation with bandwidth constraint create reservations, max-bandwidth= <upper-limit>
make reservation with duration constraint create reservations, max-duration=<upper-limit>
make reservation with topology constraint create reservations, specify-path-elements
list own reservations list reservations
query own reservations query reservations
cancel, modify own reservation modify reservations
signal own reservation signal reservations
list all reservations starting or terminating at a site
list reservations, my-site
query any reservations starting or terminating at a site query reservations, my-site
cancel, modify any reservations starting or terminating at a site modify reservations, my-site
signal any reservations starting or terminating at a site signal reservations, my-site
list all reservations list reservations, all-users
query any reservations query reservations, all-users
cancel, modify any reservations modify reservations, all-users
signal any reservations signal reservations, all-users
cancel, modify and signal any reservations regardless of state
signal reservations, unsafe-allowed
(signaling instantiates a reservation or tears down an established circuit by causing the appropriate commands to be sent to the routers involved)

Permissions with respect to topology

desired action permission resource, constraint
view topology query domains
modify the topology modify domains

Permission with respect to authorizations

desired action permission resource, constraint
view all attributes and authorizations list AAA
create or delete attributes modify AAA
add/modify authorizations associated with attributes
modify AAA

Permission with respect to notification server

desired action permission resource, constraint
register to publish events create publishers
remove publishers registration modify publishers
subscribe to events create subscriptions
renew or cancel a subscription modify subscriptions


Default Tables

The distribution includes scripts (sql/aaa/populateDefaults.sql) to set up the roles described above. The standard attributes are entered into the Attributes table.

Attributes Table

attribute name (string)
attribute type (int)
OSCARS-user
role
OSCARS-engineer role
OSCARS-administrator role
OSCARS-service role
OSCARS-operator role
OSCARS-site-administrator
role
OSCARS-publisher role
OSCARS-may-specify-path
privilege

Default Authorizations Table

attributeId  (int) resource permission constraint name (string) value (string)
<OSCARS-user> users query none [1]
<OSCARS-user> users modify none [1]
<OSCARS-user> reservations list none [2]
<OSCARS-user> reservations query none [2]
<OSCARS-user> reservations create none [2]
<OSCARS-user> reservations modify none [2]
<OSCARS-user> reservations signal none [2]
<OSCARS-user> subscriptions create

<OSCARS-user> subscriptions modify

<OSCARS-engineer> users query none [1]
<OSCARS-engineer> users modify none [1]
<OSCARS-engineer> reservations list all-users true
<OSCARS-engineer> reservations query all-users true
<OSCARS-engineer> reservations create specify-path-elements true
<OSCARS-engineer> reservations modify all-users true
<OSCARS-engineer> reservations modify
specify-path-elements
true
<OSCARS-engineer> reservations signal all-users true
<OSCARS-engineer> reservations signal unsafe-allowed true
<OSCARS-engineer> subscriptions create

<OSCARS-engineer> subscriptions modify

<OSCARS-engineer> domains view

<OSCARS-engineer> domains modify

<OSCARS-service> reservations list

<OSCARS-service> reservations query my-site true
<OSCARS-service> reservations create specify-path-elements true
<OSCARS-service> reservations create
specify-gri
true
<OSCARS-service> reservations modify specify-path-elements
true
<OSCARS-service> reservations modify
specify-gri true
<OSCARS-service> reservations signal

<OSCARS-service> domains view

<OSCARS-service> domains modify

<OSCARS-service> subscriptions create

<OSCARS-service> subscriptions modify

<OSCARS-service> publishers
create


<OSCARS-servicer> publishers
modify


<OSCARS-operator> users
list
all-users
true
<OSCARS-operator> users query none [1]
<OSCARS-operator> users modify none [1]
<OSCARS-operator> reservations list all-users true
<OSCARS-operator> reservations query all-users true
<OSCARS-operator> subscriptions create

<OSCARS-operator> subscriptions modify

<OSCARS-site-administrator> reservations list my-site true
<OSCARS-site-administrator> reservations query my-site true
<OSCARS-site-administrator> reservations modify my-site true
<OSCARS-site-administrator> reservations
create
my-site
true
<OSCARS-site-administrator> reservations
signal
my-site
true
<OSCARS-site-administrator> subscriptions create

<OSCARS-site-administrator> subscriptions modify

<OSCARS-administrator> users list all-users true
<OSCARS-administrator> users query all-users true
<OSCARS-administrator> users modify all-users true
<OSCARS-administrator> users create

<OSCARS-administrator> AAA list

<OSCARS-administrator> AAA modify

<OSCARS-administrator> subscriptions modify

<OSCARS-administrator> publishers modify

<OSCARS-publisher> publishers create

<OSCARS-publisher> publishers modify


Defaults
[1] manage and view only his own user info
[2] unlimited bandwidth and duration, only modify, list, query and signal own reservations, not input path components.

An OSCARS-engineer can make reservations, see, modify and signal all reservations, including correcting potential errors in the reservation tables, can only see and modify his own user information, and has free rein over the topology. An OSCARS operator can view everybody's reservations and can see and modify only his own user information. An OSCARS user can make reservations of unlimited bandwidth and duration, view, modify and signal his own reservations and see and modify his own user information. An OSCARS admin can manage all user information, but not see or modify reservations.

API for access checks

CheckAccess Implementation

The preferred way to implement access control is to isolate the access checking in one place, called the PolicyDecisionPoint that returns a permit or deny response and is called by all access control points (aka Policy Enforcement Points/ PEP) to see if an action is authorized. The AAA/UserManager class provides two methods for access checking. The first is called any place where a reservation is not being modified and the second by createReservation and modifyReservation.

Standard method


AuthValue UserManager.checkAccess(String user, String resource, String permission);

Initialize the return value to DENIED
Lookup user in userAttribute table to get list of all attributes
For each attribute lookup (attrId,resource,permission) in authorization table.

At end of loop check for SELFONLY and/or MYSITE
Return DENIED, SELFONLY, SITEONLY

Method for create and modify reservations


AuthValue UserManager.checkModResAccess(String user,String resource, String permission, int ReqBandWidth, int ReqDuration, Boolean specify-path-elements);


Start out with
    ReturnValue = DENIED
    bandwidthOK = false
    maxdurationOK = false
    specPathElemsOK = false.
Look up user in userAttributes table and get a list of attributes for this user.
For each attribute look up Authorization(AttrId,resource,permission)
   if an authorization returned
        if the constraint is null
            mark bandwidthOK=true and durationOK=true,
            and returnValue=SELFONLY
       if the constraint is max-bandwidth
            mark bandwidthOK= true if  reqBandwidth < constraintValue
       if constraint is max-duration
            mark durationOK if reqDuration < constraintValue
      if constraint is specify-path-elements
            mark specPathElemsOK = true
      if constraint is all-users
            if value == 1 set returnValue = ALLUSERS
            if value == 0 set returnValue = SELFONLY
At the end of the attribute list
   if bandwidthOK == false or maxdurationOK == false
        return DENIED
if specify-path-element= true and specPathElemsOK == false
        return DENIED
otherwise return ReturnValue