Integrate On-Premise API Proxies

Enterprises that deploy the CA API Management solution require an on-premise API proxy and an instance of the
API Portal
. This article describes how to integrate one or more clusters of on-premise API proxies with
API Portal
. It also explains how to update the integration software on the API proxy when necessary.
For hybrid customers, you must keep
API Portal
integration software up to date in your solution as the software does not perform this automatically. If you do not, your solution might not take advantage of new features, defect fixes, or security patches.
If your on-premise Gateway requires a proxy setting for outbound traffic or connections, you must modify the Routing Assertions in your specific policies or services.
In this article, learn how to:
After the administrator deploys the CA API Management solution, the following functionality is available on
API Portal
:
  • Publish an API and view the details of the API.
  • Create and manage users.
  • Self-register to Portal and view the APIs.
  • Create organizations and account plans.
  • Approve or reject requests from the Requests page.
  • Perform configurations from the Settings page.
  • View APIs in the API Explorer or Swagger UI.
    You can test APIs from the API Explorer option only if an API proxy is enrolled with Portal.
When you enroll more than one API cluster with
API Portal
, you can publish APIs and can manage API keys across multiple environments from a single Portal instance. Examples of multiple environments include: developer, test, production.
After integrating the on-premise API proxy clusters with a Portal instance, users can do the following tasks:
  • Publish APIs
  • Assign organizations to specific proxies
  • Manage API keys
  • View the analytics data in the Analytics dashboard
  • Test the APIs on a proxy using the API Explorer or Swagger UI
    API Explorer is only accessible through the API Portal/Ingress tenant.
Integrate On-Premise API Proxy Clusters
During proxy enrollment, you can name a proxy, set the deployment type, and assign organizations to the proxy.
Proxies can have one of the following deployment types:
  • Automatic
    : Any changes to APIs are automatically deployed to the proxy. For example, whenever an API is created, edited, or deleted.
  • On-demand
    : API deployments are triggered on-demand by calling the deployment APIs. These APIs are accessed from the Portal APIs link in the navigation menu.
  • Scripted
    : API deployments are integrated into your existing CI/CD workflow by leveraging the deployment APIs and invoking them from your deployment script.
Ror more information about selecting an API deployment type, see Manage API Deployments.
A proxy can also have specific organizations assigned to it to allow deployment in multiple organizations. Once an organization is assigned to a proxy, a Publisher within the organization can deploy an API they own or manage to that proxy. For more information, see Organizations Assignment.
Prerequisites for Proxy Enrollment
  • API Gateway version 9.2 CR05 or higher and Compatibility Matrix for details.
  • API Portal
    supports only the default OTK installation. Do not install it with an instance modifier. Also, the OTK must be installed with JDBC connection name
    OAuth
    .
  • The API proxy can make a secure outbound connection on port 443 to
    API Portal
    .
    Use cURL or Wget to test the port.
  • Ensure that there are no global policies, including message-received, configured on the API proxy. Global policies cannot exist while the Gateway is integrated with Portal.
  • Use the enrollment URL within 24 hours, otherwise it expires. Keep it confidential. Before you use the URL, anyone who knows it can enroll a different API proxy with
    API Portal
    .
  • We recommend that you use a proper SSL certificate on your on-premise API proxy. If instead you use a self-signed certificate, for the API proxy to work, the
    API Portal
    administrator must inform all users to configure their browsers to accept the certificate.
  • The
    API Portal
    only supports the default OTK installation. It is not compatible with OTKs that are installed with an instance modifier.
If you have enabled the assertion
Add HTTP Header Strict-Transport-Security
in the OTK policy
OTK Authorization Server Configuration
, then responses include the
Strict-Transport-Security
header (HSTS). This header restricts browser communication to HSTS only. In hybrid deployments of
API Portal
, the assertion is enabled by default. In SaaS deployments, the assertion is disabled by default. We recommend disabling the HSTS assertion in your hybrid deployment. For more information about this assertion, see the OAuth Toolkit documentation.
Enroll the On-Premise API Proxy Cluster
Follow these steps:
  1. Use
    API Portal
    to get the enrollment URL:
    1. Log in to
      API Portal
      as a Portal administrator.
    2. Go to
      Publish
      ,
      Proxies
      .
    3. Select
      Add Proxy
      .
    4. On the Add Proxy Details page, complete the following fields, and then select
      Save & Next
      :
      • For
        Proxy Name
        : Give your proxy cluster a unique name.
      • For
        Deployment Type
        : Choose between Automatic, On Demand, or Scripted. For more information about federated deployment types, see Manage API Deployments.
    5. On the Add Proxy Organization Assignment >
      Organizations
      : Select organizations that have access to this proxy. For more information on how organizations assignment affects deployment, see Organizations Assignment.
    6. On the Complete Proxy Enrollment page, select
      Select URL
      to copy the enrollment URL to the clipboard. Do not close or navigate away from the Complete Proxy Enrollment page.
    7. Use the Policy Manager to submit the enrollment URL:
      1. Log in to the API proxy as the API proxy administrator.
      2. On the
        Tasks
        menu, select
        Extensions and Add-Ons
        ,
        Enroll with Portal
        . The URL is automatically pasted when using the desktop client version of the Policy Manager.
      3. Select
        Apply
        .
The enrollment process adds several items to the API proxy:
  • New certificate
  • New private key
  • New cluster properties
  • New encapsulated assertions
  • New scheduled tasks (which you can edit, but not remove)
  • New folders:
    • API Portal Integration
    • API Portal SSO
    • Portal APIs (This folder is not populated until APIs are deployed to the proxy.)
If your on-premise API proxy has the CA Mobile Access Gateway (MAG) components that are installed, we recommend that you hide the social-media login buttons from Portal users, as described below.
Enroll Additional API Proxy Clusters
You can enroll multiple on-premise API proxy clusters with Portal. After enrolling the first API proxy cluster, use the following procedure to enroll each additional API proxy.
Follow these steps:
  1. Use
    API Portal
    to get the enrollment URL:
    1. Log in to
      API Portal
      as an
      API Portal
      administrator.
    2. Select the
      Services
      icon.
    3. Select
      Publish, Proxies
      .
    4. Select
      Add Proxy
      , complete the following fields, and then select
      Next
      :
      • In Proxy Details >
        Proxy Name
        : Give your proxy cluster a unique name.
      • In Proxy Details >
        Deployment Type
        : Choose between Automatic, On Demand, or Scripted. For more information about federated deployment types, see Manage API Deployments.
      • In Organizations Assignment >
        Organizations
        : Select organizations that have access to this proxy. For more information on how organizations assignment affects deployment, see Organizations Assignment.
  2. In the Complete Proxy Enrollment page, select
    Select URL
    to copy the enrollment URL to the clipboard. Do not close or navigate away from the Complete Proxy Enrollment page.
  3. Use the Policy Manager to submit the enrollment URL:
    1. Log in to the API proxy as the API proxy administrator.
    2. On the
      Tasks
      menu, select
      Extensions and Add-Ons
      ,
      Enroll with Portal
      . The URL is automatically pasted when using the desktop client version of the Policy Manager.
    3. Select
      Apply
      and wait until you see a message stating that the enrollment succeeded.
  4. In the Policy Manager, use the
    Manage Scheduled Tasks
    dialog to disable the following cron job from any additional API proxies: Portal Tenant Sync Policy Template.
  5. (Optional) To verify that the enrollment succeeded, follow the
    To view the status of an API proxy
    section.
Update the Integration Software on the API Proxy
When an update for the
API Portal
integration software on an on-premise API proxy is available, this information is noted in the ReleaseNotes that an upgrade is available. The
API Portal
administrator then asks an API proxy administrator to update the integration software on the API proxy.
  • The update overwrites any customizations to standard services installed by the Portal integration software, policies, policy templates, or encapsulated assertions. The update does not affect non-standard services, policies, policy templates, or encapsulated assertions. It also does not affect scheduled tasks, or the cached age of APIs and Account Plans (cluster properties).
  • This update feature does not update the version of the API proxy. This upgrade feature only upgrades the integration software. For information about general API proxy updates, see Upgrade CA API Gateways in the online documentation for the API Gateway.
Follow these steps:
  1. In the Policy Manager, log in to the API proxy as an administrator.
  2. (
    For API Gateway 10 CR1 and higher only; skip this step if using other versions of the Gateway
    )
    Download and replace the PortalUpgradeAssertion file. Follow the instructions in KB 201757: Upgrade Portal Integration bundle operation fails for API Gateway 10 CR1 and above.
  3. On the
    Tasks
    menu, click
    Extensions and Add-Ons
    ,
    Update Portal Integration
    .
  4. Restart the API proxy. To do this, open a privileged shell on the API proxy and then run these commands:
    service ssg stop
    service ssg start
    For more information, see 'Using the Privileged Shell' in the online documentation for the API Gateway.
