Editing module deployment properties


Editing module deployment properties

In IBM Integration Designer, any changes that you directly make to module deployment properties in deployment descriptor files are typically overwritten when the deploy code is next regenerated. However, you can use the module deployment editor to specify and retain changes to module deployment properties, such as changes to the web services security settings. The module deployment editor saves your changes to a deployment side file, which is used to automatically update the module deployment properties in the deployment descriptor files whenever the deploy code is regenerated or the module is installed on the server.

By design, custom SCA application names are deployed with the naming convention "Application_Name"+"App". This is a restriction imposed by SCA. You should not modify the application name when you are using the administrative console wizard to manually deploy the application. This may cause conflicts with the module deployment properties. The following topics describe the key concepts in editing module deployment properties and explain how to open and use the module deployment editor.


Module deployment properties

In IBM Integration Designer, you can use the module deployment editor to specify and retain changes to module deployment properties in deployment descriptor files.

Use the module deployment editor, you can accomplish numerous tasks relating to module deployment properties, such as:

Editing module deployment properties is a task that is best suited to advanced users of IBM Integration Designer. This is especially true of module deployment properties that relate to web services security, which requires a solid understanding of the OASIS WS-Security specification.

To work with the module deployment editor, you should be familiar with the Rational Application Developer tools that are used to manage properties in the deployment descriptor files, such as the web services editor and the EJB deployment descriptor editor. However, you can successfully use the module deployment editor with only a basic understanding of modules and web services exports and imports.

When use the module deployment editor to change the deployment properties for a module, your changes are saved to an XML deployment side file named ibm-deploy.scaj2ee that resides directly under your module in the Physical Resources view of the Business Integration perspective. The side file automatically updates the module deployment properties in the deployment descriptor files whenever your deploy code is regenerated during a build or when your module is installed on the server. This ensures that your changes are retained even though the deploy code is periodically regenerated.

The deployment side file contains the name and relative folder location of any web services imports or exports. If you choose to rename or move an import or export using refactoring, the name and folder location of the import or export is automatically refactored in the deployment side file.

Although the module deployment editor documentation provides basic information on using the editor to manage module deployment properties, detailed information on managing web services and their deployment properties is found in the IBM redbook WebSphere Version 6 Web Services Handbook - Development and Deployment (SG246461), which is available at the following IBM Redbooks site: http://www.redbooks.ibm.com



WS-Security specification

The web services WS-Security specification describes enhancements to SOAP messaging to provide quality of protection through message integrity, message confidentiality, and single message authentication. These mechanisms can be used to accommodate a wide variety of security models and encryption technologies.

A web service is a self-contained, self-describing modular application that can be published, discovered, and invoked over a network using standard network protocols. Typically, XML is used to tag the data, SOAP is used to transfer the data, WSDL is used for describing the services available, and UDDI is used for listing the services that are available.

The WS-Security specification is one of several security standards that can be used to secure a web service. It provides message-level security, which means it is independent of the transport protocol and can be used for any web service binding, such as HTTP, SOAP, and RMI. It also provides a general-purpose mechanism for associating security tokens with message content.


Security mechanisms

The WS-Security specification provides the following three mechanisms for securing web services at the message level:

Authentication

This mechanism uses a security token to validate the user and determine whether a client is valid in a particular context. A client can be an end user, machine, application, or import. Without authentication, an attacker can use spoofing techniques to send a modified SOAP message to the service provider.

Integrity

This mechanism uses message signing to ensure that information is not changed, altered, or lost in an unauthorized or accidental way. When integrity is implemented, an XML digital signature is generated on the contents of a SOAP message. If the message data changes illegally, the signature is not validated. Without integrity, an attacker can use tampering techniques to intercept a SOAP message between the web service client and server and then modify it.

Confidentiality

This mechanism uses message encryption to ensure that no unauthorized party or process can access or disclose the information in the message. When a SOAP message is encrypted, only a service that knows the key for confidentiality can decrypt and read the message. Without confidentiality, an attacker can use eavesdropping techniques to intercept a SOAP message and read the contained information.

In this release of IBM Integration Designer, basic authentication is the only WS-Security mechanism that is thoroughly documented. If you want detailed information on advanced authentication, integrity, or confidentiality, you should consult the web resources listed in the following table.

Web resource Location
OASIS WS-Security specification http://www.oasis-open.org/specs/index.php#wssv1.0
Chapters 9 and 21 in the IBM redbook SG246461 WebSphere Version 6 Web Services Handbook - Development and Deployment http://www.redbooks.ibm.com/abstracts/sg246461.html?Open

Although the redbook that is mentioned in the table shows how the web services and EJB deployment descriptor editors of Rational Application Developer are used to edit the WS-Security properties, there is a direct mapping between these editors and the IBM Integration Designer module deployment editor.


Authentication

In authentication, a security token is inserted in the request message of an import. Depending on the type of security token that is being used, the security token can also be inserted in the response message of an export.

Several types of security tokens are used in authentication, including:

Username tokens are used to simply validate user names and passwords. They are the sole means of security in basic authentication (and for this reason, basic authentication should only be used in secure networks like HTTPS sites or corporate intranets). When a username token is received by a web service server, the user name and password are extracted and passed to a people directory for verification. If the user name and password combination is valid, the result is returned to the server and the message is accepted and processed. When used in basic authentication, username tokens are typically only passed in the request message of an import and they are not passed in the response message of an export.

