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.

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

Table of Contents

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.

Specifications

The JOSE Security Policy v2 supports the following specifications:

In addition, it supports the following versions of the UK Open Banking specification:

JOSE Security Policy v2: supported HTTP methods

The JOSE Security Policy v2 is applicable to only POST, PUT, PATCH methods. It is designed to protect the payload.

The message content must be in JSON format.

JOSE Security Policy v2 support of the Open Banking specification

The JOSE Security Policy v2 includes the option to enable Open Banking support.

This policy supports UK Open Banking versions as specified above.

When you enable this feature, the policy enforces additional rules determined by the Open Banking specification that you specify.

Some examples of UK Open Banking support are:

Content-Type and Accept header values

The JOSE Security Policy v2 enforces the requirements regarding the content-type and accept header values as per the applicable Open Banking specification.

crit claim

The JOSE Security Policy v2 supports the required crit claim with specific values.

3.0 and earlier:

For Open Banking 3.0 and earlier, the JOSE policy v2 supports sending the custom iat and iss claims, and supports specifying those custom claims in the crit claim, as per the specification.

For example, in version 2.0, the crit claim is required, and must be a string array of the three specific values shown below:

"b64", "http://openbanking.org.uk/iat", "http://openbanking.org.uk/iss"

3.1:

In version 3.1, the JOSE Security Policy v2 supports sending the additional tan claim which is required, see tan claim below, and supports including the tan claim in the crit claim, as per the specification.

In version 3.1, the crit claim is required and must be a string array of the four specific values shown below:

"b64", "http://openbanking.org.uk/iat", "http://openbanking.org.uk/iss", "http://openbanking.org.uk/tan"

For more information, see the Open Banking 3.1 specification: https://openbanking.atlassian.net/wiki/spaces/DZ/pages/937656404/Read+Write+Data+API+Specification+-+v3.1#Read/WriteDataAPISpecification-v3.1-ProcessforSigningaPayload (Step 2).

Note: The platform validates the tan header using the value configured in the policy. If no value is specified in the policy, the header is validated using the default value, openbanking.org.uk.

iat claim

JOSE Security Policy v2 supports the custom iat private header parameter claim.

For this claim, the details are the same for 2.0/3.0 and 3.1.

The JOSE policy v2 supports sending the iat claim, which must be a JSON number representing a UTC value, and validates it per the specification.

iss claim

JOSE Security Policy v2 supports the custom iss private header parameter claim.

3.0 and earlier:

For Open Banking 3.0 and earlier, the JOSE policy v2 supports sending the iss claim, and supports specifying it in the crit claim, as per the specification.

For example, for version 2.0, the iss claim must be a string with the ID of the third-party provider, and it must match the domain name of the signing certificate.

3.1:

For version 3.1, a JOSE policy using the JWKS URL option can retrieve the certificate to verify the iss claim from the JWKS rather than requiring the x5c claim to be in the JWS header. When retrieving the certificate, the policy looks in the following locations, in the specified sequence:

  1. The x5c parameter in the JWS header
  2. The x5c parameter from the JWKS URL
  3. The certificate for the consumer (app)

The X5C (X.509 Certificate Chain) parameter is defined as part of the JSON Web Key (JWK) spec. This parameter contains a chain of one or more certificates. The certificate chain is represented as a JSON array of certificate value strings.

tan claim (v3.1)

The tan claim is required in the JOSE header per the Open Banking 3.1 specification.

When Open Banking support is enabled in the policy, if a tan claim exists in the JWS header, the JOSE Security Policy v2 validates the header value and validates that it is present in the crit claim list.

For more information, see the Open Banking 3.1 specification: https://openbanking.atlassian.net/wiki/spaces/DZ/pages/937656404/Read+Write+Data+API+Specification+-+v3.1#Read/WriteDataAPISpecification-v3.1-ProcessforSigningaPayload (Step 2).

typ claim (v3.1)

The typ claim is optional in the JOSE header per the Open Banking 3.1 specification. If present, it must have the value JOSE.

The JOSE Security Policy v2 validates that if a typ claim exists, it has the correct value.

For more information, see the Open Banking 3.1 specification: https://openbanking.atlassian.net/wiki/spaces/DZ/pages/937656404/Read+Write+Data+API+Specification+-+v3.1#Read/WriteDataAPISpecification-v3.1-ProcessforSigningaPayload (Step 2).

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

Error messaging requirements (v3.1)

When you enable Open Banking support on the JOSE Security Policy v2, and choose version 3.1, the error messages returned to the API client application are formatted according to the Open Banking specification version 3.1; see Open Banking 3.1 specification, section titled Standard Error Code(s). By default, only a generic summary error message is returned.

For more information about the specific messaging used, see Open Banking error messages for the JOSE Security Policy v2.

Enforce Appendix F

Valid in version: 2019.1.14 and later

When you choose the Unencoded Detached Payload option, for the Provider role, and choose Enforce Appendix F, the policy applies Base64 encoding to the payload and removes the Base64 header, as covered in the Appendix F (Detached Content) section of the JWS specification (RFC-7515).

More detailed configuration information later in this document:

Creating a JOSE Security Policy v2

The first step in creating a policy is to define the basic policy information.

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.

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 activate it, then attach it to a web service, operation, or binding.

Configuring JOSE Security Policy v2 options

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

On the Specify JOSE Security Policy v2 Options page, 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.
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 claim, with a value of false; for OUT or FAULT messages, the platform sends the b64 claim with a value of false. If the detached payload option is not used, the b64 claim 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"}
Header Parameter Name—The name of the header containing a detached JWS signature of the body of the payload. For example, x-jws-signature. Required if Unencoded Detached Payload is checked.
Enforce Appendix F (2019.1.14 and later)—Optional: check this box if you want the policy to integrity-protect content that is not itself contained in the JWS. For details, refer to the Appendix F (Detached Content) section of the JWS specification (RFC-7515). This option is available only for Provider role, and only if Unencoded Detached Payload is checked.
When this box is checked, the policy applies Base64 encoding to the payload and removes the Base64 header.
UK Open Banking (3.1 support in all versions, URL support in 2019.1.0 and later)
Enable this option for conformance to the UK Open Banking specification. Check the box and then specify the version. Versions up to 3.1 are supported, as shown below.
Specify JOSE Policy v2 Option for Open Banking
If you choose this option, the policy enforces additional rules as per the Open Banking specification. For details, see JOSE Security Policy v2 support of the Open Banking specification.
If you choose Version 3.1, an additional field appears, Documentation URL:
Specify JOSE Policy v2 Option for Open Banking version 3.1: Documentation URL
In this field, you can specify the documentation URL to include with Open Banking-compliant error messages returned by the policy. The default value is the URL for the UK Open Banking Read/Write Data Specification version 3.1.1: https://openbanking.atlassian.net/wiki/spaces/DZ/pages/1000702294/Read+Write+Data+API+Specification+-+v3.1.1. You can change the value to another valid URL, which will be used in the Url field in error messages returned by your JOSE Security v2 policy.
For more information about Open Banking error message format, see Open Banking error messages for the JOSE Security Policy v2 below.

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

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 public 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
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 Community Manager 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).

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.

Configuring JOSE Security Policy v2 IN Message options for Consumer

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.

Configuring JOSE Security Policy v2 OUT Message options for Consumer

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
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 Community Manager 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).

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:

  • HS256
  • HS384
  • HS512
  • PS256
  • PS384
  • PS512
  • RS256
  • RS384
  • RS512
  • ES256
  • ES384
  • ES512

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

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.

Activating a policy

When you create and configure a policy, the policy is in Draft state. When the policy configuration is complete, activate the policy: click Activate Policy and then confirm. See Activate a Policy.

A policy in Draft state is not available for general use. Once you activate the policy, it is in Active state and is available for use.

Attaching a policy

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

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.

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.eyJQVVQtcmVzcG9uc2UiOiJzaWduZWQgam9zZSByZXNwb25zZSJ9.damrs8P_kUGDR0RJ6Vn1aB6VDHgGwZZyFXsYwzGLSXvHg60BNsTNn8geKAA-ObcnEDj_5-FTBt42u8Kt0MGkzWcvxkM4iU8mCyAaxqpA1zv_4r0I-bk46Odt9VeKXiLezjRoLLctLvD-LRgVvwNG9EMmwe_qV6tWUCChSdw7cAxH9dthqD3sKmHBtVWEzO1PVWIQn46TuWCEeBla0ggiK6UPYD4fnJCpGiq_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.

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.