Edit Application Synchronization Schedules
Scheduled recurring tasks synchronize application entities on
API Portal
and the API proxy. So after a developer adds an application to
API Portal
, the next occurrence of an application synchronization task gets information about the application from
API Portal
and adds it to the API proxy. When a developer edits an application on
API Portal
, such as adding another API to it, then the next scheduled synchronization task updates the information about the application on the API proxy. There are two scheduled tasks for synchronizing applications:
  • Portal Sync Application
    is an
    incremental
    synchronization task, updating only applications on the API proxy that were changed on
    API Portal
    . By default, it occurs once per minute.
  • Portal Bulk Sync Application
    is a
    bulk
    synchronization task, updating all applications on the API proxy, whether they were changed on
    API Portal
    . By default, it occurs once per day.
Because a bulk synchronization needs more computing resources than an incremental synchronization needs, the bulk synchronization task is scheduled to run much less frequently.API proxy administrators can edit the synchronization schedules.
Follow these steps:
  1. In the
    Policy Manager
    , log in to the API proxy as an
    administrator.
  2. On the
    Task
    menu, select
    Global Settings
    ,
    Manage Scheduled Tasks
    . The Manage Scheduled Tasks dialog opens.
  3. Double-click the
    Portal Sync Application
    task or
    Portal Bulk Sync Application
    task. The Scheduled task Properties dialog opens.
  4. Edit the schedule. For example, to reschedule the Portal Sync Application task to run every 30 seconds, enter 30 in the
    Every
    field and select
    Second
    on the adjacent menu.
  5. Select
    OK
    .
image2016-3-22 13:7:9.png
Hide Social-Media Login Buttons from Portal Users
If your on-premise API proxy has the CA Mobile Access Gateway (MAG) components installed, then the OAuth 2.0 Authorization Login dialog displays social-media login buttons to Portal users. However, Portal SaaS does not support social media login. So when a Portal user clicks a social-media login button (
shown next
), an error message appears. image2016-11-17 13:2:23.png To hide the social-media login buttons from Portal users, API proxy administrators can edit the "MAG Enabled Social Login Providers" policy fragment.
Follow these steps:
  1. Start the Policy Manager.
  2. Log in to the proxy as an administrator.
  3. Locate the
    MAG Enabled Social Login Providers
    policy fragment in the MAG Social Login folder: MAG-<version>, configuration, MAG Social Login.
  4. Set the following context variables to false:
    enable_google
    enable_facebook
    enable_linkedin
    enable_salesforce
    enable_enterprise
    enable_device2device
Clean Up the API Gateway and Portal after a Failed Enrollment
If you tried to enroll a tenant API Gateway with an
API Portal
but the enrollment failed, then clean up the API Gateway and Portal before you try again.
You can use the following procedures whether you set up the API Proxy on AWS or on another cloud or network.
Step 1. Clean up the tenant API Gateway:
  1. In the Policy Manager, log in to the Gateway as a Gateway administrator.
  2. On the
    Tasks
    menu, select
    Certificates, Keys and Secrets
    and
    Manage Certificates
    .
  3. Remove the PSSG and DSSG certificates.
    Do not delete the API Gateway self-signed SSL certificate.
  4. On the
    Tasks
    menu, select
    Certificates, Keys and Secrets
    and
    Manage Private Keys
    .
  5. Remove the portalman private key.
  6. On the
    Tasks
    menu, select
    Global Settings
    and
    Manage Scheduled Tasks
    .
  7. Remove all scheduled tasks.
  8. On the
    Tasks
    menu, select
    Global Settings
    and
    Manage Cluster-wide Properties
    .
  9. Remove all properties that begin with
    portal
    .
Step 2. Remove the API Gateway from the API Portal:
  1. Log in to the API Portal as an API Portal administrator.
  2. Select the
    Services
    icon.
  3. Select
    Publish
    ,
    Proxies
    .
  4. On the API Proxy page, find the Gateway. Its state is
    Cluster is currently pending enrollment completion
    .
  5. Select
    Delete
    next to the Gateway you want to remove.