In this release of IBM Integration Designer, username tokens (as used in basic authentication) are the only form of security token that is thoroughly documented. If you want detailed information on other types of security tokens, such as binary tokens or custom tokens, you should consult the web resources listed in the table.


Message security architecture

The WS-Security message security architecture consists of four major components.

These components are described individually in the following table.

Component Description
1 Request generator On the client (import) side, the request generator defines the security constraints on the outgoing SOAP request message with one or more security mechanisms, such as digital signing, encryption, or security tokens.
2 Request consumer On the server (export) side, the request consumer defines the security constraints on the incoming SOAP request message, such as ensuring that:

  • The required integrity parts are signed and the signature is verified.
  • The required confidential parts are encrypted and subsequently decrypted.
  • The security tokens are validated.

The WS-Security properties defined for the request consumer must match those that were defined for the request generator.

3 Response generator On the server (export) side, the response generator defines the security constraints on the outgoing SOAP response message with one or more security mechanisms, such as digital signing, encryption, or security tokens.
4 Response consumer On the client (import) side, the response consumer defines the security constraints on the incoming SOAP response message, such as ensuring that:

  • The required integrity parts are signed and the signature is verified.
  • The required confidential parts are encrypted and subsequently decrypted.
  • The security tokens are validated.

The WS-Security properties defined for the response consumer must match those that were defined for the response generator.


Advantages of WS-Security

There are numerous advantages to using WS-Security, such as:



Module deployment editor

In IBM Integration Designer, the module deployment editor is the designated tool for editing module deployment properties for web services exports and imports. It enables you to specify and persist changes to module deployment properties in deployment descriptor files. The module deployment editor features a simple user interface that enables you to manage module deployment properties.

You can open the module deployment editor from either the Business Integration view or the Physical Resources view of the Business Integration perspective, or from the properties of web service exports in the assembly diagram editor. The module deployment editor is shown in the following figure:

As shown in the figure, there are two main pages of the module deployment editor:

These two pages are described in the following sections.


Design page

The Design page provides a graphical user interface that enables you to view and configure deployment properties. The Design page contains two main sections:

The Overview section contains a list of artifact types, such as Web Services Exports. The details section enables you to view and configure deployment properties for any artifact that is selected in the Overview section.


Source page

The Source page displays the underlying XML source code for artifacts in the Module Deployment Editor. Using the Source page, you can view and configure deployment properties. The Design and Source pages are automatically synchronized with each other whenever changes are made in one page or the other. Although you can use the Source page to configure deployment properties, it is a best practise to always use the Design page to configure deployment properties, and use the Source page for viewing the underlying XML source code.



Mappings to Java EE deployment descriptor editors

The module deployment editor maps to several Java EE deployment descriptor editors.

The following table shows you how the module deployment editor maps to the pages and sections in the corresponding Java EE deployment descriptor editors.

Module deployment editor mapping

Module Deployment Editor Java EE Deployment Descriptor Editors
Scope   Section Editor Page Section File
Application project   Resource References web deployment descriptor editor References Various web.xml
Security Role Application deployment descriptor editor Security Various application.xml
web services eExports General Context Root Application deployment descriptor editor Source context-root tag application.xml
Security Roles Web deployment descriptor editor Security Security Roles web.xml
Security Constraints Web deployment descriptor editor Security Security Constraints web.xml
URL Mappings Web deployment descriptor editor Servlets URL Mappings web.xml
Handlers Web services editor Handlers Various webservices.xml
Security Web deployment descriptor editor Servlets Security Role References web.xml
Web services security extensions (including WS-Security) All Web services editor Extensions All webservices.xml
Web services security extensions (Router Module) All Web services editor Extensions All webservices.xml
Web services binding configurations (including WS-Security) All Web services editor Binding configurations All webservices.xml
Web services imports   Handlers Web deployment descriptor editor WS handler Various web.xml
Web services client security extensions (including WS-Security) All Web deployment descriptor editor WS extension All web.xml
Web services client binding configurations (including WS-Security) All Web deployment descriptor editor WS binding All web.xml



Opening the module deployment editor

You can open the module deployment editor from the Business Integration view, Physical Resources view, or the assembly diagram of your module.

To open the module editor:

  1. Ensure the Business Integration perspective is open.

  2. Complete one of the following steps:

    • To open the module deployment editor from the Business Integration view, right-click your module and select Open Deployment Editor.
    • To open the module deployment editor from the Physical Resources view, expand your module and then right-click the deployment side file ibm-deploy.scaj2ee and select Open with > Module Deployment Editor. The deployment side file will not exist in the Physical Resources view unless you have previously opened the module deployment editor.
    • To open the module deployment editor from the assembly diagram, right-click a web service export in the assembly editor and click the Properties tab to open the Properties view, then select the Binding tab and click the Configure button.



Editing WS-Security properties

Use the module deployment editor, you can edit WS-Security properties for your web services exports and imports. The high-level tasks in editing these web services security properties are essentially the same regardless of whether you are securing your exports and imports with authentication, signing, or encryption.

The high-level tasks in editing WS-Security properties are:

