Introduction

Widgetized Campaign Manager enables you to seamlessly integrate the pre-built Campaign Manager with your existing system without requiring your advertisers/sellers to have a separate login for campaign management. You can start the integration process by creating an SSO URL. The URL contains all the information needed to properly initiate the Widgetized Campaign Manager, including the ID of the user in your system, the ad account that the user will be able to access, and the role you want to give the user. Then, you will sign the URL with a secret key provided by Moloco. Once the URL is generated and signed, it is ready to be used. The Widgetized Campaign Manager can be presented by putting it in an iframe.

Required information

Before creating your SSO URL, you’ll want to determine all the information that must be included.

SSO secret key

Your SSO secret can be found in the Standalone Campaign Manager, in the Developer side menu under Credential Management. Please remember that the SSO secret works like a master password for the entire ad platform. Please ensure the secret key is stored in a secure location using encryption.

Platform ID

Your Moloco representative will issue your Platform ID during the onboarding process.

Ad Account ID and Title

You will need to set the ID and title of the ad account which will associate it to the ad account user. The Widgetized Campaign Manager will create a new ad account if the Ad account ID has never been used before. The Campaign Manager will also update the title of the ad account when signing in via this SSO workflow if it differs from the current title we stored in the database. You must use the same IDs in the seller_id column found in the catalog feed if the ad account is a seller in the platform.

Ad Manager Account ID and Title

For Ad Manager Account users, you will need to set the ID and title of the ad manager account. The Ad Manager Account must already exist in the system beforehand. The campaign manager will only update the title if provided.

User roles

For more information please review the User Roles & Permissions page.

Path

Path defines the first screen that users will see after the SSO process. Ad Account Home would be the best choice for most use cases because it provides core performance metrics and all the features that are needed to manage ad campaigns To use it as the first page, set it as /embed/sponsored-ads/cm/a/[ad-account-id], /embed/sponsored-ads/cm/ama/[ad-manager-account-id], or /embed/sponsored-ads for ad account, ad manager account, and agency users, respectively. If you’d like to set a specific page as a landing page, please contact your Moloco representative.

Build the SSO URL - V1.1.0 (Recommended)

The following sections describe how to build and sign an SSO URL using V1.1.0, the latest and recommended version. If you are implementing the Widgetized Campaign Manager for the first time, start here.

Building and signing your SSO URL will require you to write code. Please examine our sample code repository before you start: https://github.com/moloco-mcm/sso-examples.

An SSO Login URL has the following format:

https://[host]/sso?[parameters]&signature=[signature]

Host

The host is the location where the MCM portal is hosted. Please use the domain name that your Moloco representative provided during the onboarding process.

Parameters

The following parameters should be provided to specify the information required to process the request.

Parameter	Data Type	Required or Optional	Note
path	String	Required	The path to the landing page. Example: `/embed/sponsored-ads/cm/a/ad_account_1234`
platform_id	String	Required	A unique identifier for the platform in the MCM Portal. Example: `MYCOMMERCE`, `MYCOMMERCE_TEST`
ad_account_id	String	Required	A unique identifier for the ad account in the MCM Portal. Example: `ad_account_1234`
name	String	Required	User's name
email	String	Required	User's email address
role	String	Required	User's role. It must be one of the following: `PLATFORM_OWNER` `AD_ACCOUNT_OWNER` `AD_ACCOUNT_USER` `AD_ACCOUNT_AGENCY`
external_user_id	String	Required	A unique identifier for the user in your system. (Limit: `50` characters)
timestamp	Integer	Required	The current time in a UNIX timestamp in seconds (NOT in milliseconds). Example: `1625771555`
nonce	String	Required	Any random string that cannot be repeated within an hour. This helps to prevent an attacker from re-submitting a legitimate SSO URL to take control over the user. Example: `07e00c8b8b99`
version	String	Required	The version of the signature. Always put the value as `1.0.0`
ad_account_title	String	Optional	The title or name of the ad account. If omitted and the ad account is not yet created, ad_account_id will be used as the title.
ad_account_ids	String	Optional	Array of ad account IDs (max 20) for multi-account AGENCY role. All ad accounts must already exist.
ad_manager_account_id	String	Optional	A unique identifier for the ad manager account. The AMA entity must already exist.
ad_manager_account_title	String	Optional	The title of the ad manager account. If provided, the ad manager account title will be updated.
config:language	String	Optional	UI language. For example, use `en` for English and `ko` for Korean.
config:color_mode	String	Optional	UI color mode. Set the value as `light` or `dark`