eyJraWQiOiJzaWduS2V5IiwiYWxnIjoiUlMyNTYiLCJjdHkiOiJhcHBsaWNhdGlvbi9qc29uIiwiYjY0IjpmYWxzZSwiY3JpdCI6WyJiNjQiLCJodHRwOi8vb3BlbmJhbmtpbmcub3JnLnVrL2lhdCIsImh0dHA6Ly9vcGVuYmFua2luZy5vcmcudWsvaXNzIl0sImh0dHA6Ly9vcGVuYmFua2luZy5vcmcudWsvaWF0IjoxNTMyNjQzNjExLCJodHRwOi8vb3BlbmJhbmtpbmcub3JnLnVrL2lzcyI6IkNOPW9iam9zZXNpZ25lciwgT1U9QWxpQm9icywgTz1BbGksIEw9TG9uZG9uLCBTVD1Mb25kb24sIEM9R0IgIn0..Eg7LgJakjT9e0eCsin8MtKbtqFxOguvMFA7dT-xpT60nsU1ulZZJvsSYwo_kZxe-06aMIR7dxkXaWT7eH6vPZYSTrzn0KuYRt_VR6uin9D6-QLYLTIDMG8p5VlzqyQlMppzDAJq2plxPoSk2MJC7hMCd76niw-tdnoC4LdhRMZK9YfVt-GUk11a78XarzRGPFJ96tZ4d1qHWTm2eIbIJ10EMHXPPmh5U8HbRuBvFr6UGGnTnuLMVaiPLNHLsbCMNaVm50QjcabxlQWfKgGPSHH-7QmNwRSOubBJD7e7Y-JeLZJ6zGHe4sWECZVwhKFgsBX2jH_ZijIq1jrMdKp5W6w

Online tools for encoding and decoding

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

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.

Open Banking error messages for the JOSE Security Policy v2

As part of the UK Open Banking specification 3.1, error messages are returned as JSON objects with a specific format.

For full details, review the Error Response section of the Open Banking 3.1 specification.

This section includes information about the specific error messaging that Akana returns for the JOSE Security Policy v2. An example is given below.

{
  "Code":"[400] Bad Request",
  "Id":"94428-19d48b3e-c1ac-404a-9ac3-aaa1bc93e314",
  "Message":"An invalid or no value is supplied in the JOSE header.",
  "Errors":[
    {
      "ErrorCode":"UK.OBIE.Signature.Missing",
      "Message":"No JWS content found using header [x-jws-signature].",
      "Path":"x-jws-signature",
      "Url":"https://openbanking.atlassian.net/wiki/spaces/DZ/pages/16254920/Documentation"
    }
  ]
}

The Open Banking error message format includes the following values:

  • Code—Standard HTTP message code and definition.
  • Id—A unique ID assigned by the Akana platform. The first five digits correspond to the CM ID in the tables below.
  • Message—A short general explanation of the error. See OB Msg in the tables below.
  • Errors:
    • ErrorCode—UK Open Banking standard error code. See OB Code in the table below.
    • Message—An explanation of the error as it relates to the Open Banking context; for example, a header required by the Open Banking specification is missing. See OB Errors Msg in the tables below.
    • Path—Per the specification, a recommended but optional field referring to the element that generated the error. In the example above, the error was with the x-jws-signature header, so the value in the Path field in the JSON error response is the header name. In another scenario, if a claim is missing, the name of the claim is displayed in this field.
    • Url—A URL to additional information about UK Open Banking.

The tables below provide information about the specific error messages you might encounter when using the JOSE Security Policy v2 to process messages using the UK Open Banking version 3.1. Messages are broken down into the following groups:

Note: To find details about a specific error message, look for any value in the message and search in the tables below. In some cases there are multiple entries for a specific OB code or OB message. To arrive at the exact message applicable to your scenario, it's a good idea to search for the five-digit code at the beginning of the Id, which corresponds to the CM ID code below. For example, in the sample above, the Id value is 94428-19d48b3e-c1ac-404a-9ac3-aaa1bc93e314. The applicable line entry is 94428-uuid below.

Errors returning HTTP 400 Bad Request

Information on all HTTP 400 messages is below. Use the CM ID, or another value, to identify a specific message.

OB code/CM ID Value Meaning

UK.OBIE.Header.Invalid

94415-uuid

 Reason If Accept header is sent with the JOSE request, the value must be application/json.
OB Msg An HTTP header is invalid.
OB Errors Msg Accept header value [{0}] is invalid. The value should be [{1}].

UK.OBIE.Header.Missing

94414-uuid

 Reason Content-Type header is expected in the JOSE request.
OB Msg An HTTP header is invalid.
OB Errors Msg Content-Type header missing.

UK.OBIE.Signature.Invalid

94455-uuid

 Reason Error occurred during signature verification. JOSE-specific error is logged.
OB Msg Error verifying the message.
OB Errors Msg Error verifying signature of the message.

UK.OBIE.Signature.Invalid

94413-uuid

 Reason Error occurred during signature verification. No JOSE errors were thrown, but verification did not succeed.
OB Msg Error verifying the message.
OB Errors Msg Signature verification failure.

UK.OBIE.Signature.InvalidClaim

94457-uuid

 Reason The algorithm used to create a signature is using an algorithm that is unsupported.
OB Msg An invalid value is supplied in the JOSE header.
OB Errors Msg Algorithm is not supported.

UK.OBIE.Signature.InvalidClaim

94459-uuid

 Reason JWT is invalid, as determined by JOSE.
OB Msg The JOSE request has an invalid JWT.
OB Errors Msg JOSE-specific error.

UK.OBIE.Signature.InvalidClaim

94463-uuid

 Reason A header listed in crit header list is missing from the policy configuration Private Headers list.
OB Msg An invalid value is supplied in the JOSE header.
OB Errors Msg Crit header missing private key.

UK.OBIE.Signature.InvalidClaim

94464-uuid

 Reason b64 header is expected in the JOSE request, with a value of false.
OB Msg An invalid value is supplied in the JOSE header.
OB Errors Msg b64 header value is incorrect. It should be false.

UK.OBIE.Signature.InvalidClaim

94465-uuid

 Reason iat header is expected in the JOSE request, whose value is time in milliseconds.
OB Msg An invalid value is supplied in the JOSE header.
OB Errors Msg iat header value is incorrect. It should be timestamp in seconds.

UK.OBIE.Signature.InvalidClaim

94466-uuid

 Reason iat header value is expected in the JOSE request, with a value in the past.
OB Msg An invalid value is supplied in the JOSE header.
OB Errors Msg iat header value is incorrect. It should be timestamp in the past.

UK.OBIE.Signature.InvalidClaim

94467-uuid

 Reason iss header is expected in the JOSE request, with property values that match the cert for the JOSE request. Examples of these properties are CN=value, OU=value, O=value, L=value, ST=value, C=value.
OB Msg An invalid value is supplied in the JOSE header.
OB Errors Msg iss header value is incorrect. It should match the certificate issuer DN.

UK.OBIE.Signature.InvalidClaim

94468-uuid

 Reason tan header is expected in the JOSE request, with a String value that is non-null and non-empty.
OB Msg An invalid value is supplied in the JOSE header.
OB Errors Msg tan header value is incorrect. It should be a string value.

UK.OBIE.Signature.InvalidClaim

94469-uuid

 Reason tan header is expected in the JOSE request, with a value equal to the domain, openbanking.org.uk.
OB Msg An invalid value is supplied in the JOSE header.
OB Errors Msg tan header value is incorrect. It must match the domain name.

UK.OBIE.Signature.InvalidClaim

94470-uuid

 Reason If typ header is in the JOSE request, it must be set to the value "JOSE"
OB Msg An invalid value is supplied in the JOSE header.
OB Errors Msg typ header value is incorrect.

