API Management cross domain policies
This article provides a reference for API Management policies used to enable cross domain calls from different clients.
More information about policies:
- Policies overview
- Set or edit policies
- Policy expressions
- Policy reference for a full list of policy statements and their settings
Cross domain policies
- Allow cross-domain calls - Makes the API accessible from Adobe Flash and Microsoft Silverlight browser-based clients.
- CORS - Adds cross-origin resource sharing (CORS) support to an operation or an API to allow cross-domain calls from browser-based clients.
- JSONP - Adds JSON with padding (JSONP) support to an operation or an API to allow cross-domain calls from JavaScript browser-based clients.
Allow cross-domain calls
Use the cross-domain
policy to make the API accessible from Adobe Flash and Microsoft Silverlight browser-based clients.
Note
Set a policy's elements and child elements in the order provided in the policy statement. Learn more about how to set or edit API Management policies.
Policy statement
<cross-domain>
<!-Policy configuration is in the Adobe cross-domain policy file format,
see https://www.adobe.com/devnet-docs/acrobatetk/tools/AppSec/CrossDomain_PolicyFile_Specification.pdf-->
</cross-domain>
Example
<cross-domain>
<cross-domain-policy>
<allow-http-request-headers-from domain='*' headers='*' />
</cross-domain-policy>
</cross-domain>
Elements
Name | Description | Required |
---|---|---|
cross-domain | Root element. Child elements must conform to the Adobe cross-domain policy file specification. | Yes |
Caution
Use the *
wildcard with care in policy settings. This configuration may be overly permissive and may make an API more vulnerable to certain API security threats.
Usage
This policy can be used in the following policy sections and scopes.
- Policy sections: inbound
- Policy scopes: global
CORS
The cors
policy adds cross-origin resource sharing (CORS) support to an operation or an API to allow cross-domain calls from browser-based clients.
Note
If request matches an operation with an OPTIONS method defined in the API, pre-flight request processing logic associated with CORS policies will not be executed. Therefore, such operations can be used to implement custom pre-flight processing logic.
Important
If you configure the CORS policy at the product scope, and your API uses subscription key authentication, the policy will only work when requests include a subscription key as a query parameter.
CORS allows a browser and a server to interact and determine whether or not to allow specific cross-origin requests (i.e. XMLHttpRequests calls made from JavaScript on a web page to other domains). This allows for more flexibility than only allowing same-origin requests, but is more secure than allowing all cross-origin requests.
You need to apply the CORS policy to enable the interactive console in the developer portal. Refer to the developer portal documentation for details.
Tip
To help you configure this policy, the portal provides a guided, form-based editor. Learn more about how to set or edit API Management policies.
Policy statement
<cors allow-credentials="false|true" terminate-unmatched-request="true|false">
<allowed-origins>
<origin>origin uri</origin>
</allowed-origins>
<allowed-methods preflight-result-max-age="number of seconds">
<method>http verb</method>
</allowed-methods>
<allowed-headers>
<header>header name</header>
</allowed-headers>
<expose-headers>
<header>header name</header>
</expose-headers>
</cors>
Example
This example demonstrates how to support pre-flight requests, such as those with custom headers or methods other than GET and POST. To support custom headers and additional HTTP verbs, use the allowed-methods
and allowed-headers
sections as shown in the following example.
<cors allow-credentials="true">
<allowed-origins>
<!-- Localhost useful for development -->
<origin>http://localhost:8080/</origin>
<origin>http://example.com/</origin>
</allowed-origins>
<allowed-methods preflight-result-max-age="300">
<method>GET</method>
<method>POST</method>
<method>PATCH</method>
<method>DELETE</method>
</allowed-methods>
<allowed-headers>
<!-- Examples below show Azure Mobile Services headers -->
<header>x-zumo-installation-id</header>
<header>x-zumo-application</header>
<header>x-zumo-version</header>
<header>x-zumo-auth</header>
<header>content-type</header>
<header>accept</header>
</allowed-headers>
<expose-headers>
<!-- Examples below show Azure Mobile Services headers -->
<header>x-zumo-installation-id</header>
<header>x-zumo-application</header>
</expose-headers>
</cors>
Elements
Name | Description | Required | Default |
---|---|---|---|
cors | Root element. | Yes | N/A |
allowed-origins | Contains origin elements that describe the allowed origins for cross-domain requests. allowed-origins can contain either a single origin element that specifies * to allow any origin, or one or more origin elements that contain a URI. |
Yes | N/A |
origin | The value can be either * to allow all origins, or a URI that specifies a single origin. The URI must include a scheme, host, and port. |
Yes | If the port is omitted in a URI, port 80 is used for HTTP and port 443 is used for HTTPS. |
allowed-methods | This element is required if methods other than GET or POST are allowed. Contains method elements that specify the supported HTTP verbs. The value * indicates all methods. |
No | If this section is not present, GET and POST are supported. |
method | Specifies an HTTP verb. | At least one method element is required if the allowed-methods section is present. |
N/A |
allowed-headers | This element contains header elements specifying names of the headers that can be included in the request. |
No | N/A |
expose-headers | This element contains header elements specifying names of the headers that will be accessible by the client. |
No | N/A |
header | Specifies a header name. | At least one header element is required in allowed-headers or expose-headers if the section is present. |
N/A |
Caution
Use the *
wildcard with care in policy settings. This configuration may be overly permissive and may make an API more vulnerable to certain API security threats.
Attributes
Name | Description | Required | Default |
---|---|---|---|
allow-credentials | The Access-Control-Allow-Credentials header in the preflight response will be set to the value of this attribute and affect the client's ability to submit credentials in cross-domain requests. |
No | false |
terminate-unmatched-request | This attribute controls the processing of cross-origin requests that don't match the CORS policy settings. When OPTIONS request is processed as a pre-flight request and doesn't match CORS policy settings: If the attribute is set to true , immediately terminate the request with an empty 200 OK response; If the attribute is set to false , check inbound for other in-scope CORS policies that are direct children of the inbound element and apply them. If no CORS policies are found, terminate the request with an empty 200 OK response. When GET or HEAD request includes the Origin header (and therefore is processed as a cross-origin request) and doesn't match CORS policy settings: If the attribute is set to true , immediately terminate the request with an empty 200 OK response; If the attribute is set to false , allow the request to proceed normally and don't add CORS headers to the response. |
No | true |
preflight-result-max-age | The Access-Control-Max-Age header in the preflight response will be set to the value of this attribute and affect the user agent's ability to cache pre-flight response. |
No | 0 |
Usage
This policy can be used in the following policy sections and scopes.
- Policy sections: inbound
- Policy scopes: all scopes
JSONP
The jsonp
policy adds JSON with padding (JSONP) support to an operation or an API to allow cross-domain calls from JavaScript browser-based clients. JSONP is a method used in JavaScript programs to request data from a server in a different domain. JSONP bypasses the limitation enforced by most web browsers where access to web pages must be in the same domain.
Note
Set a policy's elements and child elements in the order provided in the policy statement. Learn more about how to set or edit API Management policies.
Policy statement
<jsonp callback-parameter-name="callback function name" />
Example
<jsonp callback-parameter-name="cb" />
If you call the method without the callback parameter ?cb=XXX
, it will return plain JSON (without a function call wrapper).
If you add the callback parameter ?cb=XXX
, it will return a JSONP result, wrapping the original JSON results around the callback function like XYZ('<json result goes here>');
Elements
Name | Description | Required |
---|---|---|
jsonp | Root element. | Yes |
Attributes
Name | Description | Required | Default |
---|---|---|---|
callback-parameter-name | The cross-domain JavaScript function call prefixed with the fully qualified domain name where the function resides. | Yes | N/A |
Usage
This policy can be used in the following policy sections and scopes.
- Policy sections: outbound
- Policy scopes: all scopes
Next steps
For more information about working with policies, see:
- Tutorial: Transform and protect your API
- Policy reference for a full list of policy statements and their settings
- Policy expressions
- Set or edit policies
- Reuse policy configurations
- Policy samples
Feedback
Submit and view feedback for