Evaluate X509 Certificate Action

Evaluate X509 Certificate Action

1. INTRODUCTION

2. PRE-REQUISITE

3. SUMMARY

4. CONFIGURATIONS

    4.1. Create a Consumer Application with Identification token

    4.2. Create a virtual alias in BusinessUI with the Evaluate WSS X.509 Certificate action

    4.3. Configure the Evaluate WSS X.509 Certificate Action 

5. DEPLOY AND VALIDATE THE DEPLOYMENT

6. EXECUTION AND VERIFICATION OF VIRTUAL SERVICE RUNTIME INVOCATION

7. TROUBLESHOOTING WITH THE EVALUATE WSS X.509 CERTIFICATE ACTION


1. INTRODUCTION

To Secure the web services, Web service providers enforce the clients to send a valid X.509 certificate during runtime. The Certificate is used to validate and identify the client.  

There are several ways that the providers can achieve the identification of the client using X.509 certificates in using Mediator.

This tutorial will explain the configuration and usage of the runtime action "Evaluate X.509 Certificate Action" using CentraSite and webMethods Mediator.

The Evaluate X.509 Certificate runtime policy enforcement will help in the following 

  • Identify the consumer application Evaluate X.509 Certificate making the request for the virtual service if identify attribute is turned ON
  • Validate against a set of global or pre-registered consumer applications with the WSS X.509 Certificatein wM Mediator

Refer introduction page to get general information on consumer identification in wM Mediator.

2. PRE-REQUISITE

  1. Knowledge in basics of wM Mediator runtime and WS-Security.
  2. Configure the Keystore & Truststore in Integration Server and Mediator
    Refer "Configuration of Certificates in Integration Server and wM Mediator" in Overview of WS-Security documentation here... 

3. SUMMARY

Steps involved when using of Evaluate WSS X.509 Certificate action in CentraSite and wM Mediator

  1. Create a Consumer Application (eg. MyX509Consumers) with Identification token and deploy it to wM Mediator which can be used during the virtual service invocation 
  2. Create a virtual alias (eg. VS_EchoWS_WSSx509Cert) in CentraSite BusinessUI with Evaluate X.509 Certificate action.
  3. Deploy the virtual alias to wM Mediator target.
  4. Invoke the virtual alias deployed in Mediator using SOAP UI with one of a consumer from the previously created Consumer Application
  5. Validation and troubleshooting 

4. CONFIGURATIONS

4.1. Create a Consumer Application with Identification token

  1. Login to CentraSite Control UI and Create an asset type of "Application" (eg. MyX509Consumers and MyPGConsumers). 
    In this article, MyPGConsumers is used to demonstrate the registered consumer(s) with evaluate x.509 certificate 
  2. Choose "Consumer Certificate" as identifier for MyX509Consumers and upload a consumer certificate. This is used to identify this consumer by this certificate.
  3. In this example, client.jks used to demonstrate which is provided by the Apache.


    1. In Addition, we will create an another consumer application (eg. MyPGConsumers) with different consumer certificate to verify registered consumer identification. This step is optional
       
  4. Navigate to Operations -> Deployment and invoke "Deploy Consumers" tab in CentraSite Control.
  5. Select target(s) and invoke "Syncronize" to deploy the Consumer Application to wM Mediator and confirm the status as success.
    User can now enforce the restriction of allowing only these consumer applications or identifying the calling applications for virtual services in wM Mediator using the Evaluate WSS X.509 Certificate policy.
  6. After the successful deployment of consumer application(s), verify the deployed consumer application(s) with expected certificate in wM Mediator.
    1. Open webMethods wM Mediator page, http://<hostname>:5555/WmMediator and click on "Consumers" link 
    2. Verify the deployed consumer application(s) listed and the mapped certificate details can be viewed in the Mediator consumer page as follows
    3. This serial number should match with the consumer certificate used in step 4.3

4.2. Create a virtual alias in BusinessUI with the Evaluate WSS X.509 Certificate action

Perform the following steps to create a virtual alias (eg.VS_EchoWS_WSSx509Cert and VS_EchoWS_WSSx509CertID) with Evaluate WSS X.509 Certificate action

  1. Login to BusinessUI and open a service (Eg. EchoWS) details page of the service that needs to be virtualized..
  2. Click on "Virtualize" action to get virtualization wizard screen. 
  3. Provide alias name in "Create a New Virtual Alias" input box and select an endpoint from the list of "Endpoints of <service name> to Virtualize" and click "Next".

