Configuring secrets in event forwarding

Last update: 2023-10-24
  • Topics:
  • Tags
    View more on this topic
  • Created for:
  • Developer
    User
    Admin
    Leader

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.

The following secret types are currently supported:

Secret type Description
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.
HTTP Contains two string attributes for a username and password, respectively.
LinkedIn OAuth 2 The system asks you for the required information, then handles the renewal of these tokens for you on a specified interval.
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.
OAuth 2 JWT Contains several attributes to support JSON Web Token (JWT) Profile for OAuth 2.0 Authorization grants. The system asks you for the required information, then handles the renewal of these tokens for you on a specified interval.
Token A single string of characters representing an authentication token value that is known and understood by both systems.

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

OAuth 2 JWT

To create an OAuth 2 JWT secret, select OAuth 2 JWT from the Type dropdown.

The Create Secret tab with the OAuth 2 JWT secret highlighted in the Type dropdown.

NOTE

The only Algorithm that is currently supported for signing the JWT is RS256.

In the fields that appear below, provide your Issuer, Subject, Audience, Custom Claims, TTL, then select the Algorithm from the dropdown. Next, enter the Private Key Id, as well as your Token URL for your OAuth integration. The Token URL field is not a mandatory field. If a value is provided, the JWT is exchanged with an access token. The secret will be refreshed according to the expires_in attribute from the response and the Refresh Offset value. If a value is not provided, the secret pushed to the edge is the JWT. The JWT will be refreshed according to the TTL and Refresh Offset values.

The Create Secret tab with a selection of input fields highlighted.

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

The Create Secret tab highlighting the Credential Options fields.

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.

The Create Secret tab highlighting the Refresh Offset field.

For example, if the refresh offset is set to the default value of 1800 (30 minutes) and the access token has an expires_in value of 3600 (one hour), the system will automatically refresh the secret in one hour.

IMPORTANT

An OAuth 2 JWT secret requires at least 30 minutes between refreshes and must also be valid for a minimum of one hour. This restriction gives you a minimum of 30 minutes to intervene if problems arise with the generated token.

For example, if the offset is set to 1800 (30 minutes) and the access token has an expires_in of 2700 (45 minutes), the exchange would fail due to the resulting difference being less than 30 minutes.

When finished, select Create Secret to save the secret.

The Create Secret tab highlighting Create Secret

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.

LinkedIn OAuth 2

To create a LinkedIn OAuth 2 secret, select LinkedIn OAuth 2 from the Type dropdown. Next, select Create Secret.

The Create Secret tab with the Type field highlighted.

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

LinkedIn authorization popover highlighting Create & Authorize secret with LinkedIn.

A dialog appears prompting you to enter your LinkedIn credentials. Follow the prompts to grant event forwarding access to your data.

Once the authorization process is complete, you are returned to the Secrets tab, where you can see your newly created secret. Here you can see the status of the secret and the date of expiration.

The Secret tab highlighting the newly created secret.

Reauthorize a LinkedIn OAuth 2 secret

IMPORTANT

You are required to reauthorize using your LinkedIn credentials every 365 days. If you do not reauthorize in due time, your secret will not be refreshed, and the LinkedIn conversion requests will fail.

Three months prior to the secret requiring reauthorization, a popup will begin to show when you are navigating any page of the property. Select Click here to go to your secrets.

The Property Overview tab highlighting the secret re-authorization popup.

You are redirected to the Secrets tab. The secrets listed on this page are filtered to show only the secrets that need to be reauthorized. Select Auth Needed for the secret you need to reauthorize.

The Secret tab highlighting Auth Neededfor the LinkedIn secret.

A dialog appears that prompts you to enter your LinkedIn credentials. Follow the prompts to reauthorize your secret.

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