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:
|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.|
|OAuth2||Contains several attributes to support the OAuth2 authentication spec. The system asks you for the required information, then handles the renewal of these tokens for you on a specified interval. Currently only the Client Credentials version of OAuth2 is supported.|
This guide provides a high-level overview of how to configure secrets for an event forwarding (Edge) property in the Data Collection UI.
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.
This guide assumes that you are already familiar with how to manage resources for tags and event forwarding in the Data Collection 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.
To create a secret, log in to the Data Collection UI and open the event forwarding property you want to add the secret under. Next, select Secrets in the left navigation, followed by 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.
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.
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.
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.
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.
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:
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.
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.
Upon being saved, the credential is encoded using the “Basic” HTTP authentication scheme.
To create an OAuth2 secret, select OAuth2 from the Type dropdown. In the fields that appear below, provide your Client ID and Client Secret, as well as your Authorization URL for your OAuth integration. The Authorization URL field in the Data Collection UI is a concatenation between the authorization server host and the token path.
Under Credential Options, you can provide other credential options such as
audience in the form of key-value pairs. To add more key-value pairs, select Add another.
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.
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.
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
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.
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.
The next screen allows you to change the name and credentials for the secret.
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.
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 to Cloudfare.|
|OAuth2||Select Generate Token to exchange the credentials and return an access token from the authentication provider.|
To delete an existing secret in the Secrets workspace, select the checkbox next to its name before selecting Delete.
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.
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.
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.
This guide covered how to manage secrets in the Data Collection UI. For information on how to interact with secrets using the Reactor API, see the secrets endpoint guide.