A consumer application is a computer application that consumes (invokes) assets (services, BPEL processes or XML schemas) at run time. Typically, you create consumer applications to specify the consumers that are allowed to consume a particular asset. Then, you include the consumer application in the Consumers profile of the asset.
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 asset.
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.
The following subsections describe how to create and manage consumer applications:
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 section About Roles and Permissions in the document Users, Groups, Roles and Permissions.
To identify consumer applications, you perform the following high-level steps:
Include the Identify Consumer action in the asset's run-time
policy.
To identify the consumer applications that are requesting an asset, that asset must have a run-time policy that includes the
Identify
Consumer action. In this action, you specify the consumer identifier(s) you want to
use for identifying consumer applications. (Alternatively, you may configure
this action to allow unrestricted access.) 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 Identify Consumer action to identify consumers by IP address, 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 the Identify Consumer action to identify consumer applications based on one or more of the following consumer identifiers in a request message:
| Consumer Identifier | Description |
|---|---|
| IP Address | The IP address from which the request originated. |
| Host Name | The name of the host machine from which the request originated. |
| HTTP Authentication Token | The user ID submitted by the requestor when it was asked to provide basic HTTP credentials (user name and password). |
| 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. |
| 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. |
| Consumer Certification | The X.509 certificate supplied in the header of the SOAP or XML request that the consumer application submitted to the asset. |
| 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 type of identifier to use to identify 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 Identify Consumer action, see the section Run-Time Governance Reference > Built-In Run-Time Actions Reference for Virtual Services. 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 Identify Consumer action. For details,
see Creating a Consumer
Application Asset.
Specify the application asset in the Consumers profile of the asset
to be consumed.
The Consumers profile is located in the asset's detail page.
The run-time behavior of identifying 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 create a consumer application asset
In CentraSite Control, go to Asset Catalog > Browse.
Click Add Asset(s).
In the Add Asset dialog, enter values for the following fields:
| In this field... | Specify... |
|---|---|
| Type | The Application asset type. |
| Name | A name for the application asset. An asset name can contain any character (including spaces). |
| Description | Optional. A comment or descriptive information about the new application asset. |
| 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 Using the Asset Catalog). |
Click .
Now the detail page of the newly created asset opens. Here you can enter the values of various attributes of the new asset.
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 Consumers profile of the asset to be consumed. To do this, open the detail page of the asset to be consumed and specify the application asset the Consumers profile.
To configure the profiles of a consumer application, see one of the following sections as appropriate:
In this profile, specify the precise values for the consumer identifier(s) that you specified in the Identify Consumer action.
Notes:
To configure the Identification profile
Specify values for one or more of the following fields.
Note:
The value(s) that you specify in the Identification profile depend
on how the run-time policy's Identify Consumer is configured. For example, if
Identify Consumer is configured to identify consumers by their IP address, you
should specify the consumer IP addresses here. For information about this
action, see the Run-Time Governance Reference > Built-In Run-Time Actions
Reference for Virtual Services.
| In this field... | Do the following... |
|---|---|
| IPv4 Address |
Identify consumers based on their originating 4-byte IP address. Use this field when the Identify Consumer action is configured to identify consumer applications by IP address.
|
| IPv6 Address |
As for IPv4 Address, but using the 128-bit IPv6 format. For example: "1234:5678:9ABC:DEF0:1234:5678:9ABC:DEF0". |
| Identification Token |
Identify consumers based on one or more of the following kinds of identification tokens: Use this field when the Identify Consumer action is configured to identify consumer applications by host name, HTTP user name, WSS user name or a custom token.
If you need to specify additional tokens, use the plus button to add more rows. |
| Consumer Certificate | Identify consumers based on information in an X.509 v3
certificate.
Use this field when the Identify Consumer action is configured to identify consumer applications by a consumer certificate. Click to locate the certificate (.cer) file and select the certificate file. |
Use this profile to set permissions for the application asset. For information, see the section Setting Permissions on an Asset in Using the Asset Catalog.
Use this profile to generate a new version of the application asset. For information, see the section Versioning an Asset in Using the Asset Catalog.
Optional. If you want to be notified when the application asset is changed, click the Actions button and select Notify me from the drop-down list. Your owner name will appear in the Subscriptions profile. Any other users who have permission to access the asset can add their own user names to this list.
This profile displays an audit log of the changes made to the application asset (including changes in an asset's lifecycle state).
Optional. Use this profile to add object-specific properties to the application asset.
To configure the Object-Specific Properties tab
Click the Add Property button.
Specify values for the following fields:
| In this field... | Specify... |
|---|---|
| Name | The name of the property. |
| Namespace | Optional The namespace of the property. |
| Values | Optional A value for the property. If you want to specify multiple values, use the plus button to add additional rows. |
Use the following procedure to edit the attributes associated with a consumer application asset in the catalog.
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 Control, go to .
On the Browse page, perform a keyword or advanced search to display the application asset(s). For procedures, see the section Searching the Asset Catalog in Using the Asset Catalog.
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.
Note:
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.
When you have finished making your edits, click .
You can deploy consumer application assets to a policy enforcement point (such as webMethods Mediator) in either of the following ways:
You can deploy multiple consumer applications to a Mediator target in a single step (see Deploying Consumer Applications).
You can run a script file to deploy multiple consumer applications to a Mediator target in a single step (see Deploying Consumer Applications).
Before you delete an application asset, we strongly recommend that you examine the asset's Impact Analysis profile to determine whether other assets will be affected by the asset's deletion.
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 Viewing Details for an Asset in Using the Asset Catalog.
In the menu, click .
You can delete multiple application assets in a single step. The rules described above for deleting a single application asset apply also when deleting multiple application assets.
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.
To delete multiple application assets in a single operation
In CentraSite Control, use either the Browse or the Search feature in the asset catalog to select a list of the application assets. If you need information on how to browse or search the asset catalog, refer to the section Browsing the Asset Catalog or Searching the Asset Catalog in Using the Asset Catalog.
Mark the checkbox of each application asset you want to delete.
In the menu, click .
The term consumer provisioning means providing users with the ability to consume assets. Consumer provisioning with CentraSite enables you to control and monitor who consumes assets.
A consumer can be any of the following:
A registered user of CentraSite.
A registered group of users.
A guest user.
A consumer who is identified in an application asset.
To control who consumes assets, you:
Register users to consume assets.
CentraSite users with the proper permissions can register themselves
or other users as consumers of specified assets. That is, users can request
permission to access specified assets in the registry. The owners of the assets
may approve or reject such requests.
Specify the registered consumers in the asset's Consumers
profile.
After users, groups and/or applications are approved to consume an
asset, you must specify those consumers in the asset's Consumers profile. The
Consumers profile appears in the asset's detail page.
Because consumers are registered, CentraSite can easily track consumer-provider relationships. The purpose of tracking consumer-provider relationships is to identify:
The artifacts in the registry that will be affected if an asset is not available or must be changed.
The organizations that need to be informed in such situations.
You can track consumer-provider relationships in the following ways:
View pending registrations.
If you are the owner of an asset, and another user has made a request
to register as a consumer of the asset, you can view the request (see
Viewing Consumer Registration
Requests).
View your registration requests.
If you have made a request to register as a consumer of an asset owned
by another user, you can view the status of the request (see
Viewing Consumer Registration
Requests).
Generate reports on consumer-provider relationships.
See Working with Reports and Report
Templates.
Inspect the “Impact Analysis” view of the assets.
You can view associations between the registry objects to identify the
impact when updating or deleting an asset in the catalog. For more information,
see the section Impact Analysis in Using the Asset Catalog.
This section covers the following topic:
To provide consumers with access to assets, you perform the following tasks:
To enable users to register as consumers of assets, you must first create a policy that enables the asset owners to approve or reject the "Register as Consumer" requests. To create the policy, use this procedure.
To create the Consumer-Provider Relationship Policy
Create a Design/Change-Time policy with the following specifications:
| Field | Value |
|---|---|
| Name |
Consumer-Provider Relationship Policy |
| Object Type | Assets |
| Event Type | OnConsumerRegistration |
| Actions |
|
If you need instructions for creating a Design/Change-Time policy, see Working with Design/Change-Time Policies. For information about setting the action parameters, see the Built-In Design/Change-Time Actions Reference.
When you register users to consume assets (as described in Registering Users to Consume Assets), the policy is triggered and the "Register as Consumer" request is submitted to all members of the approval list specified in the Initiate Approval action. Then, the approvers can either approve or decline the request. If the approvers approve the request, the consumers will be registered as consumers, and appropriate permissions will be assigned to users and groups (permissions are not applicable to application consumers).
If you have permissions to view assets in the catalog, and you belong to a role that includes the "Register as Consumer" permission, the feature is enabled in the menu when you browse or search the asset catalog in CentraSite Control. This feature opens a dialog that lets you request the right to be a consumer of one or more of the displayed assets. You can request the right for yourself, or for any user or group in any organization, or for any consumer application owned by any organization.
The request must be subsequently approved or rejected for each asset by at least one of the owners of the asset. This functionality is also available in the detail view of an asset by choosing the menu entry in the menu. This functionality is not available to guest users.
To register users to consume assets
Ensure that you have created a design-time policy named
Consumer-Provider Relationship Policy, as described in
Creating the Consumer-Provider
Relationship Policy.
In CentraSite Control, go to .
Select the check box next to each of the required assets and click .
In the User/Group field, use the button to display a list of all users and groups from all organizations, and then select the one you want.
If you want to specify additional users or groups, use the plus button beside the User/Group field to create a new User/Group input field, then use the button to select the required user or group as in the previous step.
In the Application field, choose an application asset from the selection box. The selection box shows Applications assets from all organizations.
If you want to specify additional application assets, use the plus button beside the Application field to create a new Application input field, and choose another application asset.
When you have specified all required users, groups and applications, click .
Requests to register the users, groups and/or applications are sent to the owner(s) of the assets.
The owner of each asset can either accept or decline a "Register as Consumer" request as follows:
Go to Home > My CentraSite > Consumer Registrations and click Pending Registrations.
To start the approval process for the request, select the check box next to the request and click Apply Registration Policies. This triggers the OnConsumerRegistration event, which in turn activates the Consumer-Provider Relationship Policy.
To decline the request, select the check box next to the request and click . The Consumer-Provider Relationship Policy is not activated.
After the users, groups and/or applications are approved to consume an asset, you must specify those consumers in the asset's Consumers profile. The Consumers profile appears in the asset's detail page.
To view a summary of all "Register as Consumer" requests, go to Home > My CentraSite > Consumer Registrations and use the following links:
Pending Registrations: If you are the owner of an asset, and another user has made a request to register as a consumer of the asset, you can view the request here. As the asset owner, you can accept or decline the request.
Registration Requests: If you have made a request to register as a consumer of an asset owned by another user, you can view the status of the request here.
