About the Instance ID and Structure for Components Rendered in Inline Frames

The component Instance ID is the unique identifier for a component rendered in an inline frame within a site.

When a user drags and drops a component rendered in an inline frame from the Component Catalog onto a site page, a provisioning call is made to Oracle Sites Cloud Service to generate a new unique component instance ID. This ID is guaranteed to be unique and all such component instances provisioned on that service will get the same instance ID.

A component instance ID contains additional information that can be used to secure the settings and use of a component rendered in an inline frame, so that the component can be sure that the Settings update is coming from a trusted place.

The instance ID parameter enables developers to identify the site and authenticate the calling party. The caller is authenticated by verifying a digital signature that is generated using the component secret key. The secret key is generated during the component registration process.

The component instance consists of two parts separated by a ‘.’ delimiter: data and structure.

Component Instance: Data

The data portion of the instance for a component rendered in an inline frame is a Base64 JSON encoded string. Here’s the structure of the JSON string:

{
  "instanceid": "BBDC7614F693B75110D811E6C0B77C935FAEC5112E5E",
  "permissions": "",
  "entitlements": "",
  "signdate": "1435426735293",
  "sitedomain": "service1-tenant4.localhost"
}

Field Name	Description
`instanceid`	Unique identifier of a component rendered in an inline frame for an Oracle Content Management tenant.
`signdate`	Signature generation date.
`sitedomain`	Domain name of the Oracle Content Management instance.
`permissions`	Set of permissions of the site member. In editing mode, it will have the value `"SITE_OWNER"`; otherwise, it will have no value.
`entitlements`	List of premium features purchased by the site owner.

Component Instance: Signature

The data portion of the component instance is serialized before being signed by an APP_SECRET_KEY. This secret key must be generated and shown to the developer while registering the component. The signature is calculated by generating a hash of the data portion of the component instance (a serialized JSON structure) with the secret key as shown here:

$signature = HMAC (serialized JSON structure, APP_SECRET_KEY)

The hash algorithm used in generating the signature is SHA256. The token is then the concatenation of the serialized JSON structure and the generated signature component as shown here:

$instance = {base64encoded serialized JSON structure}.{base64encoded $signature}

Example:

//base64 encoded serialized object           //signature
eyJpbnN0YW5jZWlkIjoiQTRGOTE3REY5OTZEN0Q3ODBCMjUzODZFOTFEMDA3ODJGMjVBRjY2Rjc3OTIiLCJzaWduZGF0ZSI6IjE0NDU2MzcwNTk5MTciLCJzaXRlZG9tYWluIjoic2VydmljZTEtdGVuYW50MS51cy5vcmFjbGUuY29tIiwicGVybWlzc2lvbnMiOiJTSVRFX09XTkVSIiwiZW50aXRsZW1lbnRzIjoiIn0=.5p3of7t11OwuysF3zpm+YgICSHH8C/BHczdbVZx2VH8=