Configuring secrets in event forwarding

In event forwarding, a secret is a resource that represents an authentication credential for another system, allowing for the secure exchange of data. Secrets can only be created within event forwarding properties.

There are currently three supported secret types:

Secret type Description
Token A single string of characters representing an authentication token value that is known and understood by both systems.
HTTP Contains two string attributes for a username and password, respectively.
OAuth 2 Contains several attributes to support the client credentials grant type for the OAuth 2.0 authentication spec. The system asks you for the required information, then handles the renewal of these tokens for you on a specified interval.
Google OAuth 2 Contains several attributes to support the OAuth 2.0 authentication spec for use in the Google Ads API and Pub/Sub API. The system asks you for the required information, then handles the renewal of these tokens for you on a specified interval.

This guide provides a high-level overview of how to configure secrets for an event forwarding (Edge) property in the Experience Platform UI or Data Collection UI.

NOTE

For detailed guidance on how to manage secrets in the Reactor API, including example JSON of a secret’s structure, refer to the secrets API guide.

Prerequisites

This guide assumes that you are already familiar with how to manage resources for tags and event forwarding in the UI, including how to create a data element and an event forwarding rule. See the guide on managing resources if you require an introduction.

You should also have a working understanding of the publishing flow for tags and event forwarding, including how to add resources to a library and install a build onto your website for testing. See the publishing overview for more details.

Create a secret

To create a secret, select Event Forwarding in the left navigation, then open the event forwarding property you want to add the secret under. Next, select Secrets in the left navigation, followed by Create New Secret.

Create new secret

The next screen allows you to configure the details of the secret. In order for a secret to be usable by event forwarding, it must be assigned to an existing environment. If you do not have any environments created for your event forwarding property, see the guide on environments for guidance on how to configure them before continuing.

NOTE

If you still want to create and save the secret before adding it to an environment, disable the Attach Secret to Environments toggle before filling in the rest of the information. Note that you will have to assign it to an environment later if you want to use the secret.

Disable environment

Under Target Environment, use the dropdown menu to select the environment you want to assign the secret to. Under Secret Name, provide a name for the secret in the context of the environment. This name must be unique across all secrets under the event forwarding property.

Environment and name

A secret can only be assigned to one environment at a time, but you can assign the same credentials to multiple secrets across different environments if you wish. Select Add Environment to add another row to the list.

Add environment

For each environment you add, you must provide another unique name for the associated secret. If you exhaust all available environments, the Add Environment button will be unavailable.

Add environment unavailable

From here, the steps to create the secret differ depending on the type of secret you are creating. Refer to the subsections below for details:

Token

To create a token secret, select Token from the Type dropdown. In the Token field that appears, provide the credential string that is recognized by the system you are authenticating to. Select Create Secret to save the secret.

Token secret

HTTP

To create an HTTP secret, select Simple HTTP from the Type dropdown. In the fields that appear below, provide a username and password for the credential before selecting Create Secret to save the secret.

NOTE

Upon being saved, the credential is encoded using the “Basic” HTTP authentication scheme.

HTTP secret

OAuth 2

To create an OAuth 2 secret, select OAuth 2 from the Type dropdown. In the fields that appear below, provide your Client ID and Client Secret, as well as your Token URL for your OAuth integration. The Token URL field in the UI is a concatenation between the authorization server host and the token path.

OAuth 2 secret

Under Credential Options, you can provide other credential options such as scope and audience in the form of key-value pairs. To add more key-value pairs, select Add another.

Credential options

Finally, you can configure the Refresh Offset value for the secret. This represents the number of seconds before the token expiry that the system will perform an automatic refresh. The equivalent time in hours and minutes is displayed to the right of the field and updates automatically as you type.

Refresh Offset

For example, if the refresh offset is set to the default value of 14400 (four hours) and the access token has an expires_in value of 86400 (24 hours), the system will automatically refresh the secret in 20 hours.

IMPORTANT

An OAuth secret requires at least four hours between refreshes and must also be valid for a minimum of eight hours. This restriction gives you a minimum of four hours to intervene if problems arise with the generated token.

For example, if the offset is set to 28800 (eight hours) and the access token has an expires_in of 36000 (ten hours), the exchange would fail due to the resulting difference being less than four hours.

When finished, select Create Secret to save the secret.

Save OAuth 2 Offset

Google OAuth 2

To create a Google OAuth 2 secret, select Google OAuth 2 from the Type dropdown. Under Scopes, select the Google APIs that you want to use this secret to grant access to. The following products are currently supported:

When finished, select Create Secret.

Google OAuth 2 secret

A popover appears informing you that the secret needs to be manually authorized through Google. Select Create & Authorize to continue.

Google authorization popover

A dialog appears that allows you to enter the credentials for your Google account. Follow the prompts to grant event forwarding access to your data under the selected scope. Once the authorization process is complete, the secret is created.

IMPORTANT

If your organization has a re-authentication policy set for Google Cloud applications, the created secrets will not be refreshed successfully after the authentication expires (between 1 and 24 hours depending on the policy configuration).

To resolve this issue, sign in to the Google Admin console and navigate to the App access control page so you can mark the event forwarding app (Adobe Real-Time CDP Event Forwarding) as Trusted. Refer to the Google documentation on setting session lengths for Google Cloud services for more information.

Edit a secret

After you have created secrets for a property, you can find them listed in the Secrets workspace. To edit the details of an existing secret, select its name from the list.

Select secret to edit

The next screen allows you to change the name and credentials for the secret.

Edit secret

NOTE

If the secret is associated with an existing environment, you cannot reassign the secret to another environment. If you wish to use the same credentials on a different environment, you must create a new secret instead. The only way to reassign the environment from this screen is if you never assigned the secret to an environment beforehand or if you deleted the environment that the secret was attached to.

Retry a secret exchange

You can retry or refresh a secret exchange from the editing screen. This process varies depending on the type of secret being edited:

Secret type Retry protocol
Token Select Exchange Secret to retry the secret exchange. This control is only available when there is an environment attached to the secret.
HTTP If there is no environment attached to the secret, select Exchange Secret to exchange the credential to base64. If an environment is attached, select elect Exchange and Deploy Secret to exchange to base64 and deploy the secret.
OAuth 2 Select Generate Token to exchange the credentials and return an access token from the authentication provider.

Delete a secret

To delete an existing secret in the Secrets workspace, select the checkbox next to its name before selecting Delete.

Delete secret

Using secrets in event forwarding

In order to make use of a secret in event forwarding, you must first create a data element that references the secret itself. After saving the data element, you can include it in event forwarding rules and add those rules to a library, which in turn can be deployed to Adobe’s servers as a build.

When creating the data element, select the Core extension, then select Secret for the data element type. The right panel updates and provides dropdown controls to assign up to three secrets to the data element: one for Development, Staging, and Production respectively.

Data element

NOTE

Only secrets attached to the development, staging, and production environments appear for their respective dropdowns.

By assigning multiple secrets to a single data element and including it a rule, you can have the value of the data element change depending on where the containing library is in the publishing flow.

Data element with multiple secrets

NOTE

When creating the data element, a development environment must be assigned. Secrets for the staging and production environments are not required, but builds that try to transition to those environments will fail if their secret-type data elements do not have a secret selected for the environment in question.

Next steps

This guide covered how to manage secrets in the UI. For information on how to interact with secrets using the Reactor API, see the secrets endpoint guide.

On this page