Security for Remote Components

Oracle Content Management enables third-party developers to integrate their custom components into the Oracle Content Management platform but have them stored on a remote server.

Each remote component must have registered settings and rendering endpoints with Oracle Content Management. In addition to endpoints, developers also need to provide a secret key unique to the registered component.

Oracle Content Management invokes registered component’s endpoints to realize the content in a site page. Because these endpoints are exposed to public Internet, developers should verify that the endpoints of a registered remote component are being invoked from Oracle Content Management. For verifying the authenticity of the caller, a signed token is delivered to the registered endpoints of an URL. The calling party is authenticated by verifying the digital signature embedded in the signed token with the secret key of the remote component that was provided during the registration process.

The format of the token is:

{base64 encoded serialized JSON data}.{base64 encoded signature}

A sample token passed to the registered app endpoints follows:

eyJpbnN0YW5jZWlkIjoiQTRGOTE3REY5OTZEN0Q3ODBCMjUzODZFOTFEMDA3ODJGMjVBRjY2Rjc3OTIiLCJzaWduZGF0ZSI6IjE0NDU2MzcwNTk5MTciLCJzaXRlZG9tYWluIjoic2VydmljZTEtdGVuYW50MS51cy5vcmFjbGUuY29tIiwicGVybWlzc2lvbnMiOiJTSVRFX09XTkVSIiwiZW50aXRsZW1lbnRzIjoiIn0=.5p3of7t11OwuysF3zpm+YgICSHH8C/BHczdbVZx2VH8=

The token consists of two distinct parts: data and signature separated by a '.' delimiter.

As a general guideline, developers should always authenticate the token in Edit or Preview mode before granting access to registered endpoints of a component. In addition, while authenticating the calling party in the settings endpoint, developers should always take care to look for a SITE_OWNER value in the permissions field of the token. The permissions field of the token shows the SITE_OWNER value only in Edit mode. A token generated during an editing session is never persisted back to the page model and is switched out with a runtime token that has a NULL value in the permissions field.

Data

The data portion of the instance 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 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 Edit mode, it will have the value `"SITE_OWNER"`; otherwise, it will have no value.
`entitlements`	List of premium features purchased by the site owner.

Signature

The data portion of the remote 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}