4.3. Configure the Evaluate WSS X.509 Certificate Action 

  1.  Navigate to "Policy Enforcement" -> "Security" section, drag & drop "Evaluate WSS X.509 Certificate" action into "Enforce" message flow. 
  2. Click on the configure icon, the icon will appears on mouse over of "Evaluate WSS X.509 Certificate" text in message flow. 
  3. Select one of the following identification method to identify the consumer(s)

    1. "Global Consumers" - wM Mediator will try to verify the consumer certificate against a list of all global consumers available in wM Mediator.

    2. "Registered Consumers" - wM Mediator will try to verify the consumer certificate against the list of consumer applications which are registered as consumers with this API.

    3. "Do not identify- If don't want to identify the consumer(s). 

      Note

      Icon

      Do not identify – Does not identify the consumer, nevertheless it will evaluate the value presents in the header and the request will be sent to the native service. 

      This policy will fail if the expected value(s) is not present in the request header.

    4. Optional Step 1: Apply Log Invocation Policy to the virtual service and select CentraSite to the log data. This step is only required to generate and validate the events
    5. Optional Step 2: This step is only required to identify consumer(s) using registered consumers
      1. Open the detail page of the virtual alias VS_EchoWS_WSSx509CertID in BusinessUI

      2. Select the consumer  icon to choose the desire consumer application (eg. MyPGConsumers) from the list.

        You can also input minimum *** (3 starts) as wild card to get all available consumer applications in this CentraSite.

      3. After the successful selection of consumer application in the above step, Click Consumers link and you will be able to see the selected consumer application 

      4. Now Mediator can identify MyPGConsumers by invoking the virtual service (VS_EchoWS_WSSx509CertID) with relevant client's certificate and verify in step 5.
         
  4. Click "Virtualize" to complete the virtualization of the service with Evaluate WSS X.509 Certificate action.

4. DEPLOY AND VALIDATE THE DEPLOYMENT

  1. Deploy the virtual alias (Eg. VS_EchoWS_WSSx509Cert) to wM Mediator target(s) by clicking "Publish..." option from BusinessUI
  2. Verify the service deployment in wM Mediator page
    1. Invoke http://<mediator_host>:5555/WmMediator from a web browser and provide credentials to access the page.
    2. Click "Services" link to get list of mediated service(s) in the wM Mediator and find your virtual service (eg.VS_EchoWS_WSSx509Cert).
  3. Verify virtual service definition in wM Mediator.
    After the successful service deployment, you should be able to find WSSecurityPolicy policy with X509Token as SupportingTokens in the VSD as follows In the above page. 

Click on the [VSD] link for the virtual service to see the virtual service definition.

WS-Policy in VSD
<policy id="WSSecurityPolicy">
      <wsp:Policy xmlns:wsp=" xmlns:wsu=" wsu:Id="WSSecurityPolicy">

For the demo purpose the client.jks is copied to the Mediator location at <<SoftwareAG_Home>>>\IntegrationServer\instances\default\packages\WmMediator\config\resources\security\ from Apache.

    1. Also, you should be able to find the following entries in the VSD as seen below if Global Consumers (relax) is selected

    2. If Registered Consumers is selected as identification method then identify attribute's value will be "strict". This is needed to identify the consumer against the register consumers list.

       
    3. If Do not identify is selected as identification method then identify attribute's value will be "donotidentify". This is needed to identify the consumer against the register consumers list.

5. EXECUTION AND VERIFICATION OF VIRTUAL SERVICE RUNTIME INVOCATION

Verify the runtime execution with Evaluate WSS X.509 Certificate policy.

  1. Find the WSDL by clicking on [WSDL] link adjacent to the service(s) list
  2. Verify the scenario by invoking the virtual service (Eg.VS_EchoWS_WSSx509Cert) using a SOAP Client
  3. Invoke the virtual service with consumer certificate to identify as mediator consumer(s).
    1. The <wsse:BinarySecurityToken/> is the X 509 certificate that is being sent in the request. This is the certificate in PEM encoding
  4. A sample Request with client certificate (eg.client.cer) PEM encoding would look like

    Now, the invoking consumer should be identified as MyX509Consumers which can be verified in runtime event in next step.

     

  5. Verifying the result with log invocation policy in BusinessUI
    1. View Runtime events after invoking the service as guided in step 5.2 and verify Consumer as expected.
    2. Successful consumer identification would looks like

    3. Unsuccessful consumer identification would looks like

    4. Successful identification by MyPGConsumers using register consumers

6. TROUBLESHOOTING WITH THE EVALUATE WSS X.509 CERTIFICATE ACTION

Possible cause/ Solution
1 General security error  (Unexpected number of certificates: 0)

 

A violation was detected for policy (WS-Security Policy:WSSecurityPolicyuser ):

General security error (Unexpected number of certificates: 0)

Certificate encoding string is not valid or invalid certificate

  • Make sure the certificate encoding is correct by validating
    the certificate string being sent with the request. Use certificate decoder to view the certificate
2 Missing wsse:Security header in request A violation was detected for policy (WS-Security Policy:WSSecurityPolicyuser ): Missing wsse:Security header in request

The security header is missing

Make the certificate is attached with the request header in the<wsse:BinarySecurityToken/>.see step 5.4

3 Consumer not identified In Mediator, consumer is not identified as expected
  • Consumer application is not deployed to target Mediator
    • Verify the consumer application is deployed into this 
      Mediator as in the step 4.1.6
    • Make sure the certificate's serial number matches with the certificate being sent in the request header. See step 4.3
    • Deploy the desired consumer application with consumer's certificate to target Mediator.
       
  • The Evaluate WSS X.509 Certificate action may not be applied to this virtual service

 

Click here to download PDF version of this tutorial.