These tasks are described in the following steps:

  1. Set the request generator properties for the import:

    1. In the Business Integration view, right-click the module that contains your import and select Open Deployment Editor. The module deployment editor opens.

    2. Select the Design tab.

    3. Select the Web Services Imports node.

    4. Click Add and select Web Services Client Security Extensions, then click OK. The Web Services Client Security Extensions node is added under Web Services Imports and the Component Scoped Reference node is added under the Web Services Client Security Extensions node.

    5. Select the Component Scoped Reference node.

    6. Click Add and select Service Reference, then click OK. The Select a Web Service Import window appears.

    7. In the window, select your web service import and click OK.

    8. Select the Port Qualified Name Binding node.

    9. Click Add and select Client Service Configuration, then click OK.

    10. Select the Client Service Configuration node.

    11. Click Add and select Request Generator Configuration, then click OK.

    12. Add nodes to the Request Generator Configuration node to specify properties for the security mechanism that you are implementing, such as security token, integrity, confidentiality, and timestamp.

    13. Select the Web Services Imports node.

    14. Click Add and select Web Services Client Binding Configurations, then click OK. The Web Services Client Binding Configurations node is added under Web Services Imports and the Component Scoped Reference node is added under the Web Services Client Binding Configurations node.

    15. Select the Component Scoped Reference node.

    16. Click Add and select Service Reference, then click OK. The Select a Web Service Import window appears.

    17. In the window, select the import to use and click OK.

    18. Select the Port Qualified Name Binding node.

    19. Click Add and select Security Request Generator Binding Configuration, then click OK.

    20. Add nodes to the Security Request Generator Binding Configuration node to specify properties that correspond to the extension properties that you specified under Request Generator Configuration, such as token generator, signing information, and encryption information.
    21. Press Ctrl-S to save your changes to the deployment side file ibm-deploy.scaj2ee in the Physical Resources view.

  2. Set the request consumer properties for the export:

    1. In the Business Integration view, right-click the module that contains your export and select Open Deployment Editor. The module deployment editor opens.

    2. Select the Design tab.

    3. Select the Web Services Exports node.

    4. Click Add and select Web Services Security Extensions, then click OK.

    5. Select the Web Services Security Extensions node.

    6. Click Add and select Web Service Description Extension, then click OK. The Select a Web Service Export window appears.

    7. In the window, select the export to use and click OK.

    8. Select the Port Component Binding node.

    9. Click Add and select Server Service Configuration, then click OK.

    10. Select the Server Service Configuration node.

    11. Click Add and select Request Consumer Service Configuration Details, then click OK.

    12. Add nodes to the Request Consumer Service Configuration Details node to specify properties that correspond to the extension properties that you specified for the import, such as required security token, required integrity, required confidentiality, and timestamp.

    13. Select the Web Services Exports node.

    14. Click Add and select Web Services Binding Configurations, then click OK.

    15. Select the Web Services Binding Configurations node.

    16. Click Add and select Web Service Description Binding, then click OK. The Select a Web Service Export window appears.

    17. In the window, select the export to use and click OK.

    18. Select the Port Component Binding node.

    19. Click Add and select Request Consumer Binding Configuration Details, then click OK.

    20. Add nodes to the Request Consumer Binding Configuration Details node to specify properties that correspond to the properties that you specified under Request Consumer Service Configuration Details, such as token consumer, signing information, and encryption information.
    21. Press Ctrl-S to save your changes to the deployment side file ibm-deploy.scaj2ee in the Physical Resources view.

  3. Set the response generator properties for the export:

    1. In the Business Integration view, right-click the module that contains your export and select Open Deployment Editor. The module deployment editor opens.

    2. Select the Design tab.

    3. Select the Web Services Exports node. (If you followed the instructions in step 2 and you are now working with the same export, you can simply expand all levels of the Web Services Exports node and skip to step j below.)

    4. Click Add and select Web Services Security Extensions, then click OK.

    5. Select the Web Services Security Extensions node.

    6. Click Add and select Web Service Description Extension, then click OK. The Select a Web Service Export window appears.

    7. In the window, select the export to use and click OK.

    8. Select the Port Component Binding node.

    9. Click Add and select Server Service Configuration, then click OK.

    10. Select the Server Service Configuration node.

    11. Click Add and select Response Generator Service Configuration Details, then click OK.

    12. Add nodes to the Response Generator Service Configuration Details node to specify properties for the security mechanism that you are implementing, such as security token, integrity, confidentiality, and timestamp.

    13. Select the Web Services Exports node. If you followed the instructions in step 2 and you are now working with the same export, expand all levels of the Web Services Exports node and skip to step r below.

    14. Click Add and select Web Services Binding Configurations, then click OK.

    15. Select the Web Services Binding Configurations node.

    16. Click Add and select Web Service Description Binding, then click OK. The Select a Web Service Export window appears.

    17. In the window, select the export to use and click OK.

    18. Select the Port Component Binding node.

    19. Click the Add button and select Response Generator Binding Configuration Details, then click OK.

    20. Add nodes to the Response Generator Binding Configuration Details node to specify properties that correspond to the properties that you specified under Response Generator Service Configuration Details, such as token generator, signing information, and encryption information.
    21. Press Ctrl-S to save your changes to the deployment side file ibm-deploy.scaj2ee in the Physical Resources view.

  4. Set the response consumer properties for the import:

    1. In the Business Integration view, right-click the module that contains your import and select Open Deployment Editor. The module deployment editor opens.

    2. Select the Design tab.

    3. Select the Web Services Imports node. (If you followed the instructions in step 1 and you are now working with the same import, you can simply expand all levels of the Web Services Imports node and skip to step j below.)

    4. Click Add and select Web Services Client Security Extensions, then click OK. The Web Services Client Security Extensions node is added under Web Services Imports and the Component Scoped Reference node is added under the Web Services Client Security Extensions node.

    5. Select the Component Scoped Reference node.

    6. Click Add and select Service Reference, then click OK. The Select a Web Service Import window appears.

    7. In the window, select your web service import and click OK.

    8. Select the Port Qualified Name Binding node.

    9. Click Add and select Client Service Configuration, then click OK.

    10. Select the Client Service Configuration node.

    11. Click Add band select Response Consumer Configuration, then click OK.

    12. Add nodes to the Response Consumer Configuration node to specify properties that correspond to the extension properties that you specified for the export, such as required security token, required integrity, required confidentiality, and timestamp.

    13. Select the Web Services Imports node. (If you followed the instructions in step 1 and you are now working with the same import, you can simply expand all levels of the Web Services Imports node and skip to step r below.)

    14. Click Add and select Web Services Client Binding Configurations, then click OK. The Web Services Client Binding Configurations node is added under Web Services Imports and the Component Scoped Reference node is added under the Web Services Client Binding Configurations node.

    15. Select the Component Scoped Reference node.

    16. Click Add and select Service Reference, then click OK. The Select a Web Service Import window appears.

    17. In the window, select the import to use and click OK.

    18. Select the Port Qualified Name Binding node.

    19. Click Add and select Security Response Consumer Binding Configuration, then click OK.

    20. Add nodes to the Security Response Consumer Binding Configuration node to specify properties that correspond to the extension properties that you specified under Response Consumer Configuration, such as token consumer, signing information, and encryption information.
    21. Press Ctrl-S to save your changes to the deployment side file ibm-deploy.scaj2ee in the Physical Resources view.


