REST API: Cross-Origin Resource Sharing (CORS)

ccppmop1591
As a developer, refer to this page for information about CORS and the
Clarity
REST API. Cross-Origin Resource Sharing (CORS) uses additional HTTP headers to instruct a web browser to grant permission to
Classic 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.
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
    Clarity
    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,
    Clarity
    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
    Clarity
    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
Clarity
REST API
To improve
Clarity
integration capabilities,
Clarity
includes support for Cross-Origin Resource Sharing (CORS) with external applications.
Clarity
allows you to define external domains and accept external URL requests in PPM. CORS support extends to all
Clarity
environments including on-premise, SaaS, and our new mobile app.
With CORS, all of the following use cases are now possible:
  • Improved
    Clarity
    Integration with CA Agile Central
    : The CA Agile Central (formerly Rally) agile application can make webhook calls to
    Clarity
    to read project data that is personalized for the current user.
  • Improved Integrations by Broadcom Service partners
    : If you can imagine an integration solution, our Broadcom Service partners 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
    Clarity
    and other applications.
  • Improved Third-Party Integrations
    : Leverage the power of
    Clarity
    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:
Clarity
and CA Agile Central
Clarity
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
Clarity
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.
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
    Clarity
    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
On-Premise Environments
The following command options, available in on-premise editions of
Clarity
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
Clarity
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
Clarity
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
Clarity
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
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
    Clarity
    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
Clarity
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
    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.