Enable HTTPS access to the Akana Administration Console for Policy Manager

Configure the container system.properties file to enable HTTPS access to the Akana Administration Console.

Table of Contents

  1. Introduction
  2. Configuration
  3. Troubleshooting

Introduction

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

This process involves:

  • Adding an HTTPS listener to Policy Manager or Network Director container instance folders ({release_directory}\instances): You can do this 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 Akana 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 Akana Administration Console access scenarios. We use port 9446 in these examples.

Option 1: HTTPS Access / UI Browsing Only

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

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

Settings:

  • 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 Akana 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: You must add a certificate to the listener in Policy Manager using the Manage PKI Keys function.

Settings:

  • 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 Akana Administration Console

If you want access to the Akana 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
  1. Create a new file in the \{release_directory} directory and call it:

    com.soa.admin.console.cfg

  2. 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).

  3. Copy the file to the \deploy folder as illustrated below:

  4. Restart the container.
Step 3: Test HTTPS Access to Akana Administration Console

When the container is up and running launch the Akana 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 Akana Administration Console through HTTPS port only.
  • If you try to access Akana Administration Console using the default HTTP port you will receive a 404 error.
com.soa.admin.console.cfg enabled (False)
  • You can access the Akana 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 still seeing 404 errors when you try to launch Policy Manager or Network Director, 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 the system.properties file are different from the ports specified in Policy Manager, the problem must exist elsewhere. If the port numbers match, then ONE of the following must occur:
    • com.soa.http.bind.all in the system.properties file AND the Bind to All Interfaces option for the HTTPS Container Listener in the Policy Manager Management Console must both be set.
    • The com.soa.http.host value in the system.properties file and the hostname in the Policy Manager Management Console must match.

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

Back to top