|
Topics: |
Syntax:
com.ibi.agents.XDCorsAgent
iIT Service Object:
http: Cross-Origin Resource Sharing
Description:
This service implements the server-side processing of Cross-Origin Resource Sharing (CORS) as described in http://www.w3.org/TR/cors/.
Normally, browsers forbid cross-origin requests for security reasons. CORS specifies a mechanism that allows browsers to make cross-origin requests to resources that opt in to provide access. CORS defines a set of HTTP headers and the rules to process them. Most common browsers implement CORS natively. It is expected that the user agent making the request will be a browser. The CORS service implements the server-side rules to respond to CORS requests received by an nHTTP listener.
If the request is simple (such as GET, HEAD, or POST), then the user agent (for example, the browser) can make the request directly. The user agent adds the Origin header to indicate which site is asking for this resource. The syntax of an origin is:
scheme "://" host [ ":" port ]
The same syntax is used to configure the allowed origins in the service.
If the request is not simple, then the user agent must send a pre-flight request before the actual request to authorize it. The pre-flight request is an OPTIONS request for the same URL. The Access-Control-Request-Method header indicates the method of the actual request (for example, PUT). The optional Access-Control-Request-Headers header indicates which headers will be used in the actual request. Depending on the response of the pre-flight request, the user agent can abort or make the actual request following the same rules as a simple request.
The CORS service analyzes the request, and depending on its configuration, will report one of the following results:
In accordance with the specification, the CORS service adds the CORS response headers only if the request is allowed. The new headers appear as Special Registers (SREGs) in the Response Header Namespace.
The CORS service sets the output document of an OPTIONS request to a zero-length byte array. This will return an empty body with Content-Length equal to 0. This is the most appropriate result, but an application can modify the output document afterwards if necessary. For other requests, the CORS service returns the input document as the output document. Unlike the headers, the output document will be the same irrespective of the actual outcome (allowed, notallowed, or notcompliant).
The nHTTP listener must be configured carefully to make CORS processing possible. The OPTIONS Handling property must be set to event. This instructs the listener to pass the request to the channel instead of responding directly. The Request Header Namespace and the Response Header Namespace must not be none, and they must be different from each other. This makes the request headers available to the CORS service, and allows the response headers be sent with the response. Of course, the Excluded Headers property should not list the CORS headers. The HTTP Response Code must be 200 for a CORS pre-flight response. The Authentication Scheme and the Authentication Realm properties should be considered carefully. CORS is a mechanism used to relax security. It does not replace the need for user credentials to protect sensitive data.
Parameters:
The following table describes the parameters for the Cross-Origin Resource Sharing Service.
|
Parameter |
Description |
|---|---|
|
Allowed Origins |
List of origins that are allowed access to the resource. Leave empty or enter * to allow all origins. The syntax of an origin is: scheme "://" host [ ":" port ] This property is used to validate the Origin header in the request and influences the value of the Access-Control-Allow-Origin header in the response. The return value of the Access-Control-Allow-Origin header will be * if the Allowed Origins is * and Supports Credentials is false. |
|
Allowed Methods |
Comma-separated list of HTTP methods that are supported by the resource. Leave empty to allow all methods. This is used to validate the Access-Control-Request-Method header in the pre-flight request and to initialize the Access-Control-Allow-Methods header in the pre-flight response. |
|
Supported Headers |
Comma-separated list of HTTP header field names that are supported by the resource. Leave empty to claim support for all headers. This is used to validate the Access-Control-Request-Headers header in the pre-flight request and to initialize the Access-Control-Allow-Headers header in the pre-flight response. |
|
Exposed Headers |
Comma-separated list of HTTP header field names of headers (other than the simple response headers) that the resource might use and can be exposed. This is used to initialize the Access-Control-Expose-Headers header in the response of the actual request. |
|
Supports Credentials |
Indicates whether the resource supports user credentials in the request. This is used to initialize the Access-Control-Allow-Credentials header in the response. Notice the return value of the Access-Control-Allow-Origin header will never be * for a resource that supports credentials. |
|
Max Age |
Specifies the amount of seconds the user agent (for example, the browser) is allowed to cache the result of the pre-flight request. The value 0 means unbounded. This is used to initialize the Access-Control-Max-Age header in the response of the pre-flight request. |
Edges:
The following table lists the available line edges for the Cross-Origin Resource Sharing Service (com.ibi.agents.XDCorsAgent).
|
Line Edge |
Description |
|---|---|
|
OnError |
Error |
|
OnSuccess |
Success: The message was successfully analyzed. The cors Special Register contains the result. |
|
OnFailure |
Failure |
|
OnCustom |
|
Special Registers:
The following table describes the Special Register (SREG) that is assigned upon a successful execution.
|
Special Register |
Description |
|---|---|
|
cors |
The outcome of analyzing the request. This will be one of the following values:
Note: These values are lowercase and do not contain any spaces. |
The following examples show the result of executing the Cross-Origin Resource Sharing Service on various HTTP requests. The following table lists the parameter values for the Cross-Origin Resource Sharing Service that are used by the examples.
|
Parameter |
Value |
|---|---|
|
Allowed Origins |
http://host1.com http://host2.com:8080 |
|
Allowed Methods |
GET,POST |
|
Supported Headers |
ReqHdr1,ReqHdr2,ReqHdr3 |
|
Exposed Headers |
RespHdr1,RespHdr2 |
|
Supports Credentials |
true |
|
Max Age |
30 |
Example 1
This HTTP request is missing the Origin header. When analyzing this request, the service would set the cors Special Register to notcompliant and return success. No response headers would be added. The output document is the input document.
GET /app/page1 HTTP/1.1 Host: example.com
Example 2
Since the Allowed Origins is not empty or *, the origin must match exactly one of the listed origins. When analyzing this request, the service would set the cors Special Register to notallowed and return success. No response headers would be added. The output document is the input document.
GET /app/page1 HTTP/1.1 Host: example.com Origin: http://host.com
Example 3
When analyzing this request, the service would set the cors Special Register to allowed and return success. The output document is the input document.
GET /app/page1 HTTP/1.1 Host: example.com Origin: http://host1.com
The following response headers will be added:
Access-Control-Allow-Origin: http://host1.com Access-Control-Expose-Headers: RespHdr1,RespHdr2 Access-Control-Allow-Credentials: true
Example 4
This pre-flight request is missing the Access-Control-Request-Method header. When analyzing this pre-flight request, the service would set the cors Special Register to notcompliant and return success. No response headers would be added. The output document is a zero-length byte array.
OPTIONS /app/page1 HTTP/1.1 Host: example.com Origin: http://host1.com
Example 5
The actual request method HEAD is not allowed. When analyzing this pre-flight request, the service would set the cors Special Register to notallowed and return success. No response headers would be added. The output document is a zero-length byte array.
OPTIONS /app/page1 HTTP/1.1 Host: example.com Origin: http://host1.com Access-Control-Request-Method: HEAD
Example 6
The header names in Access-Control-Request-Headers are all supported headers. When analyzing this pre-flight request, the service would set the cors Special Register to allowed and return success. The output document is a zero-length byte array.
OPTIONS /app/page1 HTTP/1.1 Host: example.com Origin: http://host1.com Access-Control-Request-Method: GET Access-Control-Request-Headers: ReqHdr1,ReqHdr2
The following response headers will be added:
Access-Control-Allow-Origin: http://host1.com Access-Control-Allow-Methods: GET,POST Access-Control-Allow-Headers: ReqHdr1,ReqHdr2,ReqHdr3 Access-Control-Allow-Credentials: true Access-Control-Max-Age: 30