Example

If you later want to reset the deployment side file to its original state:

  1. Close the module deployment editor.

  2. In the Physical Resources view, right-click the deployment side file ibm-deploy.scaj2ee and select Delete.

  3. In the Physical Resources view or the Business Integration view, click your module to select it.

  4. From the Project menu, select Clean. The Clean? window opens.

  5. Select Clean selected projects and then click OK. When the module has finished rebuilding, you can open the module deployment editor as usual.


When you have finished editing your web services exports and imports, you can test the content of the deployment side file at run time. For example, you can send events to the web services exports from a custom client and you can use the integration test client to send messages to a module that contains your web services imports.



Implementing authentication

WS-Security supports a variety of security token types for authentication, such as username tokens, binary tokens, and custom tokens. Username tokens are used in basic authentication, whereas binary tokens (like x.509 and LTPA tokens) are used in more advanced forms of authentication. In this release of IBM Integration Designer, the module deployment editor documentation describes how to implement basic authentication using username tokens.

To help illustrate how to implement basic authentication, a running example is used throughout the documentation. The example assumes that you have the following library and modules:

As the import and export names imply, the import sendWebServiceCallToServer sends a request message to the export receiveWebServiceCallFromClient at run time.

In basic authentication, username tokens are inserted in the request message of the import. There are typically no corresponding username tokens in the response message from the export.

The following topics describe how to implement basic authentication using a username token.



Create a security token for the request message

The first step in implementing basic authentication is to create a security token for the request message to be sent by the import. The security token is sent to the server inside the header of the SOAP message.

To create a security token for the request message:

  1. In the Business Integration view, select the module that contains your web services import.
  2. Right-click the selected module and select Open Deployment Editor. The module deployment editor opens.

  3. Click the Design tab.

  4. Select the Web Services Imports node.

  5. Click Add and select Web Services Client Security Extensions and click OK. The Web Services Client Security Extensions node is added under Web Services Imports. The Component Scoped Reference node is added under the Web Services Client Security Extensions node.

  6. Select the Component Scoped Reference node.

  7. Click Add and select Service Reference. The Select a Web Service Import window appears.

  8. In the window, select your web service import. For example, sendWebServiceCallToServer.

  9. Select the Port Qualified Name Binding node that was added.

  10. Click Add and select Client Service Configuration. The Client Service Configuration node is added under Port Qualified Name Binding.

  11. Select the Client Service Configuration node.

  12. Click Add and select Request Generator Configuration. The Request Generator Configuration node is added under Client Service Configuration.

  13. Select the Request Generator Configuration node.

  14. Click Add and select Security Token. The Select a Token Type window appears.

  15. In the window, select Username Token. A Security Token node is added under Request Generator Configuration.

  16. Select the Security Token node.

  17. In the Name field, type a name for the new security token. For example, basicAuth.
  18. Leave the URI field blank. No URI value is required for a username token.
  19. Press Ctrl-S to save your changes.


Now that you have created a security token, you should create a token generator as described in the topic "Creating a token generator for the request message".



Create a token generator for the request message

The second step in implementing basic authentication is to create a token generator for the request message to be sent by the import. The token generator reads the user name and password from the configuration file and generates the username token with the user name and password.

Before you create a token generator, you should ensure that you have created a security token, as described in the topic "Creating a security token for the request message".

