OSCARS Authorization Policy
- Introduction
- Authorization policy requirements
- Permissions with respect to users
and institutions
- Permissions with respect to
bandwidth and reservations
- Permissions with respect to
topology
- Permission with respect to
authorizations
- Permission with respect to
notification server
- Policy Tables
- Table summary
- Default behaviors
- Mapping of requirements to
authorizations
- Permissions with respect to users
and institutions
- Permissions with respect to
bandwidth and reservations
- Permissions with respect to topology
- Permission with respect to
authorizations
- Permission with respect to
notification server
- Default Tables
- Attributes Table
- Default Authorizations Table
- API for access checks
- CheckAccess Implementation
- Standard method
- 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
- see own profile
- modify own profile
- list all users
- see all user profiles
- add/delete a user
- modify any user profile
- grant or remove attributes for any user
- add, edit or delete 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
- cancel, modify any reservations
- signal any reservations
- cancel, modify and signal any reservations regardless of state
(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 – constains 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:
- OSCARS-user
- OSCARS-engineer
- OSCARS-admin
- OSCARS-service
- OSCARS-operator
- OSCARS-site-administrator
- OSCARS-publisher
- 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 desciption
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 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.
- 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 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.
- 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