Authorization Policy

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

make unlimited reservation
make reservation with bandwidth constraint
make reservation with duration constraint
make reservation with topology constraint
list own reservations
query own reservations
cancel, modify own reservations
signal own reservations
list all reservations starting or terminating at a site
query any reservations starting or terminating at a site
cancel, modify any reservations starting or terminating at a site
list all reservations
query any 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

view topology
modify the topology

Permission with respect to authorizations

view all attributes and authorizations
create, modify or delete attributes
modify authorizations associated with attributes

Permission with respect to notification server

register to publish events
remove publisher registrations
subscribe to events
renew or cancel a subscription

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 – contains an entry for each registered user, containing among other things, user loginId, institution to which the user belongs, certSubject and certIssuer

resources – contains an entry for each resource that needs to be controlled:

reservations - all information about reservations
topology - the description of the network topology
users - all information about users
AA - the attributes, institutions and authorizations
subscriptions - receiving notifications of OSCARS events
publishers - publish OSCARS events

permissions – actions that can be performed on a resource

list – shows minimum information about a reservation or user, shows the authorization tables
query – shows all information about a reservation, user or the topology
create – allows a new user to added, a reservation to be created, a new subscription to be made, or to register as a publisher
modify – allows deletion of a user and modification to a user profile or cancellation or modification of a reservation. Allows modification of the institutions, attributes and authorizations tables. Allows reloading of the topology tables. Also allows renewal and cancellation of subscriptions and deletion of a publisher registration
signal – allows a circuit for reservation to be instantiated or torn down

Attributes – has entries for attributes on which authorization is based. The default attributes are:

There is an attribute-type field which is set to role for all these attributes. There is currently one privilege attribute: specify-path-elements, which is intended to be an additional attribute for some non-privileged users. It is possible to define explicit user attributes for users with specific permissions, e.g. user-david with the attribute type user. So far we have not found the need for any user attributes. For a more detailed description of the attributes see here.

UserAttributes - maps userIds to the attributes they possess

Constraints - The current constraints that are supported are:

none applies to everything, place holder in tables indicating there is no constraint
max-bandwidth (int), applies to create and modify reservation
max-duration (int), applies to create and modify reservation
specify-path-elements (boolean), applies to create and modify reservation
specify-gri (boolean) can a Global Reservation Identifier be specified on create reservation
all-users (boolean), applies to everything except create reservation.
my-site (boolean) currently applies only to list, query, cancel and modify reservations
unsafe-allowed (boolean) allows state changes to a reservation regardless of whether it is an acceptable change. e.g. allows FINISHED->CANCELLED rather than just ACTIVE or PENDING -> CANCELLED. Intended for use by a network engineer trying to correct errors in the OSCARS tables.

authorizations - combines these elements into a row for each action that each user is permitted. Each row consists of an attribute id, a resource id, a permission id, a constraint id and value.

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 redefine 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.

If there is no max bandwidth constraint specified, there is no limit on the bandwidth that may be requested.

If there is no duration constraint, unlimited duration and persistent reservations are allowed.

If no all-users constraint is specified, the default is false (only access to own information is allowed).

If a my-site constraint is specified access to information that is site specific is allowed.

If specify-path-elements is not specified, the default is false and no routers or hops may be input.

If an unsafe-allowed constraint is specified any reservation state change will be accepted e.g. FINISHED -> ACTIVE. Otherwise only reasonable state changes will be made, e.g. PENDING or ACTIVE to CANCELLED (cancel reservation), ACTIVE to PENDING (signal a teardown), PENDING to ACTIVE (signal a setup)

If specify-gri is not specified, a GlobalResourceId may not be specified by the user, but will be automatically generated by the CreateReservation code. This is should be used only by OSCARS-service.

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 AA

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.

If deny is returned, continue

If there is no constraint, remember SELFONLY and continue

If all-users=true is returned, return ALLUSERS

If all-users=false is returned, remember SELFONLY and continue

If my-site constraint is found remember SITEONLY and continue

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

Contact Us

Technical Assistance:

Report Network Problems:

Provide Web Site Feedback: