Using the JOSE Profile-Driven Security Policy

Valid in version: 2022.1.0 and later

Learn how to use the JOSE Profile-Driven Security Policy to supplement your JOSE Security Policy v2 with additional security standards such as RSA Adaptive Authentication for eCommerce, Visa Token Service, or UK Open Banking.

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

Table of Contents

Introduction

The JOSE Security Policy v2 allows you to enforce security standards required by the JSON Web Signature (JWS) Unencoded Payload Option (https://tools.ietf.org/html/rfc7797) specification. However, there are other security specifications you might want to use in combination with it.

In version 2022.1.x and later, the Akana JOSE Security Profile for RSA Adaptive Authentication for eCommerce, Akana JOSE Security Profile for UK Open Banking, Akana JOSE Security Profile for VISA Token Services, and Akana Enhanced JOSE Security Policy Plug-In for Network Director plugins have been merged into the Akana core product. Any existing XML JOSE Extension Policy will continue to work seamlessly as an XML based policy and not as a JOSE Profile-Driven Security policy that is created from the Community Manager UI. Similarly, any existing JOSE Profile-Driven Security policies will continue to work seamlessly as JOSE Profile-Driven Security policies.

You can use the JOSE Profile-Driven Security Policy as a supplement to the JOSE Security Policy v2, using existing out-of-the box templates to set up your API Platform to comply with additional security standards such as:

Note: It's best to use the Community Manager portal for configuring this policy. In Policy Manager, you can add the JOSE Profile-Driven Security Policy and configure it via XML; in Community Manager, you can load the out-of-the-box templates and add your configuration settings in the additional user interface pages.

Specifications

This policy complies with/enforces the following standards:

If you have a JOSE profile policy defined as an XML policy in a previous version

If you created one or more JOSE policy profiles in a version prior to 2022.1.0, defining it as an XML policy, you can continue to use these policies, and configure them in Policy Manager.

For any new policy, use the JOSE Profile-Driven policy functionality provided in Community Manager.

For information about working with an existing JOSE profile defined as an XML policy, refer to Using the XML Policy.

Creating a JOSE Profile-Driven Security Policy

The first step in creating a policy is to define the basic policy information. You can add the policy:

To add a JOSE Profile-Driven Security policy in Policy Manager

  1. Go to Workbench > Browse > Organization, and select Policies > Operational Policies. The Policies Summary is displayed.
  2. Click Add Policy.
  3. At the Select Policy Creation Option page, do one of the following:
    • Add Policy: from the drop-down list, choose the policy type.

      Note: If you choose to add a JOSE Profile-Driven security policy in Poliy Manager, it's expected that you will create a new policy and then cut and paste valid XML, matching one of the supported profile types, from your source environment.

    • Import Policy: Click Browse to import a valid JOSE Profile-Driven security policy XML definition file.

      Note: If you choose to create a JOSE Profile-Driven security policy in Poliy Manager by importing, it's expected that you already have the XML, matching one of the supported profile types, configured as an XML policy in a previous version.

  4. Click Next.
  5. In the Specify Policy Details page, specify:
    • Policy Name: A short, descriptive name for the policy. Used on the policy summary page.
    • Description: A brief description of the policy. Include any key information relating to how the policy is used and what it does.
  6. Click Finish.
  7. At the Completion Summary page, 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.

To add a JOSE Profile-Driven Security policy in the Community Manager developer portal

  1. In the Developer Portal, go to More > Organizations > All Organizations.
  2. Find your organization on the list, and then click the title to view the Details page for the organization.
  3. On the left navigation bar, choose Policies. All policies associated with the organization are displayed.
  4. Click Add.
  5. On the Add Policy page, specify:
    • Policy Name: A short, descriptive name for the policy. Used on the policy summary page.
    • Policy Category: Choose Operational Policy.
    • Policy Sub-Type: Choose JOSE Profile-Driven Security Policy.
    • Policy Description: A brief description of the policy. Include any key information relating to how the policy is used and what it does.
  6. Click Save.

The next step is to configure the policy details. Follow the steps to configure in Community Manager as given below.

For more information about working with policies in Community Manager, see Organization Policies (Community Manager help).

Note: If you have an existing JOSE-based XML profile defined as an XML policy in a previous version, and you want to update it in 2022.1.x and later, see If you have a JOSE profile policy defined as an XML policy in a previous version above.

Configuring the JOSE Profile-Driven Security Policy in Community Manager

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.

The fields available on each policy configuration page are determined by the profile you're working with. For links to the details for each profile, see Step 7 below.

There are four policy configuration pages:

  • JOSE Profile-Driven Security Policy Configuration
  • JOSE Profile-Driven Security Policy Inbound Settings
  • JOSE Profile-Driven Security Policy Outbound Settings
  • JOSE Profile-Driven Security Policy Properties

To configure a JOSE Profile-Driven Security Policy in Community Manager

  1. Log in to the Community Manager developer portal as a Business Admin.
  2. Go to More > Organizations > All Organizations.
  3. Choose your organization.
  4. On the left navigation bar, choose Policies. All policies associated with the organization are displayed.
  5. Find the policy on the list and click to go to the Details page for the policy.
  6. In the Policy Summary section, click Edit to access the JOSE Profile-Driven Security Policy Configuration page.
  7. Provided configuration options for the selected profile, for each of the three settings pages (Inbound, Outbound, and Properties). For information about the fields, refer to the linked sections provided above.
  8. When done, click Finish.

After you've configured your policy, remember to activate it so that it can be used. See Activating a Policy below.

Configuring the JOSE Profile-Driven Security Policy: RSA-AAEC-3.0, 3.1, and 3.2 settings

To configure your RSA-AAEC-3.0, 3,1, or 3.2 profile, provide configuration settings on the following pages:

Inbound Settings: RSA-AAEC-3.0, 3,1, and 3.2 profiles

Specify applicable values for the following fields.

Signature Verification Key Source section:

Authenticate Subject from Certificate
The source for the signature verification key. Options: Consumer, End User, Service, or User Defined (specify value).

Message Decryption Key Source section:

Validate Certificate is Assigned to
The source location for the message decryption key. Options: Consumer, End User, Service, User Defined (specify value), or Platform Identity (specify value).

When done configuring inbound settings, click Next.

Outbound Settings: RSA-AAEC-3.0, 3,1, and 3.2 profiles

On the next page, configure the outbound settings. Specify applicable values for the following fields.

Message Signing Key Source section:

Private Key from API Platform
The source for the message signing key. The source must be a private key from the API Platform. Options: Consumer, End User, Service, User Defined (specify value), or Platform Identity (specify value).

Message Encryption Key Source section:

Public Key from API Platform
The source location for the message encryption key. The source must be a public key from the API Platform. Options: Consumer, End User, Service, User Defined (specify value), or Platform Identity (specify value).

When done configuring outbound settings, click Next.

JOSE Profile-Driven Security Policy Properties: RSA-AAEC-3.0, 3,1, and 3.2 profiles

On the next page, configure additional properties for the policy. Some default properties and values are provided as part of the default profile. Add, modify, or delete property name/value pairs as needed to complete your policy configuration.

In version 2022.1.0 and later, there are four fields for Java Cryptographic Provider, to support having different providers for different cryptographic functions such as for signing or for encryption.

Name/value pair: clock.skew.secs
The clock skew value, in seconds. Default: 120.
Name/value pair: message.expiration.secs
The message expiration time, in seconds. Default: 60.
Java Cryptographic Sign Provider
URL for the provider for Java cryptographic signing.
Java Cryptographic Verify Provider
URL for the provider for Java cryptographic verification.
Java Cryptographic Encrypt Provider
URL for the provider for Java cryptographic encryption.
Java Cryptographic Decrypt Provider
URL for the provider for Java cryptographic decryption.
Generate Audit Data
Check the box to activate this option. When you choose this option, you can check an additional box to choose On Error Only.
Verbose Error Responses
Check the box to activate this option.
Forced Diagnostic Logging
Check the box to activate this option.
Note: This setting is not recommended for production environments, because it logs debug information for every request processed by the policy (success as well as failure).

That completes the policy configuration. Click Finish.

When you create and configure a policy, the policy is in Draft state. A policy in Draft state is not available for general use. The next step is to activate the policy: click Activate Policy and then confirm. See Activate a Policy. The policy is then in Active state and is available for use.

Configuration example: RSA-AAEC-3.1

The configuration properties for a default RSA-AAEC-3.1 profile are shown below.

Inbound settings:

JOSE Profile-Driven Security Policy, configuration example, RSA-AAEC-3.1, inbound settings

Outbound settings:

JOSE Profile-Driven Security Policy, configuration example, RSA-AAEC-3.1, outbound settings

Configuring the JOSE Profile-Driven Security Policy in Community Manager: Visa-TS-3.1 settings

To configure your Visa-TS-3.1 profile, provide configuration settings on the following pages:

Inbound Settings: Visa-TS-3.1 profile

Specify applicable values for the following fields.

Signature Verification Key Source section:

Public Key from API Platform
The source for the signature verification key. Options: Consumer, End User, Service, User Defined (specify value), or Platform Identity (specify value).
Create Subject for API Platform Identity
The subject for the API Platform identity. Options: Consumer, End User, Service, or User Defined (specify value).

Message Decryption Key Source section:

Private Key from API Platform
The source location for the message decryption key. The source must be a private key from the API Platform. Options: Consumer, End User, Service, User Defined (specify value), or Platform Identity (specify value).

When done configuring inbound settings, click Next.

Outbound Settings: Visa-TS-3.1 profile

On the next page, configure the outbound settings. Specify applicable values for the following fields.

Message Signing Key Source section:

Private Key from API Platform
The source for the message signing key. Options: Consumer, End User, Service, User Defined (specify value), or Platform Identity (specify value).

Message Encryption Key Source section:

Public Key from API Platform
The source location for the message encryption key. The source must be a public key from the API Platform. Options: Consumer, End User, Service, User Defined (specify value), or Platform Identity (specify value).

When done configuring outbound settings, click Next.

JOSE Profile-Driven Security Policy Properties: Visa-TS-3.1 profile

On the next page, configure additional properties for the policy. Some default properties and values are provided as part of the default profile. Add, modify, or delete property name/value pairs as needed to complete your policy configuration.

Name/value pair: clock.skew.secs
The clock skew value, in seconds. Default: 120.
Name/value pair: issuer.cert.kid
The key ID value for the issuer certificate. Set it to the key ID of the issuer's keys.
Name/value pair: jose.element.name
A placeholder value for any JOSE standard element that might be needed for your policy configuration.
Name/value pair: visa.client.cert.kid
Set this property to the key ID of the Visa client certificate.
Java Cryptographic Sign Provider
URL for the provider for Java cryptographic signing.
Java Cryptographic Verify Provider
URL for the provider for Java cryptographic verification.
Java Cryptographic Encrypt Provider
URL for the provider for Java cryptographic encryption.
Java Cryptographic Decrypt Provider
URL for the provider for Java cryptographic decryption.
Generate Audit Data
Check the box to activate this option. When you choose this option, you can check an additional box to choose On Error Only.
Verbose Error Responses
Check the box to activate this option.
Forced Diagnostic Logging
Check the box to activate this option.
Note: This setting is not recommended for production environments, because it logs debug information for every request processed by the policy (success as well as failure).

That completes the configuration of the Visa-TS-3.1 profile for the policy. Click Finish.

When you create and configure a policy, the policy is in Draft state. A policy in Draft state is not available for general use. The next step is to activate the policy: click Activate Policy and then confirm. See Activate a Policy. The policy is then in Active state and is available for use.

Configuring the JOSE Profile-Driven Security Policy in Community Manager: UKOpenBanking-3.1.2_SETS

The UKOpenBanking-3.1.2_SETS profile supports the Event Notification API which is defined as part of the UK Open Banking standard (see https://openbankinguk.github.io/read-write-api-site3/v3.1.4/profiles/event-notification-api-profile.html). It specifically addresses aggregated polling of Security Event Tokens.

This profile would typically be applied to messages that have a JSON payload and include an object that is a group of Security Event Tokens. Each Security Event Token becomes an individually signed JSON web signature (JWS).

For more information, see https://datatracker.ietf.org/doc/html/rfc8417 (Security Event Token specification).

To configure your UK Open Banking 3.1.2 SETS profile, provide configuration settings on the following pages:

Inbound Settings: UKOpenBanking-3.1.2_SETS profile

The UKOpenBanking-3.1.2_SETS profile is not applicable to inbound messages.

In the Community Manager developer portal user interface, the following fields are display-only:

  • Signature Verification Key Source
  • Message Decryption Key Source

Just click Next.

Outbound Settings: UKOpenBanking-3.1.2_SETS profile

On the JOSE Profile-Driven Security Policy Outbound Settings page, you can change the message signing key source:

  • Message Signing Key Source: Under Private Key from API Platform, specify key source. Options: Consumer (the default), End User, Service, User Defined (specify value), or Platform Identity (specify value).
  • Message Encryption Key Source: display-only.

Just click Next.

JOSE Profile-Driven Security Policy Properties: UKOpenBanking-3.1.2_SETS profile

On the next page, configure additional properties for the policy. Some default properties and values are provided as part of the default profile. Add, modify, or delete property name/value pairs as needed to complete your policy configuration.

Name/value pair: ukob.outbound.iss.header
The value for the http://openbanking.org.uk/iss iss (issuer) header field; the subject DN of the signing certificate.
Name/value pair: ukob.outbound.tan.header
The value for the tan (trust anchor) header field; required in the JOSE header per the Open Banking 3.1 specification. Per the specification, the tan header is a string consisting of a domain name that is registered to and identifies the Trust Anchor that hosts the public counter-part of the key used for signing.
Name/value pair: ukob.outbound.kid.header
The default value for the outbound kid JOSE header name—the header that the receiver, such as a trading partner, will use to find the signature verification certificate.
The value depends on the environment. Refer to 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).
Name/value pair: sets.json.path
A JSONPath expression that results in a list of the SET elements.
In the response message there is a JSON object that contains a list of name/values, where the values are the SET elements to be signed. This JSONPath expression results in pulling the SET elements out individually so that they can be signed.
Default value: $.sets[*].
Java Cryptographic Sign Provider
URL for the provider for Java cryptographic signing.
Java Cryptographic Verify Provider
URL for the provider for Java cryptographic verification.
Java Cryptographic Encrypt Provider
URL for the provider for Java cryptographic encryption.
Java Cryptographic Decrypt Provider
URL for the provider for Java cryptographic decryption.
Generate Audit Data
Check the box to activate this option. When you choose this option, you can check an additional box to choose On Error Only.
Verbose Error Responses
Check the box to activate this option.
Forced Diagnostic Logging
Check the box to activate this option.
Note: This setting is not recommended for production environments, because it logs debug information for every request processed by the policy (success as well as failure).

That completes the configuration of the UKOpenBanking-3.1.2_SETS profile for the policy. Click Finish.

When you create and configure a policy, the policy is in Draft state. A policy in Draft state is not available for general use. The next step is to activate the policy: click Activate Policy and then confirm. See Activate a Policy. The policy is then in Active state and is available for use.

Configuring the JOSE Profile-Driven Security Policy in Policy Manager

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.

In Policy Manager, you can configure by editing or uploading XML. In the Community Manager portal you can configure via the user interface (recommended). See Configuring the JOSE Profile-Driven Security Policy in Policy Manager: Default Content below.

To configure a JOSE Profile-Driven Security Policy in Policy Manager

  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 Modify XML Policy page. The default content is shown (see Configuring the JOSE Profile-Driven Security Policy in Policy Manager: Default Content below).
  4. Modify the XML as needed by typing or pasting content.
  5. As needed, use the validation options. See Configuring the JOSE Profile-Driven Security Policy in Policy Manager: Validating the XML below.
  6. Click Apply.

Configuring the JOSE Profile-Driven Security Policy in Policy Manager: Default Content

The default content on the Modify XML Policy page is shown below.

<wsp:Policy xmlns:wsp="http://schemas.xmlsoap.org/ws/2004/09/policy" visibility="private">
  <ns2:JoseExtPolicy xmlns:ns2="http://federatedgovernance.org/policy/jose_ext/">
    <ns2:properties />
    <ns2:audit>NONE</ns2:audit>
    <ns2:verboseErrors>false</ns2:verboseErrors>
    <ns2:forceLogging>false</ns2:forceLogging>
  </ns2:JoseExtPolicy>
</wsp:Policy>

If you're creating the policy by editing or pasting the XML in Policy Manager, update the XML as needed, validate, and save. You can also configure via the user interface in the Community Manager portal (recommended): see Configuring the JOSE Profile-Driven Security Policy in Community Manager above.

Configuring the JOSE Profile-Driven Security Policy in Policy Manager: Validating the XML

If you're creating the policy by editing or pasting the XML in Policy Manager, after you've modified the default content, you can validate it. It's best to use both options:

  • Check Syntax: Validates the XML syntax to make sure that it is well-formed.
  • Check Schema: Validates the XML against the specified schema to make sure it conforms with the schema.

Fix as needed to make sure the XML is valid before saving the policy.

Activating a policy

When you create and configure a policy, the policy is in Draft state. A policy in Draft state is not available for general use. The next step is to activate the policy: click Activate Policy and then confirm. See How do I activate a policy that's in Draft state? The policy is then in Active state and is available for use.

Attaching a policy

To use the JOSE Profile-Driven Security Policy:

  • In the Community Manager developer portal, go to the API implementation policies section and click Attach. For instructions, see Managing Policies for an API Implementation.
  • In Policy Manager, go to the Policies folder in the respective organization and attach the policy to a web service, binding, or binding operation.