UK.OBIE.Signature.InvalidClaim

94412-uuid

 Reason Unable to determine verification key.
OB Msg An invalid value is supplied in the JOSE header.
OB Errors Msg Could not determine the verification key using subject category [subject category].

UK.OBIE.Signature.InvalidClaim

94428-uuid

 Reason No JWS content found. It could be that x-jws-signature was empty or header name in the policy config is incorrect.
OB Msg An invalid or no value is supplied in the JOSE header.
OB Errors Msg No JWS content found using header [header name].

UK.OBIE.Signature.InvalidClaim

94430-uuid

 Reason JWK not found for kid header.
OB Msg The JOSE request has an invalid claim that is mandatory.
OB Errors Msg Claim [claim name] is invalid.

UK.OBIE.Signature.Malformed

94418-uuid

 Reason Signature verification error trying to get JWS content.
OB Msg An invalid value is supplied in the JOSE header.
OB Errors Msg Error retrieving JWS during verification. JOSE-specific message.

UK.OBIE.Signature.Malformed

94453-uuid

 Reason A serialization error occurred during signing.
OB Msg Error serializing or deserializing the message.
OB Errors Msg JOSE-specific error.

UK.OBIE.Signature.Malformed

94454-uuid

 Reason A deserialization error occurred during verification.
OB Msg Error serializing or deserializing the message.
OB Errors Msg JOSE-specific error.

UK.OBIE.Signature.MissingClaim

94461-uuid

 Reason crit header is found in the JOSE request, but one of the headers it specifies is missing from the request.
OB Msg An invalid value is supplied in the JOSE header.
OB Errors Msg Crit header [header name] is missing.

UK.OBIE.Signature.MissingClaim

94462-uuid

 Reason crit header is expected in the JOSE request, with a value that is expected to be an array.
OB Msg An invalid value is supplied in the JOSE header.
OB Errors Msg Crit header must be an instance of a list.

UK.OBIE.Signature.MissingClaim

94471-uuid

 Reason b64 header is expected in the JOSE request, but is missing.
OB Msg An invalid value is supplied in the JOSE header.
OB Errors Msg b64 header is missing.

UK.OBIE.Signature.MissingClaim

94472-uuid

 Reason iat header is expected in the JOSE request, but is missing.
OB Msg An invalid value is supplied in the JOSE header.
OB Errors Msg iat header is missing.

UK.OBIE.Signature.MissingClaim

94473-uuid

 Reason iss header is expected in the JOSE request, but is missing.
OB Msg An invalid value is supplied in the JOSE header.
OB Errors Msg iss header is missing.

UK.OBIE.Signature.MissingClaim

94474-uuid

 Reason tan header is expected in the JOSE request, but is missing.
OB Msg An invalid value is supplied in the JOSE header.
OB Errors Msg tan header is missing.

UK.OBIE.Signature.MissingClaim

94475-uuid

 Reason typ header is expected in the JOSE request, but is missing.
OB Msg An invalid value is supplied in the JOSE header.
OB Errors Msg typ header is missing.

UK.OBIE.Signature.MissingClaim

94476-uuid

 Reason crit header is expected in the JOSE request, but is missing.
OB Msg An invalid value is supplied in the JOSE header.
OB Errors Msg crit header is missing.

UK.OBIE.Signature.MissingClaim

94431-uuid

 Reason A required claim, such as kid or x5c, is missing.
OB Msg The JOSE request has a missing claim that is mandatory.
OB Errors Msg Claim [claim name] is missing.

UK.OBIE.Signature.Unexpected

94429-uuid

 Reason x-jws-signature header was sent with request, but was not expected.
OB Msg An unexpected JOSE header was found.
OB Errors Msg Header [x-jws-signature] was found, but was not expected.

Errors returning HTTP 500 Internal Server Error

Information on all HTTP 500 messages is below. Use the CM ID, or another value, to identify a specific message.

OB code/CM ID Value Meaning

UK.OBIE.UnexpectedError

94403

 Reason Private subject is missing.
OB Msg Unexpected error
OB Errors Msg Private subject key is missing. Cannot decrypt the content.