To create a token generator for the request message:

  1. If the module deployment editor is closed, open it by completing the following steps:

    1. In the Business Integration view, select the module that contains your web services import.
    2. Right-click the selected module and select Open Deployment Editor. The module deployment editor opens.

  2. Click the Design tab.

  3. Select the Web Services Imports node.

  4. Click Add and select Web Services Client Binding Configurations. The Web Services Client Binding Configurations node is added under Web Services Imports and the Component Scoped Reference node is added under the Web Services Client Binding Configurations node.

  5. Select the Component Scoped Reference node.

  6. Click Add and select Service Reference. The Select a Web Service Import window appears.

  7. In the window, select your web service import. For example, sendWebServiceCallToServer.

  8. Select the Port Qualified Name Binding node that was added.

  9. Click Add and select Security Request Generator Binding Configuration. The Security Request Generator Binding Configuration node is added under Port Qualified Name Binding.

  10. Select the Security Request Generator Binding Configuration node.

  11. Click Add button and select Token Generator. A Token Generator node is added under Security Request Generator Binding Configuration.

  12. Select the Token Generator node.

  13. In the Token generator name field, type a name for the new token generator. For example, basicAuthToken.

  14. In the Token generator class field, ensure the following token generator class is selected: com.ibm.wsspi.wssecurity.token.UsernameTokenGenerator.

  15. Select the Part Reference node under the Token Generator node.

  16. In the Security token field, select basicAuth. This is the name of the security token that you created earlier under the import extensions of the module deployment editor.

  17. Select the Token Generator node, then press Add and select Use Value Type. The Select a Token Type window appears.

  18. In the window, select Username Token. The Use Value Type node is added under Token Generator.

  19. Select the Callback Handler node under the Token Generator node.

  20. In the Callback handler class drop-down list, ensure the following callback handler class is selected: com.ibm.wsspi.wssecurity.auth.callback.NonPromptCallbackHandler. You use the call back handler to manually specify a user ID and password in the token generator configuration.

  21. In the User ID and Password fields under the Basic Authentication subsection, specify the user ID and password for the client. For example, if you are using the default security settings of IBM Integration Designer, you would type admin as both the user ID and password.

    You can also set the user ID and password to match the user ID and password of Business Process Manager.

  22. Press Ctrl-S to save your changes.


Now that you have created a token generator, you should create a required security token by following the instructions in the topic "Creating a required security token for the request message".



Create a required security token for the request message

The third step in implementing basic authentication is to create a required security token for the request message to be received by the export.

Before you create a required security token, you should ensure that you have created a token generator as described in the topic "Creating a token generator for the request message."

To create a required security token:

  1. In the Business Integration view, select the module that contains your web services export.
  2. Right-click the selected module and select Open Deployment Editor. The module deployment editor opens.

  3. Click the Design tab.

  4. Select the Web Services Exports node.

  5. Click Add and select Web Services Security Extensions. The Web Services Security Extensions node is added under the Web Services Exports node.

  6. Select the Web Services Security Extensions node.

  7. Click Add and select Web Service Description Extension. The Select a Web Service Export window appears.

  8. In the window, select your web service export, for example, receiveWebServiceCallFromClient.

  9. Select the Port Component Binding node that was added.

  10. Click Add and select Server Service Configuration. The Server Service Configuration node is added under Port Component Binding.

  11. Select the Server Service Configuration node.

  12. Click Add and select Request Consumer Service Configuration Details. The Request Consumer Service Configuration Details node is added under Server Service Configuration.

  13. Select the Request Consumer Service Configuration Details node.

  14. Click Add and select Required Security Token. The Select a Token Type window appears.

  15. In the window, select Username Token. A Required Security Token node is added under Request Consumer Service Configuration Details.

  16. Select the Required Security Token node.

  17. In the Name field, type a name for the new required security token. For example, reqUNToken.
  18. Leave the Namespace URI field blank. No URI value is required for a username token.

  19. In the Usage type drop-down list, select Required. The Required usage type will cause a SOAP fault to be thrown whenever a required security token is not included in the import's request message.
  20. Press Ctrl-S to save your changes.


After you have finished creating a required security token, you need to create a caller part as described in the topic "Creating a caller part for the request message."



Create a caller part for the request message

The fourth step in implementing basic authentication is to create a caller part for the request message to be received by the export.

Before you create a caller part, you should ensure that you have created a required security token as described in the topic "Creating a required security token for the request message."

To create a caller part for the request message:

  1. If the module deployment editor is closed, open it by completing the following steps:

    1. In the Business Integration view, select the module that contains your web services export.
    2. Right-click the selected module and select Open Deployment Editor. The module deployment editor opens.

  2. Click the Design tab.

  3. Select the node for your export. For example, receiveWebServiceCallFromClient has a ServerInterfaceExport1_ServerInterfaceHttpService web service description extension, and a receiveWebServiceCallFromClient_ServerInterfaceHttpPort port component binding.

  4. Select the Web Services Exports node.

  5. Click Add and select Web Services Security Extensions. The Web Services Security Extensions node is added under the Web Services Exports node.

  6. Select the Web Services Security Extensions node.

  7. Click Add and select Web Service Description Extension. The Select a Web Service Export window appears.

  8. In the window, select your web service export. For example, receiveWebServiceCallFromClient.

  9. Select the Port Component Binding node that was added.

  10. Click Add and select Server Service Configuration. The Server Service Configuration node is added under Port Component Binding.

  11. Select the Server Service Configuration node.

  12. Click Add and select Request Consumer Service Configuration Details. The Request Consumer Service Configuration Details node is added under Server Service Configuration. (For example, receiveWebServiceCallFromClient has a ServerInterfaceExport1_ServerInterfaceHttpService web service description extension and a receiveWebServiceCallFromClient_ServerInterfaceHttpPort port component binding.)

  13. Select the Request Consumer Service Configuration Details node.

  14. Click Add and select Caller Part. The Select a Token Type window appears.

  15. In the window, select Username Token. A Caller Part node is added under Request Consumer Service Configuration Details.

  16. In the Name field, type a name for the new caller part. For example, basicAuth.
  17. Press Ctrl-S to save your changes.


