A consumer application is a computer application that consumes (invokes) APIs (services, XML services or REST services) at run time. Typically, consumer applications specify the consumers that are allowed (registered) to consume a particular API. Then, you include the consumer application in the Consumer action of the API.
A consumer application in CentraSite is represented by an Application asset. The Application asset defines the precise consumer identifiers (for example, a list of user names in HTTP headers, a range of IP addresses, etc.). Thus the policy enforcement point (such as Mediator) can identify or authenticate the consumers that are requesting an API.
You can use Application assets with any supported policy enforcement point (that is, webMethods Mediator or any supported third-party policy enforcement point).
Note:
If you want to authenticate consumers (using LDAP or another external
authentication mechanism), make sure that your policy enforcement point is configured to enable
authentication. For information, see the documentation for your policy enforcement point.
To create and manage consumer applications, you must belong to a role with the following permissions:
Create Assets —OR— Manage Assets
Manage Lifecycle Models (required to change state of consumer applications)
For more information about roles and permissions, see the online documentation section Users, Groups, Roles and Permissions > About Roles and Permissions .
To identify and authenticate consumer applications, you perform the following high-level steps:
Include the Evaluate (consumer) action in the API's Message Flow.
To identify and authenticate the consumer applications that are requesting a proxy API, that API must have a run-time policy
that includes one of the "Evaluate" action. In an "Evaluate" action, you specify the consumer identifier you want to
use for identifying and authenticating consumer applications. This action extracts the specified
identifier from an incoming request and locates the consumer application defined
by that identifier.
For example, if you configure the Evaluate IP Address action to identify and authenticate consumers, the PEP extracts the IP address from a request’s HTTP header at run time and searches its list of application assets for the application that is defined by that IP address.
You can configure an "Evaluate" action to identify consumer applications based on the appropriate consumer identifier in a request message:
| Action Name | Consumer Identifier | Description |
|---|---|---|
| Evaluate IP Address | IP Address | The IP address from which the request originated. |
| Evaluate Hostname | Host Name | The name of the host machine from which the request originated. |
| Evaluate HTTP Basic Authentication | HTTP Authentication Token | The user ID submitted by the requestor when it was asked to provide basic HTTP credentials (user name and password). |
| Evaluate WSS Username Token | WS-Security Authentication Token | The WSS username token supplied in the header of the SOAP or XML request that the consumer application submitted to the virtualized service. |
| Evaluate XPath Expression | Custom Identification | A string produced by applying a specified XPath expression to the SOAP or XML request that the consumer application submitted to the virtualized service. |
| Evaluate WSS X.509 Certificate | Consumer Certification | The X.509 certificate supplied in the header of the SOAP or XML request that the consumer application submitted to the asset. |
| Evaluate Client Certificate for SSL Connectivity | Client Certificate for SSL Connectivity | The client's certificate that the consumer application submits to the asset. The certificate is supplied during the SSL handshake over the Transport layer. Communication between the client and the asset must be over HTTPS. |
When deciding which "Evaluate" action to use to identify and authenticate a consumer application, consider the following points:
Whatever identifier you choose to identify a consumer application, it must be unique to the application. Identifiers that represent user names are often not suitable because the identified users might submit requests for multiple applications.
Identifying applications by IP address or host name is often a suitable choice, however, it does create a dependency on the network infrastructure. If a consumer application moves to a new machine, or its IP address changes, you must update the identifiers in the application asset.
Using X.509 certificates or a custom token that is extracted from the SOAP or XML message itself (using an XPATH expression), is often the most trouble-free way to identify a consumer application.
For more information about the "Evaluate" actions, see the online documentation section Run-Time Governance Reference > Built-In Run-Time Actions Reference for APIs. Additionally, within that section see Usage Cases for Identifying/Authenticating Consumers.
Create an application asset in the registry.
In the application asset you specify precise values for the consumer
identifier(s) that you specified in the "Evaluate" action. For details,
see Creating a Consumer
Application Asset.
Specify the application asset in the Consume action of the API
to be consumed.
The Consume action is located in the API's detail page.
The run-time behavior of identifying and authenticating consumers is as follows:
CentraSite translates the application asset to the appropriate WS-Security policy assertions or an equivalent XML when the application asset is enforced by the PEP.
When a consumer application requests access to an asset, the PEP tries to map the consumer's identifier (which is found in the request) to an identifier in the application asset.
If the identifier is an IP address, a host name, a custom identification string or a consumer certificate, the PEP tries to identify the consumer (the consumer is not authenticated).
If the identifier is an HTTP Authentication token or a WS-Security Authentication token, the PEP tries to authenticate the consumer. If you use webMethods Mediator, authentication is handled by LDAP or by another external authentication mechanism, depending on how Mediator is configured. If you use a third-party PEP, authentication capabilities depend on the PEP.
The identified or authenticated consumer information is published back to the registry as part of the transaction or other events. This information is used to correlate the consumer-specific run-time dependencies.
Use the following procedure to create a consumer application asset.
To add an asset to the catalog
In CentraSite Business user interface, click the activity. This opens the Create Asset wizard.
In Basic Information panel, enter values for the following fields:
| In this field... | Specify... |
|---|---|
| Name |
A name for the application asset. An asset name can contain any character (including spaces). |
| Type | The Application asset type. |
| Organization | The organization to which the application asset belongs. |
| Initial Version | Optional. An identifier for the
initial version of the application asset. The default is
"1.0", but you can use any versioning scheme you
choose. The version identifier does not need to be numeric.
Examples:
0.0a 1.0.0 (beta) Pre-release 001 V1-2007.04.30 You can later create new versions of the application asset (see the section Versioning an Asset in the document Managing Assets). |
| Description | Optional. A comment or descriptive information about the new application asset. |
Click .
Note:
If you do not enter information into a required field, the system will alert you with a red error icon. Pointing to the icon
shows a hint with an error description.
In the Preview panel, click .
Configure the profiles of the detail page, as described in the following sub-sections.
If you belong to a role that has the "Register as Consumer" permission, the entry is enabled in the menu of the details page. If you select this menu entry, a dialog opens that lets you select users, groups and consumer applications that can use this asset. The request must be subsequently approved or rejected by the owner of the asset.
Specify the application asset in the Consume action of the API to be consumed. To do this, open the detail page of the API to be consumed and specify the application asset in the Consume action.
Use the following procedure to edit the attributes associated with a consumer application asset in the Business UI.
When editing attributes, keep the following general points in mind:
If you are not the owner of the asset, you cannot edit the asset unless you have Modify permission on the asset (granted though either a role-based permission or an instance-level permission).
When you view the details for the asset, you will only see profiles for which you have View permission. You will only be able to edit the profiles on which you have Modify permission.
To edit the attributes for a consumer application asset
In CentraSite Business UI, Browse or Search to display the application asset(s). For procedures on how to browse or search the CentraSite, see the section Browsing the CentraSite Catalog or Searching the CentraSite Catalog in the document Managing the CentraSite Catalog.
Locate the application asset whose details you want to view.
On the asset's actions menu, click the
icon.
Locate the application asset whose details you want to view and, from its context menu, select Details.
To edit the application asset's Name, Description or user-defined version number, place the cursor in the appropriate field and modify the text as required.
To modify the extended attributes associated with the asset, do the following:
Select the profile that contains the attribute(s) that you want to modify.
Edit the attributes on the profile as necessary.
When you have finished making your edits, click the
icon from the actions menu.
When you are prompted to confirm the save operation, click .
Or:
If at any time you want to abandon your unsaved
edits, click . CentraSite will ask you if you
want to save your edits. Click to abandon your edits
and return the asset's attributes to their previous settings.
You use the Identification profile to specify the precise values for the consumer identifier(s) that you specified in the "Evaluate" action.
Notes:
To configure the consumer identifiers
Specify values for one or more consumer identifier tokens.
Note:
The value(s) that you specify in the Identification profile depend
on how the run-time policy's "Evaluate" is configured. For example, if
"Evaluate IP Address" action is configured to identify and validate consumers by their IP address, you
should specify the consumer IP addresses here. For information about this
action, see the online documentation section Run-Time Governance Reference > Built-In Run-Time Actions
Reference for APIs.
Note:
For reasons of legibility some of the examples below contain break
lines and may not work when pasted into applications or command line tools.
| In this field... | Do the following... |
|---|---|
| IPv4 Address |
Specify a range of IPv4 addresses. Type the lowest IP address in the From field and the highest IP address in the To field. This will identify only those requests originating from any IP address that lies between the specified range. Example: "192.168.0.0 and 192.168.0.10" If you need to specify additional IP addresses, use the plus button to add more rows. |
| IPv6 Address |
Specify a IPv6 address. This will identify only those requests that originate from the specified IP address. Example: "fdda:5cc1:23:4::1f" If you need to specify additional IP addresses, use the plus button to add more rows. |
| Hostname |
Specify the hostname. This will identify only those requests that originate from the specified hostname. Example: "pcmachine.ab.com"If you need to specify additional hostnames, use the plus button to add more rows. |
| HTTP Authentication Token |
Specify one or more HTTP user names. This will identify only those requests that contain the specified user names encoded and passed in the HTTP authentication user token. Example: "SAGUser123"If you need to specify additional tokens, use the plus button to add more rows. |
| WS-Security Authentication Token |
Specify the WSS username token. This will identify only those requests that contain the specified user name passed in the SOAP or XML message header. Example: "userwss"If you need to specify additional tokens, use the plus button to add more rows. |
| XPath Token |
Specify one or more XPath expressions. This will identify only those requests that contain the specified XPath in the SOAP or XML message or request. Example: //*[local-name()= 'Envelope']/* [local-name()='Body']/* [local-name()= 'echoInt']/* [local-name() ='echoIntInput='] [.='2'] If you need to specify additional tokens, use the plus button to add more rows. |
| Consumer Certificate |
Specify the X.509 certificates that help the API owner to identify requests from you. Click to locate and select the certificate (.cer) file. |
You can publish consumer application assets to a policy enforcement point (such as webMethods Mediator) in either of the following ways:
You can publish multiple consumer applications to a Mediator target in a single step (see Publishing Consumer Applications Using the CentraSite Business UI).
You can publish multiple consumer applications to a Mediator target in a single step (see Publishing Consumer Applications Using the CentraSite Control).
You can run a script file to publish multiple consumer applications to a Mediator target in a single step (see Publishing Consumer Applications Using the Command Line Tool).
Note that the CentraSite Business UI does not have a dedicated user interface available to publish consumer applications to webMethods Mediator. Instead, deploys the consumer applications that are associated to an API when that particular API is published to the Mediator.
You use this procedure to publish the consumer applications associated with an API using its action.
To publish consumer applications
Display the details page for the API whose associated consumer applications you want to publish to webMethods Mediator. For procedures, see the section Viewing Details for an API Proxy.
On the API detail page, click 
.
This opens the Publish API dialog.
From the Available Targets list, choose one or more targets in which you want to publish the consumer applications.
Or:
If you want to publish the consumer applications across all the targets, select the All Targets checkbox.
When attempting to publish the consumer applications, without selecting at least on target, a warning popup box appears.
In the Advanced Settings node, select the Expose to Consumers checkbox. This allows unauthorized consumers (guests) to search and access the consumer applications.
Click .
Or:
If at any time you wish to terminate this operation, click .
A Publish Progress popup will display the progress state of publishing the consumer applications to the webMethods Mediator.
If the publish process failed, identify and correct the error and then try publishing the consumer applications again.
Use the following procedure to delete a consumer application asset.
To delete an application asset
In CentraSite Control, display the detail page of the application asset that you want to delete. If you need procedures for this step, see the section Administering the CentraSite Business UI > Managing Assets > Viewing Details for an Asset .
Locate the application asset that you want to delete.
On the asset's actions menu, click the
icon.
When you are prompted to confirm the delete operation, click .
The asset is permanently removed from the CentraSite registry.
You can delete multiple application assets in a single step.
To delete multiple application assets in a single operation
In CentraSite Business UI, Browse or Search to display the application asset(s). For procedures on how to browse or search the CentraSite, see the section Browsing the CentraSite Catalog or Searching the CentraSite Catalog in the document Managing the CentraSite Catalog.
Mark the checkbox of each application asset you want to delete.
In the menu, click .
Important:
If you have selected several application assets where one or more
of them are predefined application assets, you can use the
button to delete the assets. However, as you are
not allowed to delete predefined application assets, only assets you have
permission for will be deleted. The same applies to any other application
assets for which you do not have the required permission.
