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.
ccppmop156
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 PPM
 or 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.
  image2019-3-9_10-46-35.png  
 
 
|  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.
 
2
 
 
Introduction
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 an 
    Access-Control-Allow-Origin
     header 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 the 
    Origin
     header. 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 are 
    Server-Sent Events
     and 
    XMLHttpRequest
    .
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. 
Origins
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 
omit credentials 
 
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 
example.org/app-name/
 and the 
app-name
 portion 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 
representation
 of 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:
  1. The administrator configures the origin information using commands for system options.
  2. When an external request is received, the CA PPM application reads and caches the original permitted origin value or values.
  3. A CORS filter intercepts every request to the REST API and validates if it is a valid preflight 
    OPTIONS
     request by examining the origin and request headers.
  4. The CORS filter responds with required information back to the browser. 
  5. 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:
 
 
admin
 system-options -
add
 <option code> <option value>
 
 
Example
: The following command adds a new 
ca.com
 domain option value for the CONTENT_SECURITY_DOMAINS setting in the cmn_option_values table:
 
 
admin
 system-options -
add
 CORS_ALLOW_ORIGIN ca.com
 
 
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):
 
 
admin
 system-options -
delete
 CORS_ALLOW_ORIGIN
 
admin
 system-options -
add
 CORS_ALLOW_ORIGIN 'https://rallydev.com,https://ca.com,http://localhost:8011'
service stop start app
 
To configure the supported types of cross-origin requests, use the following system options:
  •  
     
    CORS_ALLOW_ORIGIN
     
    : A comma-separated list of allowed origins.
  •  
     
    CORS_ALLOW_SUBDOMAINS
     
    : Set this Boolean property to 
    true
     or 
    false
    . When 
    true
    , requests from applications in subdomains are allowed. For example, in domain 
    a1.ppm.com
     this setting allows requests from 
    b2.ppm.com
    .
  •  
     
    CORS_SUPPORTED_METHODS
     
    :
     
     
     
    A comma-separated list of permitted HTTP methods such as GET, POST, and PUT. As an example, using this property, you could restrict or allow a DELETE call from another domain.
  •  
     
    CORS_SUPPORTED_HEADERS
     
    : A comma-separated list of headers allowed for a request.
  •  
     
    CORS_ALLOW_GENHTTP_REQUESTS
     
    : Set this Boolean property to 
    true
     or 
    false
    . When 
    true
    , non-CORS requests are allowed.
  •  
     
    CORS_CACHE_AGE
     
    : Indicates how long the results of a preflight request can be cached by the web browser, in seconds. If not specified, 7200 is the default, equivalent to 120 minutes or two hours. This information is passed to the browser in the Access-Control-Max-Age header.
 
Example
: The following default configuration allows CA Agile Central SaaS users to make requests in an associated CA PPM environment:
  •  
     
    CORS_ALLOW_GENHTTP_REQUESTS: 
     
     
    true
     
  •  
     
    CORS_ALLOW_ORIGIN: 
     
     
    https://rallydev.com,https://ca.com
     
  •  
     
    CORS_ALLOW_SUBDOMAINS: 
     
     
    true
     
  •  
     
    CORS_CACHE_AGE: 
     
     
    7200
     
  •  
     
    CORS_SUPPORTED_HEADERS
     
    =
    Content-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:
 
 $ 
admin
 system-options -
delete
 CORS_ALLOW_ORIGIN  $ 
admin
 system-options -
add
 CORS_ALLOW_ORIGIN https://rallydev.com/,https://ca.com,http://localhost:7001 
 
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:7001
 or 
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 as 
    https://rally.forwardinc.com
     and 
    https://ppm.forwardinc.com
     and both are routed by a reverse proxy setup. In this scenario, add 
     
    https://forwardinc.com
     
     to the allowed origins and PPM will allow requests from Agile Central.
  • 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.
Test App
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, set 
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
 
 error in the browser console as expected.
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
Error:
Explanation:
Corrective Action:
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.