Log in to the master host machine as the regular user, and use the oc utility to authenticate against OpenShift:

$ oc login -u ocuser --certificate-authority=/etc/origin/master/ca.crt --server=https://apimgmt-master.apimgmt.example.com:8443
Authentication required for https://apimgmt-master.apimgmt.example.com:8443 (openshift)
Username: ocuser
Password: PASSWORD
Login successful.

Welcome! See 'oc help' to get started.

Please follow the On-premises Installation Guide to install 3scale API Management Platform (AMP) 2.0 on OpenShift

Create a new project called 3scale-api.

oc new-project 3scale-api --display-name="3scale APM on OpenShift" --description="This project demonstrates the use of 3scale APM on OpenShift"

Next, download amp.yml and proceed with the installation. In the OpenShift environment used for this reference architecture, the wildcard domain is set up as apimgmt.example.com.

oc new-app --file amp.yml --param WILDCARD_DOMAIN=apimgmt.example.com

--> Deploying template "3scale-api/system" for "amp.yml" to project 3scale-api

     system
     ---------
     Login on https://3scale-admin.apimgmt.example.com as admin/bptp5gec


     * With parameters:
        * AMP_RELEASE=2.0.0-CR2-redhat-1
        * ADMIN_PASSWORD=bptp5gec # generated
        * ADMIN_USERNAME=admin
        * APICAST_ACCESS_TOKEN=sjvkpnun # generated
        * ADMIN_ACCESS_TOKEN=kc2tdwob1wijaori # generated
        * WILDCARD_DOMAIN=apimgmt.example.com
        * TENANT_NAME=3scale
        * MySQL User=mysql
        * MySQL Password=ovixy777 # generated
        * MySQL Database Name=system
        * MySQL Root password.=hclunkck # generated
        * SYSTEM_BACKEND_USERNAME=3scale_api_user
        * SYSTEM_BACKEND_PASSWORD=ogboxf8d # generated
        * REDIS_IMAGE=rhscl/redis-32-rhel7:3.2-5.7
        * MYSQL_IMAGE=rhscl/mysql-56-rhel7:5.6-13.14
        * SYSTEM_BACKEND_SHARED_SECRET=sip7ekg4 # generated
        * SYSTEM_APP_SECRET_KEY_BASE=b0b2ec645aa60c2d47bebc817dada0dba73ea5183401185e0060728e7e0c4aa52adb72a112cca22568084b502c2212dc78b8e213187dabeb747a0d55c8ec5c87 # generated
        * APICAST_MANAGEMENT_API=status
        * APICAST_OPENSSL_VERIFY=false
        * APICAST_RESPONSE_CODES=true

--> Creating resources ...
    persistentvolumeclaim "system-storage" created
    persistentvolumeclaim "mysql-storage" created
    persistentvolumeclaim "system-redis-storage" created
    persistentvolumeclaim "backend-redis-storage" created
    deploymentconfig "backend-cron" created
    deploymentconfig "backend-redis" created
    deploymentconfig "backend-listener" created
    service "backend-redis" created
    service "backend-listener" created
    service "system-provider" created
    service "system-developer" created
    deploymentconfig "backend-worker" created
    service "system-mysql" created
    service "system-redis" created
    deploymentconfig "system-redis" created
    service "system-sphinx" created
    deploymentconfig "system-sphinx" created
    service "system-memcache" created
    deploymentconfig "system-memcache" created
    route "system-provider-admin-route" created
    route "backend-route" created
    route "system-developer-route" created
    deploymentconfig "apicast-staging" created
    service "apicast-staging" created
    deploymentconfig "apicast-production" created
    service "apicast-production" created
    route "api-apicast-staging-route" created
    route "api-apicast-production-route" created
    deploymentconfig "system-app" created
    deploymentconfig "system-resque" created
    deploymentconfig "system-sidekiq" created
    deploymentconfig "system-mysql" created
    configmap "redis-config" created
    configmap "smtp" created
--> Success
    Run 'oc status' to view your app.

Please record the username (admin) and password, as these will later be used to log in into 3scale API Management Platform Admin Portal.

Below are the commands to reset and clean up, if you ever need to do a re-installation of the 3scale-api project.

oc delete all --all
oc delete configmap redis-config smtp
oc delete pvc system-storage mysql-storage system-redis-storage backend-redis-storage

