The IBM WebSphere Application Server Feature Pack for Service Component Architecture (SCA) provides a framework for describing abstract policy requirements through SCA intents, and for applying particular capabilities or constraints on services and references through SCA policy sets. An SCA intent is an abstract assertion about a specific Quality of Service (QoS) used to describe requirements of SCA components, service, and references. A policy defines a particular capability or constraint. Policies in SCA are associated with services and references via the PolicySet element. Intents are typically used by developers to specify the broad assertions needed for the intended behavior of a service. The assembler and deployer have options to associate the appropriate concrete policy using these intents as their guide.
The feature pack supports:
- Reliable messaging
- Interactive (based on existing standards for WS Policy and WS Policy
- Reliable messaging
- Security policy
- Security identity
- Transaction policy
- Security policy
- Interactive (based on existing standards for WS Policy and WS Policy attachments):
Interactive intents and policies refer to constraints that influence the interaction between services and references. Implementation types specify how the SCA container should condition the environment for proper execution of the components.
Interactive intents and policies
Authentication, confidentiality, and integrity
Applications use security intents when there is a need to protect access to data and services or a need to protect the data transferred between clients and services:
- The authentication intent indicates that a client must authenticate itself in order to invoke an SCA service.
- The confidentiality intent indicates that the content of a message is protected and accessible only to those who are authorized.
- The integrity intent indicates the need for assurance that a message was not tampered with or altered during transmission between a sender and receiver.
The authentication, confidentiality, integrity, and reliable messaging security intents are currently supported by the Feature Pack for SCA using the WS binding only. These security intents can be qualified with the "transport" qualifier if the intent is enforced at the transport layer of the communication protocol, and the "message" qualifier if the intent is realized at the message level.
In case of the confidentiality intent, specifying the transport qualifier causes data to be encrypted by the transport protocol (such as https), while specifying the message qualifier would encrypt the message itself (just the body or with the headers).
Figure 1 depicts how SCA integrates intents and policies.
Figure 1. QoS integration
Security intents are specified on the binding.ws element. For example, when the data transferred to and from a referred service needs to be confidential, and this confidentiality needs to be achieved by encryption of the message, you would specify the lines below (for the "sampleReference" service) in its SCDL file:
<reference name="sampleReference"> <binding.ws requires="confidentiality.message" ... /> </reference>
To specify a requirement for all access to a service to be authenticated by the transport protocol, the SCDL file might look like this (for the "AccountService" service):
<service name="AccountService"> <binding.ws requires="authentication.transport" ... /> </service>
The concrete policy that guarantees this assertion is provided by WebSphere Application Server V7.0 and can be used by SCA services, references, and components.
You can attach these concrete policy sets to service providers and service references using the WebSphere Application Server administrative console. An instance of a policy set consists of a collection of policies. For example, the WS-I RSP default policy set consists of instances of the WS-Security, WS-Addressing, and WS-ReliableMessaging policy types. A policy set is identified by a name that is unique across the cell.
Services can be configured by attaching them to a provider, its endpoints, or operations. Likewise, a policy set can be attached to a service reference, its endpoints, or operations. WebSphere Application Server also supports attaching policy sets to all references or all providers in a composition unit.
WebSphere Application Server provides preconfigured policy sets that you can use as a starting point and customize to your particular requirements. An attached policy set can be further customized by using bindings that are specific to the composition unit (application-specific bindings) or by using general bindings. General bindings are global to the security domain can be shared across applications and composition units.
Figure 2. Importing additional policy sets from the default repository
An SCA component service or reference can be configured to require specific Web service policy sets by specifying its requirements at the binding element's qos.wsPolicySet attribute. The SCDL snippets below specify the "WSHTTPS Default" policy set attached to a service element (Listing 3) and a reference element (Listing 4):
<service name="AccountService"> <binding.ws qos.wsPolicySet="WSHTTPS default" ... /> </service>
<reference name="AccountServiceReference"> <binding.ws qos.wsPolicySet="WSHTTPS default" ... /> </reference>
Several common policy sets are already imported and ready for you to attach to your service and client composition unit. For your reference, the current list of preconfigured policy sets already imported for your use are shown in Figure 3.
Figure 3. Policy sets that are imported in the Websphere Application Server admin console
The reliable messaging policy enables you to control the reliability of requests between services, including sequence of delivery and guarantee of delivery. The intents are applied at the operation level via the binding element, and the concrete policies are provided by WebSphere Application Server's WS-ReliableMessaging policy set. The level of QoS achieved by WS-ReliableMessaging depends on the level of durability and transaction support provided by the data store being used to manage the reliable messaging state. The Feature Pack for SCA recognizes these qualities of service, provided by WebSphere Application Server using SOAP over HTTP binding:
- Unmanaged-non-persistent is non-transactional and provides for resending messages lost on the network; however, it will lose pending requests when the server goes down, and it does not work in a cluster.
- Managed-non-persistent uses a message engine to store requests, and so can recover from loss of messages due to network and server failures. Messages that are managed-non-persistent, however, are lost when the message engine is restarted. These types of requests can be deployed using clusters, as well as with a single server setup.
- Managed-persistent is the most reliable, using the message engine and store to persist messages across server and message engine restarts.
A use case that requires messages for a service be stored in a message engine and persist across server restarts would need to specify the following in its SCDL (for the "OrderStatusService" service):
<binding.ws wsdlElement="http://jdbc.sca.orderstatus#wsdl.port (OrderStatusServiceWebService/OrderStatusServiceSOAP11port)" qos:wsPolicySet="WSReliableMessaging persistent" />
An application running inside a Web container and using a managed QoS can use WS-ReliableMessaging to provide transaction recoverable messages. Properties supported include:
- A JAX-WS request context map contains the enableTransactedOneWay property, which can be set to true if this behavior is needed.
- The inOrderDelivery property is available as an option either in the admin console or by setting that property to "true" via the wsadmin tool when configuring the WS-ReliableMessaging policy.
See Resources for more information.
SCA authorization policy controls the users, groups, and roles that can access SCA resources. SCA uses policy assertions of <allow>, <deny>, <permitAll>, and <denyAll> on user-roles to control the access. Security identity declares the role under which the operation will be performed. SCA defines a Java™ EE-like role-based permission model. These security assertions are created in a definition.xml file using a policySet SCA element. The definition.xml file must be packaged within the same JAR file containing the SCA resources that need access control.
The policy administrator creates a file named definition.xml with SCA policySets like this:
<?xml version="1.0" encoding="UTF-8"?> <definitions xmlns="http://www.osoa.org/xmlns/sca/1.0" targetNamespace="http://application.workload" xmlns:sca="http://www.osoa.org/xmlns/sca/1.0"> <policySet name="ERWW1AdminPolicy" appliesTo="sca:implementation.java"> <authorization> <allow roles="policyadmin superintendent"/> </authorization> <securityIdentity> <runAs role="policyadmin"/> </securityIdentity> </policySet> </definitions>
The assembler then attaches this SCA policySet to the SCA composite; the portion of SCDL code that attaches the policySet is shown here:
<component name="ConvertInputOutputServiceComponent"> <implementation.java class="convert.inputoutput.sca.ConvertServiceImpl" policySets="erww:ERWW1AdminPolicy" />
The definition.xml file in Listing 7 illustrates an SCA policySet that will apply to implementation.java and, when attached, will enable user roles policyadmin and superintendent to invoke the service and perform the operation ConvertService() under the “policyadmin” security identity.
The deployer then assigns users or groups to the roles defined for the composite, and assigns a user to the runAs roles defined in the composite.
The definition.xml file must be packaged in the same resource (a JAR or EAR file) as the composite that refers to it. Role assignments are made at the configuration unit scope, and the policy that it inherits from its ancestor element and will apply if there is no explicit policy assertion attached to the element. When no policySets are attached, the default is to run unprotected. When multiple policySets or allow/deny combinations are encountered, the deny roles override the allow roles and conflicting elements, like both denyAll and permitAll, will cause validation errors.
Be aware that SCA authorization policy is not supported in composites packaged as WAR (Web Archives) files.
The Feature Pack for SCA provides implementation and interaction policies to provide transactional QoS for both components and interactions. The transaction policy can be specified using intents on component implementations, bindings in the SCDL, or language-specific annotations. The SCA runtime provides a transactional environment for the components to interact and coordinate with each other.
Implementation transactional intents
The intents relating to transactions are specified at the implementation element in SCDL.
- Global transactions
The SCA managedTransaction.global intent is used to indicate that a component will operate under a global transaction. This intent defines a unit of work scope, within which the transaction is atomic. The transaction can use multiple transactional resources or multiple remote service provider running distributed requests. The SCA container uses a two phase commit to achieve atomicity when multiple transactional resource managers are used. Global transactions can be propagated to services used by this component. Listing 8 shows an example of using managedTransaction.global.
<component name="PaymentComponent"> <implementation.java class="payment.PaymentServiceImpl" requires="managedTransaction.global"/> </component>
- Local transactions
A local transaction is one in which the component needs to operate in an extended resource manager local transaction (RMLT) without a global transaction in effect. Such a transaction is said to be running in a local transaction containment (LTC) which ends when the service method ends:
- managedTransaction.local defines a transaction scope that enables
access to multiple resource managers. All the interactions are requested to
commit on successful completion of the scoping service method, or else be
implicitly rolled back when a non-business exception is encountered. However,
individual RMLTs can independently fail without affecting interactions with
other RMLTs. Local transactions cannot be propagated. Below is an example of an SCA component that uses managedTransaction.local:
<component name="PaymentComponent"> <implementation.java class="payment.PaymentServiceImpl" requires="managedTransaction.local"/> </component>
- noManagedTransaction components run without a managed transaction, neither global nor LTC. The application or the individual resource manager is responsible to commit or rollback interactions. For example:
<component name="PaymentComponent"> <implementation.java class="payment.PaymentServiceImpl" requires="noManagedTransaction"/> </component>
- managedTransaction.local defines a transaction scope that enables access to multiple resource managers. All the interactions are requested to commit on successful completion of the scoping service method, or else be implicitly rolled back when a non-business exception is encountered. However, individual RMLTs can independently fail without affecting interactions with other RMLTs. Local transactions cannot be propagated. Below is an example of an SCA component that uses managedTransaction.local:
Interaction transaction intents
These intents are specified at the interaction level, typically in the binding elements of the SCDL. The supported interaction intents are:
- The suspendsTransaction intent will cause the caller's transaction context to not to be propagated to the invoked service. When specified on the reference element, this intent has the effect of not propagating the transaction context of the calling service. When specified on the service element, it has the effect of not participating in the caller's transaction and starting a new global transaction.
- When specified on a reference, the propagatesTransaction intent indicates that the current transaction context will be propagated to the called service. When specified on a service, the intent indicates that the service will run under the caller's global transaction, if one is present, or it will start a new one if no global transaction is present. It is an error to propagate transactions on one-way services. It is also an error to specify interaction intents when the component is under the noManagedTransaction implementation intent.
The SCA policy framework enables you to specify service constraints at a broader level using SCA intents, leaving the choice of concrete policy to the assembler, deployer, or administrator. This article described the main features of the SCA intents and policySets supported by the Feature Pack for SCA, their behavior in WebSphere Application Server V7 and common ways to utilize them. These capabilities empower the assembler to provide a combination of services that can behave differently based on its operating environment and needs -- without changing the underlying business logic itself -- and in keeping with SCA concepts. A sample use case and a typical implementation is illustrated in a sample user scenario, which follows.
Use case: Pay for items
Description: This use case illustrates a customer completing a payment transaction. The transaction involves the customer providing confidential information to enable the application to charge a preset account, and then mark an order as paid.
Preconditions: This use case is shown only for the payment portion of the given application. The user login and password information has already been setup and activated. The payment is to be made from a choice of customer accounts with sufficient funds for completing the transaction.
- Customer enters the site's URL.
- Customer logs in with a valid user ID and password.
- Application displays a list of merchandise for the customer to select.
- Customer selects one or more items from the list to purchase.
- Customer indicates intent to pay for the selected items.
- Application displays list of pre-configured payment accounts that qualify for the amount due.
- Customer chooses payment method.
- Application prompts customer for secure payment information.
- Customer provides secure payment information.
- System charges the account.
- Application marks the order as paid.
- System logs the payment transaction and provides customer with a confirmation number.
Alternate flow 1: Step 2 fails. User is directed back to login prompts.
Alternate flow 2: Step 9 fails authentication. User returns to step 6.
Alternate flow 3: Steps 10 through 12 fail. User returns to step 6.
The use case illustrates one scenario where some of the SCA QoS intents and policies can be demonstrated. In the flow above:
- The requirement for authentication in step 2 can be achieved using a WS policy set, WSHTTPS.
- The information passed by the customer in step 8 is confidential and the confidentiality SCA policy intent will ensure protection of sensitive information.
- The operations between steps 10 and 12 needs to be a single atomic operation, and SCA transaction intent can be specified to achieve that.
A typical implementation would include the following components:
- Client user interface
- InputPortlet: Collects input from the customer and displays output data based on the control flow.
- Server services
- WelcomeService: Provides information for the InputPortlet to display as part of its welcome screen.
- ListItemsService: Retrieves a list of items from a permanent store for display to the customer.
- PaySessionService: Orchestrates the payment session.
- ProcessPayment: Posts and authorizes the payment. This service returns a payment ID.
- updateItems: Marks the items as paid if payment was processed successfully.
- LogHistory: Logs an audit trail for the payment transaction.
This typical implementation would have a technical flow similar to this:
- InputPortlet displays the site's welcome panel.
- InputPortlet uses the Web services LTPA WSSecurity default policy set to
ensure the message. The service side the SCDL would look like Listing 11, and
the reference side SCDL would look like Listing 12.
<service name="WelcomeService"> <binding.ws wsdlElement="http://session.pay.WecomeService/#wsdl.port (WecomeService/WecomeService)" requires="authentication.transport" qos:wsPolicySet="LTPA WSSecurity default" ... /> </service>
<reference name="WelcomeService" target="WelcomeServiceComponent/WelcomeService"> ... <binding.ws wsdlElement="http://sca.WelcomeService#wsdl.port (WelcomeServiceWebService/WelcomeServiceSOAP11port)" qos:wsPolicySet="LTPA WSSecurity default"/> </reference>
The WSSecurity concrete policy set LTPA is attached to the service at run time. For the service side, you can attach the policy set by going to the administrative console and navigating to Applications => Application Types => Business-level applications. Navigate to the business level application containing the WelcomeService, then to the composition unit (CU) containing the WelcomeService, and click on Service provider policy sets and bindings (Figure 4).
Figure 4. Panel to manage CU, to attach policy set
On the next panel (Figure 5), check the WelcomeService row and click on the Attach Policy Set pull down menu. Choose LTPA WSSecurity default from the list and follow the prompts to save the configuration.
Figure 5. Attach policy set
On the client side, access the policy sets and binding panel by following the same path as the service side, but choose the client BLA, composite, and service instead.
- The information displayed in subsequent service calls needs to be confidential. The ListItemsService can specify the confidentiality intent:
<service name="listItemsService"> <binding.ws requires="confidentiality.message" qos:wsPolicySet="LTPA WSSecurity default" ... /> </service>
The step to attach the concrete policy and binding is exactly the same as step 2.
- The PaySessionService collects the customer information and calls the processPayment service, updateItems service, and logHistory service, in that sequence. The service then returns a paymentconfirmation ID for the customer if it completes without errors. The processPayment and updateItems services are required to be part of a single atomic transaction. Hence, the PaySessionService has the following in its SCDL file:
<component name="PaymentComponent"> <implementation.java class="payment.PaymentServiceImpl" requires="managedTransaction.global"/> <reference name="processPayment" target="ProcessComponent" requires="propagatesTransaction" /> <reference name="updateItems" target="UpdateComponent" requires="propagatesTransaction" /> <reference name="logHistory" target="AuditComponent" requires="suspendsTransaction" /> </component>
The transaction intents do not need an explicit policy set attachment if the services and references are not using binding.ws. However, when transactional behavior is needed over WS binding, the qos:wsPolicySet attribute should be set to a value of "WSTransaction," or else this WS policy set must be attached via the admin console using the same step.
- Delivery of messages to PaySessionService needs to be guaranteed by setting
the WS-ReliableMessaging persistent SCA policySet:
<component name="PaymentComponent"> <service name="PaySessionService "> <interface.wsdl xmlns:wsdli="http://www.w3.org/2006/01/wsdl-instance" interface="http://session.pay#wsdl.interface(PaySessionService)" wsdli:wsdlLocation="http://session.pay PaySessionService.wsdl"/> <binding.ws wsdlElement="http://session.pay#wsdl.port(PaySessionWebService/ PaySessionServiceSOAP11port)" qos:wsPolicySet="WSReliableMessaging persistent"/> </service> <reference name="processPayment" target="ProcessComponent" requires="propagatesTransaction" /> <reference name="updateItems" target="UpdateComponent" requires="propagatesTransaction" /> <reference name="logHistory" target="AuditComponent" requires="suspendsTransaction" /> </component>
In addition to the previously explored procedure for attaching the policy set, the WS-ReliableMessaging persistent policy set requires a bus and a messaging engine to be used. Policy bindings then need to be created for both the service and client. For this example, a bus needs to be created and a messaging engine needs to be configured:
- To create a bus, from the admin console, navigate to Service Integration =>
Buses => New. Enter a name, then click Finish.
Figure 6. Bus after creation
- Next, you will create a bus member. Click on the newly created bus, then select Bus members => Add. Choose the server or cluster to add the bus from the drop down menu. Click Next.
- On the next panel, check Enable messaging engine policy assistance and High availability options, then click Next.
- Choose a file or data store for persistence, then Next.
- Click Is the message store configured. Customize the values as needed, then click Next.
- Tune performance parameters if needed, then click Finish to add the bus member and create the messaging engine. At this point, you must restart the servers.
Next, create the service and client policy set bindings:
- To create the service policy set binding, navigate from the admin console to
Services => Policy Sets => General Provider policy set bindings. Click
New. Enter a Bindings configuration name, such as
PayServiceBind(Figure 7) then click Add.
- Select WS-ReliableMessaging from the list. Choose the previously created bus and messaging engine, then click OK.
- Repeat these steps to create client policy set bindings: from the admin
console, select Services => General client policy set bindings, and creating a new client binding.
Figure 7. Create new service policy set binding
- Next, attach the policy set bindings for the client and service. From the admin console, navigate to Application types => Business Level Application => Paymentcomposite => PaySessionComposite => Service Provider Policy Sets and Bindings.
- Select PaySessionService, click on Assign
Binding, and choose the service binding created above from the drop down
Figure 8. Assign binding to service
- Perform the same step on the client side by navigating to the client BLA, CU, and client binding panels.
This completes the configuration steps needed to attach the WS-ReliableMessaging policy set to the application.
- To create a bus, from the admin console, navigate to Service Integration => Buses => New. Enter a name, then click Finish.
- A new payment ID is returned as a confirmation of a successful completion of all steps.
- More in this series
- Service Component Architecture Specifications
- Open SOA
- OASIS Open CSA technical committees
- Apache Tuscany
- SCA Policy Framework Specification v1.0
- ACID Transaction Policy in SCA v1.0
- Information Center: Web services policy sets
- Information Center: Learning about WS-ReliableMessaging
- IBM developerWorks WebSphere