Secure a Custom Activity Using an OAuth 2.0 Bearer Token

Marketing Cloud Engagement supports the use of OAuth 2.0 bearer tokens in calls to external services. By using OAuth 2.0 bearer tokens, you can increase the security of requests that come into and out of Marketing Cloud Engagement.

Create a JWT Bearer Token

To use OAuth 2.0 to secure your requests to external services, you must first configure Marketing Cloud Engagement to obtain bearer tokens from your token exchange endpoint. After you configure Marketing Cloud Engagement to obtain these tokens, it automatically uses them in the request headers for requests that you make to external applications.

In Setup, under Data Management, select Key Management.
Click Create.
For Key Type, choose Security Context.
For Name, enter a name for the key.
For External Key, enter an external key.
The value that you enter can contain only ASCII characters.
For Grant Type, select the type of grant to issue:
- To create a key that is authenticated using a client key and client secret, select Client Credentials. This option is helpful for basic server-to-server authentication. This type of grant is defined in section 2.3.1 of RFC 6749.
- To create a key that is authenticated using a private key in a signed JWT, select Client Credentials with JWT assertion. This option is helpful for secure authentication between servers. This type of grant is defined in section 4.2 of RFC 7521 and section 2.2 of RFC 7523.
- To create a key that is authenticated using a JWT that contains a user assertion, select Authorization grant with JWT assertion. This option is helpful in single sign-on (SSO) scenarios. This type of grant is defined in section 4.1 of RFC 7521 and section 2.1 of RFC 7523.
For Content Type, select a value to use in the content-type headers of requests that Marketing Cloud Engagement sends to the external application. Choose from these options:
- application/json
- application/x-www-form-urlencoded
Make sure that the value you select aligns with the content type that the token endpoint expects.
Note
Complete the remaining fields for the grant type you selected. This table lists the properties that you specify to create a key.

Property	Applies to These Grant Types	Description
Audience	Authorization grant with JWT assertion Client Credentials with JWT Assertion	The JWT audience name to use in the token exchange.
Client ID	Client Credentials	A public identifier for the client.
Client Secret	Client Credentials	The private credential that is used to authenticate the client.
Issuer	Authorization grant with JWT assertion Client Credentials with JWT Assertion	The JWT issuer name to use in the token exchange.
Key ID	Authorization grant with JWT assertion Client Credentials with JWT Assertion	The unique ID that identifies the key used to sign the JWT for an authorization grant.
Private Key	Authorization grant with JWT assertion Client Credentials with JWT Assertion	An RSA private key in PEM format.
Subject	Authorization grant with JWT assertion Client Credentials with JWT Assertion	The JWT subject to use in the token exchange.
Token Endpoint	Client Credentials Client Credentials with JWT Assertion	The URL of the external web service to call to retrieve an access token.
Valid Service URLs	Authorization grant with JWT assertion Client Credentials Client Credentials with JWT Assertion	The URLs that the returned access token applies to. Enter each URL on a new line. You can specify up to 10 URLs.

To add extra parameters to the key request, specify them in the Key and Value fields, and then click Add.
If you add parameters, you must specify both the key and the value.
Save the key.

Use the Bearer Token in Journeys

After you configure Marketing Cloud Engagement to perform token exchanges, you can create or update journeys to use OAuth 2.0 authentication. In your custom activity, add a securityOptions object. The object must contain this information. (Substitute <externalKeyName> for the name that you provided when you configured the key exchange.)

1"securityOptions": {
2  "securityType": "securityContext",
3  "securityContextKey": "<externalKeyName>"
4}

Sample Journey Request Payload

1{
2  "key": "<journeyKey>",
3  "name": "<journeyName>",
4  "version": 1,
5  "workflowApiVersion": 1,
6  "activities": [
7    {
8      "key": "REST-1",
9      "name": "Custom REST Activity",
10      "type": "REST",
11      "outcomes": [
12        {
13          "next": null
14        }
15      ],
16      "arguments": {
17        "execute": {
18          "inArguments": [
19            {
20              "message": "<message>"
21            }
22          ],
23          "outArguments": [],
24          "url": "https://example.com/post.php?dir=et_rest_activity_execute",
25          "body": "<emailBody>",
26          "headers": "",
27          "useJwt": false,
28          "securityOptions": {
29            "securityType": "securityContext",
30            "securityContextKey": "<externalKeyName>"
31          }
32          "timeout": 10000
33        }
34      },
35      "configurationArguments": {
36        "save": {
37          "url": "https://example.com/post.php?dir=et_rest_activity_save",
38          "body": "",
39          "headers": "",
40          "useJwt": false,
41          "securityOptions": {
42            "securityType": "securityContext",
43            "securityContextKey": "<externalKeyName>"
44          }
45        },
46        "validate": {
47          "url": "https://example.com/post.php?dir=et_rest_activity_validate",
48          "body": "",
49          "headers": "",
50          "useJwt": false,
51          "securityOptions": {
52            "securityType": "securityContext",
53            "securityContextKey": "<externalKeyName>"
54          }
55        },
56        "publish": {
57          "url": "https://example.com/post.php?dir=et_rest_activity_publish",
58          "body": "",
59          "headers": "",
60          "useJwt": false,
61          "securityOptions": {
62            "securityType": "securityContext",
63            "securityContextKey": "<externalKeyName>"
64          }
65        }
66      },
67      "metaData": {
68        "isConfigured": true
69      }
70    }
71  ],
72  "triggers": [],
73  "goals": [],
74  "entryMode": "SingleEntryAcrossAllVersions",
75  "executionMode": "Production",
76  "status": "Draft"
77}