The console URL, username and the generated password are logged during the processing of the application template by OpenShift. Use this information to log in to the 3scale AMP console.

Login on https://3scale-admin.apimgmt.example.com as admin/bptp5gec

ActiveDocs make API documentation user friendly, interactive, intuitive, and clear. With 3scale ActiveDocs, based on the Swagger Framework, developers can explore APIs live, straight from the documentation web pages.

To take advantage of this feature, it is best to set up ActiveDocs before further defining the API. Click on top menu item called API, then select ActiveDocs to bring up the ActiveDocs page. There is one demo service spec, called Echo, already defined.

Click the link to Create a new spec:

After filling out all the required fields and clicking the Update Service button, the exposed services can be viewed and tested on the next preview screen:

Click on each service to reveal details, including the schema and/or model for the request and response, and the newly added user_key, used for 3scale API Management Platform’s authentication.

Use the following values to create three sets of ActiveDocs. For API JSON Spec content, use the corresponding swagger files from the github repository:

Service 1:

Name:           Fuse-gateway-internal
System Name:    Fuse-gateway-internal

Service 2:

Name:           Fuse-gateway-partner
System Name:    Fuse-gateway-partner

Service 3:

Name:           Fuse-gateway-public
System Name:    Fuse-gateway-public

Click on the top menu item, titled Developers.

A default developer by the name of John Doe has been created during installation; it is best to remove this developer to avoid future confusion.

Click on the Create link to navigate to the Create new Account page.

With each new user, should an existing API with an application plan exist, the system will create an application to point to them. The created application will select the first available API plan by default, which may not be appropriate, unless a Default Plan is already chosen for the API. Review the corresponding screen and create the needed applications, once the right APIs are defined.

Click on the application name to display detailed information about the application, and make changes.

The API Credentials for this application is also displayed on this page:

Note the associated application plan:

Use below values to create four accounts:

Account 1:

Username:                   desktop-user
Email:                      desktop-user@test.com
Password:                   password
Organization/Group Name:    desktop-group

Account 2:

Username:                   mobile-user
Email:                      mobile-user@test.com
Password:                   password
Organization/Group Name:    mobile-group

Account 3:

Username:                   partner-user
Email:                      partner-user@test.com
Password:                   password
Organization/Group Name:    partner-group

Account 4:

Username:                   public-user
Email:                      public-user@test.com
Password:                   password
Organization/Group Name:    public-group

3.7.1. Create Applications using the new APIs

This step is required to create an associated user_key for each API. Click on the top menu item, titled Developers and choose one of the group defined earlier.

Click on Application, then click the Create Application link:

Select the right corresponding application plan and type an application name:

Repeat this step to create the follow applications:

Finally, click on the top API menu item and from there, go to the Integration section of each defined API. Click to edit APIcast configuration and add two more values.

First, add Shared_secret_sent_from_proxy_to_API_backend_12345678987654321 to Secret Token under AUTHENTICATION SETTINGS. For further explanation of this setting, refer to the next chapter.

Then, add /products?featured=1 to the input field for API test Get request at the bottom of the page. Notice that the curl command will already include the proper user_key at the end of the URL. This is the new application’s user_key.

Press the button to Update & test in staging Environment. If everything is set up properly, the test will go through. The automatically generated curl command can also be used in a shell environment to verify.

[czhu@apimgmt-master ~]$ curl "https://fuse-gateway-service-3scale-apicast-staging.apimgmt.example.com:443/products?featured=1&user_key=032acee45c566dc8b510b0ab7d30be4d"

