Configure authentication for a Streaming SDK connector

Authentication is required for all connectors built with Streaming SDK. Before you submit or release a connector, configure one supported authentication mechanism:

Configure the mechanism that matches your connector’s integration model.

Before you begin

Make sure that you have:

Additional OAuth requirements

If you use OAuth 2.0, make sure that you have:

For the appropriate Adobe credential type and implementation details, see:

Additional HMAC requirements

If you use HMAC, make sure that you have:

Configure OAuth 2.0

1. Create or select an Adobe credential

First, you must create or select Adobe Developer Console credential required by your connector.

Configure:

Do not use a credential type that is not supported by the connector’s integration model.

2. Store the OAuth configuration securely

Store the following values securely:

Do not commit client secrets to source control or include them in logs, error messages, screenshots, or test results.

3. Add the OAuth configuration to your connector

Store the OAuth configuration values in your connector’s own configuration or service. Streaming SDK does not define a connection specification field for this authentication step, because it governs how your connector calls the Streaming Ingestion API, not how Experience Platform connects to your source.

Your connector’s configuration must include:

4. Obtain an access token

Implement the OAuth flow documented for your credential type.

The connector must:

5. Add the access token to requests

Include the access token as a bearer token on requests sent by the connector:

Authorization: Bearer {ACCESS_TOKEN}

Use HTTPS for all requests.

6. Handle token failures

The connector should detect and handle authentication failures, including:

When a token expires, obtain a new token using the documented OAuth flow and retry only when the operation is safe to retry.

Configure HMAC-based authentication

1. Configure the shared secret

Create or obtain the shared secret required by the connector and configure it in the connector or webhook setup.

The secret must be:

2. Serialize the event

Serialize the event before calculating the signature.

The signature must be calculated from the same serialized message that the connector sends in the request body.

serializedMessage = serialize(event)

Do not calculate the signature from one representation of the event and send another representation. Changes to whitespace, property order, escaping, encoding, or line endings can cause signature validation to fail.

3. Calculate the HMAC-SHA256 signature

Calculate the HMAC-SHA256 value using:

signature = HMAC-SHA256(secret, serializedMessage)

4. Add the HMAC header

Add the calculated signature to the request as the x-hmac-sha256 header:

POST <streaming-ingestion-endpoint>
Content-Type: application/json
x-hmac-sha256: {CALCULATED_SIGNATURE}

<serialized-message>

For example, the header resolves to a value similar to:

{
  "x-hmac-sha256": "5f2c8b7e0d9c3a4e6b1f2d3c4a5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b1c2d3"
}

The header value must represent the HMAC-SHA256 calculation for the exact request body sent to Adobe.

5. Send the request

Send the signed request over HTTPS to the Streaming Ingestion API endpoint.

The Streaming Ingestion API verifies the signature before processing the event. Requests with a missing or invalid signature are rejected.

6. Rotate the secret safely

When you rotate a secret, follow this sequence:

Verify the connector

Test the connector with both successful and unsuccessful authentication scenarios.

Troubleshooting

OAuth authentication failures

Check the following:

HMAC authentication failures

Check the following:

Submission requirements

Before you submit or release your connector, confirm the following:

Next steps

With authentication configured and verified, continue to Test and submit your source. To learn how to document the authentication requirements for your source, see Document your source (Streaming SDK).