Signature

Every valid SSO Login URL must be signed with the pre-registered secret key. The steps to sign an SSO Login URL are as follows.

1. Gather all parameters in alphabetical order

Collect all parameters used for the SSO request and arrange their values in the canonical order. Parameters with the “config:” prefix should not be included.

Canonical parameter order

ad_account_id
ad_account_ids
ad_account_title
ad_manager_account_id
ad_manager_account_title
email
external_user_id
name
nonce
path
platform_id
role
timestamp
version

2. Create the canonical message

Concatenate the parameter values in the exact order above using a newline character(\n).

const canonicalMessage = params.join('\n');

3. Generate the signature

Generate the signature by hashing the canonical message using HMAC-SHA256 with your SSO secret key, and encode the result using Base64.

const crypto = require('crypto');

const signature = crypto
  .createHmac('sha256', 'your_sso_secret_key')
  .update(canonicalMessage)
  .digest('base64');

Example 1. Ad Account Owner

const params = [
  'ad_account_1234',              // ad_account_id
  '',                             // ad_account_ids (empty array = empty string)
  'Test Ad Account',              // ad_account_title
  '',                             // ad_manager_account_id
  '',                             // ad_manager_account_title
  '[email protected]',            // email
  'User_1234',                    // external_user_id
  'John Smith',                   // name
  '07e00c8b8b99',                 // nonce
  '/embed/sponsored-ads/cm/a/ad_account_1234', // path
  'GS_SHOP',                      // platform_id
  'AD_ACCOUNT_OWNER',             // role (enum as string)
  '1625771555',                   // timestamp (as string)
  '1.1.0',                        // version
];

const canonicalMessage = params.join('\n');
/*
ad_account_1234

Test Ad Account


[email protected]
User_1234
John Smith
07e00c8b8b99
/embed/sponsored-ads/cm/a/ad_account_1234
GS_SHOP
AD_ACCOUNT_OWNER
1625771555
1.1.0
*/

const crypto = require('crypto');
const signature = crypto.createHmac('sha256', 'your_sso_secret_key')
  .update(canonicalMessage)
  .digest('base64');
/*
Example output: kX7Y2mN9pQ3wR8sT4vU6zA1bC5dE7fG8hI9jK0lM2nO=
*/

Example 2. Ad Account Agency (Multi-account)

// Note: ad_account_ids array is joined with semicolon ';' separator
const adAccountIdsArray = ['acc_123', 'acc_456', 'acc_789'];
const adAccountIds = adAccountIdsArray.join(';'); // 'acc_123;acc_456;acc_789'

const params = [
  '',                             // ad_account_id
  adAccountIds,                   // ad_account_ids (array joined with ';')
  '',                             // ad_account_title
  '',                             // ad_manager_account_id
  '',                             // ad_manager_account_title
  '[email protected]',           // email
  'User_5678',                    // external_user_id
  'Agency Manager',               // name
  'a1b2c3d4e5f6',                 // nonce
  '/embed/sponsored-ads/cm/agency', // path
  'GS_SHOP',                      // platform_id
  'AD_ACCOUNT_AGENCY',            // role (enum as string)
  '1625771555',                   // timestamp (as string)
  '1.1.0',                        // version
];

const canonicalMessage = params.join('\n');
/*

acc_123;acc_456;acc_789



[email protected]
User_5678
Agency Manager
a1b2c3d4e5f6
/embed/sponsored-ads/cm/agency
GS_SHOP
AD_ACCOUNT_AGENCY
1625771555
1.1.0
*/

const crypto = require('crypto');
const signature = crypto.createHmac('sha256', 'your_sso_secret_key')
  .update(canonicalMessage)
  .digest('base64');
/*
Example output: kX7Y2mN9pQ3wR8sT4vU6zA1bC5dE7fG8hI9jK0lM2nO=
*/

Example 3. Ad Manager Account Owner

