2. Service Administrator's Guide

This is a guide for service administrators who wish to deploy and manage services that support PBAC.

PBAC 2 : Service Administrator's Guide

This is a guide for service administrators who wish to deploy and manage services that support PBAC. The guide assumes that you have already read the introduction.

PBAC provides some web components which can be incorporated into a service's web administration interface. How these components are accessed will depend on your service; consult the service documentation for details.

The policies list

The screenshot below shows the PBAC policy list interface component, which lists each resource type registered with PBAC. The policy types shown in this example are:

Services: There are four service types shown: data-service, job-service, private-account-service and trade-account-service. There is a single resource (not shown here) of each type, representing each service itself (this server hosts once job service, one data service, etc).
Service-specific objects: Each service in this example manages a single type of object (data, job, private-account or trade-account, ). There will be many objects of each type (many accounts, many data stagers and many jobs). A service may manage any number of different types, or none at all, but this example is typical.
Groups: Group objects are not managed by a service in this example (although they could be, in which case there would be a group-service type as well). They are managed here only through the web interface, and their purpose is to group access control lists which should be shared between many resources.

The policies list provides access to the list of resources of each type (by clicking on a policy in the list), and it also allows policies to be deployed, undeployed or updated.

Policy deployment

Services will normally deploy a default policy for each type they require during installation. These policies state which roles can perform which actions (for example "A service-administrator may invoke suspend-account when an account is open"). Normally you will want to change the dynamic access control lists (which control who has the service-administrator role), not the policy itself.

However, if you do need to deploy a new policy:

Enter the name for the resource type (a full URI like the ones shown above).
Select the XML file containing the new policy which you want to upload.
Click on Deploy policy.

For information about creating policy files, see the developer's guide.

To update an existing policy you will need to undeploy the old policy first:

Click on the policy to select it.
Click on the Undeploy button that appears beside it.

While a policy is undeployed, no resources of that type can be accessed (but existing resources of that type are not destroyed). If an invocation on a resource of the type is currently in progress the type is disabled but not undeployed; this allows the operations in progress to complete but prevents new ones from starting. Once all operations are complete, click on Undeploy again to actually undeploy the policy. Note that the disabled status is only held in memory; after restarting the web service container all deployed policies will be enabled.

The resource list

Clicking on a resource type in the policies list will select that type and display an additional table showing all resources of that type. The screenshot below has the private-account resource type selected. An Undeploy policy button appear beside the policy type, and each private account resource is shown in a new table below:

Each resource has a process state. The operations available given a set of process roles depends on the process state. Some resources have very simple state models; the account service has only an active state (besides the UNINITIALISED_STATE and DESTROYED_STATE states, which all resources have), while private accounts can be open or suspended.

Clicking on a resource (such as one of the accounts shown in the lower table) will usually show the dynamic policy for that resource. The dynamic policy controls which process roles a user has.

Setting the dynamic policy

Each resource has a set of match rules. For someone to have a particular process role, they must match at least one Sufficient rule, and no Deny rules. This list of rules is called the dynamic policy, because it is typically updated frequently during the lifetime of the resource.

The trade account service resource type defines a single process role, world, which will grant access to all of the service's public methods which don't take a context. This will usually include any operations that create resources (such as openAccount) and methods for fetching the service's identity or policy.

The figure below shows a typical default dynamic policy for a service resource, which grants anyone the world role.

There are four types of match rule you can add using the web interface (select the type to add and then click on Add):

Subject DN is ...: Upload an X.509 certificate for a particular subject (a person or service) and the CA of their issuer. The rule will only match someone with that exact distinguished name (DN), signed by the CA. Note that only the distinguished name is taken from the user's certificate, not their public key. If the user generates a new key they can still get the role, provided it has the same DN and is signed by the same issuer. This allows the use of short-lived X.509 user certificates.
Certificate is signed by ...: Upload an X.509 certificate for a certificate authority to create a rule that will match anyone whose identity is vouched for by a particular CA. This could be used to ensure that people can't open new accounts under bogus names, for example. If you wish to trust multiple CA's, add a new rule for each one.
Has SAML attribute ...: Upload an X.509 certificate for a SAML issuer and an attribute (name, value) pair. The rule will match anyone with a SAML assertion signed by the issuer asserting that they have the specified attribute.
Member of group ...: Select a group from the list of groups. Anyone who is a member of the group will match. Each group is itself a resource, and has its own set of match rules to determine who is a member.
Anyone: Creates a match rule that matches anyone at all. This would create the default rule shown above.

The figure below shows the dynamic policy for an individual trade account (rather than for the service). This determines who can invokes operations on this account (such as closeAccount or getAccountStatement).

Here we have four process roles, with a single rule for each:

service-admin: Granted to anyone who is a member of the account-service-admins group. Service administrators can suspend accounts.
billing-service: Granted to anyone who is a member of the account-billing-services group. A billing service can check whether someone has the user role, and can record charges on the account.
budget-holder: Granted to james@gria.org, if his certificate is signed by GRIA CA. Budget holders can get the account statement and control who gets the user role.
user: Granted to anyone with a SAML assertion from security@gria.org stating that their supervisor is james. Users can use other services and charge the use to this account.

The use of groups here allows the service administrator to affect the access control policy of many accounts at once. For example, when they deploy a new job service (which should be able to record usage on any client's account) then can make the job service a member of the account-billing-services group, rather than having to update the dynamic policy of every account individually.

Like the service administrator, the budget holder (James) also does not wish to list every permitted user against the account, because then when a new member of staff joined it would be necessary to update the dynamic policy at every service provider he uses. Instead, he grants anyone access if they have a SAML token stating that they work for him. He controls who can get these tokens, valid at many service providers, using his SecurityService.

Next: Developer's Guide

Sections