Using the JOSE Security Policy
Learn how to use the JOSE security policy to sign and encrypt JSON message content.
Note: The platform now includes an updated policy (version 8.4.17 and later), JOSE Security Policy v2 (Unencoded Payload Support), which supports the newer JSON Web Signature (JWS) Unencoded Payload Option specification (https://tools.ietf.org/html/rfc7797). In general, if you're creating a new policy, it's best to choose the newer policy rather than this legacy JOSE Security policy. If you're still using the legacy policy, we recommend that you migrate to the new policy as soon as possible.
Supported Platforms: 8.2x and later
Table of Contents
- Creating a JOSE Security Policy
- Configuring the JOSE Security Policy
- Configuring JOSE Security Policy Options
- Configuring JOSE Security Audit Options
- Attaching the policy
- JOSE Security Policy: use case
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:
- JSON Web Signature (JWS) (https://tools.ietf.org/html/rfc7515)
- JSON Web Encryption (JWE) (https://tools.ietf.org/html/rfc7516)
Creating a JOSE Security policy
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
- Go to Workbench > Browse > Organization, and select Policies > Operational Policies. The Policies Summary is displayed.
- Click Add Policy.
- Choose the policy type and click Next.
- 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
To configure your JOSE Security policy, follow the steps below.
To configure the JOSE security policy:
- Create the policy as covered above.
- At the Policies Summary page, in the JOSE Security Policy section, click Modify. The Specify JOSE Security Policy Options page appears, as shown below.
- Specify values. For information about the fields, refer to Configuring JOSE Security Policy Options below.
- Click Next. The Specify JOSE Security Audit Options page appears, as shown below.
- Specify values. For information about the fields, refer to Configuring JOSE Security Audit Options below.
- When done, click Finish.
- At the Completion Summary page, click Close.
Configuring JOSE Security Policy Options
Once you've created the policy, you can configure the policy options. The sections below provide more information on the options available.
- 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.
- 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.
- Sign content
- If this box is checked, the content is signed using the selected Signature/MAC algorithm. By default, the checkbox is cleared, so this section is disabled. To enable it, just check the box, and then specify the algorithm from the drop-down list. For available values, see Sign Content: supported Signature/MAC Algorithms below.
- If needed, you can also check the optional Embed Key box. The public key (corresponding to the private key used to sign the content) is embedded in the JSON structure in the jwk header, in OUT messages, so that it can be verified later.
- Encrypt content
- if this box is checked, the content is encrypted using the selected Encryption Algorithm.
- 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. For available values, see Encrypt Content: supported Encryption Algorithms below.
- You can also protect the encryption key by selecting an optional Key Management Algorithm. For available values, see Encrypt Content: supported Key Management Algorithms below.
- If needed, you can also check the optional Embed Key box. The public key (corresponding to the private key used to sign the content) is embedded in the JSON structure in the jwk header of OUT messages, so that it can be verified later. If you add this option when the JOSE Security policy is applied to OUT messages, it ensures that the client has the key to verify the encryption.
- 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.
- Initiator Subject Category
- Options: Consumer, End-User, User-Defined, and None. For more information, see Initiator Subject Category options below.
Sign Content: supported Signature/MAC Algorithms
The Signature/MAC algorithms supported by the JOSE Security policy for signing content are:
Encrypt Content: supported Encryption Algorithms
The encryption algorithms supported by the JOSE Security policy for encrypting content are:
Encrypt Content: supported Key Management Algorithms
The Key Management algorithms supported by the JOSE Security policy for encrypting content are:
Initiator Subject Category options
In the Initiator Subject Category field, you can specify the subject category of the inbound identity that will be used for the outbound identity. 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.
The Initiator Subject Category options supported by the JOSE Security policy are:
- Consumer: The consumer of the service; the client application. This is the default and most common value.
- End-User: The end-user of the client application.
- User-Defined: You can define a specific subject category that will be used for identification purposes. If you choose this option, specify the value that will be used. Make sure you spell it exactly correctly, including capitalization.
- None: If you choose None, the selection of the identity whose keys should be used for signing and encrypting content is not specified by the policy.
Configuring JOSE Security Audit Options
Once you've created the policy, you can configure the audit options on the Specify JOSE Security Audit Options page.
Choose from the available options controlling the audit data that's captured:
- Generate Audit Data
- 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, go to the Policies folder in the Root Organization and attach the policy to a web service, binding, or binding operation.
JOSE Security Policy: use case
The follow use case illustrates a scenario where the JOSE Security policy is used to secure the Swagger Petstore API. In this example, we're creating an API secured with HTTP Basic authentication that signs the response based on the client's certificate. The Authentication policy and HTTP Security policies secure the API with Basic Auth. The JOSE Security policy takes the consumer information and signs the output based on the JOSE policy configuration.
In this example:
- The information is signed but not encrypted.
- Signing is applied to the OUT message.
- Assumes some setup in Policy Manager and Community Manager.
- Outlines the key steps for setting up the app, API, and contract, assigning the policy, and viewing the JSON response content.
This use case includes the following steps:
- Prerequisites in Policy Manager
- Prerequisites in the Developer Portal
- Step 1: In Policy Manager, Create, Configure, and Activate JOSE Security Policy
- Step 2: In the developer portal, create the Swagger Petstore API (without policies)
- Step 3: In the developer portal, create an app to consume the API
- Step 4: In the developer portal, create and activate a contract between the app and the API
- Step 5: access the API in an external client such as Postman
- Step 6: In the developer portal, add policies to the API
- Step 7: Save out the app credentials
- Step 8: Generate PKI keys and certificate for the app
- Step 9: In external client, access the API using authentication
- Step 10: View the JOSE response
Prerequisites in Policy Manager
In Policy Manager, this use case assumes that you have:
- Defined, configured, and activated the following operational policies:
- Authentication Policy: Subject Category = Consumer. Domain=LocalDomain
- HTTP Security Policy: HTTP Basic authentication, Subject Category = Consumer.
- Authentication Policy: Subject Category = Consumer. Domain=LocalDomain
- Defined a certificate authority at the root level (Configure > Security > Certificates > Certificate Authority > Configure Certificate Authority).
Prerequisites in the Developer Portal
In the developer portal, this use case assumes that you have:
- Configured a deployment zone (Admin > Deployment Zones).
Step 1: In Policy Manager, Create, Configure, and Activate JOSE Security Policy
Create the JOSE Security Policy with the following settings, as shown below:
- Protection Scope: OUT
- Sign Content: checked
- Signature/MAC Algorithm: RS256
Save the policy, and activate it.
Step 2: In the developer portal, create the Swagger Petstore API (without policies)
In the developer portal, at the root level, create the API, using the following values:
- Reference the standard Swagger JSON file URL: http://petstore.swagger.io/v2/swagger.json.
- Disable anonymous access (Implementations > Live > Edit > clear check box and save).
- Update the URL context path: Implementations > Live > Deployments > Context Path. For example, change it to: /josepolicytest.
- Do not add policies to the API at this point. You'll add the policies in a later step.
Step 3: In the developer portal, create an app to consume the API
In the developer portal:
- Create an app.
Step 4: In the developer portal, create and activate a contract between the app and the API
In the developer portal:
- Go to the Overview page for the API and click Access.
- Request a contract for the app you created in Step 3.
- As the API Admin, approve and activate the contract.
At this point, the app can access the API.
Step 5: access the API in an external client such as Postman
In an external client, access one of the operations for the API. The example below uses Get Pet By ID, and uses an ID that was previously added.
If you're not sure what URL to use, look in the developer portal: go to the API and to the specific implementation, and copy the URL listed in Endpoints. An example is shown below.
The response should look something like the below:
Now it's time to add the JOSE policy to the API.
Step 6: In the developer portal, add policies to the API
Now, in the developer portal, add the following policies to the API's implementation. You defined these policies in earlier steps:
- Authentication Policy
- HTTP Security Policy
- JOSE Security Policy which you defined in Step 1: In Policy Manager, Create, Configure, and Activate JOSE Security Policy
Step 7: Save out the app credentials
Go to the Details page for your app that has a contract with the API.
Save out these two values to a notepad or other text application:
- App ID
- Shared Secret (click Show Keys and then Click to View)
These are the credentials for the app, and will be needed to access the API, which now has the JOSE Security Policy attached to it.
An example is shown below.
Step 8: Generate PKI keys and certificate for the app
You'll need to generate PKI keys so that the platform has a private key for the app, to use in applying the JOSE Security policy.
To do this in Policy Manager:
- Security > Users > find the app on the list > click Manage PKI Keys.
- Choose Generate PKI Keys and X.509 Certificate and click Next.
- Fill in the certificate details and click Finish.
The platform now has a certificate associated with the app, that it can use for signing and encrypting.
Step 9: In external client, access the API using authentication
Now, in your client, call the API again. You'll get a 401 Unauthorized response.
You'll need to add Basic authorization onto the API in your client, as shown below, and send the app credentials, in order to get a successful response.
The example below shows the credentials added for the authorization, and also shows the JWT response.
Step 10: View the decoded JWT response
Copy the response content into the JSON Web Token debugger at https://jwt.io/. In the right pane, you'll see the response message, as in the example below.