Using the HTTP Security Policy

Learn how to specify the transport security requirements for web services (SOAP or REST) with HTTP or HTTPS as the underlying transport protocol, using the HTTP Security Policy.

About Policies Managing Policies About Operational Policies

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

Table of Contents

  1. Introduction
  2. Creating and Configuring the HTTP Security Policy
  3. Specify HTTP Basic Authentication Options
  4. Specify HTTP Digest Authentication Options
  5. Specify SAML Bearer Token Options
  6. Specify JWT Bearer Token Options
  7. Specify Client Certificate Authentication Options
  8. Specify Cookie Authentication Options
  9. Configuring Security Audit Options
  10. Attaching the Policy

Introduction

The HTTP Security Policy is an operational policy that specifies the transport security requirements for web services (SOAP or REST) using HTTP or HTTPS as the underlying transport protocol.

Options include:

  • HTTP Basic Authentication—Allows a client to provide credentials in the form of a username and password with making a request.
  • HTTP Digest Authentication—Allows a client to negotiate credentials using the HTTP protocol. It supersedes unencrypted use of Basic Authentication and makes it possible to establish a user identity securely without sending a password in plain text over the network.
  • SAML Bearer Token Authentication—Allows a client to provide credentials in the form of a SAML token that uses the Bearer subject confirmation method when making a request.
  • JWT Bearer Token Authentication—Allows a client to provide credentials in the form of a JWT Bearer token.
  • Client Certificate—Allows authentication based on an X.509 certificate provided by the client. The certificate can be taken from the Secure Sockets Layer (SSL) protocol context. This option requires that your client application use SSL to make a secure connection with the application server. The application server must enable mutual authentication for the SSL connection.
  • Cookie Authentication—Allows authentication by passing user credentials through HTTP cookies when making a request. The cookie is typically issued to clients by a third-party identity provider and Access Manager software for single sign-on purposes.

Creating and Configuring the HTTP Security Policy

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

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

    HTTP Security Policy, Select Authentication Options

  3. Choose one or more authentication options and click Next.
  4. The page that's next, and the sequence of pages, is determined by the authentication option or options you choose. Possible pages, in sequence, are listed below. Specify values. For details of the choices available, refer to the information for each page:
  5. After each page, click Next.
  6. When you've set up the basic information for each authentication type you selected, the Specify Security Audit Options page appears. Choose options. For more information, refer to Configuring HTTP Security Audit Options below.
  7. When done, click Finish. The completion summary is displayed. An example is shown below.

    HTTPSecurity Policy completion summary

  8. Click Close.

Once the policy is configured, you can attach it to a service.

Back to top

Specify HTTP Basic Authentication Options

If you choose HTTP Basic Authentication, you'll see the page below.

HTTP Security Policy Configuration: Specify HTTP Basic Authentication Options

To configure basic authentication options
  1. Specify the subject category the authenticated identity will be used as. You can choose:
    • Consumer (the default)
    • End-User
    • User-defined: specify the subject category you want to use
    • None: no subject category will be used.
  2. Click Next to specify security audit options. See Configuring Security Audit Options below.

Back to top

Specify HTTP Digest Authentication Options

If you choose HTTP Digest Authentication, you'll see the page below.

HTTP Security Policy Configuration: Specify HTTP Digest Authentication Options

To configure http digest authentication options
  1. Specify the subject category the authenticated identity will be used as. You can choose:
    • Consumer (the default)
    • End-User
    • User-defined: specify the subject category you want to use
    • None: no subject category will be used.
  2. Click Next to specify security audit options. See Configuring Security Audit Options below.

Back to top

Specify SAML Bearer Token Options

If you choose SAML Bearer Token, you'll see the page below.

HTTP Security Policy Configuration: Specify SAML Bearer Token Options

To configure SAML bearer token authentication options
  1. Specify the subject category the authenticated identity will be used as. You can choose:
    • Consumer (the default)
    • End-User
    • User-defined: specify the subject category you want to use
    • None: no subject category will be used.
  2. Click Next to specify security audit options. See Configuring Security Audit Options below.

