Integrate On-Premise API Proxies

Enterprises that deploy the CA API Management hybrid solution instead of the SaaS solution require an on-premise API proxy and an instance of the aan in the cloud. This article describes how to integrate one or more clusters of on-premise API proxies with aan. It also explains how to update the integration software on the API proxy when necessary.
apip43
Enterprises that deploy the CA API Management 
hybrid
 solution instead of the SaaS solution require an on-premise API proxy and an instance of the 
API Portal
 in the cloud. 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, it is important to note that it is your responsibility to keep the API Portal integration software up-to-date in your solution as this is not performed automatically by the software. If you do not, your solution may not take advantage of new features, defect fixes, or security patches.
For hybrid customers, if your on-premise Gateway requires a proxy setting for any outbound traffic or connections, you need to modify the Routing Assertions in your specific policies or services.
In this article, learn how to:
2
After the administrator deploys the CA API Management solution, the following functionality is available on CA API Developer Portal:
  • Publish an API, and view the details of the API from API Catalog page
  • 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
  • Only view APIs in the API explorer 
    As no API Proxy is enrolled with Portal, you cannot test APIs from the API Explorer option.
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 perform the following tasks:
  • Publish APIs
  • Manage API keys
  • View the analytics data in the Analytics dashboard
  • Test the APIs on Proxy using the API Explorer
Integrate On-Premise API Proxy Clusters
To deploy the CA API Management hybrid SaaS solution, connect your on-premise API proxy clusters to your instance of 
API 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, then the
    API Portal
    administrator must inform all users to configure their browsers to accept the certificate. Otherwise, the API proxy will not work.
  • The
    API Portal
    only supports the default OTK installation. It is not compatible with OTKs that are installed with an instance modifier.
Prerequisites:
  • API Gateway version 9.2 CR05 or higher or 9.3 and Compatibility Matrix for details.
  • The 
    API Portal
     only supports 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 the API Portal. 
    Use cURL or Wget to test the port.
  • Ensure that no global policies, including message-received, are configured on the API Proxy. No global policies can exist while the Gateway is integrated with API Portal.
If the assertion
Add HTTP Header Strict-Transport-Security
in OTK policy
OTK Authorization Server Configuration
is enabled, then responses include the
Strict-Transport-Security
header (HSTS). That 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
Strict-Transport-Security
assertion in your hybrid deployment. For more information about the assertion, see the OAuth Toolkit documentation.
Enroll the On-Premise API Proxy
To enroll the on-premise API proxy cluster:
  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,
      and complete the following fields:
      • Proxy Name
        : Give your proxy cluster a unique name.
      • Deployment Type
        : Choose between Automatic, On Demand, or Scripted. For more information about federated deployment types, see Manage API Deployments.
  2. Select 
    Create
    .
  3. In Complete Proxy Enrollment, select 
    Select URL 
    to copy the enrollment URL to the clipboard. Do not close or navigate away from the Complete Proxy Enrollment page.
  4. 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 Proxies
You can enroll multiple on-premise API proxy clusters with the Portal. After enrolling the first API proxy cluster, use the following procedure to enroll each additional API proxy.
 A Proxy supports 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.
See Manage Manage API Deployments for more information about selecting a deployment type.
To enroll additional API proxy clusters:
  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
      , and complete the following fields:
      • Proxy Name
        : Give your proxy cluster a unique name.
      • Deployment Type
        : Choose between Automatic, On Demand, or Scripted. For more information about federated deployment types, see Manage API Deployments.
  2. Select 
    Create
  3. In Complete Proxy Enrollment, select 
    Select URL 
    to copy the enrollment URL to the clipboard. Do not close or navigate away from the Complete Proxy Enrollment page.
  4. 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.
  5. 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.
  6. (Optional) To verify that the enrollment succeeded, follow the
    To view the status of an API proxy
    section.
View the Status of an API Proxy
The API Proxy Details page displays the following information:
  • Deployment status
  • Deployment type
  • Date and time of last deployment
To view the status of an API Proxy:
  1. Log in to 
    API Portal
     as a Portal administrator.
  2. Select the
    Services
    icon.
  3. Select
    Publish, Proxies.
  4. On the
    API Proxy
    page, select 
    View Details
    . Green check marks indicate that the API proxy is synchronizing correctly. Red
    x
    icons may indicate a problem, especially if the last synchronization far exceeds the synchronization interval.  
  5. For on-demand and scripted deployment types, select the Deployed link to view details of deployment
  6. To view details of an error, select the red error icon.
    If you did not complete the proxy enrollment, the proxy is considered
    pending enrollment
    and no details can be shown. To complete the enrollment, select
    View Details
    on the API Proxy page for that proxy and follow the instructions on the screen. Note that the enrollment URL expires and regenerates after 24 hours. If more than 24 hours have elapsed because you copied the URL, you must copy a new one.
    See Troubleshoot API Deployments for more information about troubleshooting deployments.
Edit an API Proxy
You can change the name of an API proxy (for example, to give it a new name or to correct a spelling mistake).
In this release, you cannot edit the deployment type for proxies that have not been deployed.
To edit an API proxy:
  1. Log in to 
    API Portal
     as a Portal administrator.
  2. Select the
     Services 
    icon.
  3. Select
     Publish, Proxies.
  4. On the API Proxy page, select 
    Edit
     next to the API proxy.
  5. Edit the 
    Proxy Name.
  6. Select the deployment type and select 
    Save
Delete an API Proxy
You can remove a proxy if you no longer need it, if it is causing problems, or if it was added by mistake.
To delete an API proxy:
  1. Log in to 
    API Portal
     as a Portal administrator.
  2. Select the
     Services 
    icon.
  3. Select
     Publish, Proxies.
  4. On the API Proxy page, select 
    Delete
     next to the API proxy.
  5. Select OK to confirm the deletion.
When an API proxy is deleted, all references to that proxy are removed from 
API Portal
. Analytics data for that API proxy remain in the system but is no longer accessible. 
You cannot delete the last enrolled API Proxy.
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, you will see a note in the release notes 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 will not affect non-standard services, policies, policy templates, or encapsulated assertions. It will also 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.
To update the integration software on the API proxy:
 
  1. In the Policy Manager, log in to the API proxy as an administrator.
  2. On the 
    Tasks
     menu, click 
    Extensions and Add-Ons
    Update Portal Integration
    .
  3. 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.
To edit the schedule of an application synchronization task:
  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.
To hide the social-media login buttons:
  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
    enabel_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
    . Use the dialog to remove the PSSG and DSSG certificates. 
    Note:
     Do not delete the API Gateway self-signed SSL certificate.
  3. On the 
    Tasks
     menu, select 
    Certificates, Keys and Secrets
     and 
    Manage Private Keys
    . Use the dialog to remove the portalman private key.
  4. On the 
    Tasks
     menu, select 
    Global Settings
     and 
    Manage Scheduled Tasks
    . Use the dialog to remove all scheduled tasks.
  5. On the 
    Tasks
     menu, select 
    Global Settings
     and 
    Manage Cluster-wide Properties
    . Use the dialog to 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.