const params = [
  '',                             // ad_account_id
  '',                             // ad_account_ids (empty array = empty string)
  '',                             // ad_account_title
  'ama_9999',                     // ad_manager_account_id
  'Premium Ad Manager Account',   // ad_manager_account_title
  '[email protected]',        // email
  'User_9999',                    // external_user_id
  'Jane Doe',                     // name
  'f6e5d4c3b2a1',                 // nonce
  '/embed/sponsored-ads/cm/ama/ama_9999', // path
  'GS_SHOP',                      // platform_id
  'AD_MANAGER_ACCOUNT_OWNER',     // role (enum as string)
  '1625771555',                   // timestamp (as string)
  '1.1.0',                        // version
];

const canonicalMessage = params.join('\n');
/*



ama_9999
Premium Ad Manager Account
[email protected]
User_9999
Jane Doe
f6e5d4c3b2a1
/embed/sponsored-ads/cm/ama/ama_9999
GS_SHOP
AD_MANAGER_ACCOUNT_OWNER
1625771555
1.1.0
*/

const crypto = require('crypto');
const signature = crypto.createHmac('sha256', 'your_sso_secret_key')
  .update(canonicalMessage)
  .digest('base64');
/*
Example output: kX7Y2mN9pQ3wR8sT4vU6zA1bC5dE7fG8hI9jK0lM2nO=
*/

🚧
Caution
SSO URLs with timestamps older than 5 mins will be considered expired. Always generate the SSO URLs on the fly; do not pre-generate or cache the SSO URL.

Present the campaign manager

Once you get the final signed SSO URL, you can present the Widgetized Campaign Manager by setting it as the “src” attribute of an iframe tag.

<iframe src="<https://rmp-sample-domain.com/sso?ad_account_id=ad-account-id&ad_account_title=My+Ad+Account&email=test%40example.com&external_user_id=user-id&name=Example+User+Name&nonce=OdWlPI8W4XMzoKzJMqU%2F%2FB75wJQ%3D&path=%2Fembed%2Fsponsored-ads%2Fcm%2Fa%2Fad-account-id&platform_id=RMP_PLATFORM_ID&role=AD_ACCOUNT_OWNER&timestamp=1636003094&version=1.0.0&signature=9B9Ls%2Bktk7NIAckz2vFXtF6jppjJF44jl8TGP%2FO%2Fjog%3D&config:color_mode=light&config:language=en>" style="width: 800px; height: 600px;" />

🚧
Caution
The Widgetized Campaign Manager does not persist user login sessions. User sessions will be cleared as soon as the iframe element that hosts the Campaign Manager is unmounted. In the case that the user wants to return to the Campaign Manager after visiting different pages, you’ll need to create another SSO URL. For enhanced security, SSO URLs are valid only for 5 minutes after creation. Please avoid pre-generating or caching the URLs.

⚠️ The following section applies only if you are maintaining an existing V1.0.0 integration. Follow the instructions for only one version.

Build the SSO URL - V1.0.0 (Legacy - for existing integrations only)

The following sections will guide you on how to build your SSO URL using the Legacy V1.0.0. This legacy version is still supported for existing integrations.

Do not use V1.0.0 for new integrations. If possible, migrate to V1.1.0 to access additional user roles and improved navigation.

Building and signing your SSO URL will require you to write code. Please examine our sample code repository before you start: https://github.com/moloco-mcm/sso-examples.

An SSO Login URL has the following format:

https://[host]/sso?[parameters]&signature=[signature]

Host

The host is the location where the MCM portal is hosted. Please use the domain name that your Moloco representative provided during the onboarding process.

Parameters

The following parameters should be provided to specify the information required to process the request.

Parameter	Data Type	Required or Optional	Note
path	String	Required	The path to the landing page. Example: `/embed/sponsored-ads/cm/a/ad_account_1234`
platform_id	String	Required	A unique identifier for the platform in the MCM Portal. Example: `MYCOMMERCE`, `MYCOMMERCE_TEST`
ad_account_id	String	Required	A unique identifier for the ad account in the MCM Portal. Example: `ad_account_1234`
name	String	Required	User's name
email	String	Required	User's email address
role	String	Required	User's role. It must be one of the following: `PLATFORM_OWNER` `AD_ACCOUNT_OWNER` `AD_ACCOUNT_USER` `AD_ACCOUNT_AGENCY`
external_user_id	String	Required	A unique identifier for the user in your system. (Limit: `50` characters)
timestamp	Integer	Required	The current time in a UNIX timestamp in seconds (NOT in milliseconds). Example: `1625771555`
nonce	String	Required	Any random string that cannot be repeated within an hour. This helps to prevent an attacker from re-submitting a legitimate SSO URL to take control over the user. Example: `07e00c8b8b99`
version	String	Required	The version of the signature. Always put the value as `1.0.0`
ad_account_title	String	Optional	The title or name of the ad account. If omitted and the ad account is not yet created, ad_account_id will be used as the title.
config:language	String	Optional	UI language. For example, use `en` for English and `ko` for Korean.
config:color_mode	String	Optional	UI color mode. Set the value as `light` or `dark`.

