WebSphere Service Registry and Repository (hereafter called Service Registry) supports fine-grained access control for security. This article describes how fine-grained access control fits into a security model that includes WebSphere Application Server authentication and Service Registry's declarative, or coarse-grained, role-based access control (hereafter called RBAC) using WebSphere Application Server Java™ Authorization Contract for Containers (JACC) support at the Web and EJB container level. It also describes the Service Registry fine-grained access control (hereafter called fine-grained access control) model in more detail than is currently available in the product documentation.
Part 2 of this two-part series recommends some best practices for exploiting fine-grained access control. In that article, we'll describe how to classify Service Registry entities using classes from a user-defined classification system, thus enabling the definition of fine-grained access control rules that restrict access to Service Registry entities based on their type and classification. It also describes best practices for fine-grained access control based on Service Registry entity type and properties, and how to use fine-grained access control to restrict the roles that can modify governance and transition services to certain life cycle states.
Separating authentication, Web/EJB container-level RBAC and fine-grained access control
As a WebSphere Application Server V6.0.2.X (hereafter called Application Server) application, Service Registry supports both Web and EJB programming interfaces.
In Application Server configurations that have global security enabled, requesters attempting to access Service Registry managed entities protected by fine-grained access control would need to be able to:
- Successfully complete WebSphere Application Server authentication at the server level, supplying the credentials or token appropriate for the configured authentication mechanism and user registry.
- Successfully complete Service Registry coarse-grained Java 2 Enterprise Edition (J2EE) JACC role-based access control checks at the Web or EJB container level. The requester's principal (or the principal of a group to which the requester belongs) must be mapped to a role, defined by a Service Registry deployment descriptor, that permits access to the relevant Service Registry API method.
- Successfully complete fine-grained access control checks, at the Service Registry application level, that apply the permissions defined for the roles to which the requester's principal maps (or to which the principal of a group the requester belongs to maps) to determine whether the requester is permitted to execute the requested action on the target artifacts.
This means that for successful requests the requester is authenticated and the request is authorized twice. Although these are separate steps, important considerations arise from the first two steps (Application Server authentication and Application Server J2EE RBAC) that are relevant to the third step (fine-grained access control).
Fine-grained access control is RBAC
Fine-grained access control is role-based. This RBAC is achieved by exploiting the advantages of a common authorization engine. However, fine-grained access control roles are different from the J2EE JACC RBAC roles defined declaratively in the Service Registry deployment descriptor, so you must define them separately. You must also separately define the Application Server User and Group principal mapping to these roles. Once defined, you can add fine-grained access rules, or permissions, to the roles to define their entitlement.
Requesters with principals that map to a given fine-grained access role, or that are members of groups whose group principal maps to a fine-grained access role, have the role's rules applied to each Service Registry API request at the Service Registry application level. Service Registry triggers fine-grained access control checks from Policy Enforcement Points (hereafter called PEPs) within Service Registry support for Create, Retrieve, Update, Delete, Transition and Governance requests. At PEPs, Service Registry determines the access control decision based on the requesting principal's role and the rules associated with the role.
Fine-grained access rules define actions that can be performed on a target set of Service Registry objects. Together, the definitions for a specific action form an authorization domain. Fine-grained access control supports rules for create, retrieve, update, delete (CRUD) actions, as well as actions to support governance (manage governance and transition). Therefore, the Service Registry authorization model currently has six different authorization domains, all separate from each other, as shown in Figure 1. The authorization domain applicable for each Service Registry API request is determined by the request's action.
It's important to understand that different authorization domains are applicable according to a request's action, and are applied separately.
Figure 1. Service Registry authorization model
As shown above, the Create authorization domain (srrCreate) has rules A,B,C and D. In this simple example, the four rules (A,B,C,D) with the action= srrCreate have the following targets:
Now let's say that rules A,B and C have been added to the Service Registry fine-grained access role AliceRole, that the principal-to-role mapping maps Alice to AliceRole, that rule D has been added to the fine-grained access role BobRole, and that the principal-to-role mapping maps Bob to BobRole.
Let's look at a couple of scenarios to see how fine-grained access control works in this situation:
- Alice makes a Service Registry request to create a WSDL document with the description 'foo1'.
When invoked from the Service Registry API Create support PEP, the RBAC check triggers the match of the Service Registry request's action and target. In this case, the Service Registry Create authorization domain applies, so the matching engine is triggered to find a match for the request's action and object equivalent of
srrCreate,/WSRR/WSDLDocument[@description='foo1'])with at least one of the role's Create authorization domain rule's targets (A, B or C), which together form the applicable Service Registry authorization, checkedPolicyConfiguration.
In this case, there is a match with Rule A, so the request is granted.
- Alice makes a Service Registry request to create a WSDL document with the description 'foo4'.
In this case, the request's action and target don't match any rule A,B or C associated with the requester's (Alice) role (AliceRole), so after checking the checkedPolicyConfiguration, the request is not granted. However, before rejecting the request, fine-grained access control uses the common authorization engine to perform a second check.
For a given API request action, fine-grained access controls apply only to the Service Registry objects that are defined by the targets of all the action's authorization rules. Therefore, if the request is for an action or object not in the set of objects defined by the targets of all the action's authorization rules, fine-grained access does not apply.
If you look at the Create authorization domain in Figure 1, you can see that fine-grained authorization applies to the Create action of Service Registry objects defined by the targets of rules A,B,C and D (WSDL documents with the descriptions 'foo1','foo2','foo3' and 'foo4'), which together form the Service Registry authorization, uncheckedPolicyConfiguration, that applies to create requests, and that this authorization does not apply to the Create action of any other Service Registry artifacts (the rest of Service Registry document space represented by the light blue shading).
Alice's request to create a WSDL document with description 'foo4' is an attempt to access a resource to which fine-grained access controls apply (it's part of the Create request's uncheckedPolicyConfiguration). In this case, Alice does not have specific entitlement to the requested resource, only Bob in BobRole does. Therefore, since the resource is in the request's uncheckedPolicyConfiguration, fine-gained access control applies and the request is rejected.
- Alice makes a Service Registry request to create a WSDL document with the description 'foo5'. In this case, no rule restricts access to a create of WSDL documents with the description 'foo5', so although Alice does not have specific entitlement (checkedPolicyConfiguration) to the requested resource, the resource is not part of the request's uncheckedPolicyConfiguration. Hence, fine-grained access control does not apply and the request is granted.
- Alice makes a Service Registry request to delete a WSDL document with the description 'foo1'.
In this case the Delete authorization domain applies. In our simple example, there are no rules in this domain, so the request is granted.
In order to apply specific fine-grained access control to different CRUD actions on sets of Service Registry resources, different explicit rules are needed. These rules are more specific than just Read and Write. Recommendations for fine-grained access rule definition is covered in Part 2 of this series.
Fine-grained access control and Application Server authenticated users
You must configure fine-grained role-based access control to map the User or Group principals to the fine-grained access roles to which they are entitled. This is what we call principal-to-role mapping. The Service Registry Information Center describes how to do this mapping using the wsadmin jacl scripts. The relevant script is addPrincipalToRole.jacl.
The User or Group principals used in the mapping (the first paramenter in the jacl script) are identified by their Application Server User Registry securityName, commonly known as UserId or shortName. However, there is an exception to this when defining group principals when the configured User Registry is LDAP. See the Service Registry Information Center for details.
For each Service Registry request, at the Service Registry API PEP before the common authorization engine is invoked to determine the fine-grained access control decision, the Application Server request's WSSubject context, which is set up after a successful JAAS login, is used to set the common authorization engine Subject handler data, identifying the requester's user principal, as well as the group principal of any group to which the user belongs. When determining the fine-grained access decision, the common authorization engine uses this Subject handler data to determine the requester's User and Group principals, which it uses along with the principal-to-role mapping to find the requester's role and, thus, the requester's fine-grained access rule entitlement.
Fine-grained access control and Application Server JACC RBAC
Though different by default, fine-grained access control and Service Registry declarative, or deployment descriptor, J2EE RBAC are both configured with the roles User and Administrator. In order to access Service Registry EJB and Web API methods, a user must at least be mapped to the Service Registry deployment descriptor-defined J2EE User role. This coarse-grained access control is the enforcement of J2EE JACC RBAC security at the Web and EJB container level, which limits access to these interfaces only to principals mapped to the User role.
By default the special subject ALL_AUTHENTICATED is mapped to both the Service Registry User and Administrator roles at installation. Unless modified, this means that any Application Server authenticated user can access Service Registry Web and EJB APIs. However, most installations will redefine the mapping of ALL_AUTHENTICATED users to the User and Administrator roles, and replace it with a mapping that restricts access to only those Users or Groups who are permitted, rather than allow access by all authenticated users. There is no restriction on the definition of other J2EE roles with appropriate User and Group mappings.
As described earlier, in order for a Service Registry API request to be successful, the requester must have succeeded in Application Server authentication and in the coarse-grained J2EE RBAC at the Web or EJB container level before accessing the Service Registry API support. Part of that API support is fine-grained access control, applied at PEPs, which determines whether the requester is entitled to take the request's action on the target resource.
Fine-grained access control is also role-based, which means that it determines entitlement by finding the requester's role (in the Service Registry authorization principal-to-role mapping) and then applying the authorization role's rules.
When Service Registry is installed, it only has fine-grained access control rules that relate to governance and transition in support of the basic governance model. Apart from these governance-related permissions, there are no fine-grained access control rules limiting the access of CRUD actions on Service Registry resources.
Also, depending on the options selected during Service Registry installation, it's possible that fine-grained access control principal-to-role mapping maps VirtualPrincipal.AllAuthenticatedUsers to the fine-grained access control User and Administrator roles. Most installations will replace the VirtualPrincipal.AllAuthenticatedUsers mapping to the fine-grained access control User and Administrator roles with a mapping of the specific Users and Groups that are permitted to invoke the governance permissions associated with these roles.
Most installations will also define other fine-grained access control roles, add rules (probably CRUD-related) defining the roles' entitlement, and map the User and Group principals to these roles ensuring Service Registry API users have fine-grained access to the resources they are entitled to access and are prevented from accessing those to which they aren't entitled.
Fine-grained access control configuration and XACML
Service Registry RBAC configuration is supported by a set of wsadmin jacl scripts. You can use these scripts to change the default fine-grained access control configuration, including adding or removing roles, mapping new User and Group principals to roles, and changing the definition of roles' entitlements by adding or removing permissions.
Although these changes are immediately applied to Service Registry runtime behavior, you must specifically persist the fine-grained access control policy and role mapping in order to ensure that the new configuration is used the next time Service Registry is started. You can use the jacl scripts, persistPolicy.jacl and persistRoleMappings.jacl, to do this. These scripts ensure that the XACML corresponding to the new configuration is saved in the Service Registry system configuration files, SrrAuthzPolicyXacml and SrrAuthRoleMappingXacml.
You can modify fine-grained access control configuration at the XACML level by accessing the configuration XACML (using getPolicyConfiguration.jacl and getRoleMappingConfiguration.jacl), and explicitly load a new fine-grained access control configuration's XACML (loadPolicyConfiguration.jacl, loadRoleMappingConfiguration.jacl). However, this method of updating configuration is not recommended because of the potential for errors. Instead, it's strongly recommended that you use the supplied jacl scripts to change the configuration
This article described how fine-grained access control works in Service Registry, including how it relates to Application Server authentication and J2EE declarative role-based access control. After reading this article, you should understand the simple, but powerful features provided by Service Registry fine-grained access control for protecting sets of Service Registry resources, even down to the level of a single resource.
Part 2 of this series describes best practices for using fine-grained access control to provide selective control of Service Registry artifacts based on classifications or properties.
The authors would like to thank the following for their contributions in shaping WebSphere Service Registry and Repository access control architecture and design: John Colgrave, David Lin, Satoshi Hada, Vernon Murdoch, Kerry Gunn.
- Advanced authentication in WebSphere Application Server (IBM WebSphere Developer Technical Journal, 2005): Learn more about WebSphere Application Server authentication.
- WebSphere Application Server V6 Information Center: Learn more about JACC support in Application Server in the topic "JACC support in WebSphere Application Server".
- WebSphere Application Server V6 Security Handbook: Learn more about security and how to design and implement secure solutions with WebSphere Application Server V6. Chapters 4, 6, 7, and 11 are particularly relevant.
- WebSphere Service Registry and Repository Information Center: Complete product documentation for Service Registry.
- developerWorks WebSphere Web services zone
- developerWorks WebSphere business process management zone