Partner API Key

A partner can be identified by an API key from an incoming request.

TIBCO API Exchange Gateway enables a partner to be identified by an API key from an incoming request. The API key can be sent via HTTP header or the URL. The reason for recommending to have the API key in the header is that it is more secure than having the API in the URL. The API in the URL may be exposed as it may be saved in the browser history or server log.

The API key can be passed in the header using the following format:

ASGAccessKey: nnnnnnnnnnnnnnnn

or in the URL as:

https://host:port/resource/api& ASGAccessKey = nnnnnnnnnnnnnnnn &….

If the API key is available in both URL and header, a warning is logged and the API key from the header is used.

If the API key is enabled to use for identifying a partner, the partner identified by the API key then will be used as the sender of the request, instead of the actual authenticated principal. This is useful in the case where the API key owner (or the partner) wants to be responsible for authorization of the invocation and assumes the throttling rate, mapping, and other actions associated with the request.

In a secure environment, using the API key alone to identify the partner is not enough. The request must be authenticated by some other means as the API key may be a stolen key. To protect from stolen key scenario, the API can be further protected by a policy where the sender of must be authenticated. When a request is authenticated, a principal is generated from the authentication. The authenticated principal may or may not be the owner of the API key.

If the authenticated principal is not the owner of the API key, the API key owner should have a choice to deny the use the API key in order to make sure that no else but the owner can use the API key.

In order to allow for the API key to identify the owner (partner) and be able to restrict the API key to be used by the owner, each API key will have the following configuration options:
  • API key
  • Partner name
  • Flag to use API key to identify partner
  • Flag to restrict the API key for the partner principal only
    Note: This flag will make sure that if a request has and API key as when as a principal, the partner that has the API key must also be the same partner that can be identified by the principal.

The configuration file, PartnerApiKey.cfg, is used to configure the partner's API keys.

When a partner request passes through a security processing stage, the authenticated principle will be used to identify a partner. If the API key is in the request, the API key will be used as one of the identification method. Issuer and Serial number from the SSL will also be used to identify the partner, if available. For a request to map to a partner, the API Key or principal and serial number/Issuer combination are used to identify the partner. If a partner is authorized to invoke the operation, then the rest of the operation processing will be based on the authorized partner. If a partner cannot be authenticated, it will be treated as an unidentified partner. If a partner cannot be identified, it is classified as an anonymous partner and the request is rejected. A request without any partner identifier is treated as an anonymous partner.

The following global variable in asg.properties is used as the partner name for an anonymous partner: 
# Default PartnerName for unauthenticated requests tibco.clientVar.ASG/anonymous/PartnerName/Authenticated=anonABC
In the above example, the anonymous partner is set to anonABC. The default value is anon and can be changed.
Note: No certificate issuer and serial number is assigned to the anonymous partner. The issuer and serial number in partner data configuration should be left as empty fields, otherwise they will be ignored.