UK.OBIE.UnexpectedError

94405

 Reason Cannot use service for direct.
OB Msg Unexpected error
OB Errors Msg Cannot use service for Direct Algorithm.

UK.OBIE.UnexpectedError

94406

 Reason No key found for signing.
OB Msg Unexpected error
OB Errors Msg No key found for signing.

UK.OBIE.UnexpectedError

94407

 Reason Missing content (message content is null).
OB Msg Unexpected error.
OB Errors Msg No message content found to enforce JOSE policy.

UK.OBIE.UnexpectedError

94408

 Reason Unsupported encoding.
OB Msg Unexpected error
OB Errors Msg Unsupported encoding exception: {system error message}.

UK.OBIE.UnexpectedError

94409

 Reason Cannot determine the decrypt key.
OB Msg Unexpected error
OB Errors Msg Could not determine the decrypt key using subject category [subject category].

UK.OBIE.UnexpectedError

94410

 Reason Invalid algorithm.
OB Msg Unexpected error
OB Errors Msg Invalid algorithm exception: {system error message}.

UK.OBIE.UnexpectedError

94411

 Reason HMAC not supported with JWKS.
OB Msg Unexpected error.
OB Errors Msg HMAC algorithm not supported when reading the key using JWKS URL.

UK.OBIE.UnexpectedError

94416

 Reason JWE decryption error.
OB Msg Unexpected error
OB Errors Msg Error retrieving JWE during decryption. {system error message}

UK.OBIE.UnexpectedError

94417

 Reason No subject found for HMAC.
OB Msg Unexpected error
OB Errors Msg No subject found using HMAC for verification.

UK.OBIE.UnexpectedError

94419

 Reason No public key when using JWKS URL.
OB Msg Unexpected error
OB Errors Msg No Consumer found in subject when getting public key and cert from Jwks Url.

UK.OBIE.UnexpectedError

94420

 Reason Missing app id.
OB Msg Unexpected error
OB Errors Msg No Application Identity Interface is found. Community Manager product features might not be installed.

UK.OBIE.UnexpectedError

94422

 Reason Missing header name for JWS.
OB Msg Unexpected error
OB Errors Msg Missing header name. When using detached/unencoded payload, header parameter name is required.

UK.OBIE.UnexpectedError

94423

 Reason Missing detached payload and signature.
OB Msg Unexpected error
OB Errors Msg Missing detached/unencoded payload and signature.

UK.OBIE.UnexpectedError

94424

 Reason Private subject is missing for signing.
OB Msg Unexpected error
OB Errors Msg Private subject key is missing. Cannot sign the content.

UK.OBIE.UnexpectedError

94425

 Reason Missing public key for encrypting.
OB Msg Unexpected error
OB Errors Msg Public key subject is missing. Cannot encrypt the content.

UK.OBIE.UnexpectedError

94426

 Reason Cannot determine encrypt key
OB Msg Unexpected error
OB Errors Msg No key found for encrypting.

UK.OBIE.UnexpectedError

94427

 Reason Cannot determine embed key.
OB Msg Unexpected error
OB Errors Msg Could not determine embed key to use for signing.

UK.OBIE.UnexpectedError

94451

 Reason An encryption error occurred during encryption.
OB Msg Unexpected error
OB Errors Msg JOSE-specific error.

UK.OBIE.UnexpectedError

94452

 Reason A decryption error occurred during decryption.
OB Msg Unexpected error
OB Errors Msg JOSE-specific error.

UK.OBIE.UnexpectedError

94458

 Reason Error creating PublicJsonWebKey.
OB Msg Unexpected error
OB Errors Msg JOSE-specific error.

Appendix F Configuration in the JOSE Security Policy v2

Valid in version: 2019.1.14 and later

Update 2019.1.14 introduces an additional option in the JOSE Security Policy v2. This option was implemented to support Appendix F: Detached Content as defined in the JWS specification. For full details, refer to the Appendix F (Detached Content) section of the JWS specification (RFC-7515).

The JOSE Security Policy v2 includes a new flag to implement the new option, which is available for both the request and the response. For UK Open Banking support, both the Appendix F option and the UK Open Banking 3.1 flag must be checked, as shown below.

