Using the JOSE Security Policy v2 (Unencoded Payload Support)

Learn how to use the JOSE Security Policy v2 (Unencoded Payload Support) to sign and encrypt JSON message content.

About Policies Managing Policies About Operational Policies

For information about using policies in the context of the developer portal, see Business Policies.

Supported Platforms: 8.4.17 and later

Table of Contents

  1. Introduction
  2. Specifications
  3. JOSE Security Policy v2 support of the Open Banking specification
  4. Creating a JOSE Security Policy v2
  5. Configuring the JOSE Security Policy v2
  6. Configuring JOSE Security Policy v2 options
  7. Configuring JOSE Security Policy v2 IN Message options for Provider
  8. Configuring JOSE Security Policy v2 OUT Message options for Provider
  9. Configuring JOSE Security Policy v2 IN Message options for Consumer (2018.0.0 and later)
  10. Configuring JOSE Security Policy v2 OUT Message options for Consumer (2018.0.0 and later)
  11. Configuration values
  12. Configuring JOSE Security Policy v2 Audit Options
  13. Attaching the policy
  14. JSON versus compact structure, with examples
  15. Online tools for encoding and decoding
  16. JOSE Security Policy v2 (Unencoded Payload Support): troubleshooting

Introduction

The JOSE Security Policy v2 (Unencoded Payload Support) is an out-of-the-box operational policy that is part of the Policy Manager default installation.

The JOSE specification offers a way of signing payloads in such a way that it's relying on keys from whoever is doing the signing. With JOSE, a set of attributes are put together in a specific format, such that it's very clear what the consumer, or the provider, is trying to convey in that format. And then, verification follows a standard set of rules.

With JOSE Policy v2 you can do the following:

  • Sign and/or encrypt content
  • Validate signed and/or encrypted content
  • Send either signed or raw data to the client or the downstream service
  • Check for Open Banking specification requirements

This policy supports both of the following:

  • Scenarios where the entire message, including header, payload, and signature, is signed and/or encrypted.
  • A detached, unencoded payload scenario where the payload is sent as the body of the message and only the header and signature are signed and/or encrypted.

You can attach this policy to RESTful and Messaging services to secure any message content. Configuration options are flexible so that you can add more or less security as needed.

This policy includes the following additional functionality over the earlier JOSE Policy which is deprecated in 8.4.23 and 2018.0.0:

  • Support of the Unencoded Payload specification
  • Support of additional algorithms (PS256, PS384, and PS512)
  • Support of the crit headers required by the Open Banking specification
  • JWKS support (when configured for consumer Apps in the App OAuth Profile)

back to top

Specifications

The JOSE Security Policy v2 supports the following specifications:

Back to top

JOSE Security Policy v2 support of the Open Banking specification

JOSE Security Policy v2 includes the option to enable Open Banking support (Version 8.4.18 and later).