Now that you have finished creating a caller part, you need to create a token consumer as described in the topic "Creating a token consumer for the request message."



Create a token consumer for the request message

The fifth and final step in implementing basic authentication is to create a token consumer for the request message to be received by the export. The token consumer receives the security token in the request message and validates it.

To create a token consumer for the request message:

  1. If the module deployment editor is closed, open it by completing the following steps:

    1. In the Business Integration view, select the module that contains your web services export.
    2. Right-click the selected module and select Open Deployment Editor. The module deployment editor opens.

  2. Click the Design tab.

  3. Select the Web Services Exports node.

  4. Click Add and select Web Services Binding Configurations. The Web Services Binding Configurations node is added immediately after Web Service Exports.

  5. Select the Web Services Binding Configurations node.

  6. Click Add and select Web Service Description Binding. The Select a Web Service Export window appears.

  7. In the window, select your web service export. For example, receiveWebServiceCallFromClient.

  8. Select the Port Component Binding node that was added.

  9. Click Add and select Request Consumer Binding Configuration Details. The Request Consumer Binding Configuration Details node is added under Port Component Binding.

  10. Select the Request Consumer Binding Configuration Details node.

  11. Click Add and select Token Consumer. A Token Consumer node is added under Request Consumer Binding Configuration Details.

  12. Select the Token Consumer node.

  13. In the Token consumer name field, type a name for the new token consumer. For example, con_UNtcon.

  14. In the Token consumer class field, ensure the com.ibm.wsspi.wssecurity.token.UsernameTokenConsumer class is selected.

  15. Select the Token Consumer node.

  16. Click Add and select Part Reference. The Part Reference node is added under Token Consumer.

  17. In the Security token field, select the security token that you created under the extensions. For example, reqUNToken.

  18. Select the Token Consumer node.

  19. Click Add and select Use Value Type. The Select a Token Type window appears.

  20. In the window, select Username Token. A Use Value Type node is added under Token Consumer.

  21. Select the Token Consumer node.

  22. Click Add and select Use jaas.config to have the security token in the import's request message validated. The Use jaas.config node is added under Token Consumer.

  23. In the jaas.config name field, type system.wssecurity.UsernameToken. This is the default JAAS configuration name for username tokens and it causes a username token to be validated with a user name and password.
  24. Press Ctrl-S to save your changes.


After you have added a token consumer, you have essentially finished the implementation of basic authentication for your application. You may want to test your implementation by using the integration test client, as described in the topic "Testing authentication using the integration test client."



Testing authentication using the integration test client

To test your authentication implementation, you can use the integration test client. The integration test client enables you to test your modules and components and report the results of your tests.

The testing is generally performed on the interface operations of your components, which enables you to determine whether the components are correctly implemented and the references are correctly wired.

To test authentication:

  1. In the Business Integration view, right-click the module that contains your import and select Test > Test Module. The integration test client opens. In the Events area of the integration test client, an Invoke event is automatically generated whenever the test client is started. (An Invoke event is an interactive event, which means that you must manually select an operation to test and specify some initial request parameters values for the operation before the test can continue.)

  2. In the Detailed Properties area of the integration test client:

    1. In the Component field, ensure the selected component is the component to debug. For example, if you were working with the sample application that serves as a running example in these topics on implementing basic authentication, you would select sendWebServiceCallToServer.

    2. In the Interface field, ensure the component interface is selected that contains the operation to invoke.

    3. In the Operation field, ensure the interface operation is selected to invoke.

  3. In the Initial request parameters value editor, specify the input values for the selected operation in the Value column, as shown in the figure below:

  4. Click Continue. The Deployment Location wizard opens.

  5. Ensure the correct deployment location is selected in the Deployment Location wizard.

  6. In the Mode drop-down list, ensure that Run is selected and then click Finish to automatically deploy the module to the server and to invoke the selected operation. If your test is successful, the integration test client returns the result of your test.


To learn more about the integration test client, see the integration test client topic Testing modules



Create and assigning security roles to web service exports

In the module deployment editor, you can create and assign security roles to web service exports.