Request Policy Configuration:

JOSE Security Policy v2 (Unencoded Payload Support), Appendix F implementation: Request message configuration

Response Policy Configuration:

JOSE Security Policy v2 (Unencoded Payload Support), Appendix F implementation: Response message configuration

With the Appendix F option checked, the b64 critical header is not required and must not be sent in the JWS header. The differences between these headers is shown below with and without the Appendix F option selected.

With UK Open Banking 3.1, without Appendix F:

Without Appendix F selected, the JWS header includes the b64 header.

{
  "kid":"joseclient",
  "alg":"PS256",
  "cty":"application/json",
  "b64":false,
  "crit":[
    "b64",
    "http://openbanking.org.uk/iat",
    "http://openbanking.org.uk/tan",
    "http://openbanking.org.uk/iss"
  ],
  "http://openbanking.org.uk/iat":1589394578,
  "http://openbanking.org.uk/tan":"OpenBanking",
  "http://openbanking.org.uk/iss":"CN=joseclient,OU=akana,O=acmepaymentscorp,L=EUS,ST=FL,C=US"
}

With UK Open Banking 3.1, with Appendix F:

With the Appendix F option selected, the JWS header does not include the b64 header, as shown below.

{
  "alg": "PS256",
  "kid": "joseclient",
  "typ": "JOSE",
  "http://openbanking.org.uk/iat": 1588365348,
  "http://openbanking.org.uk/iss": "CN=joseclient,OU=akana,O=acmepaymentscorp,L=EUS,ST=FL,C=US",
  "http://openbanking.org.uk/tan": "OpenBanking",
  "crit": [
    "http://openbanking.org.uk/iat",
    "http://openbanking.org.uk/iss",
    "http://openbanking.org.uk/tan"
  ]
}

Appendix F option: implementation results

When the Appendix F option is selected, the b64 header must not be sent and will not be returned in the response.

Error scenario

If the b64 header is sent in the request, the following error is returned, with a status code of 400 in a UK Open Banking 3.1 scenario:

{
  "Code":"[400] Bad Request",
  "Id":"94477-a6e9a65f-7d89-4293-90cf-c78128743436",
  "Message":"An invalid value is supplied in the JOSE header.",
  "Errors":[
    {
      "ErrorCode":"UK.OBIE.Signature.InvalidClaim",
      "Message":"Error code: 94477, parameters: null",
      "Path":"b64",
      "Url":"https://openbanking.atlassian.net/wiki/spaces/DZ/pages/1000702294/Read+Write+Data+API+Specification+-+v3.1.1"
    }
  ]
}

Specifying the JCE provider

Valid in version: 2020.2.13 and later

You can configure the Akana Platform to explicitly use a specific JCE provider, so that the JOSE Policy v2 calls the specified provider for all cryptographic functions. For example, you can use this to allow the keys to be retrieved from an HSM to sign the response, or just to use a different cryptographic provider. If this property is not specified, a default provider list will be used.

To set this up, there is a new configuration option in the Akana Administration Console. Follow the steps below, or ask an Administrator to update the configuration for you.

To specify the JCE provider in the Akana Administration Console

  1. Log in to the Akana Administration Console.
  2. Click the Configuration tab.
  3. On the left, under Configuration Categories, find the com.akana.jose.config configuration category.
  4. In the CryptoProvider field or fields, specify the provider you want. Must be a valid provider. For example:
    • For nCipher: nCipherKM
    • For Bouncy Castle: BC

    Available options depend on the product version you are using:

    Versions 2020.2.13 to 2020.2.15: In the jose.v2.security.handler.factory.joseCryptoProvider field, specify the provider.

    Version 2020.2.16 and later: Specify the provider for each of the following:

    • Decryption: jose.v2.security.handler.factory.joseCryptoProviderDecrypt
    • Encryption: jose.v2.security.handler.factory.joseCryptoProviderEncrypt
    • Signing: jose.v2.security.handler.factory.joseCryptoProviderSign
    • Signature verification: jose.v2.security.handler.factory.joseCryptoProviderVerify
  5. Click Apply Changes.