REST API: Cross-Origin Resource Sharing (CORS)
As a developer, refer to this page for information about CORS and the Clarity PPM REST API. Cross-Origin Resource Sharing (CORS) uses additional HTTP headers to instruct a web browser to grant permission to cappm or another application running at one origin or domain to access certain resources from a server in a different origin or domain.
As a developer, refer to this page for information about CORS and the Clarity PPM REST API. Cross-Origin Resource Sharing (CORS) uses additional HTTP headers to instruct a web browser to grant permission to
Clarity PPMor another application running at one origin or domain to access certain resources from a server in a different origin or domain.
A web application makes a cross-origin HTTP request when interfacing with a resource in a different origin, domain, protocol, or port from its own. For security reasons, browsers restrict cross-origin HTTP requests initiated from inside scripts.
Disclaimer: The Clarity PPM REST API can only be used by our internal engineering teams. Clarity PPM REST API implementations by customers and partners are not supported in production environments. As previously announced, our strategy was to focus on developing a more robust API with each iterative design improvement to our new user experience. The API evolved and continues to grow as we make architectural improvements, add capabilities, and optimize performance. We have reviewed our strategy every release with the intention of making the API publicly available as soon as possible. Although the API is not intended for public use, the associated documentation is available for use by both internal and external stakeholders. This page will eventually form the foundation for the public REST API documentation.
| Clarity PPM 15.6.x BETA FEATURE
To take advantage of the Clarity PPM 15.6.x REST API BETA functionality, you must be an authorized partner or internal developer. BETA functionality includes limited support and is only available in non-production environments with Clarity PPM 15.6 or 15.6.1.
Network administrators commonly apply same-origin restrictions to network requests. These restrictions prevent a client-side web application from obtaining data retrieved from another origin, and also limit unsafe HTTP requests that can be automatically launched toward destinations that differ from the original running application.
Network requests have historically included user credentials with cross-origin requests, including HTTP authentication and cookie information. With CORS, our REST APIs benefit from the following improvements:
- A response can include anAccess-Control-Allow-Originheader with the original value of the request acting as a key to allow access to the resource content. As an administrator or developer, you can validate that the key value and origin for the request match.
- You can use a preflight request to discover whether a cross-origin resource is prepared to accept requests, using a non-simple method, from a given origin. As an administrator or developer, you can verify that the preflight request and the origin for the request are valid.
- Server-side applications like CA PPM are now able to discover that an HTTP request was deemed a cross-origin request by another user agent (for example, from a CA Agile Central request), through theOriginheader. With CORS, CA PPM can enforce limitations on the cross-origin requests that they are willing to service. For example, the application might return data for a specific user or project, or return no data.
- CORS serves as a building block for other CORS API specifications such as the CA PPM CORS REST API which defines how CORS can be used. Other examples areServer-Sent EventsandXMLHttpRequest.
A web application makes a cross-origin HTTP request when it requests a resource in a different origin or domain. CORS allows your web browser to trust that a web application running in an original domain is authorized to access selected resources from a server at a different domain.
When comparing origins, examine the following three components:
- Protocol: When one app is hosted with HTTPS and another is hosted with HTTP, this protocol scenario represents two different origins.
- Domain: When a request from domain 2 arrives at domain 1, this domain scenario represents two different origins. It is two different addresses in itself.
- Port: When two applications are hosted on the same server with two separate tomcat application server instances, this port scenario represents two different origins. For example, you are running a new REST API app on port 8082 and another legacy application on port 8095.
When requests have greater significance than simple retrieval and involve coordination between or data originating from more than two origins, design the requests to set an
flag.Resources must perform authorization using security tokens explicitly provided in the content of the request, especially if the origins are not all mutually and completely trusted. These multi-origin scenarios include integrations between resources enabling editing, printing, and storage, each at distinct origins.
In such multi-origin scenarios, a malicious resource at one of the origins may be able to enlist the user-agent as a confused deputy and elevate its privileges by abusing user credentials sent with cross-origin requests. Avoiding such attacks requires that the coordinating applications have explicit knowledge of the scope of privilege for each origin and that all parameters and instructions received are carefully validated at each step in the coordination to ensure that effects implied do not exceed the authority of the originating principal. Given the difficulty of avoiding such vulnerabilities in multi-origin interactions we recommended that, instead of using user credentials attached to the request by the user agent, pass security tokens which specify the particular capabilities and resources authorized as part of the explicit content of a request. OAuth provides an example of such a pattern.
Authors of client-side applications are strongly encouraged to validate content retrieved from a cross-origin resource as it might be harmful. Web applications that are not uniquely identified by specific host names, or mapped to specific ports, do not necessarily have a unique origin, and thus are not able to securely utilize CORS. This is because an origin is composed of only the scheme, hostname, and port. For example, a web application whose URL is of the type
app-nameportion is necessary to distinguish the web application from other web applications also running at
example.org, might be unable to securely employ CORS.
Mapping web applications to distinct origins is vital for secure web applications.
CORS Support in the CA PPM REST API
To improve CA PPM integration capabilities, CA PPM 15.6 introduced limited support (only for authorized partners) for Cross-Origin Resource Sharing (CORS) with external applications. Release 15.5 hinted at this feature by white-listing domains in external URLs. CA PPM 15.6 and higher allows you to define external domains and accept external URL requests in PPM. CORS support extends to all PPM environments including on-premise, SaaS, and our new mobile app version 3.0.
With CORS, all of the following use cases are now possible:
- Improved Clarity PPM Integration with CA Agile Central: The CA Agile Central (formerly Rally) agile application can make webhook calls to PPM to read project data that is personalized for the current user.
- Improved Integrations by CA Services: If you can imagine an integration solution, our CA Services and Global Delivery teams have probably already worked on it. We can help you leverage the CA Services Live API team to build integrations between PPM and other applications.
- Improved Third-Party Integrations: Leverage the power of CA PPM as a business platform with third-party integrations with an array of traditional products and new solutions. Examples include FlowDock, Slack, Microsoft Team, Atlassian JIRA, ITDesign, and OpsHub.
CORS In Action: CA PPM and CA Agile Central
CA PPM allows other applications to integrate with it by means of the REST interfaces in each application user interface. As a primary example, in Agile Central integrations, users might want to view CA PPM project data without leaving Agile Central. Since the two applications are typically hosted across different origins, requests are almost always considered cross-origin. The on-premise domain does not match the SaaS domain for the other application, or ports do not match.
Simple cross-origin requests including form submissions using GET or POST and cross-origin GET requests resulting from script elements typically include user credentials. Application resources must be prepared to expect simple cross-origin requests with credentials; however, they must also protect themselves from Cross-Site Request Forgery (CSRF) by requiring the inclusion of an unguessable token in the explicitly provided content of the request.
CORS defines how to authorize an instance of an application from another origin, executing in the original web browser, to access a
representationof the resource in an HTTP response. Some exceptions are allowed where certain types of resources do not attempt to specify particular authorized origins, but instead either deny or allow all origins.
: As a general rule, CA PPM allows CORS only within its REST API, which is not supported for public consumption. Only authorized implementation teams and CA Services personnel are permitted to use the REST API. However, CORS does present the possibility of future expanded support for this and other APIs.
The following steps illustrate the process:
- The administrator configures the origin information using commands for system options.
- When an external request is received, the CA PPM application reads and caches the original permitted origin value or values.
- A CORS filter intercepts every request to the REST API and validates if it is a valid preflightOPTIONSrequest by examining the origin and request headers.
- The CORS filter responds with required information back to the browser.
- The browser reviews the response and decides whether to accept or to reject the origin of the actual request.: Unless you implement a method for monitoring cache refreshes, if you change the origin information in system options, you must also restart the app server to pick up the new settings.
Configure CORS in Clarity PPM On-Premise Environments
The following command options, available in on-premise editions of CA PPM 15.6 and newer releases, let you add or delete system options and values:
add<option code> <option value>
Example: The following command adds a new
ca.comdomain option value for the CONTENT_SECURITY_DOMAINS setting in the cmn_option_values table:
Example: The following commands add localhost:8011 to your CORS_ALLOW_ORIGIN configuration settings for PPM 15.6 non-production SaaS environments integrated with Rally (CA Agile Central):
service stop start app
To configure the supported types of cross-origin requests, use the following system options:
- CORS_ALLOW_SUBDOMAINStrueorfalse. Whentrue, requests from applications in subdomains are allowed. For example, in domaina1.ppm.comthis setting allows requests fromb2.ppm.com.
- CORS_ALLOW_GENHTTP_REQUESTStrueorfalse. Whentrue, non-CORS requests are allowed.
Example: The following default configuration allows CA Agile Central SaaS users to make requests in an associated CA PPM environment:
- CORS_SUPPORTED_HEADERSContent-Type, User-Agent, Accept, X-Requested-With, Accept-Language, Accept-Encoding, Origin, Referer, Access-Control-Request-Method, Access-Control-Request-Headers, Connection, Pragma, Cache-Control, Authorization, AuthToken
- CORS_SUPPORTED_METHODS:GET, POST, HEAD, OPTIONS, PUT, DELETE
Edit a Configuration
Changes can be made using the admin utility. For example, to set up a development environment, issue the following commands:
Restart the ppm app server:
service stop start app
: After editing the configuration, clear your browser cache or open your browser in incognito mode and then refresh the page.
Clarity PPM On-Premise Non-Production Development and Testing
During development of your integration, you might host applications using
http://localhost:8020. In this case, add the URL and port to the allowed origins. You might also need to add more headers or methods.
The following two scenarios are common during installation of an on-premise integration:
- Application 1 (for example, Agile Central) and Application 2 (PPM) are hosted ashttps://rally.forwardinc.comandhttps://ppm.forwardinc.comand both are routed by a reverse proxy setup. In this scenario, addhttps://forwardinc.com
- If both apps are deployed in separate domains and ports (which would cover on-premise and SaaS hybrid cases), then add those URLs to the configuration.
You can edit and then use the following test app to simulate access to your PPM test instance through a subdomain such as localhost:7001:
For example, seterror in the browser console as expected.
CORS_ALLOW_SUBDOMAINS: false. If you attempt access from a different subdomain such as my.localhost:7001, you will get a
blocked by CORS policy
Other valid test examples:
- Make a XOG import or export call to a Clarity PPM instance using custom scripting in another application such as SharePoint.
- Restrict access to HTTP delete methods by external domains
- Test integrations with and without SSO
Troubleshooting REST API Errors
Cross-Origin Resource Sharing (CORS) Filter: CORS origin denied.
Invalid origin in header.
Specify a valid origin in the header.
CORS 403 Forbidden error.
You might be making an API call to a server but did not set the CORS origin for the port you are using.
Set the CORS origin for the port you are using.
My API call is never made.
Your origin is valid but your host name is not.
Specify a valid host name or add the host name in your hosts configuration.
My API call returns an error.
The command (HTTP method) you are using (for example, GET) has been disabled on the target server (or the SSO server if using SSO).
Enable the REST API command you want to use on the server.