When you enable this feature, the policy enforces additional rules determined by the Open Banking specification (https://openbanking.atlassian.net/wiki/spaces/DZ/pages/4011436/Payment+Initiation+API+Specification+-+v1.0.0).

For example, it supports specifications regarding the Content-Type and Accept header values as well as the required crit header with specific values.

For full details, see Configuring JOSE Security Policy v2 options below (Enforce Open Banking section).

back to top

Creating a JOSE Security Policy v2

The first step in creating a policy is to define the basic policy information. Then, you can configure the policy details.

To add an operational policy
  1. Go to Workbench > Browse > Organization, and select Policies > Operational Policies. The Policies Summary is displayed.
  2. Click Add Policy.
  3. Choose the policy type and click Next.
  4. Specify a name (required) and description (optional) and click Finish. At the Completion Summary, Click Close. The Add Policy Wizard creates a draft policy instance that you can then configure on the Policy Details page.

For more information, see Add Policy.

back to top

Configuring the JOSE Security Policy v2

Once you've defined the basic policy information, you can configure the technical details that determine how the policy works when it's attached to a service.

To configure a JOSE Security Policy v2
  1. Go to Workbench > Browse > Organization and select the Policies > Operational Policies folder. The Policies Summary is displayed.
  2. Find the policy on the list and double-click to go to the Details page for the policy.
  3. In the second panel, click Modify to access the Specify JOSE Security Policy v2 Options page.
  4. Specify values for Protection Scope, Serialization, and Role, and optionally choose Unencoded Detached Payload. For details on field values, see Configuring JOSE Security Policy v2 options below. When you're done, click Next.

    The next pages are determined by your choices in the Options page:

    • The message options are different depending on the Role you specify, Provider (the default) or Consumer.
    • There are separate message option configuration pages for IN and for OUT/FAULT.
  5. If applicable: In the Specify JOSE Security Policy v2 IN Message Options for Provider page, specify values as needed. For details on field values, see Configuring JOSE Security Policy v2 IN Message options for Provider below. When you're done, click Next.
  6. If applicable: In the Specify JOSE Security Policy v2 OUT Message Options for Provider page, specify values as needed. For details on field values, see Configuring JOSE Security Policy v2 OUT Message options for Provider below. When you're done, click Next.
  7. If applicable: In the Specify JOSE Security Policy v2 IN Message Options for Consumer page, specify values as needed. For details on field values, see Configuring JOSE Security Policy v2 IN Message options for Consumer below. When you're done, click Next.
  8. If applicable: In the Specify JOSE Security Policy v2 OUT Message Options for Consumer page, specify values as needed. For details on field values, see Configuring JOSE Security Policy v2 OUT Message options for Consumer below. When you're done, click Next.
  9. In the Specify JOSE Security Policy v2 Audit Options page, specify values as needed. For details on field values, see Configuring JOSE Security Policy v2 Audit Options below.
  10. Click Finish.
  11. At the Completion Summary page, click Close.

After you've configured your policy, you can attach it to a web service, operation, or binding.

back to top

Configuring JOSE Security Policy v2 options

JOSE Security Policy v2 (Unencoded Payload Support): policy options

On this page, you specify general configuration settings. Refer to the details below.

Protection Scope
Identifies which messages in a message exchange will be protected by the policy. Choices:
  • IN: protects all incoming messages.
  • OUT: protects all outgoing messages.
  • FAULT: protects all fault messages.
Serialization
For serialization, you can specify Compact (dot-separated, consumes less bandwidth) or JSON (key-value pairs, more human-readable). For more information, refer to the applicable sections in the JWS RFC: JWS Compact Serialization and JWS JSON Serialization.
Role
Identifies the role that the platform takes in securing the messages:
  • Provider means that the platform acts as a provider to the client. The policy is applied to message exchanges between the client and the platform:
    • For IN messages (request messages), the client signs and/or encrypts the request per the policy configuration and sends it to the platform. The platform enforces the policy (verifies the signature and/or decrypts, and any other aspects of the policy configuration).
    • For OUT or FAULT messages (response messages), the downstream service sends the response to the platform. The platform implements the policy configuration (signs and/or encrypts), and sends it on to the client. The client enforces the policy (verifies the signature and/or decrypts, and any other aspects of the policy configuration).
  • Consumer means that the platform acts as a consumer to the downstream service. The policy is applied to message exchanges between the platform and the downstream service:
    • For IN messages (request messages), the platform acts as the client to the downstream service. The client sends the request to the platform. The platform implements the policy configuration (signs and/or encrypts), and sends it on to the downstream service. The downstream service enforces the policy agreement (verifies the signature and/or decrypts, and any other aspects of the policy configuration).
    • For OUT or FAULT messages (response messages), the downstream service implements the policy configuration to the response/fault message (signs and/or encrypts), and sends it to the platform. The platform enforces the policy (verifies the signature and/or decrypts, and any other aspects of the policy configuration).
Unencoded Detached Payload
Check this box if you want to exclude the payload from the signed and/or encrypted portion of the message. Instead, the payload is sent in the message body, unencoded. You'll also need to specify the Header Parameter Name—the name of the header containing a detached JWS signature of the body of the payload.
If you want the signing/encryption to apply to all parts of the message, including the payload, leave this box cleared (the default).
Note: If you check this box, for IN messages the client must send the b64 header, with a value of false; for OUT or FAULT messages, the platform sends the b64 header with a value of false. If the detached payload option is not used, the b64 header is not sent.
Sample header for unencoded detached payload:
{"kid":"signKey","alg":"RS256","cty":"application/json", "b64":false, "crit":["b64"]}
Sample header when unencoded detached payload is not selected:
{"kid":"signKey","alg":"RS256","cty":"application/json"}
Enforce Open Banking (8.4.18 and later)
Check this box if you want this policy to enforce the additional requirements of the Open Banking specification (https://openbanking.atlassian.net/wiki/spaces/DZ/pages/4011436/Payment+Initiation+API+Specification+-+v1.0.0). If you choose this option, the policy enforces the following additional rules as per the Open Banking specification:
  • The Content-Type header must be set to application/json.
  • If there is an Accept header, it is set to application/json.
  • The crit header is a string array of the b64, iat, and iss headers: "b64", "http://openbanking.org.uk/iat", "http://openbanking.org.uk/iss".
  • The values for the iat and iss headers comply with the Open Banking specification, as per the above.

Click Next to go to the next page, which is determined by your choice in the Protection Scope field:

Back to top

Configuring JOSE Security Policy v2 IN Message options for Provider

JOSE Security Policy v2 (Unencoded Payload Support): IN options (Provider role)

If you choose a Protection Scope of IN and a role of Provider, you'll need to determine signing and encryption settings for incoming messages.

There are two main categories of settings: Signed Content and Encrypted Content. For each, if you choose to sign and/or encrypt, additional configuration options are available so that you can specify the identity of the signed content for IN messages, as shown below.

Signed content, Subject Category
If you specify signed content for IN messages, define the Subject Category, the identity whose private key is used to sign the message. For IN messages, the options are:
  • Consumer: If you choose Consumer, you can specify that the configuration settings should be read from the JWKS URL for the identity specified in the kid in the incoming header. See Referencing the JWKS URL from the App OAuth Profile below.
  • End User: The end-user identity associated with the message.
  • User Defined: If you choose User Defined, specify a custom category name; for example, a platform identity such as a platform user.
Encrypted content, Subject Category
If you specify encrypted content for IN messages, define the Subject Category—the owner of the private key used to encrypt the content, and the corresponding public key will be used to decrypt the incoming message. Choices:
  • Service: A service on the platform.
  • User Defined: If you choose User Defined, specify a custom category name; for example, a platform identity such as a platform user.
Private Headers (8.4.18 and later)
A private header is any header other than the registered headers defined by the specification; see Private Header Parameter Names section of RFC 7515.
You can specify one or more private headers; check the box and specify the header name and value. You can also add or delete existing private headers as needed.
Referencing the JWKS URL from the App OAuth Profile

You can set up this policy to read the applicable JWKS URL for the consumer, from the app's OAuth profile in the developer portal, if it's been set up. For instructions on setting up the JWKS URL and other values in the App OAuth Profile page, see What are the settings available on the App OAuth Profile page? (Authentication Settings section). You can also add it using the platform API; see PUT /api/apps/versions/{AppVersionID}/oauthclient (CM API doc).

Back to top

Configuring JOSE Security Policy v2 OUT Message options for Provider

JOSE Security Policy v2 (Unencoded Payload Support): OUT options (Provider role)

If you choose a Protection Scope of OUT and/or FAULT and a role of Provider, you'll need to determine signing and encryption settings for outbound messages.

If you choose to sign and/or encrypt content for OUT and/or FAULT messages, configure the signing and encryption options. The settings will apply to OUT messages, FAULT messages, or both.

You can also specify one or more private headers. This page has three sections:

Sign Content options for OUT or FAULT messages
Signature/MAC Algorithm
Choose the algorithm to be used for signing the OUT or FAULT messages. For a list of valid options, see Sign Content: supported Signature/MAC Algorithms below.
Embed Key
Check the box if you want to embed the public key in the signed content, so that the client can use the key to verify the signature.
Subject Category
If you specify signed content for OUT or FAULT messages, define the Subject Category, the identity whose private key is used to sign the message. For Out or Fault messages, the options are:
  • Service: A service on the platform.
  • User Defined: If you choose User Defined, specify a custom category name; for example, a platform identity such as a platform user.
Custom Headers
If a custom header is used for the encrypted content, check the box and specify the header name and value. You can also add or delete existing custom headers as needed.
Encrypt Content options for OUT or FAULT messages

For OUT messages, the option to reference the JWKS URL is not included, since there might be multiple kid (Key ID) header parameters specified at the JWKS URL. Instead, you can specify the kid to use, in the Custom Headers section.

Encryption Algorithm
Choose the algorithm to be used for encrypting the OUT or FAULT messages. For a list of valid options, see Encrypt Content: supported Encryption Algorithms below.
Key Management Algorithm
Choose the algorithm to be used for the OUT or FAULT messages. For a list of valid options, see Encrypt Content: supported Key Management Algorithms below.
Subject Category
If you specify signed content for OUT or FAULT messages, define the Subject Category. Choices:
  • Consumer: If you choose Consumer, you can choose to use the JWKS URL to read the configuration settings.
  • End User: The end-user identity associated with the message.
  • User Defined: If you choose User Defined, specify a custom category name; for example, a platform identity such as a platform user.
Private Headers

A private header is any header other than the registered headers defined by the specification; see the Private Header Parameter Names section of RFC 7515.

You can specify one or more private headers; check the box and specify the header name and value. You can also add or delete existing private headers as needed.

Back to top

Configuring JOSE Security Policy v2 IN Message options for Consumer

Valid in version: 2018.0.0 and later

JOSE Security Policy v2 (Unencoded Payload Support): IN options (Consumer role)

If you choose a Protection Scope of IN and a role of Consumer, you'll need to configure the signing and encryption options that will apply to response messages coming in from the downstream service.

You can also specify one or more private headers. This page has three sections:

Sign Content options for IN messages
Signature/MAC Algorithm
Choose the message signing algorithm. For a list of valid options, see Sign Content: supported Signature/MAC Algorithms below.
Embed Key
Check the box if the public key will be embedded in the signed content, so that the platform can use the key to verify the signature.
Subject Category
If you specify signed content for IN messages, define the Subject Category, the identity whose private key is used to sign the message. Options:
  • Service: A service on the platform.
  • User Defined: If you choose User Defined, specify a custom category name; for example, a platform identity such as a platform user.
Custom Headers
If a custom header is used for the encrypted content, check the box and specify the header name and value. You can also add or delete existing custom headers as needed.
Encrypt Content options for IN messages

For IN messages, the option to reference the JWKS URL is not included, since there might be multiple kid (Key ID) header parameters specified at the JWKS URL. Instead, you can specify the kid to use, in the Custom Headers section.

Encryption Algorithm
Choose the algorithm to be used for encrypting the IN messages. For a list of valid options, see Encrypt Content: supported Encryption Algorithms.
Key Management Algorithm
Choose the algorithm to be used for the OUT messages. For a list of valid options, see Encrypt Content: supported Key Management Algorithms.
Subject Category
If you specify signed content for IN messages, define the Subject Category. Choices:
  • Consumer: If you choose Consumer, you can choose to use the JWKS URL to read the configuration settings.
  • End User: The end-user identity associated with the message.
  • User Defined: If you choose User Defined, specify a custom category name; for example, a platform identity such as a platform user.

Back to top

Configuring JOSE Security Policy v2 OUT Message options for Consumer

Valid in version: 2018.0.0 and later

JOSE Security Policy v2 (Unencoded Payload Support): OUT options (Consumer role)

If you choose a Protection Scope of OUT and/or FAULT and a role of Consumer, you'll need to configure the signing and encryption options for outbound messages to the client. When the messages come in from the downstream service, the platform will apply these settings to the content and send it to the client.

There are two main categories of settings: Signed Content and Encrypted Content. For each, if you choose to sign and/or encrypt, additional configuration options are available so that you can specify the identity of the signed content for IN messages, as shown below.

Signed content, Subject Category
If you specify signed content for OUT or FAULT messages, define the Subject Category, the identity whose private key is used to sign the message. For IN messages, the options are:
  • Consumer: If you choose Consumer, you can specify that the configuration settings should be read from the JWKS URL for the identity specified in the kid in the incoming header. See Referencing the JWKS URL from the App OAuth Profile below.
  • End User: The end-user identity associated with the message.
  • User Defined: If you choose User Defined, specify a custom category name; for example, a platform identity such as a platform user.
Encrypted content, Subject Category
If you specify encrypted content for IN messages, define the Subject Category—the owner of the private key used to encrypt the content, and the corresponding public key will be used to decrypt the incoming message. Choices:
  • Service: A service on the platform.
  • User Defined: If you choose User Defined, specify a custom category name; for example, a platform identity such as a platform user.
Private Headers (8.4.18 and later)
A private header is any header other than the registered headers defined by the specification; see Private Header Parameter Names section of RFC 7515.
You can specify one or more private headers; check the box and specify the header name and value. You can also add or delete existing private headers as needed.
Referencing the JWKS URL from the App OAuth Profile

You can set up this policy to read the applicable JWKS URL for the consumer, from the app's OAuth profile in the developer portal, if it's been set up. For instructions on setting up the JWKS URL and other values in the App OAuth Profile page, see What are the settings available on the App OAuth Profile page? (Authentication Settings section). You can also add it using the platform API; see PUT /api/apps/versions/{AppVersionID}/oauthclient (CM API doc).

Back to top

Configuration values

This section includes information about configuration values available for the JOSE Policy v2, including:

Sign Content: supported Signature/MAC Algorithms

The Signature/MAC algorithms supported by the JOSE Security Policy v2 for signing content are:

Encrypt Content: supported Encryption Algorithms

The encryption algorithms supported by the JOSE Security Policy v2 for encrypting content are:

  • A128CBC-HS256
  • A192CBC-HS384
  • A256CBC-HS512
  • A128GCM
  • A192GCM
  • A256GCM

Encrypt Content: supported Key Management Algorithms

The Key Management algorithms supported by the JOSE Security Policy v2 for encrypting content are:

  • None
  • RSA1_5
  • RSA-OAEP
  • A128KW
  • A192KW
  • A256KW
  • A128GCMKW
  • A192GCMKW
  • A256GCMKW

Back to top

Configuring JOSE Security Policy v2 Audit Options

JOSE Security Policy v2 (Unencoded Payload Support): Audit Options

Once you've created the policy, you can configure the audit options on the Specify JOSE Security Policy v2 Audit Options page.

Choose from the available options controlling the audit data that's captured:

Generate Audit Data
Enables the audit feature. By default, this captures all message data, whether success or failure, for all message exchanges.
On Error Only
If you choose to generate audit data, you can specify that audit data is captured only when an error occurs on a message exchange.

Attaching the policy

To use the JOSE Security Policy v2, go to the Policies folder in the Root Organization and attach the policy to a web service, binding, or binding operation.

Back to top

JSON versus compact structure, with examples

For serialization, you can specify Compact (dot-separated, consumes less bandwidth) or JSON (key-value pairs, more human-readable). These are just two different ways of showing the same information.

For full details, refer to the applicable sections in the JWS RFC: JWS Compact Serialization and JWS JSON Serialization.

This section includes the following examples:

These are just examples. For guidance on how to structure your messages, refer to the specification: https://tools.ietf.org/html/rfc7797.

JSON format, not detached

Refer to RFC 7797 JWS specification:

The example below shows a response message in JSON format with the payload not detached.

Body (payload)

This example has a protected header, payload, signature, and the headers themselves:

  • The headers are raw data.
  • The protected value is base-64 encoding of the headers.
  • The payload is base 64-encoded.
  • The signature signs all those things together.
{
  "protected":"eyJraWQiOiJzaWduS2V5IiwiYWxnIjoiUlMyNTYiLCJjdHkiOiJhcHBsaWNhdGlvbi9qc29uIiwiY3JpdCI6WyJiNjQiXX0",
  "payload":"eyJQVVQtcmVzcG9uc2UiOiJzaWduZWQgam9zZSByZXNwb25zZSJ9",
  "signature":"damrs8P_kUGDR0RJ6Vn1aB6VDHgGwZZyFXsYwzGLSXvHg60BNsTNn8geKAA-ObcnEDj_5-FTBt42u8Kt0MGkzWcvxkM4iU8mC
yAaxqpA1zv_4r0I-bk46Odt9VeKXiLezjRoLLctLvD-LRgVvwNG9EMmwe_qV6tWUCChSdw7cAxH9dthqD3sKmHBtVWEzO1PVWIQn46TuWCEeBla0
ggiK6UPYD4fnJCpGiq_3r_6Ygb64YjnjSMScoF2-f8z8mGZptOZsojzlI_bcJ3yFRyzit__uwQcyMBQ73maen9gZnXb48RCy-QTdEAQbhOWXYDe8
oCFYaoEOkGZlREUmWcQtQ",
  "header":{
    "kid":"signKey",
    "alg":"RS256",
    "cty":"application/json"
  }
}

Detached header

Not applicable.

JSON format, detached

Refer to RFC 7797 JWS specification:

The detached versions of JSON is similar, but the payload is unsigned. The payload is sent in the body of the message, and the other values are sent in a header. The name of the header is defined as part of the policy definition setup.

The example below shows the same response message used in the previous example, in JSON format with detached payload.

With JSON detached, you put the payload in the body and the rest of the message goes in the header.

Body (payload)

{
  "PUT-response": "signed JOSE response"
}

Detached header

This example has a protected header, signature, and the headers themselves.

{
  "protected":"eyJraWQiOiJzaWduS2V5IiwiYWxnIjoiUlMyNTYiLCJjdHkiOiJhcHBsaWNhdGlvbi9qc29uIiwiYjY0IjpmYWxzZSwiY3JpdCI6WyJiNjQiXX0",
  "signature":"AuwXL1pWxgQfyS7Scim0uhqGyLyehkQtp4sAaW9Fz5X10HkcAWS5zY4F-xwYeiGb21ZrL6yurxfPPKpkwD9F8W6p1jYqOaEX5leu49r0VDWoWE
lw-X6c9v4PiYRfEu38jwxgbppZkQRke9RyfbO9yQw9ZUgNCo-Q0NIvgcM4JducNz09qsPrHuSJiOQ86TyOyKfug9zsahJ7-rpxxPicvGfVRMlRhGeKNgG57ombDsD
stmZKsRWrVx-tnmLX7aIhz9NL0jOmRf1deh4HAenk7JKPzUgAxZssylmTCivkuV10yrdlIgyUYELkHNz63QQVcXdODHFWvdSHWJvwx_xe2A",
  "header":{
    "kid":"signKey",
    "alg":"RS256",
    "cty":"application/json",
    "b64":false,
    "crit":[
      "b64"
    ]
  }
}

Compact format, not detached

Refer to RFC 7797 JWS specification:

With Compact format, the request is similar in structure, but it's not a JSON object.

It is simply a compact version of the information. The values should be the same, if the content is the same.

The example below shows the body (payload) of the same response message used in the previous examples, now in Compact format. Line breaks have been added for display purposes.

The Compact structure is in three sections:

  1. The protected value, followed by a period separator.
  2. The payload value, followed by a period separator.
  3. The signature (signed with the private key of the sender).
eyJraWQiOiJzaWduS2V5IiwiYWxnIjoiUlMyNTYiLCJjdHkiOiJhcHBsaWNhdGlvbi9qc29uIiwiY3JpdCI6WyJiNjQiXX0.eyJQVVQtcmVzcG9uc2UiOiJzaWd
uZWQgam9zZSByZXNwb25zZSJ9.damrs8P_kUGDR0RJ6Vn1aB6VDHgGwZZyFXsYwzGLSXvHg60BNsTNn8geKAA-ObcnEDj_5-FTBt42u8Kt0MGkzWcvxkM4iU8mC
yAaxqpA1zv_4r0I-bk46Odt9VeKXiLezjRoLLctLvD-LRgVvwNG9EMmwe_qV6tWUCChSdw7cAxH9dthqD3sKmHBtVWEzO1PVWIQn46TuWCEeBla0ggiK6UPYD4f
nJCpGiq_3r_6Ygb64YjnjSMScoF2-f8z8mGZptOZsojzlI_bcJ3yFRyzit__uwQcyMBQ73maen9gZnXb48RCy-QTdEAQbhOWXYDe8oCFYaoEOkGZlREUmWcQtQ

Detached header

Not applicable.

Compact format, detached

Refer to RFC 7797 JWS specification:

As with detached JSON, the payload is unsigned, so the middle part of the message, between the two periods, is missing. The raw payload is sent with the request or returned with the response.

In this scenario, the detached payload goes into a header.

The example below shows the body (payload) of the same response message in Compact format with detached payload. Line breaks have been added for display purposes.

In this example, the structure is in three sections:

  1. The protected value, followed by a period separator.
  2. No payload, just a second period separator.
  3. The signature (signed with a public key).

The detached version is similar to the previous example, but the payload is sent separately in the body, un-encoded, and is not included as the second section of the detached header. The period separators are preserved.

{
  "PUT-response": "signed JOSE response"
}

Detached header

Note the two consecutive periods on line 4, where the payload is missing.

eyJraWQiOiJzaWduS2V5IiwiYWxnIjoiUlMyNTYiLCJjdHkiOiJhcHBsaWNhdGlvbi9qc29uIiwiYjY0IjpmYWxzZSwiY3JpdCI6WyJiNjQiLCJodHRwOi8vb3Bl
bmJhbmtpbmcub3JnLnVrL2lhdCIsImh0dHA6Ly9vcGVuYmFua2luZy5vcmcudWsvaXNzIl0sImh0dHA6Ly9vcGVuYmFua2luZy5vcmcudWsvaWF0IjoxNTMyNjQz
NjExLCJodHRwOi8vb3BlbmJhbmtpbmcub3JnLnVrL2lzcyI6IkNOPW9iam9zZXNpZ25lciwgT1U9QWxpQm9icywgTz1BbGksIEw9TG9uZG9uLCBTVD1Mb25kb24s
IEM9R0IgIn0..Eg7LgJakjT9e0eCsin8MtKbtqFxOguvMFA7dT-xpT60nsU1ulZZJvsSYwo_kZxe-06aMIR7dxkXaWT7eH6vPZYSTrzn0KuYRt_VR6uin9D6-QLY
LTIDMG8p5VlzqyQlMppzDAJq2plxPoSk2MJC7hMCd76niw-tdnoC4LdhRMZK9YfVt-GUk11a78XarzRGPFJ96tZ4d1qHWTm2eIbIJ10EMHXPPmh5U8HbRuBvFr6U
GGnTnuLMVaiPLNHLsbCMNaVm50QjcabxlQWfKgGPSHH-7QmNwRSOubBJD7e7Y-JeLZJ6zGHe4sWECZVwhKFgsBX2jH_ZijIq1jrMdKp5W6w

Back to top

Online tools for encoding and decoding

In working with JOSE payloads, you can use the following tools for base-64 encoding or decoding:

Back to top

JOSE Security Policy v2 (Unencoded Payload Support): troubleshooting

This section includes some guidance regarding errors that customers have encountered when using the JOSE Security Policy v2 (Unencoded Payload Support) policy, and the remedies.

Encoded characters in the payload

If characters are encoded in the payload, the results might not be as expected.

Nested JSON objects

The JSON structure should be per the JOSE specification, as shown in the examples above.

If there are modifications to the structure—for example, if the JSON object is nested within another JSON object—results might not be as expected.

Required header is missing

If your JOSE policy v2 is set up to require a specific header, and the required header is missing, the following error is generated:

Authentication error. No JWS content found with given header name [{header_name}]

Solution: make sure the required header is present. The header name must be exactly as set up in the policy definition.

Unexpected character in the payload

If there is a problem with the payload, so that the pre-encoding and post-encoding values would not match, the following error is generated:

Authentication error. Parsing error: org.jose4j.json.internal.json_simple.parser.ParseException: unexpected 
character ({char}) at position ({position}).

Solution: check the sequencing to find out why the beginning and ending values are different, and fix accordingly.

Back to top