To create and assign security roles to a web service export:

  1. In the Business Integration view, select the module that contains your web services export.
  2. Right-click the selected module and select Open Deployment Editor. The module deployment editor opens.

  3. Click the Design tab.

  4. Add a security role at the web project level by completing the following steps:

    1. Select the Web Project node.

    2. Click Add and select Security Role. A Security Role node is added under Web Project.

    3. In the Role name field, type the name to assign to the new security role. For example, Users.

    4. In the Description field, type the description to assign to the new security role. For example, Security role for general users.

  5. Add a security constraint by completing the following steps:

    1. Select the Web Project node.

    2. Click Add and select Security Constraint. A Security Constraint node is added beneath Web Project.

    3. In the Constraint name field, type the name to assign to the new export security constraint. For example, constraint1.

    4. Select the Web Resource Collection node.

    5. In the Resource name field, type the name to assign to the web resource. For example, receiveWebServiceCallFromClient.

    6. Under the Web Resource Collection node, add HTTP Method nodes for all of the available HTTP methods that you want constrained.

    7. Under the Web Resource Collection node, add URL Pattern nodes for all the patterns that you want constrained.

  6. Add the security role to the authorization constraint by completing the following steps:

    1. Select the Authorized Roles node.

    2. In the Description field, type the description to assign to the authorization constraint. For example, UsersAuthConstraint.

    3. Click Add and select Role. A role node is added under Authorized Roles.

    4. For the Role field, select the role to associate with the authorization constraint. For example, Users.

  7. Press Ctrl-S to save your changes and then close the module deployment editor.


When you have finished creating and assigning security roles to your web service export, you should bind the security roles that are defined in your assembly diagram by following the instructions in the topic "Binding roles defined in assembly diagrams."



Binding roles defined in assembly diagrams

In the module deployment editor, you can bind security roles that are defined in your assembly diagrams.

