Authentication

The App Developer framework uses JSON Web Tokens (JWT) to authenticate. The full specification is described here. To construct JWT tokens and learn the set of supported JWT libraries for a variety of languages and platforms, refer to http://jwt.io.

This topic provides an explanation of the JWT claims and signature values required to authenticate requests when working with the framework.

In this topic:

JSON Web Tokens

A JWT consists of 3 parts separated by a dot (.). The three parts are: Header.Payload.Signature. For example, a token resembles: 

eyJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJhYmQ1NDU2OC1jODgyLTRhM2ItYTk2MS04MDE4ZTg2MmQ2MzMiLCJhdWQiOiJhbXMiLCJleHAiOjE1MDc5NjcwNjQsImlhdCI6MTUwNzc1MTA2NH0.1vjP4oQUI0dWxQSlyV7D26Ml4567oQqBTZA3W6x2J1Q

 

This token is inserted into the Authorization header with the Bearer schema.

Authorization: Bearer eyJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJhYmQ1NDU2OC1jODgyLTRhM2ItYTk2MS04MDE4ZTg2MmQ2MzMiLCJhdWQiOiJhbXMiLCJleHAiOjE1MDc5NjcwNjQsImlhdCI6MTUwNzc1MTA2NH0.1vjP4oQUI0dWxQSlyV7D26Ml4567oQqBTZA3W6x2J1Q

 

Let's take a closer look at each part of a token.

Header

The header, at the very minimum specifies the encoding algorithms that is used, which is currently only HS256.

{
  "alg": "HS256"
}

 

This object is then Base64Url encoded and results in an output string similar to eyJhbGciOiJIUzI1NiJ9 to form the first part of our token.

Payload

The payload is an object in JSON that contains standard and private claims. This JSON is then Base64Url encoded to form the second part of the JWT from our example.

eyJpc3MiOiJhYmQ1NDU2OC1jODgyLTRhM2ItYTk2MS04MDE4ZTg2MmQ2MzMiLCJhdWQiOiJhbXMiLCJleHAiOjE1MDc5NjcwNjQsImlhdCI6MTUwNzc1MTA2NH0

Signature

To create the signature part you have to take the encoded header, the encoded payload, your App Provider Token Secret or the shared secret between the Oracle CX Marketing product and the app, the algorithm specified in the header, and sign that. Note the placement of the dot (.).

HMACSHA256(
  base64UrlEncode(header) + "." +
  base64UrlEncode(payload),
  secret)

This hash then forms the third part of the JWT from our example.

The output is three Base64 strings separated by dots that can be easily passed in HTML and HTTP environments.

eyJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJhYmQ1NDU2OC1jODgyLTRhM2ItYTk2MS04MDE4ZTg2MmQ2MzMiLCJhdWQiOiJhbXMiLCJleHAiOjE1MDc5NjcwNjQsImlhdCI6MTUwNzc1MTA2NH0.1vjP4oQUI0dWxQSlyV7D26Ml4567oQqBTZA3W6x2J1Q

Depending on the request when authenticating with the framework, different claims and signatures are required.

AMS and apps authentication flow

This section explains how AMS authenticates with apps and vice versa.

AMS to app

AMS will make requests to an app's URL endpoints throughout the app's lifecycle. An app's URL endpoints are developed by an app developer and then registered with AMS when an app is created.

To authenticate with an app, AMS will construct a JWT payload using information about the app such as the applications UUID, token key, and so on, and then sign that with the app's token secret.

Example JWT claims

When AMS is making a request to an app's install URL endpoint, the key and value pairs bear the following meanings:

Key Value Definition Context
iss The current issuer of the token. Set to "AMS".
sub The subject of the token. Set to the app's product UUID.
aud The audience of the token. Set to the app's Token Key.
exp The date and time the token will expire, expressed as a Unix timestamp. Must be after the current date/time. Set to 60 seconds after the JWT was created.
iat The date and time the JWT was issued, expressed as a Unix timestamp. Set to the current time.
jti The unique identifier for the JWT token. Set to a random UUID.
o.a.p.ctenantId The tenant Id. Set to the id of the tenant as identified by the product.
o.a.p.cproductUUID The product UUID. Set to the UUID of the product associated with the current installation.
o.a.p.cproductName The product name. Set to the name of the product, associated with the current installation.
o.a.p.csourceRequest The Source Id. Set to the UUID of the product associated with the current installation.
o.a.p.cdestinationId The destination Id. Set to the app's UUID. Found in app details.
o.a.p.cdestinationUrl The destination URL. The destination URL is the app's base URL + the app's URL endpoint for the request. These URLs are found in app details.

Note: The private claims, prefixed with o.a.p.c, are not used in all AMS to app JWT tokens.

Example JWT Payload

The JWT payload that AMS uses to call the application install endpoint may resemble the following:

{
  "iss": "AMS",
  "sub": "4af33f82-25c3-44ec-8594-7c39ef2079d4",
  "aud": "4701447f-20f1-4a25-875f-52e36d6a93ae",
  "exp": 1539915991,
  "iat": 1539915932,
  "jti": "88062cca-9b58-4391-a713-4817662526af",
  "o.a.p.ctenantId": "607",
  "o.a.p.cproductUUID": "4af33f82-25c3-44ec-8594-7c39ef2079d4",
  "o.a.p.cproductName": "Mock Product",
  "o.a.p.csourceRequest": "4af33f82-25c3-44ec-8594-7c39ef2079d4",
  "o.a.p.cdestinationId": "c1fce274-09c5-457a-a916-141de834b4cd",
  "o.a.p.cdestinationUrl": "http://localhost:8090/appInstalls/install"
}

App to AMS

When an app makes a request to AMS, the app will generate a JWT token with various JWT claims and sign it using its application secret. AMS verifies the request and JWT are valid, and then performs the request.

Example JWT claims

When an app is making a request to the AMS endpoint to view app details (/ams/rest/2.0/providers/{providerUuid}/applications/{applicationUuid}), the key and value pairs bear the following meanings:

Key Value Definition Context
iss The issuer of the token. Set to the app's Token Key.
aud The audience of the token. Set to "AMS".
exp The date and time the token will expire, expressed as a Unix timestamp. Must be after the current date/time. Set to the time the JWT should expire.
iat The date and time the JWT was issued, expressed as a Unix timestamp. Set to the current time.
jti The unique identifier for the JWT token. Set to a random UUID.

Example JWT Payload

The JWT payload for this token may resemble the following:

{
  "iss" : "4701447f-20f1-4a25-875f-52e36d6a93ae",
  "aud" : "AMS",
  "exp": 1539915991,
  "iat": 1539915932,
  "jti": "88062cca-9b58-4391-a713-4817662526af"
}

JWT signature

Signed using the app's token secret.

App and product authentication flow

This section explains how apps authenticate with Oracle CX Marketing (Oracle CX Marketing) products and vice versa.

Apps and products can communicate directly with each other. Products and apps can expose endpoints to which each other can call, using a predetermined JWT payload schema for authorization. For these type of requests, JWT tokens are signed using the app's install secret.

If the app does not know the app's install secret, a request can be sent to retrieve the secret. Otherwise, apps can proceed to calling the app's endpoint if the secret is known.

Retrieving the app install secret

The app install secret is provided during app installation. If the app does not know the app install secret, apps can retrieve the install secret by making a request to the following REST endpoint (signed with an app token key as described in App to AMS authentication):

GET ams/rest/2.0/providers/{providerUuid}/applications/{applicationUuid}/installs/{installUuid}

Response body

Both calls will return status code 200 and the following response payload, which contains the install secret as secret.

{
  "uuid": "some-install-uuid",
  "status": "UP",
  "statusMessage": {
    "body": "some body",
    "eta": 1541536016323,
    "reason": "some reason"
  },
  "configurationStatus": "CONFIGURED",
  "configurationStatusMessage": {
    "body": "some body",
    "eta": 1541536016323,
    "reason": "some reason"
  },
  "requiresConfiguration": false,
  "installedOn": "Nov 06, 2018",
  "application": {
    "uuid": "some-app-uuid",
    "name": "some app name",
    "description": "some description",
    "enabled": 1,
    "baseUrl": "http://someBaseUrl.com",
    "statusUrl": "/someStatusUrl",
    "installUrl": "/someInstallUrl",
    "configureUrl": "/someConfigureUrl",
    "saveConfigurationUrl": "/someSaveConfigurationUrl",
    "uninstallUrl": "/someUninstallUrl",
    "smallLogo": "/someSmallLogo",
    "mediumLogo": "/someMediumLogo",
    "largeLogo": "/someLargeLogo",
    "status": "UP",
    "statusMessage": {
      "body": "some body",
      "eta": 1541536015843,
      "reason": "some reason"
    },
    "publicationStatus": "DEVELOPMENT",
    "createdAt": 1541536015871,
    "updatedAt": 1541536015871,
    "platform": false
  },
  "tenant": {
    "uuid": "some-tenant-uuid",
    "restUrl": "http://someRestUrl.com",
    "product": {
      "uuid": "some-product-uuid",
      "name": "Some Product Name",
      "description": "some description",
      "loginUrl": "https://someLoginUrl.com",
      "redirectInstallUrl": "https://someLoginUrl.com",
      "dependencyUrl": "https://someDependencyUrl.com",
      "largeLogo": "https://someLargeUrl.com",
      "mediumLogo": "https://someMediumUrl.com",
      "smallLogo": "https://someSmallUrl.com",
      "deleted": 0,
      "enabled": 1
    },
    "enabled": 0
  },
  "productManaged": false,
  "secret": "some-install-secret",
  "enabled": 0
}

 

