3.4 Creating and Publishing a WebSocket API

Secure API Manager allows you to create WebSocket APIs. WebSocket is a protocol similar to HTTP that is part of the HTML 5 specification. The WebSocket protocol enables real-time interaction between a web client (such as a browser) and a web server with low overheads. For more information, see Required Knowledge.

Before you can create and publish a secure WebSocket API, you must perform some initial configuration steps in Access Manager. For more information, see Configuring WebSocket Reverse Proxy in Access Manager.

NOTE:Unsecured WebSocket APIs do not require configuration in Access Manager. For information about creating and publishing an unsecured WebSocket API in Secure API Manager, see Configuring and Publishing a WebSocket API.

3.4.1 Configuring WebSocket Reverse Proxy in Access Manager

Secure API Manager uses the Access Gateway in NetIQ Access Manager as a reverse proxy to secure WebSocket APIs. The following steps are the initial configuration of Access Manager that allows Secure API Manager to secure WebSockets.

To configure WebSocket reverse proxy in Access Manager:

  1. Log in to the Access Manager Administration Console.

  2. On the dashboard, click the Access Gateways icon.

  3. Next to the gateway cluster, click Edit.

  4. Click Reverse Proxy / Authentication.

  5. For Identity Server Cluster, select your identity provider cluster.

  6. Under Proxy Settings, ensure that Enable Via Header is selected.

  7. In the Reverse Proxy List section, click New.

  8. Provide a name for the reverse proxy, then click OK.

  9. In the Proxy Service List, click New.

  10. Provide a name for the proxy service.

  11. For the Published DNS Name, enter the gateway DNS name.

  12. For the Web Server IP Address, enter the IP address of the Secure API Manager gateway or L4 switch.

    NOTE:If you have a multi-gateway system, enter the IP address of your L4 switch. If you have a single gateway system, enter the IP address of the Secure API Manager gateway.

  13. For the Host Header, select Forward Received Host Name.

  14. Click OK.

  15. Select Enable SSL between Browser and Access Gateway.

  16. Ensure that Enable SSL with Embedded Service Provider and Redirect Requests from Non-Secure Port to Secure Port are selected.

  17. Click Auto-generate Key, then click OK. Click OK again.

  18. For Non-Secure Port, enter the appropriate port (80).

  19. For Secure Port, enter the appropriate port (443).

  20. Under the Web Server Addresses column in the Proxy Service List, click the IP address.

  21. Ensure that Enable Session Stickiness is selected and Connect Using SSL is deselected.

  22. For Connect Port, select 9102.

  23. On the Protected Resources tab, click New.

  24. Provide a name for the protected resource, then click OK.

  25. (Optional) Provide a description for the protected resource.

  26. For Authentication Procedure, select OAuth Token.

  27. In the URL Path List section, click New.

  28. For URL Path, enter /wss*, then click OK.

  29. Deselect the /wss* path and select the /* path, then click Delete. Click OK.

  30. Click OK four times until you are on the Access Gateway Servers page.

  31. Click Security > Trusted Roots.

  32. Click Auto-Import From Server.

  33. For Server IP/DNS, provide the IP or DNS for the Secure API Manager gateway or L4 switch.

    NOTE:If you have a multi-gateway system, enter the IP or DNS of your L4 switch. If you have a single gateway system, enter the IP or DNS of the Secure API Manager gateway.

  34. For Server Port, enter 9443.

  35. Provide a name for the certificate and click OK.

  36. Click OK. With the new trusted root selected, click Add Trusted Roots to Trust Stores.

  37. Click the pencil next to Trust store(s).

  38. Select the ESP Trust Store and Proxy Trust Store for the Access Gateway cluster. Click OK, then click OK again.

  39. Click OK to add the trusted roots to the trust stores.

  40. Click Close.

  41. Update the Identity Servers and Access Gateways.

Once you have completed these initial configuration steps, you can continue with creating and publishing a WebSocket API. For more information, see Configuring and Publishing a WebSocket API.

3.4.2 Configuring and Publishing a WebSocket API

A WebSocket API allows a developer to expose WebSocket services as an API while providing OAuth security, throttling, analytics, and so forth through Secure API Manager.

Secure API Manager uses the Access Gateway in Access Manager as a reverse proxy to secure WebSocket APIs. If the WebSocket API is unsecured, it goes directly through the Secure API Manager gateway and does not use the Access Gateway in Access Manager. Unsecured WebSocket APIs do not require configuration in Access Manager.

NOTE:Before you can create and publish a secure WebSocket API using Secure API Manager, you must perform some initial configuration steps in the Access Manager Administration Console. For more information, see Configuring WebSocket Reverse Proxy in Access Manager.

To create a WebSocket API:

  1. Log in to the Publisher using the account your Secure API Manager administrator gave you.

    https://dns-name-lifecycle-manager:9444/publisher

  2. To design a WebSocket API:

    1. Click Add New API.

    2. Select Design a New WebSocket API.

    3. Use the following information to define the WebSocket API:

      Name

      Specify a name for the WebSocket API that appears in the Store. No spaces are allowed.

      Context

      Specify the URI context path of the WebSocket API. It is case-sensitive.

      NOTE:If you want the WebSocket API to be secure, the context must start with wss-, followed by the regular context. For example, an echo WebSocket API could use the context wss-echo to make it a secure WebSocket API.

      Version

      Specify the version of the WebSocket API. This helps you manage the lifecycle of the API.

      Visibility

      Select whether the WebSocket API is Public and anyone can see it or select Restricted by roles to allow only the users with the correct roles to view the WebSocket API. For more information, see Section 4.0, Controlling Access to the APIs through the Access Manager Roles.

      Description

      Specify a description of the WebSocket API that appears in the Store. The description helps people understand the purpose of the WebSocket API.

      Select Image

      Upload an image to represent the WebSocket API in the Store. The maximum dimensions are 100 x 100 pixels.

  3. To implement the WebSocket API:

    1. Click Next: Implement.

    2. Select Managed API.

    3. Add the production and sandbox endpoints of the WebSocket API including the port number. For example:

      ws://echo.websocket.org:80

      or

      wss://echo.websocket.org:443

      WARNING:If do you not add a port number, the API might connect to the WebSocket but the API does not function.

  4. Click Next: Manage API.

  5. Configure the WebSocket API as follows:

    Make this the Default Version

    Select this option to make the version of the published WebSocket API the default version so that when you access the WebSocket API through a URL you do not have to enter a specific version. For example, if the API version is 2.5 and the URL is https://my.company.com/timesheet/2.5, users just have to enter https://my.company.com/timesheet/.

  6. Configure the throttling options for the API as follows:

    Maximum Backed Throughput

    This option limits the number of calls Secure API Manager allows to the back-end. If you select Specify, you must specify the number of transactions per second (TPS) for the production environment and the sandbox environment.

    Subscription Tiers

    Select the appropriate tier that allows the correct number of requests per second. When users subscribe to the WebSocket APIs, the subscription tiers controls the request to the API.

    Advanced Throttling Options

    Select whether you want the throttling policy applied at the API. If you select the API level, Secure API Manager ignores the other policies and does not apply them.

    For more information about the different throttling options, see Section 5.0, Managing Connections to the APIs with Throttling Policies.

  7. Select whether you will use the WebSocket API in a production environment, sandbox environment, or both types of environments.

  8. Define the business information about the WebSocket API. For example, specify the business owner of the WebSocket API and the technical owner of the WebSocket API.

  9. Click Save & Publish, then decide whether to continue editing the WebSocket API, access the Store, or view an overview of the WebSocket API.

You can test and ensure that the WebSocket API works by accessing the new WebSocket API in the Store. For more information, see Invoking and Testing the WebSocket APIs. If you have documentation to add to the API, proceed to Section 6.0, Managing Documentation for the APIs.