Enable HTTPS Access to the SOA Software Administration Console for Policy Manager 6.x/7.x

Configure container system.properties to enable HTTPS access to the SOA Software Administration Console.

NOTE: This article applies to version 6.x and greater.


  1. Introduction
  2. Configuration
  3. Troubleshooting

Introduction

If you would like to facilitate your own role-based access to the SOA Software Administration Console, you can do so by enabling an HTTPS port.

Note: This article can be used for Policy Manager 6.x and 7.x releases. The \sm60 and \sm70 release directories are presented as <release_directory> in the examples.

This process involves:

  • Adding an HTTPS listener to Policy Manager, Network Director, or Agent container instance folders (<release_directory>\instances): This can be done by adding an HTTPS port to the system.properties file (for UI browsing only), or by adding an HTTPS listener to the Policy Manager Management Console and to the system.properties file (for hosting services and UI browsing).
  • Adding a new configuration category to the SOA Software Administration Console to control whether you want \admin access for both HTTP and HTTPS, or HTTPS only: This can be done by manually adding a .cfg file to the \deploy folder of the <release_directory>\instances\<container name>\deploy folder.
Notes on Configuring an HTTPS Listener

Several important points to note on configuring an HTTPS listener:

  • If you add an HTTPS listener to the system.properties file (as described in the following scenarios) before you install the Policy Manager features, the HTTPS listener will be registered automatically in the database when you install the Policy Manager features and the listener will be present in the Containers section of the Policy Manager Management Console.
  • If you add an HTTPS listener to the system.properties file after you install the Policy Manager features, the HTTPS listener will not registered automatically in the database and you will need to add an HTTPS listener using the Add Container Listener function in the Policy Manager "Containers" section in order to update the container metadata. Note that the HTTPS listener configuration should have "Bind to all interfaces" checked, and you can optionally choose to clone services hosted on other listeners. You must also generate a certificate for the listener after it is defined using the Manage PKI Keys option. See screen examples below.
  • If you add a UI-Browsing listener to the system.properties file, Policy Manager will get the listener information from the system.properties file.

Back to top

Configuration

Let's take a quick walkthrough of the HTTPS configuration process to get you started.

Step 1: Add HTTPS Listener (Options)

To enable an HTTPS listener you must update the system.properties file in the \<release_directory>\instances  folder. Load the system.properties file into an editor and configure it based on the following SOA Software Administration Console access scenarios. We use port 9446 in these examples.

Option 1: HTTPS Access / UI Browsing Only

This option restricts access to the SOA Software Administration Console to the specified HTTPS listener.

Note: You must also delete the HTTP listener defined in the Policy Manager Management Console.

com.soa.http.bind.all=true (Remove for  HTTPS access ONLY)
com.soa.http.bind.all.secure=true (Add to enable HTTPS access)
org.osgi.service.http.port=9000 (Remove for HTTPS access only)
org.osgi.service.http.port.secure=9446 (Add to enable HTTPS access)

Option 2: HTTPS and HTTP Access

This option restricts access to the SOA Software Administration Console to the specified HTTPS listener and the default HTTP listener defined in the Policy Manager Management Console. You can have a UI browsing only HTTPS listener (i.e., listener is not configured in Policy Manager), or a listener that can host services (i.e., listener must be configured in Policy Manager ).
Note: If you would like your HTTPS listener to host services you must manually add it to the Policy Manager Management Console. You must also configure keys for this listener using the Manage PKI Keys function.

com.soa.http.bind.all.secure=true (Add to enable HTTPS access)
org.osgi.service.http.port.secure=9446 (Add to enable HTTPS access)

Option 3: Multiple HTTPS Listeners

If you would like to have multiple HTTPS listeners, you can add one UI browsing only HTTPS listener, and one HTTPS listener to the Policy Manager Management Console and specify both listeners in the system.properties file.

Note that you must add a certificate to the listener in Policy Manager using the Manage PKI Keys function.

com.soa.http.bind.all.secure=true (Add to enable HTTPS access)
org.osgi.service.http.port.secure=9446 (Add to enable HTTPS access - UI Browsing Only - No listener configured in Policy Manager)
org.osgi.service.http.port.secure=9448 (Add to enable HTTPS access - For Hosting Services - Listener configured in Policy Manager)

Step 2: Configure HTTPS Access to SOA Software Administration Console

If you want access to the SOA Software Administration Console via HTTPS, you must add a new configuration category. You can do this manually by adding a .cfg file to the \<release_directory>\instances\<container name>\deploy folder.

Add Configuration Category File
  • Create a new file in the \<release_directory> directory and call it:

    com.soa.admin.console.cfg


  • Add the following line to the file:

    admin.console.access.restricted=true (if you want /admin access to be HTTPS only).
    admin.console.access.restricted=false (if you want /admin access to be HTTP and HTTPS).

  • Copy the file to the \deploy folder as illustrated below:



  • Restart the container.
Step 3: Test HTTPS Access to SOA Software Administration Console

When the container is up and running launch the SOA Software Administration console (https://localhost:<port>/admin/). It should only accessible on the port defined in Step 1, and comply with the rules for the configuration category you selected as follows:

com.soa.admin.console.cfg enabled (True)
  • You can access the SOA Software Administration Console through HTTPS port only.
  • If you try to access SOA Software Administration Console using the default HTTP port you will receive a 404 error.
com.soa.admin.console.cfg enabled (False)
  • You can access the SOA Software Administration Console through the HTTP port and through the HTTPS port.


back to top

Troubleshooting

If everything appears to be configured correctly and you are receiving 404 errors when you try to launch Policy Manager, Network Director, or Agent instances, review the following steps to attempt to troubleshoot the problem.

Step 1: Inspect Log

Inspect the container logs in <release_directory>\instances\<instance name>\logs and search for the following errors which occur near the startup:

Caused by: java.net.BindException: Address already in use
at java.net.PlainSocketImpl.socketBind(Native Method)
at java.net.PlainSocketImpl.bind(Unknown Source)
at java.net.ServerSocket.bind(Unknown Source)
at java.net.ServerSocket.<init>(Unknown Source)

These errors mean that the container is trying to start its listener, but something is already listening.

Step 2: Resolve

  1. Stop the container and check to make sure that nothing is running on the port that the container is configured to run on. If nothing is running, it means that the container is trying to start TWO listeners on the same port.
  2. Check system.properties in the container directory. It will have the listeners specified that the container uses on initial startup. For example:

    com.soa.http.host=hostname
    org.osgi.service.http.port=9900
    org.osgi.service.http.port.secure=9446
    com.soa.http.bind.all=true
    com.soa.http.bind.all.secure=true
  3. Compare the host, port and bind settings above (for HTTP and HTTPS) with the actual Policy Manager listeners defined in the Policy Manager Management Console. (*.secure just refers to the HTTPS options – the same rules apply to HTTP and HTTPS). If the ports specified in system.properties are different to the ports specified in Policy Manager, then the problem must exist elsewhere. If the port numbers match, then either:

    com.soa.http.bind.all in system.properties AND "Bind to All Interfaces" option for the HTTPS Container Listener in the Policy Manager Management Console must both be set,

    OR

    The com.soa.http.host in system.properties and "hostname" in the Policy Manager Management Console must match.


    The reason is that when Policy Manager starts its listener is tries to determine if one already exists on the same port and host. If it finds one already running then it uses it. If the host names are different (or they are not running on all interfaces) then it might not be able to find the listener already running and try to start a new one on the same port.

Back to top