Registering Application Assets as Consumers of an Asset

Note:

Beginning with version 9.9, CentraSite does not support registering Application assets as consumers of an asset using the Control UI. This means that there is no consumer registration procedure in Control UI. As a result:

The Register as Consumer action in the details page of an Application asset is removed in CentraSite Control user interface.

You cannot modify details of the consumers using the Consumers profile of an Application asset in the CentraSite Control user interface. You can only view details of the consumers such as: Name, Description, Type of Consumer, Owner, Organization, Created date, Modified date, and the Lifecycle State.

However, you can still deploy, undeploy, and redeploy consumer applications to Mediator gateway in CentraSite Control user interface.

Therefore, you cannot register Application assets as consumers of an asset using the CentraSite Control UI. Instead, you can use the enhanced interface of CentraSite Business UI which supports consumer registration for users, groups, Application and arbitrary assets (in contrast, earlier versions of CentraSite Business UI supported a standardized interface for consumer registration of Application assets only). Documentation of the prior consumer registration interface is available to CentraSite customers who have a current maintenance contract in Empower Product Support website.

To register Application assets as consumers of an API using the Business user interface, you perform the following high-level steps:

1. Include the Evaluate (consumer) action in the API's run-time policy.

To identify the consumer applications that are requesting an API, that asset must have a run-time message flow that includes one or more Evaluate * actions. In these actions, you specify the consumer identifier(s) you want to use for identifying consumer applications. (Alternatively, you may configure these actions to allow unrestricted access.) These actions extract the specified identifier from an incoming request and locate the consumer application defined by that identifier.

For example, if you configure the Evaluate IP Address action to identify consumers by a specific 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 specified IP address.

You can configure the Evaluate * actions to identify consumer applications based on one or more of the following consumer identifiers in a request message:

Action	Consumer Identifier	Description
Evaluate IP Address	IP Address	The IP address from which the request message to call the API had originated.
Evaluate Hostname	Identification Token - Host Name	The name of the host machine from which the request message to call the API had originated.
Evaluate HTTP Basic Authentication	Identification Token - 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	Identification Token - WS-Security Authentication Token	The WSS username token supplied in the header of the SOAP or XML request message to call the API.
Evaluate XPath Expression	Identification Token - Custom Identification	A string produced by applying a specified XPath expression to the SOAP or XML request message to call the API.
Evaluate WSS X.509 Certificate	Consumer Certificate	The X.509 certificate supplied in the header of the SOAP or XML request message to call the API.
Evaluate Client Certificate for SSL Connectivity	Consumer Certificate - 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.
Evaluate OAuth2 Token	Identification Token - OAuth2 Token	The client's OAuth2 token supplied in the SOAP or XML request message to call the API.

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 information about the Evaluate * actions, see Built-In Run-Time Actions Reference for APIs.

2. 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 * actions. For details, see The Identification Profile.

3. Specify the Application asset in the Consume Asset dialog of the API you want to consume.

Use the Consume action in the details page of the API you want to consume. This opens the Consume Asset dialog. For procedures, see Implementing Consumer Registration

The run-time behavior of identifying and authenticating consumers is as follows:

1. CentraSite translates the Application asset to the appropriate WS-Security policy actions or an equivalent XML when the Application asset is enforced by the PEP.

2. When a consumer application requests access to an API, 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.

3. 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.