Back to top

Specify JWT Bearer Token Options

If you choose JWT Bearer Token, you'll see the page below.

HTTP Security Policy Configuration: Specify JWT Bearer Token Options

Note: for general information on JWT Bearer tokens, see https://jwt.io/introduction/ (external site).

To configure JWT bearer token authentication options
  1. Modify the Required Claims list as needed, adding or removing as applicable. Supported required claims are:
    • Issuer (checked by default)
    • Subject
    • Audience
    • Expiration (checked by default)
    • Not Before
    • issue At
    • JWT ID
  2. Add one or more custom claims if needed.
  3. In the Token Protection section, specify the type of algorithm used to protect each aspect of the JWT bearer token:
    • Signature/MAC algorithm—Supported values are: None, HS256, HS384, HS512, RS256, RS384, RS512, ES256, ES384, ES512. Default: None.
    • Content Encryption algorithm—Supported values are: None, A128CBC-HS256, A192CBC-HS384, A256CBC-HS512, A128GCM, A192GCM, A256GCM. Default: None.
    • Key Encryption algorithm—Supported values are: Direct, RSA1_5, RSA-OAEP, A128KW, A192KW, A256KW, A128GCMKW, A192GCMKW, A256GCMKW. Default: Direct.
  4. Specify the subject category the authenticated identity will be used as. You can choose:
    • Consumer (the default)
    • End-User
    • User-defined: specify the subject category you want to use
    • None: no subject category will be used.
  5. Click Next to specify security audit options. See Configuring Security Audit Options below.

Back to top

Specify Client Certificate Authentication Options

If you choose Client Certificate authentication, you'll see the page below.

HTTP Security Policy Configuration: Specify Client Certificate Authentication Options

To specify client certificate authentication:
  1. Choose one of the following authentication methods:
    • Use the client's X.509 certificate from the SSL context
    • Get the client's X.509 certificate from HTTP header: if you choose this option, specify which header to get the certificate from. Default: X-Client-Cert.
    • Get the Issuer DN and serial number of the client's X.509 certificate from HTTP headers. If you choose this option, specify which header to get each value from. Defaults: X-ClientCert-IssuerDn for Issuer DN and X-ClientCert-SerialNo for serial number.
  2. Specify the subject category the authenticated identity will be used as. You can choose:
    • Consumer (the default)
    • End-User
    • User-defined: specify the subject category you want to use
    • None: no subject category will be used.
  3. Click Next to specify security audit options. See Configuring Security Audit Options below.

Back to top

Each cookie represents a token and is stored in a text file. A cookie definition includes Cookie Name and Subject Category. Multiple cookies can be defined within one policy and can represent multiple identities.

If you choose Cookie Authentication, you'll see the page below.

HTTP Security Policy Configuration: Specify Cookie Authentication Options

To specify cookie authentication:
  1. In the Specify Cookie Authentication Options page, click Add. The Add Cookie for Authentication page appears, as shown below.

    HTTP Security Policy Configuration: Adding a cookie

  2. Enter a name for the cookie, specify Subject Category, and click Finish.
  3. Enter additional cookies if needed and then click Next. The Specify Response Cookie Options page appears, as shown below.

    HTTP Security Policy Configuration: Specify Response Cookie Options page

  4. To add a response cookie, click Add.
  5. In the Add Response Cookie page, enter the cookie name and subject category, and then click Finish.
  6. Enter additional response cookies if needed.
  7. Click Next to specify security audit options. See Configuring Security Audit Options below.

Back to top

Configuring Security Audit Options

Once you've configured the settings for the specific type or types of HTTP Security policy that you chose, the next step is the Specify Security Audit Options page, as shown below.

Policy Configuration: Specify Security Audit Options

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.

That completes the HTTP Security Policy configuration. Click Finish to close the wizard. You can now assign the policy to a service.

Back to top

Attaching the Policy

To use the HTTP 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