[{"sku":"5945c1b535c6850001d41aa0","name":"ABC HD32CS5002 32-inch LED TV","description":"HD LED Picture Quality
ConnectShare Movie Wide Color Enhancement Clear Motion Rate 60","length":29.1,"width":3.7,"height":17.5,"weight":17.0,"isFeatured":true,"availability":52,"price":249.99,"image":"TV","keywords":["Electronics","TV"]},........]

The final step is to set up the Developer Portal. The goal is to let users sign up in the developer portal and immediately get access to the APIs, so they can get started using the API interactive documentation (ActiveDocs, based on Swagger spec), with their own application key.

Click on the top menu item, titled Developer Portal, then select Documentation from the left side panel:

Replace the page source with the Documentation content found in the project repository, and save your changes.

Next, click on Homepage in the left side panel.

Replace the page source with the Homepage content found in the project repository, and save your changes.

Deploy the Presentation service, which exposes a web tier for the desktop-user to access the application.

Create a new project for this service:

$ oc new-project desktop-project --display-name="Desktop project for Fuse ecom-services" --description="Desktop project for Fuse ecom-services"

Next, use OpenShift Source-To-Image (S2I) in this project to deploy the presentation service. The presentation_template.yaml file can be found in the project repository. Note that the SERVICE_ADDRESS is passed in as environment variables, while user_key is referenced as an OpenShift Secret in the template; the value for user_key is passed to the template as a parameter.

$ oc new-app -p USER_KEY_VALUE=9331104b50c0385cc64ebd72a38d4a56 -e SERVICE_ADDRESS=fuse-gateway-internal-3scale-apicast-staging.middleware.ocp.cloud.lab.eng.bos.redhat.com -f https://raw.githubusercontent.com/RHsyseng/3scale-apm/master/template/presentation_template.yaml

To navigate to the Developer Portal, click on the top menu item titled Developer Portal and then select the Visit Developer Portal link on the next row. This will open the Developer Portal page in a new tab.

By default, the Developer Portal is not visible to the public. Users other than admin will be challenged for the Developer Portal Access Code.

This Access Code can be found in the 3scale API Management Platform Admin Portal. Click on the top menu item, titled Settings, and then choose Developer Portal.

Clearing the value for the Developer Portal Access Code makes the site public, and the address can then be bookmarked for quick access without going through the 3scale API Management Platform Admin Portal.

The Developer Portal allows registered users (desktop-user, mobile-user, partner-user and public-user) to access their own corresponding ActiveDocs. Anonymous users will see the following page, asking them to register and get an API key:

A further attempt by an anonymous user to access the documentation will result in the below page, prompting the user to sign in to see ActiveDocs, but also informing the user of the credentials for the public user account.

Registered users who have logged in will see a page displaying their API key (user_key):

Clicking the DOCUMENTATION link takes an authenticated user to a page that displays the ActiveDocs corresponding to their application plan. For desktop-user and mobile-user, as internal users, this means access to the Fuse-gateway-internal ActiveDoc defined in last chapter, which has access to all services exposed by Fuse gateway service:

For partner-user, access is limited to Fuse-gateway-partner ActiveDocs, which only exposes the product service.

For public-user, only access to Fuse-gateway-public ActiveDoc is provided, limiting such users to only product queries.

The ActiveDocs displayed on the DOCUMENTATION page accelerate development by allowing users to explore services, their parameters and responses.

The presentation application is accessible by the desktop-user and calls Fuse gateway service services. The desktop-user is associated with the internal plan, and this application also makes use of all services.

4.2.1. Browser Access

To run the web application, simply point your browser to the address exposed by the route. This address should ultimately resolve to the IP address of an OpenShift host where the router is deployed.

Figure 4.1. Application Homepage before initialization

Demo data is populated by hitting the demo.jsp page, for example at http://msa.example.com/demo.jsp. After initialization, this page will show the featured products:

Figure 4.2. Application Homepage after initialization

4.2.2. User Registration

Anonymous users are constrained to browsing inventory, viewing featured products and searching the catalog. To use other features that result in calls to the Sales and Billing services, a valid customer must be logged in.

To register a customer and log in, click on the Register button in the top-right corner of the screen and fill out the registration form:

Figure 4.3. Customer Registration Form

After registration, the purchase button allows customers to add items to their shopping cart, to subsequently visit the shopping cart and check out, and review their order history.

Rate Limit is set up for the public plan. The imposed constraint is a maximum of five requests in every one minute.

To see the effect of this Rate Limit, use the curl command example from the Fuse-gateway-public API integration page.

Click on APIs, choose Fuse-gateway-public, click on Integration link, then click edit APICast configuration link.

The curl command is at the bottom.

Execute this command multiple times in succession to exceed the limit and a message of Authentication failed will appear instead of the response data.

Click on the top menu item titled Analytics to view the Monitoring page, containing usage data for all three APIs.

Click on an API name to view more details about it. For example, clicking on Fuse-gateway-public should reveal a spike that results from the multiple curl command invocations intended to the rate limit in the previous section.

The usage graph for Fuse-gateway-internal will show multiple calls for different services. These service calls were triggered by the web application on different Fuse gateway service operations.

Note that registered users can view associated and accessible Analytics data from the Developer Portal. For example, after signing in to the Developer Portal as the desktop-user, click on STATISTICS to view a graph similar to the one displayed below:

This reference architecture uses API Key (user_key) for authentication.

Each application has its own user_key. The keys can be found in respective application pages.

Each calling application uses the assigned user_key, which corresponds to an API’s application plan. The screenshot below shows an example of an HTTP GET call:

The user_key and base URL should not be hard-coded in the application source code, as they are prone to later changes. One good example is the use of OpenShift Secret to managing the user_key in OpenShift , which is referenced in the deployment of the presentation service, for example:

The user_key value is stored in an OpenShift Secret, which is defined in the presentation_template.yaml file:

- apiVersion: v1
  kind: Secret
  metadata:
    name: 3scale-secret
    namespace: desktop-project
  stringData:
    user_key: ${USER_KEY_VALUE}

Further down in the presentation_template.yaml file, content from the Secret is referenced and made available as an environment variable.

      spec:
        containers:
        - env:
          - name: USER_KEY
            valueFrom:
                secretKeyRef:
                    name: 3scale-secret
                    key: user_key

The actual value for user_key is passed in as a parameter during deployment. The use of a parameter instead of an environment variable has the advantage that parameters won’t be kept in memory, so credentials won’t be exposed. Since the base URL is not sensitive information, it can be passed in as an environment variable during pod creation.

$ oc new-app -p USER_KEY_VALUE=9331104b50c0385cc64ebd72a38d4a56 -e SERVICE_ADDRESS=fuse-gateway-internal-3scale-apicast-staging.middleware.ocp.cloud.lab.eng.bos.redhat.com --file=presentation_template.yaml

Then RestClient.java code in the service can then retrieve both data as environment variable values and use them in the web address:

public class RestClient {
    public static String  userKey = System.getenv("USER_KEY");
    public static String serviceAddress = System.getenv("SERVICE_ADDRESS");

For troubleshooting purpose, this reference architecture’s presentation layer uses the JavaScript console to log the two variables' runtime value. This allows users to verify the actual values. To see these two values in Google Chrome, go to setting, More tools, Developer Tools, and click Console.

The network topology is often effective in blocking unauthorized access to internal services. When Red Hat 3scale API Management Platform is used to introduce a gateway, direct access to the underlying API is often blocked through network tools. In cases where such configuration is impossible or insufficient, the secret token feature of 3scale API Management Platform can be used to achieve similar results.

When enabled, 3scale API Management Platform hard codes a token in the HTTP header of all requests passing through the gateway. Applications exposing the managed API would then have to check for the existence of this token and reject any requests that do not contain it. As long as the value of this token is kept private, the only way to access such API would be through the gateway.

There are two steps to turn this feature on.

First, in 3scale API Management Platform Admin Portal, click on the top menu item titled API, then choose Integration for the API that needs to be secured. Click the AUTHENTICATION SETTINGS drop-down list and give Secret Token a value.

Second, in the application code for the managed API, check all request for a token name of X-3scale-proxy-secret-token in the HTTP header. Reject any requests that do not provide a value for this token, or have an incorrect value.

For example, the following code snippet from the Fuse gateway service shows an example of how to enforce the Secret Token.

    @Value('${gateway.token.header:X-3scale-proxy-secret-token}')
    String tokenHeader

    @Value('${gateway.token.value:#{null}}')
    String tokenValue

    Logger logger = Logger.getLogger(AppRoute.class.name)

    @Override
    void configure() throws Exception {

        if (tokenValue != null && tokenHeader != null) {

            logger.info("AUTH TOKEN REQUIREMENT DETECTED: [${tokenHeader}] adding security route interceptor")
            interceptFrom().id("auth token interceptor").process(new Processor() {
                @Override
                void process(Exchange exchange) throws Exception {

                    if (exchange.in.getHeader(tokenHeader) == null
                            || exchange.in.getHeader(tokenHeader) != tokenValue) {

                        logger.info("Authorization token required, but header missing or invalid")
                        exchange.out.setHeader(Exchange.HTTP_RESPONSE_CODE, 403)
                        exchange.out.setBody("Unauthorized [missing or invalid token]")
                        exchange.setProperty(Exchange.ROUTE_STOP, Boolean.TRUE)
                    }
                }
            })
        }

The secret token in inject into the Fuse gateway service pod as an environment variable to avoid hard-coding it.

In this example, the token value is set to Shared_secret_sent_from_proxy_to_API_backend_12345678987654321. Changing this value in the 3scale API Management Platform Admin Portal without updating it in the Fuse gateway service code would result in the API integration test failing, since the value passed from 3scale API Management Platform to Fuse gateway service will not match.

Once the security token is set up, both in 3scale API Management Platform and Fuse gateway service, requests to the Fuse gateway service API need to go through 3scale API Management Platform first; otherwise, the request will fail, as it will not have the secret security token in the header.

To demonstrate this, try the two following curl commands to the same Fuse gateway service API, where the first one bypasses the 3scale API Management Platform and uses the Fuse gateway service gateway IP address directly, while the second request goes through 3scale API Management Platform as expected.

curl http://172.30.124.155:9091/products?featured=1

curl "https://fuse-gateway-internal-3scale-apicast-staging.middleware.ocp.cloud.lab.eng.bos.redhat.com:443/products?featured=1&user_key=876286f7c3cf24899c6f390464c41429"

The first requests fails with a message of missing or invalid token, while the second command returns the expected response.

To create a new service spec, the swagger file for the new service is required. The reference architecture’s Fuse gateway service provided a swagger file at http://api.example.com/api-doc/swagger.json after installation. Several updates are required to this file before it can be used in this project:

"host" : "fuse-gateway-service-3scale-apicast-staging.apimgmt.example.com:443",

"schemes" : [ "https" ],

Note that only one parameter called customerId is included in the file:

    "/customers/{customerId}" : {
      "get" : {
        "tags" : [ "customers/{customerId}" ],
        "summary" : "get customer",
        "produces" : [ "application/json" ],
        "parameters" : [ {
          "name" : "customerId",
          "in" : "path",
          "description" : "id of customer to fetch",
          "required" : true,
          "type" : "string"
        } ],
        "responses" : {
          "200" : {
            "description" : "customer fetched",
            "schema" : {
              "$ref" : "#/definitions/Customer"
            }
          }
        },
        "x-camelContextId" : "camel-1",
        "x-routeId" : "route7"
      },

Add the new parameter:

    "/customers/{customerId}" : {
      "get" : {
        "tags" : [ "customers/{customerId}" ],
        "summary" : "get customer",
        "produces" : [ "application/json" ],
        "parameters" : [ {
          "name" : "customerId",
          "in" : "path",
          "description" : "id of customer to fetch",
          "required" : true,
          "type" : "string"
        },
        {
            "name": "user_key",
            "in": "query",
            "description": "Your API access key",
            "required": true,
            "x-data-threescale-name": "user_keys",
            "type": "string"
        }
         ],
        "responses" : {
          "200" : {
            "description" : "customer fetched",
            "schema" : {
              "$ref" : "#/definitions/Customer"
            }
          }
        },
        "x-camelContextId" : "camel-1",
        "x-routeId" : "route7"
      },

Liquid is a simple programming language used for displaying and processing most of the data from the 3scale system available for API providers.

Use Liquid control flow tags if and elsif to limit access for each registered user to their own ActiveDocs:

      	{% if current_user.username == 'desktop-user' or  current_user.username == 'mobile-user' %}
          {% active_docs version: "2.0" services: "Fuse-gateway-internal" %}
            ...............

      	{% elsif current_user.username == 'partner-user' %}
          {% active_docs version: "2.0" services: "Fuse-gateway-partner" %}
            ...............

      	{% elsif current_user.username == 'public-user' %}
          {% active_docs version: "2.0" services: "Fuse-gateway-public" %}
            ...............

		{% endif %}

Refer to the product documentation on how to publish ActiveDocs in the Developer Portal.

          <script type="text/javascript">
            $(function () {
                window.swaggerUi.options['docExpansion'] = 'none';
                window.swaggerUi.options['url'] = "https://3scale.apimgmt.example.com/swagger/spec/Fuse-gateway-internal.json";
              window.swaggerUi.load();
            });
          </script>

For more information on using Liquid and Developer Portal, please refer to Liquids: Developer Portal and the Liquid Reference pages.