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 Portalintegration 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
- 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 UIAPI Explorer is only accessible through the API Portal/Ingress tenant.
Integrate On-Premise API Proxy Clusters
During API proxy enrollment, you can name a proxy, set the API and application deployment type, and assign organizations to the proxy.
You can set the following API and application deployment types for your proxies:
- Automatic: Any change to the API or application is deployed automatically to the proxy. For example, whenever an API or application is created, edited, or deleted. This is the default type.
- On-demand: API deployments are triggered on-demand by calling the Deployment API. You can access this API from the Portal APIs link in the navigation menu.
- Scripted: API and application deployments are integrated into your existing CI/CD process by leveraging the deployment APIs and invoking them from an API deployment script. The deployment APIs retrieve API or application deployment data and update the API or application deployment status for a proxy to keepAPI Portalupdated.
A proxy can also have specific organizations assigned to it to allow API or application deployment in multiple organizations. After 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 API Proxy Enrollment
- A supported version of the API Gateway as specified in the Compatibility Matrix.
- API Portalsupports only the default OTK installation. Do not install it with an instance modifier. Also, the OTK must be installed with JDBC connection nameOAuth.
- The API proxy can make a secure outbound connection on port 443 toAPI 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 withAPI 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 Portal Admin must inform all users to configure their browsers to accept the certificate.
- TheAPI Portalonly 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-Securityin the OTK policy
OTK Authorization Server Configuration, then responses include the
Strict-Transport-Securityheader (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:
- UseAPI Portalto get the enrollment URL:
- Log in toAPI Portalas a Portal administrator.
- From the menu bar, clickManage,Proxies.
- SelectAdd Proxy.The Add Proxy Details page appears.
- Complete the following fields, and then selectSave & Next:
- ForProxy Name: Give your proxy cluster a unique name.
- ForAPI Deployment Type: Choose between Automatic, On Demand, or Scripted.For more information about API deployment types, see Manage API Deployments.
- ForKey Deployment Type: Choose between Automatic, On Demand, or Scripted.For more information about application and API key deployment types, see Manage Applications.
- On theAdd Proxy Organization Assignment>Organizations: Select organizations that have access to this proxy. For more information about how organization assignment affects API deployment to proxies, see Organizations Assignment.
- On the Complete Proxy Enrollment page, selectSelect URLto copy the enrollment URL to the clipboard. Do not close or navigate away from the Complete Proxy Enrollment page.
- Use the Policy Manager to submit the enrollment URL:
- Log in to the API proxy as the API proxy administrator.
- On theTasksmenu, selectExtensions and Add-Ons,Enroll with Portal. The URL is automatically pasted when using the desktop client version of the Policy Manager.
The enrollment process adds the following 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 installed, we recommend that you hide the social-media login buttons from Portal users, as described below.
Update Integration Software on the API Proxy
Updating to the latest version of the integration software (also known as the Portal Integration bundle) ensures that API and API key deployment synchronization between the Portal and On-Premise proxies are optimized for reliability and scalability. It also ensures that the API Portal is able to capture and present richer data in the Proxy Details page for analysis and troubleshooting.
When an update for the integration software is available as part of a Portal release, its availability is highlighted in the Release Notes. Portal administrators should coordinate with the API proxy administrator to update the integration software on the API proxy.
See Compatibility Matrix to learn what the latest version of the integration software is and how to identify if you have the latest version installed on your 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.
- For customers using API Gateway 10 CR1 and higher:Download the PortalUpgradeAssertion replacement file to replace the existing server module file when performing your update. For more information, see KB 201757: Upgrade Portal Integration bundle operation fails for API Gateway 10 CR1 and above.
Follow these steps:
- In the Policy Manager, log in to the API proxy as an administrator.
- (For API Gateway 10 CR1 and higher only; skip this step if you are using other versions of the Gateway OR if you have already replaced the PortalUpgradeAssertion file after the Portal 5.0.0 upgrade) 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.
- On theTasksmenu, clickExtensions and Add-Ons,Update Portal Integration.
- Restart the API proxy. To do this, open a privileged shell on the API proxy and then run these commands:
For more information, see 'Using the Privileged Shell' in the online documentation for the API Gateway.$ service ssg stop $ service ssg start
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.
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:
- Start the Policy Manager.
- Log in to the proxy as an administrator.
- Locate theMAG Enabled Social Login Providerspolicy fragment in the MAG Social Login folder: MAG-<version>, configuration, MAG Social Login.
- Set the following context variables to false:enable_googleenable_facebookenable_linkedinenable_salesforceenable_enterpriseenable_device2device
If you tried to enroll a tenant API Gateway with an
Clean Up the API Gateway and Portal after a Failed Enrollment
API Portalbut 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:
- In the Policy Manager, log in to the Gateway as a Gateway administrator.
- On theTasksmenu, selectCertificates, Keys and SecretsandManage Certificates.
- Remove the PSSG and DSSG certificates.Do not delete the API Gateway self-signed SSL certificate.
- On theTasksmenu, selectCertificates, Keys and SecretsandManage Private Keys.
- Remove the portalman private key.
- On theTasksmenu, selectGlobal SettingsandManage Scheduled Tasks.
- Remove all scheduled tasks.
- On theTasksmenu, selectGlobal SettingsandManage Cluster-wide Properties.
- Remove all properties that begin withportal.
Step 2. Remove the API Gateway from the API Portal:
- Log in to the API Portal as an API Portal administrator.
- From the menu bar, clickManage, Proxies.
- On the API Proxy page, find the Gateway. Its state isCluster is currently pending enrollment completion.
- SelectDeletenext to the Gateway you want to remove.