After the app has obtained the app's install secret, a new JWT must be constructed to communicate with the product. The new JWT is signed with the app's install secret.

Product to app authentication

This example demonstrates the authentication required for a product to call an app, when the product is calling an app's invoke endpoint.

Required request headers

When a product is calling an app, the Oracle CX Marketing-ID request header is required to specify the product's UUID.

Oracle CX Marketing-ID: <Oracle CX MarketingProductUUID>

When the app receives the call to the Invoke URL endpoint, first the app verifies the Oracle CX Marketing-ID contains a valid instance UUID. The app will then verify the JWT.

Example JWT claims

When a product is making a request to an app, the key and value pairs bear the following meanings:

Key Value Definition Context
iss The issuer of the token. Set to product's UUID.
sub The subject of the token. Set to the installed app's install UUID.
aud The audience of the token. Set to the installed app's service instance UUID.
exp The date and time the JWT will expire, expressed as a Unix timestamp.

Set to the time the JWT should expire.

AMS does not put a restriction on the expiration length, but it is advised to keep it as short as possible.
iat The date and time the JWT was issued, expressed as a Unix timestamp. Set to the current time.
o.a.p.ctenantId The tenant Id. Set to the id of the tenant as identified by the product.

Example JWT payload

{
  "iss": "4af33f82-25c3-44ec-8594-7c39ef2079d4",
  "sub": "4e8bc944-e2b8-4aa0-b81e-de788b95d26f",
  "aud": "154b33d5-5d83-4541-9aa7-806b901d28b4",
  "exp": 1539981608,
  "iat": 1539981578,
  "o.a.p.ctenantId": "607"
}

JWT signature

Signed using the app's install secret.

App to product authentication

This example demonstrates the authentication required for an app to call a product, when the app is calling the product's completion callback endpoint.

Example JWT claims

When a product is making a request to an app, the key and value pairs bear the following meanings:

Key Value Definition Context
iss The issuer of the token. Set to the app's UUID.
sub The subject of the token. Set to the installed app's install UUID.
aud The audience of the token. Set to the installed app's service instance UUID.
exp The date and time the JWT will expire, expressed as a Unix timestamp.

Set to the time the JWT should expire.

AMS does not put a restriction on the expiration length, but it is advised to keep it as short as possible.
iat The date and time the JWT was issued, expressed as a Unix timestamp. Set to the current time.
o.a.p.ctenantId The tenant Id. Set to the id of the tenant as identified by the product.

Example JWT payload

{
  "iss": "154b33d5-5d83-4541-9aa7-806b901d28b4",
  "sub": "4e8bc944-e2b8-4aa0-b81e-de788b95d26f",
  "aud": "4af33f82-25c3-44ec-8594-7c39ef2079d4",
  "exp": 1539981608,
  "iat": 1539981578,
  "o.a.p.ctenantId": "607"
}

JWT signature

Signed using the app's install secret.

App to product API authentication

Product APIs can be invoked by an app with or without an instance being created.

This example demonstrates the authentication required for an app to call a product API.

Required request headers

When an app is calling the product API, the Invocation-Id request header is required to be specified as omc-apps.

Authorization : Bearer token ( JWT)

Invocation-Id : omc-apps

Example JWT claims

When a product is making a request to a product API, the key and value pairs bear the following meanings:

Key Value Definition Context
iss The issuer of the token. Set to the app's UUID.
sub The subject of the token. Set to the installed app's install UUID.
aud The audience of the token. Set to Product UUID.
exp The date and time the JWT will expire, expressed as a Unix timestamp.

Set to the time the JWT should expire.

It is advised to keep it as short as possible.
iat The date and time the JWT was issued, expressed as a Unix timestamp. Set to the current time.
o.a.p.ctenantId The tenant Id. Set to the id of the tenant as identified by the product.

Example JWT payload

{
  "iss": "154b33d5-5d83-4541-9aa7-806b901d28b4",
  "sub": "4e8bc944-e2b8-4aa0-b81e-de788b95d26f",
  "aud": "4af33f82-25c3-44ec-8594-7c39ef2079d4",
  "exp": 1539981608,
  "iat": 1539981578,
  "o.a.p.ctenantId": "607"
}

JWT signature

Signed using the app's install secret.

Authentication to third parties

When building apps that authenticate using a third-party application's account credentials, you must ensure that these windows pop out of the App Manager window. For example, during the configuration of your app, you might want to prompt marketers to be able to enter their Facebook credentials. To ensure this process is successful, this configuration user experience must pop out of the App Manager configuration user experience. For more information about developing the configuration user experience, see App Configuration.

JWT resources

The following are useful third-party resources to help you create your JSON web tokens:

Learn more

Developer topics

Developing Apps for CX Apps