Signature

Every valid SSO Login URL must be signed with the pre-registered secret key. The steps to sign an SSO Login URL are as follows.

1. Gather all parameters in alphabetical order

Parameters with the “config:” prefix should not be included.

const params = [
 'ad_account_1234', // ad_account_id
 'Test ad account', // ad_account_title
 '[email protected]', //  email
 'User_1234', // external_user_id
 'John Smith', //  name
 '07e00c8b8b99', // nonce
 '/embed/sponsored-ads/cm/a/ad_account_1234', // path
 'GS_SHOP', // platform_id
 'AD_ACCOUNT_OWNER', // role
 '1625771555', // timestamp in string format
 '1.0.0', // version
];

2. Concatenate the values with line break `\n`.

const concatenatedString = params.join('\n');
/*
ad_account_1234
Test ad account
[email protected]
User_1234
ads.rmp-moloco.com
John Smith
07e00c8b8b99
/embed/sponsored-ads/cm/a/ad_account_1234
GS_SHOP
AD_ACCOUNT_OWNER
1625771555
1.0.0
*/

3. Create a signature by hashing the string we created in the previous step using HMAC-SHA256 with base64 encoding and your SSO secret key.

const crypto = require('crypto');
const signature = crypto.createHmac('sha256', 'secret').update(concatenatedString).digest('base64');

/*
7uruQXp6crvhz/ZhgiOWElkPrU9wpWo2Ho1ctM+1JZ4=
*/

🚧
Caution
SSO URLs with timestamps older than 5 mins will be considered expired. Always generate the SSO URLs on the fly; do not pre-generate or cache the SSO URL.

Present the campaign manager

Once you get the final signed SSO URL, you can present the Widgetized Campaign Manager by setting it as the “src” attribute of an iframe tag.

<iframe src="<https://rmp-sample-domain.com/sso?ad_account_id=ad-account-id&ad_account_title=My+Ad+Account&email=test%40example.com&external_user_id=user-id&name=Example+User+Name&nonce=OdWlPI8W4XMzoKzJMqU%2F%2FB75wJQ%3D&path=%2Fembed%2Fsponsored-ads%2Fcm%2Fa%2Fad-account-id&platform_id=RMP_PLATFORM_ID&role=AD_ACCOUNT_OWNER&timestamp=1636003094&version=1.0.0&signature=9B9Ls%2Bktk7NIAckz2vFXtF6jppjJF44jl8TGP%2FO%2Fjog%3D&config:color_mode=light&config:language=en>" style="width: 800px; height: 600px;" />

🚧
Caution
The Widgetized Campaign Manager does not persist user login sessions. User sessions will be cleared as soon as the iframe element that hosts the Campaign Manager is unmounted. In the case that the user wants to return to the Campaign Manager after visiting different pages, you’ll need to create another SSO URL. For enhanced security, SSO URLs are valid only for 5 minutes after creation. Please avoid pre-generating or caching the URLs.

The screenshot below shows how Widgetized Campaign Manage will look like after loaded in an iframe.

Introduction

Required information

SSO secret key

Platform ID

Ad Account ID and Title

Ad Manager Account ID and Title

User roles

Path

Build the SSO URL - V1.1.0 (Recommended)

Host

Parameters

Signature

1. Gather all parameters in alphabetical order

2. Create the canonical message

3. Generate the signature

Example 1. Ad Account Owner

Example 2. Ad Account Agency (Multi-account)

Example 3. Ad Manager Account Owner

Caution

Present the campaign manager

Caution

Build the SSO URL - V1.0.0 (Legacy - for existing integrations only)

Host

Parameters

Signature

1. Gather all parameters in alphabetical order

2. Concatenate the values with line break \n.

3. Create a signature by hashing the string we created in the previous step using HMAC-SHA256 with base64 encoding and your SSO secret key.

Caution

Present the campaign manager

Caution

2. Concatenate the values with line break `\n`.