Using the JOSE Security Policy

Learn how to use the JOSE security policy to sign and encrypt message content.

About Policies Managing Policies About Operational Policies

Supported Platforms: 8.2x

Table of Contents

  1. Introduction
  2. Creating and Configuring the JOSE Security Policy
  3. Configuring JOSE Security Policy Options
  4. Configuring JOSE Security Audit Options
  5. Attaching the policy

Introduction

The JOSE Security Policy is an out-of-the-box operational policy that is part of the Policy Manager default installation. You can attach this policy to RESTful and Messaging services to secure any message content; it signs and/or encrypts the message content. Configuration options are flexible so that you can add more or less security as needed. You can also configure the Initiator Subject category that the authenticated identity will be used as.

This policy conforms to the following standards:

back to top

Creating and Configuring the JOSE Security Policy

There are two main tasks in configuring the JOSE Security Policy:

To create the JOSE security policy:
  1. Log in to Policy Manager: {protocol}://{hostname}:{port}/ms/index.do.
  2. Go to Workbench and click Browse.
  3. Navigate to the Policies > Operational folder of the Organization that includes services you want to add this policy to.
  4. At the Policies Summary page, click Add Policy.
  5. On the Select Policy Creation Option page, in the Add Policy field, choose JOSE Security Policy, and then click Next.
  6. On the Specify Policy Details page, provide:
    • Name (required)
    • Policy Key (optional)
    • Description (optional)
  7. Click Finish.
To configure the JOSE security policy:
  1. Create the policy as covered above.
  2. At the Policies Summary page, in the JOSE Security Policy section, click Modify. The Specify JOSE Security Policy Options page appears, as shown below.

    JOSE policy options page

  3. Specify values. For information about the fields, refer to Configuring JOSE Security Policy Optionsbelow.
  4. Click Next. The Specify JOSE Security Audit Options page appears, as shown below.

    JOSE security policy, audit options

  5. Specify values. For information about the fields, refer to Configuring JOSE Security Audit Options below.
  6. When done, click Finish. The completion summary is displayed. An example is shown below.

    JOSE Security Policy completion summary

  7. Click Close.

Back to top

Configuring JOSE Security Policy Options

Once you've created the policy, you can configure the policy options.

There are five main configuration sections you can use to tailor your JOSE security policy options:

  • 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: You can specify Compact or JSON serialization.
  • Sign Content: If this box is checked, the content is signed using the selected Signature/MAC algorithm. If needed, you can check the optional Embed Key box to require that the public key (corresponding to the private key used to sign the content) is embedded in the JSON structure in the jwk header, so that it can be verified later.

    By default, this checkbox is cleared, so this section is disabled. To enable it, just check the box, specify the algorithm from the drop-down list, and choose Embed Key if needed.

  • Encrypt Content: if this box is checked, the content is encrypted using the selected Encryption Algorithm. You can also protect the encryption key by selecting an optional Key Management Algorithm. If needed, you can check the optional Embed Key box to require that the public key (corresponding to the private key used to sign the content) is embedded in the JSON structure in the jwk header, so that it can be verified later.

    By default, this checkbox is cleared, so this section is disabled. To enable it, just check the box. The default Signature/MAC algorithm value is HS256, and the default Key Management Algorithm value is None.

  • Initiator Subject Category: Here, you can specify the identity of the initiator of the message.This is the identity whose private key is used to sign the IN message and whose public key is used to encrypt OUT and FAULT messages. Predefined categories include Consumer and End-User. The default is Consumer. You can also choose User-Defined and specify a custom name. If you choose None, this indicates that the selection of the identity whose keys should be used for signing and encrypting content is left to the manageability container, not specified by this policy.

Back to top

Configuring JOSE Security Audit Options

Once you've created the policy, you can configure the audit options.

Choose from the available options controlling the audit data that is captured:

  • Generate Audit Data: captures all message data, whether success or failure, for all message exchanges.
  • On Error Only: Captures audit data only when an error occurs on a message exchange.

Attaching the Policy

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

Back to top