To bind security roles that are defined in an assembly diagram:

  1. In the Business Integration view, select the module that contains your web services export.
  2. Right-click the selected module and select Open Deployment Editor. The module deployment editor opens.

  3. Click the Design tab.
  4. Populate the application (module) level with the security roles that you created in the web project section (and defined in qualifiers within the module's assembly diagram) by completing the following steps:

    1. Select the Application Project node.

    2. In the Gather Security Roles subsection, click Gather security roles to populate the application (module) level with the security roles that you created in the web project section and that are defined in qualifiers within the module's assembly diagram. Under the Application Project node, the available security roles are displayed.

  5. Bind your security role by completing the following steps:

    1. Select the Application Project node.

    2. Click Add and select Authorization Table. An Authorization Table and a Authorization node are added.

    3. Select the Authorization node and select the security role to bind. For example, Users.

    4. Click Add and select the appropriate binding for your case.

    5. Add additional Authorization nodes for any additional security roles to bind.

  6. Press Ctrl-S to save your changes and then close the module deployment editor.

  7. If your server is already running in the Servers view, click the Build Activities tab to open the Build Activities view and then click Update Running Servers.



10. Change URLs for web service exports

In the module deployment editor, you can change the endpoint (URL) of an SCA export with a SOAP/HTTP web service binding, including both the context root and the URL mapping.

To change the URL for a web service export:

  1. In the Business Integration view, select the module that contains your web services export.
  2. Right-click the selected module and select Open Deployment Editor. The module deployment editor opens.

  3. Click the Design tab.
  4. Change the context root by completing the following steps:

    1. Select the Application Project node.

    2. Click Add and select Context Root. The Context Root node is added under Application Project.

    3. In the Context root field, replace the existing context root with a new context root. For example, NewContextRoot.

  5. Create a URL mapping for the web services export by completing the following steps:

    1. Select the Web Services Exports node.

    2. Click Add and select Web Service Export. A Web Service Export node is added under Web Services Exports.

    3. In the Name field, select your web service export. For example, receiveWebServiceCallFromClient.

    4. Click Add and select URL Mapping. A URL Mapping node is added under Web Service Export.

    5. In the URL pattern field, type the name of the new URL pattern. For example, /NewURLPattern.

  6. Remove the default URL mapping for the web services export by completing the following steps:

    1. Select the Web Services Exports node.

    2. Click Add and select URL Mapping (Default). The URL Mapping (Default) node is added beneath Web Service Export.

    3. Disable the Include default mapping check box.

  7. Press Ctrl-S to save your changes and close the module deployment editor.

  8. If your server is already running in the Servers view, click the Build Activities tab to open the Build Activities view and then click Update Running Servers.



11. Add JAX-RPC handlers for web service exports

In the module deployment editor, you can add a JAX-RPC handler before an SCA export with a SOAP1.1/HTTP using a JAX-RPC web service binding or a SOAP1.1/JMS web service binding and change the message request.

To add a JAX-RPC handlers for a web service export:

  1. In the Business Integration view, select the module that contains your web services export.
  2. Right-click the selected module and select Open Deployment Editor. The module deployment editor opens.

  3. Click the Design tab.

  4. Select the Web Services Exports node.

  5. Click Add and select Web Service Export. A Web Service Export node is added beneath Web Services Exports.

  6. Set the Name field of the Web Service Export node to your web service export. For example, receiveWebServiceCallFromClient.

  7. Select the Web Service Export node.

  8. Click Add and select JAX-RPC Handlers. A JAX-RPC Handlers and a JAX-RPC Handler node are added under Web Service Export.

  9. Select the JAX-RPC Handler node.

  10. In the Display name field, type the name to assign to the display. For example, WSExportHandler.

  11. In the Handler name field, type the name to assign to the new JAX-RPC handler. For example, WSExportHandler.
  12. Beside the Handler class field, click Browse and select your handler class. For example, com.ibm.test.li536.rpc.WSExportHandler.

  13. In the Description field, type a description for the new JAX-RPC handler. For example, JAX-RPC handler for the receiveWebServiceCallFromClient export.

  14. Add Initial Parameter, SOAP Header, and SOAP Role nodes as needed under the JAX-RPC Handler node.
  15. Press Ctrl-S to save your changes and then close the module deployment editor.

  16. If your server is already running in the Servers view, click the Build Activities tab to open the Build Activities view and then click Update Running Servers.



12. Add JAX-RPC handlers for web service imports

In the module deployment editor, you can add a JAX-RPC handler after an SCA import with a SOAP1.1/HTTP using JAX-RPC web service binding or a SOAP1.1/JMS web service binding and change the message request.

To add a JAX-RPC handler for a web service import:

  1. In the Business Integration view, select the module that contains your web services import.
  2. Right-click the selected module and select Open Deployment Editor. The module deployment editor opens.

  3. Click the Design tab.

  4. Select the Web Services Imports node.

  5. Click Add and select Web Services Import. A web service import node is added under Web Services Imports.

  6. Set the Name field of the web service import node to your web service import, for example, sendWebServiceCallToServer.

  7. Select the Web Service Import node.

  8. Click Add and select JAX-RPC Handlers. A JAX-RPC Handlers and a JAX-RPC Handler node are added under Web Service Import.

  9. Select the JAX-RPC Handler node.

  10. In the Display name field, type the name to assign to the display. For example, WSImportHandler.

  11. In the Description field, type a description for the new JAX-RPC handler. For example, JAX-RPC handler for the sendWebServiceCallToServer import.

  12. In the Handler name field, type the name to assign to the new JAX-RPC handler. For example, WSImportHandler.
  13. Beside the Handler class field, click Browse and select your handler class. For example, com.ibm.test.li536.rpc.WSImportHandler.

  14. Click OK to close the New Handler window.

  15. Add Initial Parameter and SOAP Header nodes as needed under the JAX-RPC Handler node.
  16. Press Ctrl-S to save your changes and then close the module deployment editor.

  17. If your server is already running in the Servers view, click the Build Activities tab to open the Build Activities view and then click Update Running Servers.



13. Use a resource reference in an assembly diagram

In the module deployment editor, you can add a resource reference that enables a Java component in the assembly diagram to access the resource. For example, you can add a JDBC data source reference that enables a Java component in the assembly diagram to access data in a relational database.

To use a resource reference in an assembly diagram:

  1. In the Business Integration view, select the module that contains your web service import.
  2. Right-click the selected module and select Open Deployment Editor. The module deployment editor opens.

  3. Click the Design tab.

  4. Create a resource reference by completing the following steps:

    1. Select the Resource References node.

    2. Click Add and select Resource Reference. A Resource Reference Wrapper and a Resource Reference node is added under the Resource References node.

    3. Select the Resource Reference node.

    4. In the Name field, type the name to assign to the resource reference. For example, jdbc/DataSourceRefOnModule.

    5. In the Authentication field, select the type of authentication to use. For example, Container.

    6. In the Sharing scope field, select the sharing scope to use. For example, Shareable.

    7. In the Description field, type a description for the data source reference.

  5. Set a WebSphere-specific binding on the resource reference by completing the following steps:

    1. Select the Resource Reference Wrapper node.

    2. Click Add and select WebSphere Binding. The Resource Reference WebSphere Binding window opens.

    3. In the JNDI name field, type a JNDI name. For example, jdbc/li536pip.

    4. Set the JAAS Configuration as needed. Note that JAAS Configuration can only be set for specific types of resource references that have authentication fields that have been set to Container.

    5. Click OK to close the window box. A WebSphere Binding node is added under Resource Reference Wrapper.

    6. Add properties under the WebSphere Binding node as needed.

  6. Set a WebSphere-specific extension on the resource reference by completing the following steps:

    1. Select the Resource Reference Wrapper node.

    2. Click Add and select WebSphere Extension. The WebSphere Extension node is added under Resource Reference Wrapper.

    3. In the Isolation level field, select an isolation level.

    4. In the Connection policy field, select a connection policy.

  7. Press Ctrl-S to save your changes and then close the module deployment editor.

  8. If your server is already running in the Servers view, click the Build Activities tab to open the Build Activities view and then click Update Running Servers.



14. Limitations of the module deployment editor

From time to time, you may encounter some limitations in using the module deployment editor.

A known limitation is:

This limitation is discussed in the following section.


Deployment side file must be manually updated after any binding changes

In this release of IBM Integration Designer, the module deployment editor enables a user to configure WS-Security deployment options on web service exports and imports. The data associated with the configured deployment options is stored in a deployment side file named ibm-deploy.scaj2ee, which is located in the root of the SCA module in the Physical Resources view of the Business Integration perspective. For example, MyModule/ibm-deploy.scaj2ee. The deployment side file can contain binding information, such as the port name and address of web service imports and the port name and service name of web service exports.

If the binding information of a web service import or export is changed, then the copy of this binding data in the deployment side file will be invalidated. For example, if you manually change the address of a web service import in the assembly diagram of the associated module, the binding data in the deployment side file will not reflect the new address of the web service import.

To ensure the deployment side file reflects any binding changes to your web service imports or exports, you must open the deployment side file in a text editor and then manually update the deployment information to reflect the changes to the binding information.



+

Search Tips   |   Advanced Search